guardlink 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to GuardLink CLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] — 2026-02-21
+
+### Added
+
+- **Validation**: Shared `findDanglingRefs` and `findUnmitigatedExposures` with consistent `#id`/bare-name normalization across CLI, TUI, and MCP
+- **Validation**: Expanded dangling ref checks to cover `@flows`, `@boundary`, `@audit`, `@owns`, `@handles`, `@assumes` annotations
+- **Diagrams**: Threat graph now renders `@transfers`, `@validates`, trust boundaries, data classifications, ownership, and CWE references
+- **Diagrams**: Heuristic icons for assets (👤 user, 🖥️ service, 🗄️ database) and flow mechanisms (🔐 TLS, 🌐 HTTP, 📨 queue)
+- **Prompts**: Flow-first threat modeling methodology with architecture mapping, trust boundary identification, and coupled annotation style guide
+- **Prompts**: Agent context now includes existing data flows and unmitigated exposures for smarter annotation
+- **Model**: Two-step `/model` configuration — CLI Agents (Claude Code, Codex, Gemini) or API providers
+- **Tests**: Dashboard diagram generation tests (label sanitization, severity resolution, transfers, validations)
+- **Tests**: Parser regression tests (`@flows` via + description, `@shield` vs `@shield:begin` disambiguation)
+- **Tests**: Validation unit tests (dangling refs, unmitigated exposure matching with ref normalization)
+- **README**: Manual installation instructions (build from source + npm link)
+
+### Fixed
+
+- **Parser**: `@flows` regex no longer swallows description when `via` mechanism is present
+- **Parser**: `@shield` no longer incorrectly matches `@shield:begin` and `@shield:end`
+- **Validation**: `#id` and bare-name refs now compare correctly (e.g., `#sqli` matches `sqli` in mitigations)
+
+### Removed
+
+- **TUI**: `/scan` command — redundant with `/status` coverage display; AI-driven annotation replaces manual symbol discovery
+- **TUI**: `/exposures` and `/show` commands — exposure data remains accessible via `/validate`, MCP `guardlink_status`, and `guardlink://unmitigated` resource
+- **Dependencies**: Removed accidental `build` package (unused)
+
 ## [1.0.0] — 2026-02-21
 
 Initial public release of GuardLink.

package/README.md

@@ -35,6 +35,20 @@ npm install -g guardlink
 
 Requires Node.js 18+.
 
+### Manual Installation
+
+To install from source:
+
+```bash
+# 1. Build the project
+npm run build
+
+# 2. Link globally
+npm link
+```
+
+To uninstall: `npm unlink -g guardlink`
+
 ## Quick Start
 
 ```bash

package/dist/agents/config.d.ts

@@ -15,6 +15,8 @@ interface SavedConfig {
     provider?: LLMProvider;
     model?: string;
     apiKey?: string;
+    aiMode?: 'cli-agent' | 'api';
+    cliAgent?: string;
 }
 /**
  * Resolve LLM configuration using the unified priority chain.

package/dist/agents/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/agents/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhE,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAgDD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,SAAS,GAAG,IAAI,CAmDlB;AAiCD,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAEtE;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAEvD;AAED,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAGlE;AAED,yBAAyB;AACzB,wBAAgB,gBAAgB,IAAI,WAAW,GAAG,IAAI,CAErD;AAID,uDAAuD;AACvD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED,iDAAiD;AACjD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,MAAM,CAcR"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/agents/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhE,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgDD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,SAAS,GAAG,IAAI,CAmDlB;AAiCD,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAEtE;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAEvD;AAED,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAGlE;AAED,yBAAyB;AACzB,wBAAgB,gBAAgB,IAAI,WAAW,GAAG,IAAI,CAErD;AAID,uDAAuD;AACvD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED,iDAAiD;AACjD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,MAAM,CAcR"}

package/dist/agents/config.js

@@ -176,7 +176,7 @@ export function describeConfigSource(root, flags) {
     if (process.env.DEEPSEEK_API_KEY)
         return 'DEEPSEEK_API_KEY env var';
     const pc = readJsonFile(projectConfigPath(root));
-    if (pc && Object.keys(pc).length > 0 && pc.provider)
+    if (pc && Object.keys(pc).length > 0 && (pc.provider || pc.aiMode))
         return `.guardlink/${CONFIG_FILE}`;
     const lc = readJsonFile(legacyConfigPath(root));
     if (lc && Object.keys(lc).length > 0 && lc.provider)

package/dist/agents/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/agents/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/agents/config.ts"],"names":[],"mappings":"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"}

package/dist/agents/prompts.d.ts

@@ -7,8 +7,8 @@ import type { ThreatModel } from '../types/index.js';
 /**
  * Build a prompt for annotation agents.
  *
- * Includes the GuardLink reference doc (truncated), current model summary,
- * user instructions, and precise GAL syntax rules with common pitfalls.
+ * Includes the GuardLink reference doc, current model summary with flows and exposures,
+ * flow-first threat modeling methodology, and precise GAL syntax rules.
  */
 export declare function buildAnnotatePrompt(userPrompt: string, root: string, model: ThreatModel | null): string;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/agents/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/agents/prompts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GAAG,IAAI,GACxB,MAAM,CAyGR"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/agents/prompts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GAAG,IAAI,GACxB,MAAM,CA6SR"}

package/dist/agents/prompts.js

@@ -8,8 +8,8 @@ import { resolve } from 'node:path';
 /**
  * Build a prompt for annotation agents.
  *
- * Includes the GuardLink reference doc (truncated), current model summary,
- * user instructions, and precise GAL syntax rules with common pitfalls.
+ * Includes the GuardLink reference doc, current model summary with flows and exposures,
+ * flow-first threat modeling methodology, and precise GAL syntax rules.
  */
 export function buildAnnotatePrompt(userPrompt, root, model) {
     // Read the reference doc if available
@@ -18,8 +18,17 @@ export function buildAnnotatePrompt(userPrompt, root, model) {
     if (existsSync(refPath)) {
         refDoc = readFileSync(refPath, 'utf-8');
     }
-    let modelSummary = 'No threat model parsed yet. Run `guardlink parse` after annotating.';
+    // Fall back to docs/GUARDLINK_REFERENCE.md
+    if (!refDoc) {
+        const docsRefPath = resolve(root, 'docs', 'GUARDLINK_REFERENCE.md');
+        if (existsSync(docsRefPath)) {
+            refDoc = readFileSync(docsRefPath, 'utf-8');
+        }
+    }
+    let modelSummary = 'No threat model parsed yet. This may be a fresh project — define assets, threats, and controls first.';
     let existingIds = '';
+    let existingFlows = '';
+    let existingExposures = '';
     if (model) {
         const parts = [
             `${model.annotations_parsed} annotations`,
@@ -28,6 +37,8 @@ export function buildAnnotatePrompt(userPrompt, root, model) {
             `${model.threats.length} threats`,
             `${model.controls.length} controls`,
             `${model.mitigations.length} mitigations`,
+            `${model.flows.length} flows`,
+            `${model.boundaries.length} boundaries`,
         ];
         modelSummary = `Current model: ${parts.join(', ')}.`;
         // Include existing IDs so the agent doesn't create duplicates or dangling refs
@@ -36,45 +47,208 @@ export function buildAnnotatePrompt(userPrompt, root, model) {
         const controlIds = model.controls.filter(c => c.id).map(c => `#${c.id}`);
         if (threatIds.length + assetIds.length + controlIds.length > 0) {
             const sections = [];
-            if (threatIds.length)
-                sections.push(`Threats: ${threatIds.join(', ')}`);
             if (assetIds.length)
                 sections.push(`Assets: ${assetIds.join(', ')}`);
+            if (threatIds.length)
+                sections.push(`Threats: ${threatIds.join(', ')}`);
             if (controlIds.length)
                 sections.push(`Controls: ${controlIds.join(', ')}`);
-            existingIds = `\n\nExisting defined IDs (use these in @exposes, @mitigates, etc.):\n${sections.join('\n')}`;
+            existingIds = `\n\nExisting defined IDs (REUSE these — do NOT redefine):\n${sections.join('\n')}`;
+        }
+        // Include existing flows so agent understands the current flow graph
+        if (model.flows.length > 0) {
+            const flowLines = model.flows.slice(0, 30).map(f => `  ${f.source} -> ${f.target}${f.mechanism ? ` via ${f.mechanism}` : ''} (${f.location.file}:${f.location.line})`);
+            existingFlows = `\n\nExisting data flows (extend these, don't duplicate):\n${flowLines.join('\n')}`;
+            if (model.flows.length > 30)
+                existingFlows += `\n  ... and ${model.flows.length - 30} more`;
+        }
+        // Include unmitigated exposures so agent knows what still needs attention
+        const unmitigatedExposures = model.exposures.filter(e => {
+            return !model.mitigations.some(m => m.asset === e.asset && m.threat === e.threat)
+                && !model.acceptances.some(a => a.asset === e.asset && a.threat === e.threat);
+        });
+        if (unmitigatedExposures.length > 0) {
+            const expLines = unmitigatedExposures.slice(0, 20).map(e => `  ${e.asset} exposed to ${e.threat} [${e.severity || 'unrated'}] (${e.location.file}:${e.location.line})`);
+            existingExposures = `\n\nOpen exposures (unmitigated — add @mitigates or @accepts for these):\n${expLines.join('\n')}`;
+            if (unmitigatedExposures.length > 20)
+                existingExposures += `\n  ... and ${unmitigatedExposures.length - 20} more`;
         }
     }
-    return `You are annotating a codebase with GuardLink security annotations.
+    return `You are an expert security engineer performing threat modeling as code.
+Your job is to read this codebase deeply, understand how code flows between components, and annotate it with GuardLink (GAL) security annotations that accurately represent the security posture.
+
+This is NOT a vulnerability scanner. You are building a living threat model embedded in the code itself.
+Annotations capture what COULD go wrong, what controls exist, and how data moves — not just confirmed bugs.
 
-${refDoc ? '## GuardLink Reference\n\n' + refDoc.slice(0, 4000) + '\n\n' : ''}## Current State
-${modelSummary}${existingIds}
+${refDoc ? '## GuardLink Annotation Language Reference\n\n' + refDoc.slice(0, 4000) + '\n\n' : ''}## Current State
+${modelSummary}${existingIds}${existingFlows}${existingExposures}
 
-## Task
+## Your Task
 ${userPrompt}
 
-## PRECISE Annotation Syntax (follow EXACTLY)
+## HOW TO THINK — Flow-First Threat Modeling
+
+Before writing ANY annotation, you MUST understand the code deeply:
+
+### Step 1: Map the Architecture
+Read ALL source files related to the area you're annotating. Trace:
+- Entry points (HTTP handlers, CLI commands, message consumers, event listeners)
+- Data paths (how user input flows through functions, classes, middleware, to storage or output)
+- Exit points (database writes, API calls, file I/O, rendered templates, responses)
+- Class hierarchies, inherited methods, shared utilities, middleware chains
+- Configuration and environment variable usage
+
+### Step 2: Identify Trust Boundaries
+Look for where trust changes:
+- External user → application code (HTTP boundary)
+- Application → database (data layer boundary)
+- Service → service (network boundary)
+- Frontend → backend (client/server boundary)
+- Application → third-party API (vendor boundary)
+- Internal code → spawned process (process boundary)
+
+### Step 3: Identify What Could Go Wrong
+At each boundary crossing and data transformation, ask:
+- What if this input is malicious? (@exposes)
+- What validation/sanitization exists? (@mitigates)
+- What sensitive data passes through here? (@handles)
+- Is there an assumption that could be violated? (@assumes)
+- Has the team accepted this risk intentionally? (@accepts)
+- Is this risk handled by someone else? (@transfers)
+
+### Step 4: Write Coupled Annotation Blocks
+NEVER write a single annotation in isolation. Every annotated location should tell a complete story.
+
+## ANNOTATION STYLE GUIDE — Write Like a Developer
+
+### Always Couple Annotations Together
+A file's doc-block should paint the full security picture of that module. Group annotations logically:
+
+\`\`\`
+// @shield:begin -- "Example annotation block for reference, excluded from parsing"
+//
+// GOOD — Complete story at a single code location:
+// @exposes #auth-api to #sqli [P1] cwe:CWE-89 -- "User-supplied email passed to findUser() query builder"
+// @mitigates #auth-api against #sqli using #input-validation -- "Zod schema validates email format before query"
+// @flows User_Input -> #auth-api via POST./login -- "Login form submits credentials"
+// @flows #auth-api -> #user-db via TypeORM.findOne -- "Authenticated user lookup"
+// @handles pii on #auth-api -- "Processes email, password, session tokens"
+// @comment -- "Password comparison uses bcrypt.compare with timing-safe equality"
+//
+// BAD — Isolated annotation with no context:
+// @exposes #auth-api to #sqli -- "SQL injection possible"
+//
+// @shield:end
+\`\`\`
+
+### Description Style — Reference Actual Code
+Descriptions must reference the real code: function names, variable names, libraries, mechanisms.
+
+\`\`\`
+// @shield:begin -- "Description examples, excluded from parsing"
+//
+// GOOD: -- "req.body.token passed to jwt.verify() without audience check"
+// GOOD: -- "bcrypt rounds set to 12 via BCRYPT_COST env var"
+// GOOD: -- "Rate limiter uses express-rate-limit at 100req/15min on /api/*"
+//
+// BAD:  -- "Input not validated"             (too vague — WHICH input? WHERE?)
+// BAD:  -- "Uses encryption"                 (WHAT encryption? On WHAT data?)
+// BAD:  -- "Security vulnerability exists"   (meaningless — be specific)
+//
+// @shield:end
+\`\`\`
+
+### @flows — Stitch the Complete Data Path
+@flows is the backbone of the threat model. Trace data movement accurately:
+
+\`\`\`
+// @shield:begin -- "Flow examples, excluded from parsing"
+//
+// Trace a request through the full stack:
+// @flows User_Browser -> #api-gateway via HTTPS -- "Client sends auth request"
+// @flows #api-gateway -> #auth-service via internal.gRPC -- "Gateway forwards to auth microservice"
+// @flows #auth-service -> #user-db via pg.query -- "Looks up user record by email"
+// @flows #auth-service -> #session-store via redis.set -- "Stores session token with TTL"
+// @flows #auth-service -> User_Browser via Set-Cookie -- "Returns session cookie to client"
+//
+// @shield:end
+\`\`\`
+
+### @boundary — Mark Every Trust Zone Crossing
+Place @boundary annotations where trust level changes between two components:
+
+\`\`\`
+// @shield:begin -- "Boundary examples, excluded from parsing"
+//
+// @boundary between #api-gateway and External_Internet (#public-boundary) -- "TLS termination, rate limiting at edge"
+// @boundary between #backend and #database (#data-boundary) -- "Application to persistence layer, connection pooling via pgBouncer"
+// @boundary between #app and #payment-provider (#vendor-boundary) -- "PCI-DSS scope boundary, tokenized card data only"
+//
+// @shield:end
+\`\`\`
 
-Definitions go in .guardlink/definitions.js (or .py/.rs). Source files use only relationship verbs.
+### Where to Place Annotations
+Annotations go in the file's top doc-block comment OR directly above the security-relevant code:
 
-### Definitions
 \`\`\`
-// @shield:begin -- "Example annotations for agent prompt, excluded from parsing"
-// @asset Server.Auth (#auth) -- "Authentication service"
-// @threat SQL_Injection (#sqli) [P0] cwe:CWE-89 -- "Unsanitized input in SQL"
-// @control Prepared_Statements (#prepared-stmts) -- "Parameterized queries"
+// @shield:begin -- "Placement examples, excluded from parsing"
+//
+// FILE-LEVEL (top doc-block) — for module-wide security properties:
+// Place @exposes, @mitigates, @flows, @handles, @boundary that describe the module as a whole
+//
+// INLINE (above specific functions/methods) — for function-specific concerns:
+// Place @exposes, @mitigates above the exact function where the risk or control lives
+// Place @comment above tricky security-relevant code to explain intent
+//
 // @shield:end
 \`\`\`
 
-### Relationships (use in source files)
+### Severity — Be Honest, Not Alarmist
+Annotations capture what COULD go wrong, calibrated to realistic risk:
+- **[P0] / [critical]**: Directly exploitable by external attacker, severe impact (RCE, auth bypass, data breach)
+- **[P1] / [high]**: Exploitable with some conditions, significant impact (privilege escalation, data leak)
+- **[P2] / [medium]**: Requires specific conditions or insider access (SSRF, info disclosure)
+- **[P3] / [low]**: Minor impact or very difficult to exploit (timing side-channels, verbose errors)
+
+Don't rate everything P0. A SQL injection in an admin-only internal tool is different from one in a public API.
+
+### @comment — Always Add Context
+Every annotation block should include at least one @comment explaining non-obvious security decisions, assumptions, or context that helps future developers (and AI tools) understand the "why".
+
+### @shield — DO NOT USE Unless Explicitly Asked
+@shield and @shield:begin/@shield:end block AI coding assistants from reading the annotated code.
+This means any shielded code becomes invisible to AI tools — they cannot analyze, refactor, or annotate it.
+Do NOT add @shield annotations unless the user has EXPLICITLY requested it (e.g., "shield the crypto module").
+Adding @shield on your own initiative would actively harm the threat model by creating blind spots where AI cannot help.
+
+## PRECISE GAL Syntax
+
+Definitions go in .guardlink/definitions.{ts,js,py,rs}. Source files use only relationship verbs.
+
+### Definitions (in .guardlink/definitions file)
 \`\`\`
-// @shield:begin -- "Example annotations for agent prompt, excluded from parsing"
+// @shield:begin -- "Definition syntax examples, excluded from parsing"
+// @asset Server.Auth (#auth) -- "Authentication service handling login and session management"
+// @threat SQL_Injection (#sqli) [P0] cwe:CWE-89 -- "Unsanitized input reaches SQL query builder"
+// @control Prepared_Statements (#prepared-stmts) -- "Parameterized queries via ORM or driver placeholders"
+// @shield:end
+\`\`\`
+
+### Relationships (in source files)
+\`\`\`
+// @shield:begin -- "Relationship syntax examples, excluded from parsing"
 // @exposes #auth to #sqli [P0] cwe:CWE-89 owasp:A03:2021 -- "User input concatenated into query"
-// @mitigates #auth against #sqli using #prepared-stmts -- "Uses parameterized queries"
+// @mitigates #auth against #sqli using #prepared-stmts -- "Uses parameterized queries via sqlx"
+// @accepts #timing-attack on #auth -- "Acceptable given bcrypt constant-time comparison"
+// @transfers #ddos from #api to #cdn -- "Cloudflare handles L7 DDoS mitigation"
 // @flows req.body.username -> db.query via string-concat -- "User input flows to SQL"
-// @boundary between #frontend and #api (#trust-boundary) -- "Public/private boundary"
-// @handles pii on #auth -- "Processes user credentials"
-// @comment -- "TODO: add rate limiting to prevent brute force"
+// @boundary between #frontend and #api (#web-boundary) -- "TLS-terminated public/private boundary"
+// @handles pii on #auth -- "Processes email, password, session tokens"
+// @validates #prepared-stmts for #auth -- "Integration test sqlInjectionTest.ts confirms parameterized queries block SQLi payloads"
+// @audit #auth -- "Session token rotation logic needs cryptographic review"
+// @assumes #auth -- "Upstream API gateway has already validated TLS and rate-limited requests"
+// @owns security-team for #auth -- "Security team reviews all auth PRs"
+// @comment -- "Password hashing uses bcrypt with cost factor 12, migration from SHA256 completed in v2.1"
 // @shield:end
 \`\`\`
 
@@ -84,13 +258,13 @@ Definitions go in .guardlink/definitions.js (or .py/.rs). Source files use only
    WRONG: \`@boundary api -- "desc"\`  (only one argument — will NOT parse)
    RIGHT: \`@boundary between #api and #client (#api-boundary) -- "Trust boundary"\`
 
-2. **@flows is ONE source → ONE target per line**: \`@flows <source> -> <target> via <mechanism>\`.
+2. **@flows is ONE source -> ONE target per line**: \`@flows <source> -> <target> via <mechanism>\`.
    WRONG: \`@flows A -> B, C -> D -- "desc"\`  (commas not supported)
    RIGHT: \`@flows A -> B via mechanism -- "desc"\` (one per line, repeat for multiple)
 
 3. **@exposes / @mitigates require DEFINED #id refs**: Every \`#id\` you reference must exist as a definition.
    Before using \`@exposes #app to #sqli\`, ensure \`@threat SQL_Injection (#sqli)\` exists in definitions.
-   Add new definitions to .guardlink/definitions.js FIRST, then reference them in source files.
+   Add new definitions to the .guardlink/definitions file FIRST, then reference them in source files.
 
 4. **Severity in square brackets**: \`[P0]\` \`[P1]\` \`[P2]\` \`[P3]\` or \`[critical]\` \`[high]\` \`[medium]\` \`[low]\`.
    Goes AFTER the threat ref in @exposes: \`@exposes #app to #sqli [P0] cwe:CWE-89\`
@@ -108,13 +282,31 @@ Definitions go in .guardlink/definitions.js (or .py/.rs). Source files use only
 
 8. **External refs are space-separated after severity**: \`cwe:CWE-89 owasp:A03:2021 capec:CAPEC-66\`
 
+9. **@comment always needs -- and quotes**: \`@comment -- "your note here"\`.
+   A bare \`@comment\` without description is valid but useless. Always include context.
+
+10. **One annotation per comment line.** Do NOT put two @verbs on the same line.
+
 ## Workflow
-1. Read existing definitions in .guardlink/definitions.js — reuse existing IDs
-2. Add any NEW threat/control definitions FIRST
-3. Then add relationship annotations (@exposes, @mitigates, @flows, etc.) in source files
-4. Use the project's comment style (// for JS/TS, # for Python, etc.)
-5. Run guardlink_validate (MCP) or \`guardlink validate\` to check for errors
-6. Fix any validation errors before finishing
+
+1. **Read first, annotate second.** Read ALL related source files before writing any annotation.
+   Trace the full call chain: entry point → middleware → handler → service → repository → database.
+   Understand class hierarchies, shared utilities, and configuration.
+
+2. **Read existing definitions** in the .guardlink/definitions file — reuse existing IDs, never duplicate.
+
+3. **Add NEW definitions FIRST** if you need new assets, threats, or controls.
+   Group related definitions together with section comments.
+
+4. **Annotate in coupled blocks.** For each security-relevant location, write the complete story:
+   @exposes + @mitigates (or @accepts) + @flows + @comment at minimum.
+   Think: "what's the risk, what's the defense, how does data flow here, and what should the next developer know?"
+
+5. **Use the project's comment style** (// for JS/TS/Go/Rust, # for Python/Ruby/Shell, etc.)
+
+6. **Run validation** via guardlink_validate (MCP) or \`guardlink validate\` to check for errors.
+
+7. **Fix any validation errors** before finishing — especially dangling refs and malformed syntax.
 `;
 }
 //# sourceMappingURL=prompts.js.map

package/dist/agents/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/agents/prompts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/agents/prompts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAkB,EAClB,IAAY,EACZ,KAAyB;IAEzB,sCAAsC;IACtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,wBAAwB,CAAC,CAAC;IACtE,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IACD,2CAA2C;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,wBAAwB,CAAC,CAAC;QACpE,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5B,MAAM,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,IAAI,YAAY,GAAG,uGAAuG,CAAC;IAC3H,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,aAAa,GAAG,EAAE,CAAC;IACvB,IAAI,iBAAiB,GAAG,EAAE,CAAC;IAC3B,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,KAAK,GAAG;YACZ,GAAG,KAAK,CAAC,kBAAkB,cAAc;YACzC,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,YAAY;YACrC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,SAAS;YAC/B,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,UAAU;YACjC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,WAAW;YACnC,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,cAAc;YACzC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,QAAQ;YAC7B,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,aAAa;SACxC,CAAC;QACF,YAAY,GAAG,kBAAkB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAErD,+EAA+E;QAC/E,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACrE,MAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzE,IAAI,SAAS,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/D,MAAM,QAAQ,GAAa,EAAE,CAAC;YAC9B,IAAI,QAAQ,CAAC,MAAM;gBAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrE,IAAI,SAAS,CAAC,MAAM;gBAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxE,IAAI,UAAU,CAAC,MAAM;gBAAE,QAAQ,CAAC,IAAI,CAAC,aAAa,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3E,WAAW,GAAG,8DAA8D,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpG,CAAC;QAED,qEAAqE;QACrE,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CACjD,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,GAAG,CAClH,CAAC;YACF,aAAa,GAAG,6DAA6D,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACpG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE;gBAAE,aAAa,IAAI,eAAe,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC;QAC9F,CAAC;QAED,0EAA0E;QAC1E,MAAM,oBAAoB,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;YACtD,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC;mBAC5E,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC;QACH,IAAI,oBAAoB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CACzD,KAAK,CAAC,CAAC,KAAK,eAAe,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,QAAQ,IAAI,SAAS,MAAM,CAAC,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,GAAG,CAC3G,CAAC;YACF,iBAAiB,GAAG,6EAA6E,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvH,IAAI,oBAAoB,CAAC,MAAM,GAAG,EAAE;gBAAE,iBAAiB,IAAI,eAAe,oBAAoB,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC;QACpH,CAAC;IACH,CAAC;IAED,OAAO;;;;;;EAMP,MAAM,CAAC,CAAC,CAAC,gDAAgD,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE;EAC/F,YAAY,GAAG,WAAW,GAAG,aAAa,GAAG,iBAAiB;;;EAG9D,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+NX,CAAC;AACF,CAAC"}

package/dist/analyzer/sarif.js

@@ -120,7 +120,7 @@ export function generateSarif(model, diagnostics = [], danglingRefs = [], option
                 tool: {
                     driver: {
                         name: 'GuardLink',
-                        version: '1.0.0',
+                        version: '1.1.0',
                         informationUri: 'https://guardlink.bugb.io',
                         rules: RULES,
                     },

package/dist/cli/index.js

@@ -24,7 +24,7 @@
 import { Command } from 'commander';
 import { resolve, basename } from 'node:path';
 import { readFileSync, existsSync } from 'node:fs';
-import { parseProject } from '../parser/index.js';
+import { parseProject, findDanglingRefs, findUnmitigatedExposures } from '../parser/index.js';
 import { initProject, detectProject, promptAgentSelection } from '../init/index.js';
 import { generateReport, generateMermaid } from '../report/index.js';
 import { diffModels, formatDiff, formatDiffMarkdown, parseAtRef } from '../diff/index.js';
@@ -80,7 +80,7 @@ function detectProjectName(root, explicit) {
 program
     .name('guardlink')
     .description('GuardLink — Security annotations for code. Threat modeling that lives in your codebase.')
-    .version('1.0.0')
+    .version('1.1.0')
     .addHelpText('before', gradient(['#00ff41', '#00d4ff'])(ASCII_LOGO));
 // ─── init ────────────────────────────────────────────────────────────
 program
@@ -764,58 +764,4 @@ function printStatus(model) {
     console.log(`Comments:         ${model.comments.length}`);
     console.log(`Shields:          ${model.shields.length}`);
 }
-function findDanglingRefs(model) {
-    const diagnostics = [];
-    // Collect all defined IDs
-    const definedIds = new Set();
-    for (const a of model.assets)
-        if (a.id)
-            definedIds.add(a.id);
-    for (const t of model.threats)
-        if (t.id)
-            definedIds.add(t.id);
-    for (const c of model.controls)
-        if (c.id)
-            definedIds.add(c.id);
-    for (const b of model.boundaries)
-        if (b.id)
-            definedIds.add(b.id);
-    // Check all references
-    const checkRef = (ref, loc) => {
-        if (ref.startsWith('#')) {
-            const id = ref.slice(1);
-            if (!definedIds.has(id)) {
-                diagnostics.push({
-                    level: 'warning',
-                    message: `Dangling reference: #${id} is never defined`,
-                    file: loc.file,
-                    line: loc.line,
-                });
-            }
-        }
-    };
-    for (const m of model.mitigations) {
-        checkRef(m.threat, m.location);
-        if (m.control)
-            checkRef(m.control, m.location);
-    }
-    for (const e of model.exposures)
-        checkRef(e.threat, e.location);
-    for (const a of model.acceptances)
-        checkRef(a.threat, a.location);
-    for (const t of model.transfers)
-        checkRef(t.threat, t.location);
-    for (const v of model.validations)
-        checkRef(v.control, v.location);
-    return diagnostics;
-}
-function findUnmitigatedExposures(model) {
-    // Build set of (asset, threat) pairs that are mitigated or accepted
-    const mitigated = new Set();
-    for (const m of model.mitigations)
-        mitigated.add(`${m.asset}::${m.threat}`);
-    for (const a of model.acceptances)
-        mitigated.add(`${a.asset}::${a.threat}`);
-    return model.exposures.filter(e => !mitigated.has(`${e.asset}::${e.threat}`));
-}
 //# sourceMappingURL=index.js.map