Skip to content

Feeding findings into cxg

An @exposes annotation is a hypothesis: this asset, this threat, this code location, nobody has shown it holds. cxg is what turns a hypothesis into a confirmed or refuted finding by attacking a running instance.

The interface between them is one file. guardlink writes SARIF; cxg pentest reads it. This page covers the guardlink half: what the export contains, what makes a finding useful downstream, and what never crosses.

Terminal window
mkdir -p whitebox
npx guardlink sarif . -o whitebox/findings.sarif
✓ Wrote SARIF to whitebox/findings.sarif
SARIF: 1 result(s) — 1 error(s), 0 warning(s)

cxg pentest run --codebase <dir> loads <dir>/whitebox/findings.sarif. The path is fixed, so the filename and directory above are not a convention you can change. See cxg pentest.

The -o flag does not create the directory. Without the mkdir -p, guardlink exits 1 with a raw Node ENOENT stack trace rather than a message.

Without -o, SARIF goes to stdout, which is what you want in a pipeline. The SARIF: 1 result(s) line goes to stderr either way.

SARIF 2.1.0, one run, five rules:

Rule Level From
guardlink/unmitigated-exposure warning @exposes with no matching @mitigates or @accepts
guardlink/unmitigated-critical error the same, at critical or high
guardlink/confirmed-exploitable error @confirmed
guardlink/parse-error error a malformed annotation
guardlink/dangling-ref warning a #id that resolves to nothing

A single result, from a sidecar that also declares @flows #api -> #users via GET./api/users:

{
"ruleId": "guardlink/unmitigated-critical",
"level": "error",
"message": {
"text": "#users is exposed to sqli: email is interpolated into the SQL string"
},
"locations": [
{
"physicalLocation": {
"artifactLocation": {
"uri": "src/users.js"
},
"region": {
"startLine": 3
}
},
"logicalLocations": [
{
"name": "findUserByEmail"
}
]
}
],
"partialFingerprints": {
"guardlink/threatId": "gl-5cc827267186",
"guardlink/claimKey": "e2a06832d8f6be0ae0f8b95a6c8ae211d1ad09df5ba21291a15155b83b1c69ab:0"
},
"properties": {
"threatId": "gl-5cc827267186",
"claimKey": "e2a06832d8f6be0ae0f8b95a6c8ae211d1ad09df5ba21291a15155b83b1c69ab:0",
"severity": "critical",
"asset": "#users",
"threat": "#sqli",
"codegraph_reachability": {
"http_method": "GET",
"http_path": "/api/users"
},
"route_attribution": "handler",
"guardlink/anchor": {
"scope": "symbol",
"symbol": "findUserByEmail",
"start_line": 3,
"end_line": 5
},
"guardlink/flowAttribution": "handler"
},

Truncated after properties. The result continues with relatedLocations, here the @handles pii on the same asset, and codeFlows, the declared @flows chain into the claim with the route as a webRequest. Those, taxa for a cwe: reference, and the run’s graphs[0] of every @flows and @boundary edge are the declared context 2.2.0 added. A consumer that does not read them sees the same results it saw before: no result was added, dropped or reordered.

Three fields carry the weight.

threatId, the identity that survives the round trip

Section titled “threatId, the identity that survives the round trip”

gl- plus twelve hex characters, derived from the normalised asset, the normalised threat, and the file. Not the line, and not the message text.

That means it is stable across re-runs and across code movement, and it is the same id whether the annotation is an @exposes or the @confirmed that later proves it. That is deliberate, because those are the same threat at the same place at two points in its life. Downstream tools carry the string and compare it; they never recompute it. guardlink is the sole authority for the algorithm.

It is emitted twice: in partialFingerprints, which is the SARIF-native mechanism any SARIF consumer understands, and in properties, for consumers without a SARIF library.

The accepted limitation: two genuinely distinct weaknesses at an identical (asset, threat, file) collapse to one id.

codegraph_reachability, where to point the traffic

Section titled “codegraph_reachability, where to point the traffic”

A source-code location does not tell an HTTP scanner what to request. This does, and it comes from your @flows annotations.

guardlink builds it by looking for a flow whose mechanism is a route, written METHOD./path:

@flows #api -> #users via GET./api/users

That produced the codegraph_reachability block above. The method must be one of GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS; the path must start with /. A query string is stripped, and so is anything in parentheses.

A finding takes the route declared on its own handler, else the one declared in its file, else its asset’s inbound route, and properties.route_attribution says which step found it (handler, file or asset). When the model does not tie the finding to one route, the result carries route_attribution: "ambiguous" and a route_candidates list instead, and no codegraph_reachability. Read that as “test each of these”, not as “no route”. Before 2.2.0 a finding took the first route declared in its file, which in a file with two handlers could point a scanner at the wrong endpoint.

No route annotation, no reachability field. The finding still exports, and a downstream tool has nothing but a file path to work from. If you want your annotations tested against a running service, annotating the routes is the highest-value thing you can do, higher than adding more exposures.

The path is emitted verbatim, with no base path assumed. If your service is mounted under /v2, write /v2/api/users.

critical and high are what make guardlink emit unmitigated-critical at error level rather than unmitigated-exposure at warning. cxg ranks the hypotheses it loads against the operator’s stated goal, so severity is an input to that ranking rather than the whole of it.

Severity on an @exposes is optional; when omitted it inherits from the @threat declaration. Written as:

@exposes #users to #sqli -- "no severity written here"

against @threat SQL_Injection (#sqli) [critical], the exported result is guardlink/unmitigated-critical at error, with "severity": "critical". Leaving it unset in both places is how a real finding ends up carrying nothing to rank on.

Filter before exporting if you only want the top of the list:

Terminal window
npx guardlink sarif . --min-severity high -o whitebox/findings.sarif

The default profile, github, is for code scanning. --profile pentest is for a test run, and appends three kinds of result after every github result, so no result index moves:

Rule Level One per
guardlink/mitigated-exposure note @exposes that a @mitigates or @accepts covers, with suppressions[] naming each covering annotation and where it is
guardlink/boundary-claim none, kind: "review" @boundary, with its sides, the outer side when it is known, the @flows that cross it and the routes into its inner side
guardlink/agent-reach none, kind: "review" @agents or @reaches, and @effects other than read, with whether the effect is gated and by what
Terminal window
npx guardlink sarif . --profile pentest -o whitebox/findings.sarif
✓ Wrote SARIF to whitebox/findings.sarif
SARIF: 3 result(s) — 1 error(s), 0 warning(s)
Pentest profile: 1 mitigated exposure(s), 1 boundary claim(s) appended; hypothesis ledger absent

That run is a file with two @exposes on sibling handlers, one of them covered by a @mitigates on its own handler, and one directed @boundary. The covered exposure comes back at note, with the same message an open one would carry, "#orders is exposed to idor: No ownership check", and a suppressions member naming what covers it:

[
{
"kind": "inSource",
"status": "accepted",
"justification": "Owner compared before the delete",
"location": {
"physicalLocation": {
"artifactLocation": {
"uri": "orders.py"
},
"region": {
"startLine": 16
}
},
"message": {
"text": "@mitigates #orders against #idor using #owner_check"
}
},
"properties": {
"guardlink/verb": "mitigates",
"control": "#owner_check",
"claimKey": "654e76ad7f765e15a73ededcce9f4daa4798e138f391ee6af9ba8105394b9798:0"
}
}
]

Every exposure, confirmed and boundary-claim result in this profile also carries the hypothesis ledger’s state as properties["guardlink/hypothesis"], and --baseline <file> marks each result new, unchanged or updated against an earlier export. A boundary claim’s basis is declared when the annotation is written @boundary from <outer> to <inner>, undeclared-endpoint when the outer side is inferred from an endpoint no @asset declares, and unknown otherwise.

In the default profile, @mitigates and @accepts remove the exposure entirely. They do not annotate it, flag it, or downgrade it. A covered (asset, threat) pair is absent from a github export, so a consumer of that file never probes it. That is the failure mode to keep in mind: a mitigation you wrote and have not verified removes the thing that would have verified it. Export with --profile pentest when the file feeds a test run, and the covered exposure comes back as a mitigated-exposure result to test.

guardlink sarif writes the same file whether or not the control it names still exists. Deleting an @exposes and deleting a real risk look identical from downstream.

@entitles crosses in neither direction, by design. An entitlement records that an actor is legitimately allowed a capability. SARIF for a model with entitlements is byte-identical to one without, in both profiles: the exposure is exported the same, probed the same, and a reader of the file cannot tell an entitlement exists. Only the downstream recommendation changes.

The reasoning is worth stating, because it is the opposite of how a suppression usually works: a suppression that also prevents verification is how a threat model becomes confidently wrong. An over-granted entitlement should be able to change how a finding is written up. It should never be able to stop the finding being tested.

The coverage block does not appear in SARIF at all. No field in the export carries it.

Four things, in the order they cost you the most.

  1. Annotate the routes. Without codegraph_reachability, a finding names a file and nothing an HTTP client can act on.
  2. Set severity. It decides ordering and rule level.
  3. Make sure the exposures you care about are still exposures. Anything mitigated or accepted is gone from a github export. Use --profile pentest to keep it as a result to test.
  4. Check the file count. SARIF: N result(s) on stderr, against what guardlink status . reports as unmitigated. A number lower than you expect usually means a @mitigates you forgot about, or --min-severity.