Report schema

What a Draugr report contains, field by field, for a gate or a dashboard reading it rather than a person. How to produce and deliver one is render a report and send it somewhere.

Telling a partial run from a clean one#

A gate reading report.json should check more than verdict. A run where a scanner never started and a run that found nothing both produce findings-shaped output, and the difference is what your pipeline should do about it. One is broken infrastructure, the other is work.

scanErrors, reported, notMeasured[] and scanners[].failed[] are omitted when there is nothing to report, so a clean run's document is unchanged. targets[] is omitted when the run planned no target. dependencyFiles[] is present whenever a scanner that lists its inputs ran, and an entry with no unread means every dependency file was read in full.

draugr scan draugr.saga.yaml -o out/
jq -e '[.controls[].scanErrors // empty] | length == 0' out/report.json   # fail the build on a partial run
jq -e '[.dependencyFiles[]?.unread // empty] | length == 0' out/report.json   # fail on a file no scanner read
jq -r '.targets[]? | select(.status != "reached") | "\(.kind) \(.target): \(.detail)"' out/report.json   # what was not reached, and why
jq -r '.scanners[]? | "\(.name) \(.version // "")" as $s | .failed[]? | "\($s) \(.component // "") \(.target // ""): \(.detail)"' out/report.json   # which scanner failed, at which version, and where
jq -r '[.targets[]?.refusal | select(.credential == false) | .registry] | unique[]' out/report.json   # registries to log in to

Gate#

gate in report.json is the policy the run was judged against, and the outcome of the gate on new findings where a comparison ran.

The top-level verdict is the run's verdict, the one its exit code came from. On a scan given a --base with a gate on new findings set, that is the gate on new findings' outcome; the run also fails where the organization's policy fails or the scan could not finish. The whole run's outcome against failOnPriority or threshold decides nothing there and is kept in gate.wholeRun, with each control's own in controls[].verdict. On any other run, the top-level verdict is the whole run's outcome and gate.wholeRun is absent.

failOnNew with no new is a gate on new findings that was asked for and had no base to apply to. From a scan given a --base, under failOn: critical and failOnNew: P2, of a change that committed a token. The token is a high-severity P1, so the change fails and the whole run passes its own gate, and the document's top-level verdict is fail:

"gate": {
  "threshold": "critical",
  "failOnNew": "P2",
  "new": {
    "base": {
      "commit": "0b4a9232671686284eeb6d2dd7d6d26a503b013b",
      "repositories": [
        {
          "url": ".",
          "revision": "0b4a9232671686284eeb6d2dd7d6d26a503b013b"
        }
      ]
    },
    "introduced": {
      "p1": 1,
      "p2": 0,
      "p3": 0,
      "p4": 0
    },
    "verdict": "fail"
  },
  "wholeRun": "pass"
}

jq -e '.verdict != "fail"' out/report.json                               # fail where the run failed, as its exit code did
jq -e '.gate.failOnNew == null or .gate.new != null' out/report.json     # fail where the gate had no base
jq -r '.gate.wholeRun // .verdict' out/report.json                       # the whole run's outcome, whichever gate decided

What each finding carries#

Draugr reports as one SARIF tool, so every finding keeps its own attribution in its property bag:

control and tool answer different questions, and both matter to anything grouping findings: one rule id reported by two controls is two separate things to do.

exposure and criticality are what makes the band arithmetic checkable. Priority folds a component's classification into the scanner's severity, so the same CVE is P1 on an internet-facing service and P3 on a restricted one. Naming the component is not the same as stating that premise: without these two, reconstructing a band means fetching the descriptor, and the descriptor in the repository today is not necessarily the one that produced this finding. Both are empty for a project-scoped finding, which belongs to no one component, and for a component that declares neither, which Draugr reads as public and critical so that an unclassified component surfaces rather than hides.

escalation and reachability are why a band is not what the severity alone would give. One moves a finding up and one moves it down, and both carry the evidence rather than only the verdict, the analyzer and method for reachability, the dataset and the date for escalation. A reader is told to reject a reachability claim that does not say how it was reached; the same standard applies to a claim that something is more urgent than its score.

The ranked severity is computed from these fields, in this order. Start from the score, the draugr/rating severity, or the level (error high, warning medium, note low), in that order. Raise it to severityFloor where present. Where escalation is present, take escalation.to, which was raised from that floored severity. Where reachability found no path and carries rankedAs, take rankedAs, which was lowered from the severity before it. The result is the ranked severity a severity gate judges and controls[].highest reports.

historical: true marks a finding from the repository's commit history. Its location is the path the file had in the commit that introduced the secret, which a file renamed or deleted since no longer has. The credential is still readable by anyone who can clone the repository, so a historical finding needs rotating like a tree one. A secret present in both the tree and the history is reported once, as the tree finding. Each entry in report.json's findings carries the same historical field.

Suppressions#

A finding that something set aside stays in the report with the decision recorded. In report.json each entry in findings carries it as suppressed. In results.sarif it is a suppressions entry, with justification as its own field and the rest in its properties.

To tell two revisions of one VEX document apart, compare digest. To raise a claim with its supplier, quote statementId.

Unknown licenses#

A license the scanner could not identify is reported under the rule license/unknown/<package>, and the message quotes the text it found. deny and warn accept unknown to select every such license.

What each descriptor source carries#

descriptor.sources[] in report.json lists the files the run's descriptor was assembled from, in order: the descriptor, its fragments as they merged, and each configuration file that supplied a control default, least specific first. The guide shows the block and the two digests it carries.

descriptor.contributed maps each control setting that a file other than the descriptor supplied to the files that supplied it. Absent when every setting came from the descriptor. Its keys:

• a fragment's setting: control.option, for example provenance.signers
• a configuration file's setting: the path from the control's name, for example secrets.gitleaks.history

A configuration file is listed only when one of its control defaults reached the descriptor, which is when it changes descriptor.effective and descriptor.digest. A default the descriptor sets itself is not listed, and neither is a file that sets no control default.

jq -r '.descriptor.sources[] | select(.config) | "\(.config)  \(.path)  \(.digest)"' out/report.json
jq -r '.descriptor.contributed // {} | to_entries[] | "\(.key)  \(.value | join(", "))"' out/report.json

What each exclusion carries#

report.json lists the merged descriptor's config.exclude entries as descriptor.exclusions[], in the order descriptor.effective lists them. Each entry names the file and line it is written at, and the last commit to change that line, as git blame names it.

A finding an entry set aside names it by the same source and line, on the finding's suppressed object in report.json and in its suppression's properties in results.sarif.

The history is git's record, reported only where it is reliable. That is where the checkout holds the line's history and the last commit to change the line is not the boundary of a shallow clone. A shallow clone attributes every line it holds no history for to its boundary commit, whoever wrote the line, so a line at the boundary is reported as unavailable rather than attributed. No email address is recorded, and nothing is fetched to deepen a clone.

A fragment fetched from another repository always names a revision, and Draugr clones its repository with full history to check that revision out. Its entries carry that repository's history, and gitHistory.path is the path in that repository.

Full history#

Most CI systems check out a shallow clone by default. Full history on the scan job makes the history reliable for every entry:

jq -r '.descriptor.exclusions[] | "\(.source):\(.line)  \(.gitHistory.commit // .gitHistory.unavailable)"' out/report.json

Component labels#

componentLabels in report.json maps each component the descriptor declares to its labels, after fragments are merged, with no key or value normalized.

"componentLabels": {
  "storefront": {"team": "web", "data-class": "pii"},
  "worker": {}
}

Every declared component has an entry, {} where it declares no labels. A run narrowed with --components or --labels still lists every one, and scope names the components that ran. A missing componentLabels means the labels were not recorded, as in a report from a release that predates the key.

jq -r '.componentLabels | to_entries[] | select(.value.team == "web") | .key' out/report.json   # the components labeled team=web

What each action carries#

report.json carries the fix list as actions[], most urgent first, grouped as draugr scan --view actions groups it. An action is one change and every finding that change clears.

priority, exploitation, severity and clears are the keys the list is ordered by, so two actions can be compared from their own fields. The two steps of an upgrade split by policy rank together, by the worst band and every finding either step clears:

• exploitation, severity and severityFrom are the package's, the same on both steps;
• priority and clears are each step's own.

The MCP server's fix_list returns the same objects without findings[], in one list per kind.

jq -r '.actions[] | select(.package) | "\(.component) \(.package) \(.from) → \(.target // "no single release")"' out/report.json
jq -r '.actions[].locations[] | select(.kind == "vendored") | .path' out/report.json   # copies a manifest bump leaves as they were
jq -s '.[0].actions[0].findings as $ids | .[1].runs[].results[] | select(.properties.fingerprint | IN($ids[])) | .ruleId' out/report.json out/results.sarif   # what the first action clears

What the cache contributed#

A finding can come from a cache rather than from a scan, and stats.cache says what that rests on.

"cache": {
  "enabled": true,
  "dir": "/home/runner/.cache/draugr",
  "ttl": "24h0m0s",
  "readOnly": false,
  "hits": 12,
  "oldestHit": "2026-08-31T04:11:02Z",
  "unpinned": ["ghcr.io/acme/api:1.4.2"]
}

A gate that re-runs when results are too old has everything it needs here:

jq -e '.stats.cache.enabled and (.stats.cache.unpinned // [] | length == 0)' out/report.json

Tool memory#

stats.peakToolMemoryBytes is the largest resident memory, in bytes, that any single process reached among the tools Draugr ran and the processes those tools started and waited for, such as the compile processes of a Go build. It is the largest one process, not the sum of the processes that ran at the same time. The operating system keeps the figure for the life of the Draugr process, so under draugr mcp, which runs several scans in one process, it covers every scan since the server started. Absent where the operating system does not report it, which is the case on Windows. A figure near the memory of the machine or container sets the bound too high for it; a lower GOMAXPROCS, and -p in GOFLAGS, set the bound for the next run, as the CLI reference describes under Each tool's own parallelism.

jq '.stats.peakToolMemoryBytes / 1073741824' out/report.json   # in GiB

Effects#

effects records the scanner effects the run accepted (allowed), the ones its descriptor declares (declared), and the ones its scanners had (used). allowed differs from declared only by what --allow-effects added.

All three lists are present in every report, empty when nothing applies.

network and disclosure run without being accepted, so used can name a kind allowed does not hold. Only mutate and privilege in used are bounded by allowed.

The block below is from a run whose descriptor declares allowEffects: [mutate], given --allow-effects privilege, with a headers check against one host.

"effects": {
  "declared": ["mutate"],
  "allowed": ["mutate", "privilege"],
  "used": [
    {
      "kind": "network",
      "detail": "sends an HTTP GET to the endpoint and follows its redirects"
    }
  ]
}

jq -e '.effects.allowed - .effects.declared | length == 0' out/report.json   # fail when a flag accepted an effect the descriptor does not

SBOMs#

sboms records each SBOM document the run wrote and each it failed to produce.

Each failed[] entry is also one of the scanErrors of the (sbom) entry in controls[], so the run is incomplete unless --allow-scan-errors accepts it. targets[] accounts for the controls' scans and not for SBOMs, so a repository whose inventory failed can be reached there, or absent when no control scans it.

Under scope: project a target listed in failed[] is missing from the assembled document.

sboms is absent when the run wrote no document and recorded no failure, which includes every run with config.sbom off.

The block below is from a run of one component holding two repositories, the second of which could not be cloned.

"sboms": {
  "documents": [
    {
      "scope": "component",
      "component": "storefront",
      "target": "https://github.com/draugr-dev/draugr-demo",
      "format": "cyclonedx-json",
      "file": "sbom-storefront-https-github-com-draugr-dev-draugr-demo.cdx.json",
      "digest": "sha256:b9ffb8fd666d3a4437eabf3cb82c006f794a44dec2aaf136bea48b37b524b209"
    }
  ],
  "failed": [
    {
      "scope": "component",
      "component": "storefront",
      "target": "https://github.com/draugr-dev/storefront-theme",
      "format": "cyclonedx-json",
      "reason": "checkout https://github.com/draugr-dev/storefront-theme: git clone: exit status 128: remote: Repository not found.\nfatal: repository 'https://github.com/draugr-dev/storefront-theme/' not found\n"
    }
  ]
}

jq -r '.sboms.failed[]? | "\(.target // .scope): \(.reason)"' out/report.json   # which inventories are missing, and why
(cd out && jq -r '.sboms.documents[]? | "\(.digest | ltrimstr("sha256:"))  \(.file)"' report.json | sha256sum -c)   # the files are the ones recorded

What the run carries#

Some statements are about the scan rather than about any one finding, and those live in the run's own property bag:

decided and consulted both exist to separate "looked and found nothing" from "never looked." A scanner that reports nothing about a control has either examined it and been satisfied or never examined it; escalation appears on a finding only when a signal raised it, so its absence covers a CVE that is not listed, one that is listed but was already at the top band, and a dataset nobody loaded at all. exploited is on every finding KEV lists, raised or not, which tells the second case from the other two.

Without consulted, anything explaining a priority, a dashboard, a pull-request comment, a person reading the file, cannot tell not on KEV from KEV was not consulted, and silence reads as the second. asOf is empty when you supplied a feed file by hand, which has no fetch to record; entries is there because a dataset that loaded and turned out to be empty answers every lookup with "not listed" and looks exactly like one that is working. stale is true when the copy was older than the run's maxAge when it was read, and absent otherwise; the run is the only reader that knew the limit.

thresholdFrom names what set the EPSS threshold, the default, config.exploitability.epssThreshold, or --epss-threshold. The number alone is the one input to an escalation that arrives anonymous: the dataset names itself and the day its copy was obtained, while the line a score was measured against does not say who drew it. Whether a band is a policy or an accident depends on the answer.

A run that loaded no exploitability data and whose dependency-health lookup did not answer writes no consulted block. A lookup that failed, or that knew none of the run's packages, leaves no dependency-health entry. Its entries is the number of packages it knew, and the fields that describe a feed, stale and the threshold, are absent from it.

The sarif report is also what your editor reads. See see findings in your editor for inline diagnostics in VS Code and JetBrains.

For the exact schema of config.publishers, see the Saga schema; for the full catalog of reporters and publishers, see the integrations catalog.