The open specification

GuardLink is two things that ship together. One is a specification: a grammar, a threat-model schema, and four conformance levels, published under CC-BY-4.0. The other is guardlink, an MIT-licensed CLI that implements all four of them.

That matters for one reason. If the tool is the format, then your annotations are only worth what the tool is worth. If the format is written down separately, your annotations outlive the tool.

npx guardlink gal

That prints the grammar the parser actually implements, with an example per verb. The normative text is docs/SPEC.md, version 1.0.0.

What is specified, and what is not

Layer	Licence	Where
The annotation grammar and its verbs	CC-BY-4.0	SPEC.md §2, §3
The threat-model JSON structure	CC-BY-4.0	SPEC.md §5
The SARIF mapping	CC-BY-4.0	SPEC.md §6
Diff and change classification	CC-BY-4.0	SPEC.md §7
Conformance levels and their tests	CC-BY-4.0 text, MIT tests	SPEC.md §9
This CLI, the library, the MCP server	MIT	Bugb-Technologies/guardlink

The specification does not mandate a tool, a CI platform, or a scanner. Anyone can write a parser against it, and the conformance suite exists so they can prove it works.

The four levels

Each level includes the ones below it.

Level	Name	An implementation at this level
L1	Parser	Parses every annotation type, produces the threat-model structure, reports syntax errors with file and line
L2	Analyzer	Adds SARIF output, coverage statistics, unmitigated-exposure detection, dangling-reference detection
L3	CI/CD	Adds threat-model diffs between git refs, change classification, and exit codes a pipeline can gate on
L4	AI-Integrated	Adds @shield exclusion, an MCP server or equivalent, and AI-assisted annotation generation

guardlink 2.0.0 is Level 4 conformant. Every level is reachable from the CLI:

Level	The command that shows it	Documented at
L1	guardlink parse	The threat model as an artifact
L2	guardlink sarif, guardlink validate	Feeding findings into cxg
L3	guardlink diff, guardlink ci	Annotate an existing codebase
L4	guardlink mcp, guardlink annotate	Wire up the MCP server

The grammar is older than the tool

The four core verbs come from ThreatSpec, which Fraser Scott started in 2015 and which went dormant in 2020. It was the first project to propose keeping a threat model current by writing it as code annotations. GuardLink adds severity levels, external references, data-flow and trust-boundary verbs, data classification, a JSON schema, SARIF export, MCP integration, and CI enforcement on top of that grammar.

The compatibility is not a footnote in a document. ThreatSpec-era annotations parse today. This file uses the 2015 keyword with, where current syntax says using:

src/legacy.js

// @mitigates #api against #sqli with #prepared-stmts -- "ThreatSpec-era 'with' keyword"
export function q() {}

npx guardlink validate .

✓ All annotations valid, no unmitigated exposures.

@accepts <threat> to <asset>, the ThreatSpec argument order, parses as well, and the diagnostic prints it back in the current on form:

⚠ src/legacy.js:1: @accepts #sqli on #api without @audit — risk acceptance should be paired with @audit for traceability

0 error(s), 1 warning(s)

So does @review, which GuardLink renamed to @audit. It lands in the model’s audits array rather than being dropped:

{
  "asset": "#api",
  "description": "ThreatSpec-era @review verb",
  "location": {
    "file": "src/legacy.js",
    "line": 1
  }
}

That matters if you have a repository carrying annotations from the old tool. SPEC.md §4 is the full mapping table.

A misspelled verb is not silently dropped

guardlink 2.0.0 warns when a verb is close to a real one (Unknown annotation verb @flow, did you mean @flows?). Earlier versions dropped it in silence. That is what makes the compatibility above testable rather than assumed: an unrecognised verb says so.

What the specification does not promise you

It does not make an annotation true. Conformance is about parsing and reporting. A Level 4 implementation will faithfully carry a claim that is wrong, because nothing in the specification inspects what the code does. See why annotations live in code.

It does not yet have a second independent implementation in public. SPEC.md §12.4 commits the project to maintaining at least two, so that the specification is provably implementable without vendor knowledge. Today the CLI in this documentation is the reference implementation, and it is the one you can install.

Governance is early. Changes go through GuardLink Enhancement Proposals with a 14-day comment period and a Steering Committee, and that committee currently consists of the founding contributors at Bugb. SPEC.md §12.3 sets a cap of 50% of seats per organisation once the committee exceeds four members. That is a stated intent, not a present state, and it is worth reading as such.

Deciding

If you are choosing between annotating your code and writing a threat-model document, the specification is not the deciding factor; why annotations live in code is. The specification decides a narrower question: whether the annotations you write this quarter are readable by something other than this tool in five years. They are a published grammar under a permissive licence, with a conformance suite, so the answer is yes independently of what happens to guardlink.