Introduction

GuardLink is an open specification and CLI toolset for Continuous Threat Modeling with AI. It solves the "stale threat model" problem by embedding security decisions directly into source code comments using GAL (GuardLink Annotation Language).

WHY GUARDLINK?

Security knowledge lives where the code is.
AI Agents maintain the model automatically.
CI/CD enforces security intent on every PR.
Language-agnostic and zero runtime cost.

Installation

Install GuardLink globally via npm to use the CLI from any directory. Requires Node.js 18+.

npm install -g guardlink

# Verify installation

guardlink --version

From source (dev)

Clone the repo, then npm install && npm run build. Use node dist/cli/index.js or link via npm link.

MCP / IDE

Add GuardLink to your MCP client config (e.g. Cursor) so AI agents can call guardlink_parse, guardlink_validate, and guardlink_dashboard.

Quick Start

# 1. Initialize GuardLink

guardlink init

# 2. Add your first annotation

echo '// @asset App.API (#api) -- "Main API"' > security.js

# 3. View status

guardlink status .

How to Use Guide

InitSetupAnnotateProcessInsights

1Initialize & Agent Setup

Run guardlink init in your project root. Choose your preferred AI coding agent (Cursor, Claude, etc.). GuardLink will automatically create the necessary agentic configuration files:

.cursorrulesFor Cursor users

.clauderulesFor Claude Dev/Cline

2AI-Powered Annotation

Simply instruct your AI agent to "read guardlink gal" to understand the annotation language. Then, sit back and sip your coffee while the agent autonomously scans and annotates your codebase with security intent.

# Your prompt to the AI agent:

"Read the GAL specification and annotate my current project."

AI IS ANALYZING SOURCE CODE...

3The GuardLink Toolchain

Once the AI has finished annotating, run the core toolchain to process your threat model:

guardlink parse

Extracts GAL annotations from your source code.

guardlink validate

Checks for syntax errors and unmitigated threats.

guardlink report

Generates a detailed Markdown threat model.

guardlink dashboard

Launches an interactive visualization in your browser.

4Continuous Insights & AI Analysis

Explore your system's security architecture through interactive Data Flow Diagrams and Mermaid diagrams. For a deep dive, use the AI analysis command:

guardlink /analyze

This triggers a comprehensive AI-powered audit of your threat model, providing a final report on edge cases, architectural weaknesses, and recommended mitigations.

Architecture

GuardLink is a single-binary CLI. User input (CLI args, TUI commands, or MCP tool calls) flows into the parser; the resulting ThreatModel is consumed by report, dashboard, SARIF, and diff. Definitions live in .guardlink/definitions.ts; the rest of the codebase uses relationship verbs only.

Loading diagram…

CLI / TUI / MCP

Entry points. CLI and TUI read project dir; MCP exposes tools (parse, validate, dashboard, etc.) over stdio.

Parser

Scans source files, strips comments, extracts GAL lines, resolves #id refs against definitions, outputs ThreatModel JSON.

Report / Dashboard / SARIF / Diff

Consume ThreatModel to produce markdown, HTML dashboard, SARIF 2.1.0, or git-diff of threat changes.

Codebase Overview

The GuardLink CLI codebase is organized by capability. Definitions for assets, threats, and controls live in .guardlink/definitions.ts; all other modules reference them by #id. Key directories:

src/

cli/ — CLI entry, command dispatch, options

tui/ — Interactive TUI, slash commands, /parse, /report, /dashboard

mcp/ — MCP server, guardlink_parse, guardlink_validate, guardlink_dashboard, guardlink_lookup, guardlink_suggest

parser/ — parse-project, parse-file, parse-line, validate, normalize, comment-strip

dashboard/ — generate.ts (HTML), data.ts (stats, severity, heatmap), diagrams.ts (Mermaid)

report/ — Markdown report, Mermaid diagram generation

analyzer/ — SARIF 2.1.0 export

diff/ — Git diff of threat model between refs

analyze/ — AI threat reports (STRIDE, DREAD, etc.), tools, LLM client

agents/ — Config, launcher for Claude/Cursor/Codex, prompts

init/ — guardlink init, templates, agent picker

types/ — ThreatModel and related TypeScript types

.guardlink/

definitions.ts — @asset, @threat, @control definitions only

config.json — Optional LLM provider / API config

The project is annotated with GuardLink itself: .guardlink/definitions.ts declares assets (e.g. #parser, #dashboard, #mcp), threats (#xss, #path-traversal), and controls (#output-encoding, #path-validation). Source files use @exposes, @mitigates, @flows, and @comment to document the threat model. Run guardlink dashboard . in the repo to see the generated threat-model dashboard.

GAL Specification

GAL is a structured grammar designed to be both human-readable and machine-parsable. All annotations follow a standard pattern:

<comment-prefix> @<verb> <arguments> [<qualifiers>] [<external-refs>] [-- "<description>"]

Definition Verbs

Used to declare the building blocks of your threat model.

@asset<path> (#id)

Declares a component, service, or resource.

// @asset App.API (#api) -- "Main REST endpoint"

@threat<name> (#id) [severity]

Names a threat or vulnerability class.

// @threat SQL_Injection (#sqli) [critical]

@control<name> (#id)

Names a security defense mechanism.

// @control Rate_Limiting (#rate-limit)

Relationship Verbs

Connects assets, threats, and controls into a graph.

@mitigates<asset> against <threat> [using <control>]

Declares a defense against a threat.

// @mitigates App.Auth against #sqli using #prepared-stmts -- "Login query uses parameterized statement"

@exposes<asset> to <threat> [severity] [external-refs]

Declares a known vulnerability or weakness.

// @exposes App.API.Users to #idor [P1] cwe:CWE-639 -- "No ownership check on GET /users/:id"

@accepts<threat> on <asset>

Acknowledges and accepts a known risk.

// @accepts #info-disclosure on App.API.HealthCheck -- "Health endpoint returns version info; this is public and non-sensitive"

@transfers<threat> from <source> to <target>

Delegates risk responsibility to another component or external service.

// @transfers #auth-bypass from App.API to External.Auth0 -- "Authentication delegated to Auth0"

@flows<source> -> <target> [via <mechanism>]

Describes data flow between components.

// @flows App.Frontend -> App.API via HTTPS/443 -- "All API calls over TLS 1.3"

@boundarybetween <asset-a> and <asset-b> [(#id)]

Declares a trust boundary between two components. Also supports pipe syntax: asset-a | asset-b.

// @boundary between External.Internet and Internal.DMZ (#perimeter) -- "WAF + firewall boundary"

Lifecycle Verbs

Track validation, ownership, audits, and security assumptions over time.

@validates<control> for <asset>

Declares that a test verifies a security control is working.

// @validates #prepared-stmts for App.Auth -- "Integration test confirms SQLi payloads are blocked"

@audit<asset>

Flags a component for security review.

// @audit App.Crypto -- "Is AES-128-GCM still sufficient? Consider migration to AES-256"

@owns<owner> for <asset>

Assigns security ownership of a component to a team, role, or individual.

// @owns platform-security for App.Auth -- "All auth changes require security team review"

@handles<classification> on <asset>

Classifies the type of sensitive data a component processes. Classifications: pii, phi, financial, secrets, internal, public.

// @handles pii on App.Users.Profile -- "Stores name, email, phone, address"

@assumes<asset>

Documents a security assumption that the code relies on.

// @assumes App.API -- "All requests are pre-authenticated by the API gateway"

Comment & Special Verbs

Developer notes and AI exclusion markers.

@comment[-- "<description>"]

Adds a security-relevant developer note to the threat model.

// @comment -- "Legacy OAuth1 flow, scheduled for removal in Q3"

@shield[-- "<reason>"]

Excludes code from AI agent context. Use @shield for a single function, or @shield:begin / @shield:end for a block range.

# @shield -- "Proprietary trading algorithm, do not expose to external LLMs"

Parsing & Output

The guardlink parse command recursively scans every source file in your project, extracts all GAL annotations from comments, and assembles them into a structured Threat Model. It supports 30+ comment syntaxes across all major languages.

How Parsing Works

From source code annotations to a structured threat model in seconds.

# Parse the current project

guardlink parse

# Parse and write output to a JSON file

guardlink parse --output threat-model.json

Scan

Recursively walks every source file, detecting comment syntax per language.

Extract

Parses each annotation line — resolves IDs, normalizes names, validates severity and external refs.

Assemble

Combines all annotations into a single threat model graph with full cross-referencing.

Output Structure

The parsed threat model is a JSON object containing every relationship in your codebase.

{

"version": "2.0.0",

"project": "my-app",

"source_files": 83,

"annotations_parsed": 109,

// Definition objects

"assets": [{ id, name, path, description, file, line }],

"threats": [{ id, name, severity, cwe, description }],

"controls": [{ id, name, description }],

// Relationship objects

"mitigations": [{ asset, threat, control, description }],

"exposures": [{ asset, threat, severity, description }],

"acceptances": [{ threat, asset, description }],

"transfers": [{ threat, source, target, description }],

"flows": [{ source, target, mechanism, description }],

"boundaries": [{ id, asset_a, asset_b, description }],

// Lifecycle objects

"validations": [{ control, asset, description }],

"audits": [{ asset, description }],

"ownership": [{ owner, asset, description }],

"data_handling": [{ classification, asset, description }],

"assumptions": [{ asset, description }],

"shields": [{ file, line, reason }],

"comments": [{ description, file, line }],

// Computed statistics

"coverage": { mitigated, exposed, accepted, unmitigated }

}

Supported Comment Syntaxes

GAL annotations work in any language — the parser detects the comment prefix automatically.

//JS, TS, Go, Rust, Java, C

#Python, Ruby, Shell, YAML

--SQL, Lua, Haskell

/* */CSS, C, Java

(* *)OCaml, Pascal

""" """Python docstrings

%LaTeX, Erlang

;Lisp, Clojure, INI

HTML, XML, Markdown

{- -}Haskell

REMBatch

'VB, VBA

Reports & Diagrams

GuardLink generates three output formats — a Markdown report with embedded Mermaid diagrams, a machine-readable JSON file, and an interactive HTML dashboard. Together, they produce 4 distinct diagram types that visualize your threat model from different angles.

Output Formats

Three formats for different audiences — developers, tools, and stakeholders.

Markdown Report

guardlink report

Generates threat-model.md — a complete threat model with executive summary, risk tables, data flow tables, and an embedded Mermaid diagram.

JSON Export

guardlink report --json

Generates threat-model.json — machine-readable structured data for CI/CD pipelines, custom tooling, or SIEM integration.

HTML Dashboard

guardlink dashboard

Generates threat-dashboard.html — a self-contained interactive dashboard with dark/light themes, filterable tables, and live Mermaid diagrams.

Markdown Report Sections

What's inside the generated threat-model.md file.

Executive Summary

High-level metrics — asset count, threat count, controls, mitigations, coverage percentage.

Threat Model Diagram

Embedded Mermaid diagram showing assets, threats, data flows, and trust boundaries.

Unmitigated Exposures

Table of open vulnerabilities sorted by severity — your immediate action items.

Accepted Risks

Risks acknowledged via @accepts with rationale for each acceptance.

Active Mitigations

Table showing which controls defend which assets against which threats.

Data Flows

All @flows annotations — source, target, and transport mechanism.

Data Classification

Per-asset breakdown of PII, PHI, financial, secrets, internal, and public data.

Assumptions & Audits

Security assumptions for review and components flagged for audit.

Dashboard Pages

The interactive HTML dashboard includes 7 navigable pages.

Executive Summary

Key metrics, risk grade (A–F), coverage bar chart, severity breakdown, top exposed assets.

AI Analysis

Displays saved AI analysis results from guardlink analyze — STRIDE, DREAD, or PASTA frameworks.

Threats & Exposures

Open exposures (red), mitigated (green), accepted (blue) — with interactive drill-down drawers.

Diagrams

All 3 interactive Mermaid diagrams rendered live — threat graph, data flow, and attack surface.

Code & Annotations

File browser with collapsible source listings — view annotations grouped by file with line numbers.

Data & Boundaries

Data handling classifications per asset and trust boundary definitions.

Asset Heatmap

Risk level per asset — exposure counts, mitigation counts, data flow participation, and classifications.

Sample Dashboard HTML

The generated threat-dashboard.html is self-contained: one file with embedded CSS, data, and Mermaid. Layout: top nav (project name, stats, theme toggle), sidebar (7 pages), main content, and a slide-out drawer for exposure/asset details.

<!DOCTYPE html>

<head>

<title>GuardLink — MyProject Threat Model</title>

</head>

<body>

<a onclick="showSection('summary',this)">◆ Executive Summary</a>

<a onclick="showSection('threats',this)">⚠ Threats & Exposures</a>

<a onclick="showSection('diagrams',this)">◉ Diagrams</a>

... </nav>

... </div>

</div>

</body>

</html>

Run guardlink dashboard [dir] to generate this file. Open it in a browser; all data is embedded, so it works offline. Diagrams use Mermaid.js from CDN.

Diagram Types

GuardLink auto-generates 4 distinct Mermaid diagram types from your annotations. Each diagram visualizes a different dimension of your threat model.

1. Data Flow Diagram

Generated from @flows and @boundary annotations. Shows how data moves between components.

Sources@flows, @boundary, @handles

LayoutLeft-to-Right (LR)

Used InDashboard, Report

Loading diagram…

NODE SHAPES

[("name")] Data stores (db, cache, file)

(("name")) External actors (browser, user)

["name"] Processes (api, service)

2. Threat Model Graph

Generated from @exposes, @mitigates, and @control annotations. Maps the relationship between assets, threats, and defenses.

Sources@exposes, @mitigates, @control

LayoutLeft-to-Right (LR)

Used InDashboard

Loading diagram…

EDGE TYPES

-. exposed .-> Vulnerability

-- mitigates --> Defense

-.- Control applied to asset

3. Attack Surface Map

Generated from @exposes annotations. Groups all vulnerabilities by asset, colored by severity, with mitigation status.

Sources@exposes, @mitigates, @accepts

LayoutLeft-to-Right (LR), subgroups Top-Down (TB)

Used InDashboard

Loading diagram…

STATUS ICONS

🔴 🟠 🟡 🔵 Severity: P0 → P3

✅ Mitigated exposure

⚠️ Open / unmitigated

4. Report Architecture Diagram

Generated in the Markdown report. A top-down architecture view emphasizing data security, with smart node shapes and threat markers.

Sources@asset, @flows, @boundary, @exposes, @handles

LayoutTop-Down (TD)

Used InMarkdown Report

Loading diagram…

SMART NODE DETECTION

Node shapes are auto-detected from asset names using pattern matching:

[("...")] Cylinder — names containing: db, database, store, cache, file, credential, config, secret, storage

(("...")) Circle — names containing: user, browser, client, external, attacker

["..."] Rectangle — everything else (services, APIs, modules)

Diagram Coverage Matrix

Diagram	Annotations Used	Available In	Layout
Data Flow	@flows, @boundary, @handles	Dashboard + Report	LR
Threat Graph	@exposes, @mitigates, @control	Dashboard	LR
Attack Surface	@exposes, @mitigates, @accepts	Dashboard	LR + TB
Architecture	@asset, @flows, @boundary, @exposes, @handles	Report	TD

AI & MCP Integration

GuardLink is "AI-native". It exposes an MCP (Model Context Protocol) server that allows AI coding agents to read your threat model and suggest annotations in real-time.

Automated Maintenance

When your AI agent writes a new route, it automatically adds @exposes and @mitigates annotations based on the project's security policy.

@shield Enforcement

Use the @shield annotation to exclude sensitive cryptographic or proprietary logic from AI processing entirely.

CI/CD Pipelines

Threat modeling is only effective if enforced. GuardLink integrates into your CI pipeline to block regressions.

GUARDLINK DIFF

Compares threat models between Git refs

Removed DefenseFAIL

New Unmitigated ExposureWARN

Added MitigationPASS

Open Source & Contributing

GuardLink is open source and community-driven. We believe that security standards should be transparent and accessible to everyone.

GitHub Repository Join Discord Contributing Guidelines