API
Diagnostics
What the engine reports about each function, and how to read it.
While a job runs, the engine reports what it finds: functions it couldn't protect, constructs it handled with reduced protection, and general notes. Each report is a diagnostic. They appear live on the job page and through the API.
Severities#
| Severity | Meaning |
|---|---|
error |
Something couldn't be done. Usually a function was left unprotected, its original code kept. |
warning |
Done, but with less protection than asked for, or something you should check. |
info |
Notes and summaries. |
A job with errors can still succeed: by default a function that can't be protected keeps its
original code and is reported as an error. To fail the whole job instead, use the
on_function_error option (see Tool options).
Get diagnostics#
GET /api/v1/jobs/{id}/diagnostics?severity=error&limit=1000
| Parameter | Description |
|---|---|
severity |
Optional: error, warning or info. |
limit |
Optional, default 1000, at most 5000. |
{
"status": "succeeded",
"counts": { "error": 5, "warning": 9, "info": 2 },
"truncated": false,
"diagnostics": [
{
"severity": "error",
"code": "LIFT_FRAME_UNPLACED",
"message": "The function's stack frame could not be analysed, so it keeps its original code.",
"function_rva": 72704,
"function_name": "sub_11c00"
}
]
}
Diagnostics are ordered errors first, then warnings, then info. You can call this while the job is still running to see what has been reported so far.
Fields#
| Field | Description |
|---|---|
code |
A stable identifier such as LIFT_FRAME_UNPLACED. Match on this, not on the message. See Codes. |
message |
A human-readable explanation. Wording may change. |
function_rva, function_name |
The function it applies to, when there is one. The RVA is relative to the image base. |
details |
Optional extra data, specific to the code. |
Codes#
| Code | Severity | Meaning |
|---|---|---|
PE_UNREADABLE |
error | The input could not be read as a 64-bit PE image. Nothing was processed. |
PE_NO_FUNCTIONS |
error | The input declares no functions to protect (no exception directory, or an empty one). Packed images often look like this. |
PE_SUMMARY |
info | How many functions the input declares. |
LIFT_FRAME_UNPLACED |
error | The function's stack frame could not be analysed, typically because the stack pointer is computed at run time. It keeps its original code. |
COMPILE_TIMEOUT |
error | The function ran over function_timeout and keeps its original code. Raise the limit, or set it to 0 for none. |
COMPILE_INTERNAL |
error | An internal error stopped this function; it keeps its original code. Please report the job. |
COMPILE_INCOMPLETE |
error | The function did not finish processing before the run ended; it keeps its original code. |
LINK_FAILED |
error | The protected image could not be assembled. No output was produced. Please report the job. |
CFG_INVALID |
error | The job's configuration is invalid. Nothing was processed. |
CFG_SETTING |
error | A setting is unknown or has an invalid value. Nothing was processed. |
RULE_NO_MATCH |
warning | A function rule matched no function in this binary, so it had no effect. The function may have been renamed or inlined. details gives the rule's number and pattern. |
Every function that keeps its original code has at least one error diagnostic saying why.
Limits#
GuardPkg stores up to 5,000 diagnostics per job. Past that, truncated is true; the counts
still include every diagnostic, but only the first 5,000 can be listed.
Diagnostics are deleted with the job's output when it expires; the counts are kept. After that,
this endpoint returns 410.