API / Diagnostics

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#

http
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.
json
{
  "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.