Skip to content

Write your first annotation

By the end of this page one command reads a claim you wrote and reports it against a real line of code:

Terminal window
npx guardlink validate .
⚠ 1 unmitigated exposure(s):
#users → #sqli [critical] (src/users.js:3)
Validation passed with 1 unmitigated exposure(s).

Three pieces produce that line: a definition naming what is at stake, an annotation claiming a risk against it, and an anchor tying the claim to src/users.js:3. This page writes all three, then closes the risk and gates a build on it.

It continues the project from Install GuardLink.

Assets, threats, and controls are declared once, in .guardlink/definitions.js, each with a #id. Everything else references those ids. Append to the file:

.guardlink/definitions.js
// @asset App.Users (#users) -- "User records: id, email, phone"
// @threat SQL_Injection (#sqli) [critical] cwe:CWE-89 -- "Unsanitized input reaches a SQL query"
// @control Parameterized_Queries (#prepared-stmts) -- "Queries bind parameters instead of interpolating"

Declaring ids once is what makes the model checkable rather than a pile of strings: a later claim referencing #sqli either resolves to that threat or validate fails on it.

Part Shape Notes
Name App.Users Dotted path, your choice
Id (#users) What every other annotation references
Severity [critical] One of critical, high, medium, low, or P0 to P3
External reference cwe:CWE-89 Any scheme:value, so owasp:A03:2021 and attack:T1190 work the same way
Description -- "…" Always -- "quoted text", never a colon

Create the sidecar. The path mirrors src/users.js with .gal appended:

.guardlink/annotations/src/users.js.gal
@source file:src/users.js line:3 symbol:findUserByEmail
@handles pii on #users -- "Returns email and phone"
@exposes #users to #sqli [critical] -- "email is interpolated into the SQL string"

.gal files hold raw annotation lines, with no // prefix. The @source header anchors every line below it to a real code location: findUserByEmail is on line 3 of src/users.js. symbol: is optional, and it is what lets guardlink find the block again after a refactor moves the function.

Export the model, then check it:

Terminal window
npx guardlink parse . -o .guardlink/report.json
npx guardlink validate .
Wrote threat model to .guardlink/report.json
⚠ CLAUDE.md:3: The GuardLink block here was written from annotation_hash sha256-v3:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 and agent_config_hash sha256-v1:b98538a5cf853b003fe85a02c4d29edc8016441ade2719f6b67ee85b0a736639; the model is now sha256-v3:9cd65c4ce2bb5cfa3a6a3547889602e74683e3f21ddb66ae3953e2b075d575fb and sha256-v1:1047e9aa807f3fba476fa38095f693f17aeca1bfa9aaff6fab61c452047a2845. Agents reading it are told about a model that no longer exists — run `guardlink sync`.
0 error(s), 1 warning(s)
⚠ 1 unmitigated exposure(s):
#users → #sqli [critical] (src/users.js:3)
Validation passed with 1 unmitigated exposure(s).

The first warning is about CLAUDE.md, not your annotation. The GuardLink block init wrote there is stamped with the model it was written from, and the model has changed since. Refresh it, then validate again:

Terminal window
npx guardlink sync .
npx guardlink validate .
✓ Updated 2 agent instruction file(s):
.guardlink/README.md
CLAUDE.md
Skipped: .cursor/rules/guardlink.mdc (absent — sync writes only into instruction files that exist), AGENTS.md (absent — sync writes only into instruction files that exist), .github/copilot-instructions.md (absent — sync writes only into instruction files that exist), .windsurfrules (absent — sync writes only into instruction files that exist), .clinerules (absent — sync writes only into instruction files that exist), .gemini/GEMINI.md (absent — sync writes only into instruction files that exist)
✓ Every block is stamped with this model (annotation_hash and agent_config_hash);
guardlink validate warns when one goes stale. Agents read the live model through
guardlink_lookup and guardlink_context, so the block itself carries no copy of it.
⚠ 1 unmitigated exposure(s):
#users → #sqli [critical] (src/users.js:3)
Validation passed with 1 unmitigated exposure(s).

Exit code 0. An unmitigated exposure is not an error. Recording a risk before its control exists is the intended order of work. What validate fails on is a malformed annotation or a #id that resolves to nothing.

The location it reports is src/users.js:3, not the sidecar. Every consumer of the model sees the code position, which is why the @source line has to be right.

The parse step is the one init printed as step 4. In external mode, the export is how anything other than guardlink sees the sidecars, and validate leads with a warning naming the fix whenever the export is missing or was cut from older annotations than the ones on disk.

Fix the query, then say so in the model.

  1. Bind the parameter instead of interpolating it.

    src/users.js
    import { query } from './db.js'
    export async function findUserByEmail(email) {
    return query('SELECT id, email, phone FROM users WHERE email = $1', [email])
    }
  2. Record the control against the threat. Replace the sidecar with:

    .guardlink/annotations/src/users.js.gal
    @source file:src/users.js line:3 symbol:findUserByEmail
    @handles pii on #users -- "Returns email and phone"
    @exposes #users to #sqli [critical] -- "email reaches the SQL string"
    @mitigates #users against #sqli using #prepared-stmts -- "Bound parameter, not interpolation"

    The @exposes stays. It is the record that this code path handles untrusted input at all, and deleting it would delete the reason the control exists.

  3. Export again, refresh the agent block, then validate.

    Terminal window
    npx guardlink parse . -o .guardlink/report.json
    npx guardlink sync .
    npx guardlink validate .
    Wrote threat model to .guardlink/report.json

    sync prints what it printed above. Then:

    ✓ All annotations valid, no unmitigated exposures.

    Skip the export and validate still exits 0, but it opens with ⚠ Annotations do not leave this repository: and the hash of each model, because .guardlink/report.json then describes the exposure as open.

  4. Run the CI gate.

    Terminal window
    npx guardlink ci . --strict
    Parse diagnostics: 0
    Unmitigated exposures: 0
    Confirmed exploits: 0
    Acceptances: 0 (source: @accepts annotations in this repository)
    Annotation coverage: 67% — 2 of 3 source file(s) annotated, 6 annotation(s)
    Anchor drift: 0 of 1 anchor(s)
    Stale claims: none recorded — run `guardlink verify --all` to start tracking
    ✓ No unmitigated exposures, no confirmed exploits, no anchor drift, every acceptance accounted for.

    Exit code 0. Without --strict, ci reports the same findings and always exits 0, because it is advisory by default so a first-run repository does not fail its build on the day the annotations land.

    0 of 1 anchor(s) is the line worth reading. Zero drift out of zero anchors is a different statement from zero drift out of one, and only the second means anything was checked. The coverage line is there for the same reason: a repository with nothing written down passes every other check by having nothing to fail, and --min-coverage <percent> is what turns that into a gate.

Terminal window
npx guardlink report .
✓ Wrote threat model report to threat-model.md

threat-model.md is a full report covering scope, architecture, a Mermaid threat diagram, data inventory, active mitigations, and data classification, built from the six annotations you wrote. Sections with nothing behind them say so rather than being omitted, so the gaps are visible. Its header records the version that produced it:

# Threat Model Report — guardlink-quickstart
> Generated: 2026-10-19T16:25:07.852Z
> Files scanned: 3 | Annotations: 6
> GuardLink version: 2.4.0

For the machine-readable form, and for diagrams you commit:

Terminal window
npx guardlink artifacts .
Wrote 8 artifact(s):
.guardlink/graph/threat-graph.mmd
.guardlink/graph/dataflow.mmd
.guardlink/graph/attack-surface.mmd
.guardlink/graph/by-asset/users.threats.mmd
.guardlink/model.json
.guardlink/graph/MANIFEST.json
.guardlink/graph/README.md
.guardlink/graph/index.md
annotation_hash: sha256-v3:8bed94a125e3e3ed533cd5acd7936a1e985e7e3c886fbf4a0f06c30994308278
generated_at: 2026-10-19T16:25:08.675Z
git_sha: not a git checkout
(the last two are reported here, not written into the files — they would
otherwise churn every commit; the files are tracked.)
Every .mmd carries that hash in a %% header. Check with: guardlink validate . --artifacts

The by-asset/ slice and index.md are per-question drawings: a whole-model diagram stops being readable well before a repository stops being small, so artifacts also writes the slices that fit, and index.md tables them with the question each one answers.

Your annotation_hash will match this one if your annotations match; it is a hash of the model, not of the run. generated_at and git_sha differ every time, which is exactly why they are printed rather than written into the files.

.guardlink/model.json is the whole model as JSON, canonically ordered so the diff is readable:

{
"provenance": {
"annotation_hash": "sha256-v3:8bed94a125e3e3ed533cd5acd7936a1e985e7e3c886fbf4a0f06c30994308278",
"generator": "guardlink@2.4.0"
},
"version": "1.2.0",
"project": "guardlink-quickstart",
"source_files": 3,
"annotations_parsed": 6,
"annotated_files": [
".guardlink/definitions.js",
"src/users.js"
],
"unannotated_files": [
"src/db.js"
],

Truncated after unannotated_files. The file continues with one array per verb, then coverage and external_refs, and ends with agent_config and reach_analysis: what the coding-agent configuration init wrote (the skills and .mcp.json) lets an agent do. See review what coding agents may do. The @exposes line you wrote is one entry in the exposures array:

{
"asset": "#users",
"threat": "#sqli",
"severity": "critical",
"external_refs": [],
"description": "email reaches the SQL string",
"location": {
"file": "src/users.js",
"line": 3,
"parent_symbol": "findUserByEmail",
"origin_file": ".guardlink/annotations/src/users.js.gal",
"origin_line": 3
}
}

That is the whole mapping: a verb becomes an array, and each annotation becomes one object in it. file and line are the code position, origin_file and origin_line are the sidecar the claim was written in, and parent_symbol is what lets reanchor find the block again after a refactor moves the function. External mode records both positions so a consumer can point a developer at the annotation to edit while pointing a scanner at the code. The threat model as an artifact reads the rest of it.

If validate reports something you did not expect

Section titled “If validate reports something you did not expect”

In order of likelihood.

  • Nothing is reported at all, and status says 0 annotations. Check the sidecar path. .guardlink/annotations/src/users.js.gal mirrors the source path exactly, including the source file’s own extension.
  • Unknown annotation verb @flow, did you mean @flows? The verb is not in the grammar, so the line contributes nothing. guardlink warns when a bad verb is close to a real one; versions before 2.0.0 dropped it in silence. npx guardlink gal prints every verb.
  • @exposes on a line with no comment marker (found a #reference) — not parsed. The line is not in a comment guardlink reads. It reads annotations out of comments only, so a Python docstring or the body of a /* … */ block is not a place to put one. The warning is new in 2.1.0; before it, such a line was discarded in silence.
  • Dangling reference: #x is never defined. The #id has no @asset, @threat, or @control behind it in .guardlink/definitions.js. Definitions live there in both annotation modes.
  • Malformed @exposes annotation: could not parse arguments, and validate exits 1. The line has structure, a #ref, a -- delimiter, or one of that verb’s own keywords, so it was meant to be an annotation and is treated as broken rather than as prose. Descriptions use -- "quoted text", never a colon.
  • is not at the conventional path. The .gal file is somewhere else. It is still parsed, since this is a warning rather than a refusal, but nothing will look for it there.

Every command on these two pages reads files from disk and writes files to disk, with no account, no API key, and no server. That is why they make up the onboarding path.

For a repository that already exists, writing every sidecar by hand is the wrong use of your time. guardlink annotate builds a prompt carrying the grammar, your definitions, and your project’s rules, then hands it to a coding agent you already have:

Terminal window
npx guardlink annotate "annotate the database layer" . --stdout

--stdout prints that prompt and exits, so you can read exactly what would be sent before anything is. --claude-code, --codex and --gemini launch those CLIs in the foreground; --cursor, --windsurf and --clipboard put the prompt on the clipboard. guardlink itself makes no network call in any of those modes, and the agent you point it at does.