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.
The handoff
Section titled “The handoff”mkdir -p whiteboxnpx guardlink sarif . -o whitebox/findings.sarif✓ Wrote SARIF to whitebox/findings.sarifSARIF: 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.
What crosses
Section titled “What crosses”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/usersThat 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.
severity, the rule and the level
Section titled “severity, the rule and the level”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:
npx guardlink sarif . --min-severity high -o whitebox/findings.sarifThe pentest profile
Section titled “The pentest profile”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 |
npx guardlink sarif . --profile pentest -o whitebox/findings.sarif✓ Wrote SARIF to whitebox/findings.sarifSARIF: 3 result(s) — 1 error(s), 0 warning(s)Pentest profile: 1 mitigated exposure(s), 1 boundary claim(s) appended; hypothesis ledger absentThat 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.
What does not cross
Section titled “What does not cross”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.
Before you export
Section titled “Before you export”Four things, in the order they cost you the most.
- Annotate the routes. Without
codegraph_reachability, a finding names a file and nothing an HTTP client can act on. - Set severity. It decides ordering and rule level.
- Make sure the exposures you care about are still exposures. Anything
mitigated or accepted is gone from a
githubexport. Use--profile pentestto keep it as a result to test. - Check the file count.
SARIF: N result(s)on stderr, against whatguardlink status .reports as unmitigated. A number lower than you expect usually means a@mitigatesyou forgot about, or--min-severity.
Related
Section titled “Related”- The threat model as an artifact is the model this export is a projection of.
guardlink sarifdocuments every flag on the exporter.cxg pentestis the consumer, with its flags and what it does with the file.- Bravos runs both ends of this in a loop, and says which threats it never managed to test.

