Introduction

GuardLink is an open specification and CLI for continuous threat modeling. Security decisions are embedded directly in source code as structured comments using GAL (GuardLink Annotation Language) — so your threat model updates automatically when code changes. AI coding agents maintain annotations as they write code, CI pipelines enforce security posture on every PR, and an interactive dashboard gives stakeholders real-time visibility.

WHY GUARDLINK?

Security knowledge lives next to the code it describes — never stale.
AI agents (Claude, Cursor, Windsurf, Cline, Codex) maintain the model via MCP.
CI/CD gates block PRs that introduce unmitigated exposures.
Language-agnostic (25+ comment styles), zero runtime cost, open specification.
16 annotation verbs covering assets, threats, controls, data flows, and governance.
AI threat reports with STRIDE, DREAD, PASTA, and more — powered by any LLM provider.

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 .

GuardLink CLI overview — CLI Overview
A clean terminal-first workflow for initialization, parsing, validation, reporting, and review.

GuardLink help output — Built-In Help
Discover commands quickly from the CLI before wiring GuardLink into agents or CI.

How to Use Guide

InitAnnotateProcessThreat ReportsDashboard

1Initialize & Agent Setup

Run guardlink init in your project root. GuardLink auto-detects your language and framework, creates the .guardlink/ scaffold with definition templates, and injects behavioral directives into your AI agent's instruction file so annotations are maintained as code is written.

CLAUDE.mdClaude Code

.cursorrulesCursor

.windsurfrulesWindsurf

.clinerulesCline

AGENTS.mdCodex

copilot-instructions.mdGitHub Copilot

GuardLink init workflow screenshot — Initialization Walkthrough
`guardlink init` sets up agent instructions and the local `.guardlink/` project scaffold before annotation begins.

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.

guardlink parse output — Parse
Extract annotations and assemble the threat model graph from source comments.

guardlink validate output — Validate
Catch syntax issues, dangling refs, and unmitigated exposures before they ship.

guardlink report output — Report
Generate markdown and JSON outputs for reviewers, pipelines, and downstream tooling.

guardlink dashboard output — Dashboard
Produce the interactive HTML dashboard for visual triage and stakeholder reviews.

4AI Threat Reports

Generate deep security analysis using established threat modeling frameworks. GuardLink sends your parsed threat model to an LLM and produces a structured report with actionable findings, severity ratings, and remediation guidance.

# Generate a threat report using any framework

guardlink threat-report general

# Other frameworks available:

guardlink threat-report stride # STRIDE methodology

guardlink threat-report dread # DREAD risk rating

guardlink threat-report pasta # PASTA process

guardlink threat-report attacker # Attacker perspective

guardlink threat-report rapid # Rapid assessment

# List saved reports

guardlink threat-reports

LLM Providers

Anthropic (Claude), OpenAI, Google Gemini, DeepSeek, Ollama, and OpenRouter. Configure with guardlink config.

Agent Delegation

Delegate to coding agents with --claude-code, --codex, --gemini, or copy to clipboard for IDE agents with --cursor.

Tool Use

Reports can leverage CVE/NVD lookup, codebase search, and finding validation tools during analysis for grounded results.

Saved Reports

Reports are saved to .guardlink/threat-reports/ and appear in the dashboard's AI Analysis page for team review.

GuardLink threat report generation GIF — Threat Report Generation
AI-assisted threat report generation using the parsed threat model. The LLM analyzes your assets, exposures, controls, and data flows to produce framework-driven findings.
Open full size

5Explore the Dashboard

Launch an interactive HTML dashboard to visualize your entire threat model — executive metrics, Data Flow Diagrams, threat graphs, attack surface maps, and asset heatmaps. Share the single self-contained threat-dashboard.html file with stakeholders.

# Generate and open the interactive dashboard

guardlink dashboard

7 PagesSummary, AI Reports, Threats, Diagrams, Code, Data, Heatmap

4 Diagram TypesData Flow, Threat Graph, Attack Surface, Architecture

Self-ContainedSingle HTML file with embedded data, Mermaid, and D3.js

GuardLink dashboard executive summary — Dashboard Executive Summary
Top-level metrics, risk grade (A–F), coverage percentage, severity breakdown, and exposed-asset overview — all generated from your annotations.
Open full size

Governance & Maintenance

A threat model is only useful if it stays maintained. GuardLink provides human-in-the-loop review for risk acceptance, agent instruction synchronization, coverage gap detection, and annotation cleanup — so the model stays accurate as your codebase evolves.

guardlink review

Interactive governance review for unmitigated exposures. Reviewers can accept, remediate, or skip findings with justification and audit trail support.

guardlink sync

Resynchronize agent instruction files with the current threat model so AI tooling stays aligned with the latest definitions and workspace context.

guardlink unannotated

List source files with no annotations so coverage gaps are visible before they become stale architecture blind spots.

guardlink clear --dry-run

Preview or remove annotations when you need to restart modeling, migrate formats, or clean a test repository.

Also Available In TUI / MCP

The same maintenance workflow is available in the terminal UI through /review, /clear, /sync, and /unannotated, with companion MCP tools for agent integrations.

Important Guardrail

Risk acceptance is intentionally human-owned. Use guardlink review for @accepts decisions, and rely on auto-sync in status or validate to keep agent context up to date.

Architecture

GuardLink is a single-binary Node.js CLI with three entry surfaces — CLI commands, an interactive TUI, and an MCP server — all feeding the same parse-and-report pipeline. Source files are scanned, GAL annotations extracted, references resolved, and the result assembled into a canonical ThreatModel JSON. That model powers every output: markdown reports, HTML dashboards, SARIF exports, git diffs, and AI threat analysis.

Architecture Components

The GuardLink runtime is intentionally small, but it has a few clear layers: entry surfaces, project context, parsing and resolution, governance/workspace logic, and output renderers.

Execution Path

1. Entry surfaces

CLI commands, TUI slash commands, and MCP tools all feed the same parse and reporting engine.

2. Context loading

GuardLink reads `.guardlink/definitions.ts`, optional `workspace.yaml`, and current agent instructions before resolving refs.

3. Parse and resolve

File scanners strip comments, extract GAL, normalize nodes, and resolve local plus cross-repo references.

4. ThreatModel assembly

Assets, threats, controls, exposures, flows, boundaries, metadata, and `external_refs` become one portable JSON model.

5. Output generation

The same model powers markdown, JSON, HTML dashboards, SARIF, git diff, and weekly workspace merge summaries.

Core Files And Artifacts

.guardlink/definitions.tsDefinitions for assets, threats, and controls. Runtime relationships reference these IDs instead of repeating the taxonomy in every file.

.guardlink/workspace.yamlOptional multi-repo identity and sibling registry mapping used for external reference detection and merged reporting.

guardlink-report.jsonMachine-readable report output with repo, workspace, commit SHA, schema version, and annotated coverage metadata.

threat-dashboard.htmlSelf-contained triage UI with metrics, drawers, Mermaid diagrams, AI reports, and embedded parsed model data.

CLI / TUI / MCP

Entry surfaces. CLI and TUI operate on the local repo, while MCP exposes the same capabilities to agents over stdio.

Parser Pipeline

Scans files, strips comments, extracts GAL lines, normalizes verbs, and resolves local plus workspace references into a stable graph.

ThreatModel Core

Holds assets, threats, controls, flows, boundaries, audit notes, metadata, and the `external_refs` needed for multi-repo merges.

Governance Layer

`review`, `sync`, `unannotated`, and `clear` keep the model maintained and ensure risk acceptance stays human-controlled.

Workspace Layer

`link-project`, `merge`, and `--diff-against` unify sibling repos, resolve cross-repo tags, and track week-over-week drift.

Outputs

Reports, dashboard, SARIF, git diff, and AI threat reports all consume the same model so review surfaces stay consistent.

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, /workspace, /link, /merge

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

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 parser is GuardLink's core engine. guardlink parse recursively scans every source file, detects comment syntax per language, extracts GAL annotations, resolves cross-references (including cross-repo workspace tags), and assembles everything into a structured ThreatModel JSON — the single source of truth that powers all downstream outputs.

v1.4.0 • 2026-02-27

Multi-Repo Workspaces

GuardLink can link multiple service repositories into a unified threat model with cross-repo tag resolution, merged dashboards, and week-over-week risk tracking.

# Link sibling repos into one workspace

guardlink link-project ./payment-svc ./auth-lib ./api-gateway \

--workspace acme-platform \

--registry github.com/acme

# In each repo: generate metadata-rich report JSON

guardlink report --format json -o <repo>.json

# Merge reports into dashboard + merged JSON + weekly diff

guardlink merge payment-svc.json auth-lib.json api-gateway.json \

--json merged.json -o workspace-dashboard.html \

--diff-against last-week.json

Fresh Link

guardlink link-project <repos...> --workspace <name> --registry <url>

Scaffolds .guardlink/workspace.yaml in each repo, auto-detects repo names from git or project files, and injects workspace context into agent instruction files.

Add / Remove

guardlink link-project --add ./new-service --from ./api-gatewayguardlink link-project --remove auth-lib --from ./api-gateway

Adds or removes repos from an existing workspace and updates sibling repos discovered on disk so the workspace stays consistent.

Report Metadata

guardlink report --format json -o guardlink-report.json

Per-repo JSON now carries repo, workspace, commit_sha, and schema_version metadata for CI and merge provenance checks.

Merge Outputs

guardlink merge <files...> --json merged.json -o dashboard.html

Merge produces a unified MergedReport, optional dashboard HTML or --summary-only text mode, stale/schema warnings, aggregated stats, and --diff-against weekly drift tracking.

.guardlink/workspace.yaml

workspace: acme-platform

this_repo: payment-svc

repos:

- name: payment-svc

registry: github.com/acme/payment-svc

- name: auth-lib

registry: github.com/acme/auth-lib

workspaceShared workspace name across all linked repos.

this_repoThe current repo identity used for local ownership and metadata.

repos[].nameCanonical repo short name and tag prefix owner.

repos[].registryOptional registry URL used for discovery and agent context.

Cross-Repo Annotation Rules

Relationship annotations can point at sibling repo tags. The parser scans those dot-prefixed tags using .guardlink/workspace.yaml, stores them in ThreatModel.external_refs, and the merge step resolves them against the unified tag registry.

// @asset PaymentService.RefundHandler (#payment-svc.refund)

// @flows #api-gateway.router -> #payment-svc.refund via HTTPS

// @mitigates #payment-svc.refund against #auth-lib.token-replay

Local validateExternal refs show up early so dangling sibling tags are visible before merge.

Workspace mergeUnresolved refs, duplicate tags, stale reports, and schema mismatches are surfaced in the merged summary.

Weekly Diff Tracking

guardlink merge --diff-against <prev.json> compares merged snapshots week-over-week and tracks assets, threats, mitigations, exposures, risk trend, and unresolved cross-repo reference changes.

assets added / removed

threats added / removed

mitigations drift

exposures drift

risk_delta trend

resolved / new refs

TUI, MCP, and CI

TUI/workspace, /link, and /merge expose the workspace flow directly in the terminal UI.

MCPguardlink_workspace_info returns workspace name, this repo identity, sibling tag prefixes, and cross-repo annotation rules to connected agents.

CI Examplesexamples/ci/per-repo-report.yml validates and uploads JSON per repo; examples/ci/workspace-merge.yml handles weekly merge, dashboard generation, and optional publishing.

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",

"generated_at": "2026-03-12T09:00:00.000Z",

"metadata": { schema_version, guardlink_version, repo, workspace, commit_sha, branch, generated_at },

"source_files": 83,

"annotations_parsed": 109,

"annotated_files": ["src/auth.ts", ...],

"unannotated_files": ["scripts/migrate.ts", ...],

"external_refs": [{ tag, context_verb, inferred_repo, location }],

// 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 produces three complementary outputs from the same parsed model: a Markdown report for code review and documentation, a JSON export for CI pipelines and tooling integration, and an interactive HTML dashboard with 7 navigable pages, 4 diagram types, dark/light themes, and drill-down drawers.

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 --format json

Generates threat-model.json with repo, workspace, commit SHA, and schema metadata for CI/CD pipelines and merge automation.

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.

Dashboard Tour

Real screenshots from the generated GuardLink dashboard and threat report views. These are shown large on purpose so the diagram and drawer details are readable.

GuardLink dashboard executive summary page — Executive Summary
Top-level metrics, grade, coverage, and exposed-asset overview.
Open full size

GuardLink dashboard threats and exposures page — Threats & Exposures
Filter open, mitigated, and accepted exposures from the generated dashboard.
Open full size

GuardLink dashboard open threat detail drawer — Open Threat Drawer
Drill into a live finding with severity, refs, and affected assets.
Open full size

GuardLink dashboard threat report drawer — Threat Report View
Saved AI threat reports appear directly inside the dashboard for review.
Open full size

GuardLink dashboard data and boundaries page — Data & Boundaries
Inspect data classifications and trust boundaries across the model.
Open full size

GuardLink dashboard asset heatmap page — Asset Heatmap
Spot the riskiest assets by exposure density, mitigations, and flow activity.
Open full size

GuardLink dashboard data flow diagram page — Data Flow Diagram
Mermaid-generated service and data movement view from `@flows` and boundaries.
Open full size

GuardLink dashboard threat graph page — Threat Graph
Visualize how threats, assets, and controls connect in the live model.
Open full size

Sample Dashboard HTML

GuardLink emits a single self-contained threat-dashboard.html artifact. The docs keep one embedded live demo in the diagrams section; use the standalone link below when you want the full-screen version.

Open standalone live threat report

Run guardlink dashboard [dir] to generate this file. The docs host the copied artifact at /guardlink-examples/threat-dashboard.html.

Diagram Types

GuardLink auto-generates 4 diagram views directly from your annotations — no manual diagramming required. Each view uses Mermaid rendering and is available in the interactive dashboard. The sections below show real dashboard output and captured screenshots.

Live Diagram Explorer

The real generated dashboard, opened directly on the detailed diagrams page. Use the tabs inside the frame to switch between threat graph, data flow, and attack surface.

Threat graph Data flow Attack surface

Detailed Diagram Explorer

This embed uses the copied GuardLink dashboard artifact from `public`, so the docs show the exact generated HTML rather than a separate docs-only renderer.

Open standalone

1. Data Flow Diagram

Generated from @flows and @boundary annotations. The screenshot below is taken from the real dashboard diagrams view.

Sources@flows, @boundary, @handles

LayoutLeft-to-Right (LR)

Used InDashboard, Report

GuardLink detailed data flow diagram in the dashboard — Detailed Data Flow Diagram
The real dashboard renders trust zones, data movement, and boundary labels directly from your parsed model.
Open full size

NODE SHAPES

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

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

["name"] Processes (api, service)

Open live data flow view

2. Threat Model Graph

Generated from @exposes, @mitigates, and @control annotations. This section now uses the captured dashboard output so the graph is always detailed and stable.

Sources@exposes, @mitigates, @control

LayoutLeft-to-Right (LR)

Used InDashboard

GuardLink detailed threat graph in the dashboard — Detailed Threat Graph
Threats, assets, controls, and mitigations remain connected in one detailed graph instead of a simplified docs-only preview.
Open full size

EDGE TYPES

-. exposed .-> Vulnerability

-- mitigates --> Defense

-.- Control applied to asset

Open live threat graph

3. Attack Surface Map

Generated from @exposes annotations. This view stays most useful as a live dashboard panel because the attack-surface counts, tabs, and rendering remain interactive.

Sources@exposes, @mitigates, @accepts

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

Used InDashboard

Detailed Attack Surface View

Open exposures are grouped by asset with severity and mitigation state already computed by the generated dashboard.

Open standalone

4. Detailed Architecture Context

GuardLink's architectural story is best read from the real dashboard surfaces rather than a docs-only Mermaid clone. Use the Data & Boundaries screenshot and jump into the live dashboard for the full summary and supporting views.

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

LayoutTop-Down (TD)

Used InMarkdown Report

GuardLink data and boundaries dashboard page — Data & Boundaries View
Use this alongside the live summary page to understand where sensitive data lives and which boundaries segment the model.
Open full size

Open live data & boundaries view

SMART NODE DETECTION

Report architecture views still use GuardLink's smart node detection rules:

[("...")] 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)

Open live summary

View the detailed top-level threat model output in the real dashboard artifact.

Open code browser

Correlate architectural views with the exact annotations and files that produced them.

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 with 14 tools that give AI coding agents full access to your threat model — parse, validate, suggest annotations, generate reports, and manage governance. When your agent writes security-relevant code, it adds annotations automatically.

MCP Tools

guardlink_parseFull threat model as JSON

guardlink_statusCoverage summary and risk grade

guardlink_validateSyntax errors and dangling refs

guardlink_diffCompare between git refs

guardlink_suggestSuggest annotations for code

guardlink_annotateBuild annotation prompts

guardlink_lookupQuery threats, controls, flows

guardlink_threat_reportAI threat analysis

guardlink_reportGenerate markdown report

guardlink_dashboardGenerate HTML dashboard

guardlink_sarifExport SARIF 2.1.0

guardlink_review_listList reviewable exposures

guardlink_review_acceptAccept risk with justification

guardlink_workspace_infoWorkspace and sibling context

Supported Agents

Agent	Config File	MCP	Mode
Claude Code	CLAUDE.md + .mcp.json	Full	CLI + MCP
Cursor	.cursorrules + .cursor/mcp.json	Full	IDE + MCP
Windsurf	.windsurfrules + .windsurf/mcp.json	Full	IDE + MCP
Cline	.clinerules + .cline/mcp.json	Full	CLI + MCP
Codex	AGENTS.md	No	Directive only
GitHub Copilot	copilot-instructions.md	No	Directive only

Automated Maintenance

Behavioral directives injected by guardlink init instruct agents to add @exposes, @mitigates, and @flows annotations whenever they write routes, auth logic, database access, or external service calls. The guardlink sync command keeps these directives current with the latest threat model.

@shield Enforcement

Mark sensitive code blocks with @shield to exclude them from AI agent context entirely. Use single-line @shield for a function, or @shield:begin / @shield:end for larger blocks of proprietary or cryptographic logic.

MCP Configuration

// .mcp.json (or .cursor/mcp.json, .windsurf/mcp.json)

{

"mcpServers": {

"guardlink": {

"command": "guardlink",

"args": ["mcp"]

}

This is auto-generated by guardlink init. Run guardlink mcp manually to start the MCP server on stdio.

CI/CD Pipelines

Threat modeling is only effective if enforced. GuardLink provides three CI integration points: validation gates that catch regressions, threat model diffs that block PRs with new unmitigated exposures, and SARIF export for GitHub Advanced Security integration.

# Validate annotations — syntax, dangling refs, unmitigated exposures

guardlink validate .

# Block PRs with new unmitigated exposures

guardlink diff --fail-on-new

# Export for GitHub code scanning

guardlink sarif . -o guardlink.sarif

GUARDLINK DIFF

Compares threat models between Git refs to catch security regressions

Removed DefenseFAIL

New Unmitigated ExposureWARN

Added MitigationPASS

Workspace Merge & DiffWEEKLY

SARIF 2.1.0 Export

Export unmitigated exposures as SARIF for GitHub Advanced Security, VS Code, and SonarQube. Includes file, line, severity, and CWE/OWASP references. Filter with --min-severity.

Workspace Workflows

For microservice architectures, use workspace-merge.yml to aggregate per-repo reports into a unified dashboard. Weekly diff tracking via --diff-against surfaces risk trends across services.

Example CI Workflows

Per-PR Validation

Validate, diff, upload SARIF, and comment on the PR with threat model changes.

Per-Repo Report

On push to main: generate report JSON artifact for merge and archival.

Workspace Merge

Weekly: download all repo artifacts, merge, diff, publish dashboard.

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