GuardLink Security Annotations

<!-- guardlink:begin -->
# GuardLink Security Annotations

This project uses GuardLink annotations in source code comments.

## Core Requirement
Every time you write or modify code that touches security-relevant behavior, you MUST add GuardLink annotations in the same change. This includes: new endpoints, auth logic, data validation, database queries, file I/O, external API calls, crypto, process spawning, user input handling, config parsing. Do NOT annotate pure business logic, formatting utilities, UI components, or helpers that never touch security boundaries.

## Key Rules
- ANNOTATE NEW CODE. When you add a function or endpoint that handles user input, accesses data, or crosses a trust boundary — add @exposes, @mitigates, @flows, @handles, or at minimum @comment. This is not optional.
- NEVER write @accepts — that is a human-only governance decision. For risks with no mitigation: write @exposes + @audit + @comment suggesting potential controls.
- Preserve existing annotations — do not delete or mangle them.
- Definitions (@asset, @threat, @control with (#id)) live in .guardlink/definitions.ts. Reuse IDs — never redefine. Add new definitions there first, then reference in source files.
- Source files use relationship verbs: @mitigates, @exposes, @flows, @handles, @boundary, @comment, @validates, @audit, @owns, @assumes, @transfers.
- Write coupled annotation blocks: risk + control (or audit) + data flow + context note.
- Avoid @shield unless a human explicitly asks to hide code from AI.

## Workflow
- Before writing code: skim .guardlink/definitions.ts to understand existing IDs.
- While writing code: add annotations as you write, not as a separate pass afterward.
- After changes: run `guardlink validate .` and `guardlink status .`.
- After adding annotations: run `guardlink sync` to update all agent instruction files with current threat model context.

## Quick Syntax
- @exposes App.API to #sqli [P0] cwe:CWE-89 -- "req.body.email concatenated into SQL"
- @mitigates App.API against #sqli using #prepared-stmts -- "Parameterized queries via pg"
- @audit App.API -- "Timing attack risk — needs human review"
- @flows User -> App.API via HTTPS -- "Login request"
- @boundary between #api and #db (#data-boundary) -- "Trust change"
- @handles pii on App.API -- "Processes email, token"
- @validates #prepared-stmts for App.API -- "CI test ensures placeholders"
- @audit App.API -- "Token rotation review"
- @owns security-team for App.API -- "Team responsible"
- @comment -- "Rate limit: 100 req/15min"

## Live Threat Model Context (auto-synced by `guardlink sync`)

### Current Definitions (REUSE these IDs — do NOT redefine)

**Assets:** #parser (GuardLink,Parser), #cli (GuardLink,CLI), #tui (GuardLink,TUI), #mcp (GuardLink,MCP), #llm-client (GuardLink,LLM_Client), #dashboard (GuardLink,Dashboard), #init (GuardLink,Init), #agent-launcher (GuardLink,Agent_Launcher), #diff (GuardLink,Diff), #report (GuardLink,Report), #sarif (GuardLink,SARIF), #suggest (GuardLink,Suggest), #workspace-link (Workspace,Link), #merge-engine (Workspace,Merge), #report-metadata (Workspace,Metadata), #workspace-config (Workspace,Config)
**Threats:** #path-traversal (Path_Traversal) [high], #cmd-injection (Command_Injection) [critical], #xss (Cross_Site_Scripting) [high], #api-key-exposure (API_Key_Exposure) [high], #ssrf (Server_Side_Request_Forgery) [medium], #redos (ReDoS) [medium], #arbitrary-write (Arbitrary_File_Write) [high], #prompt-injection (Prompt_Injection) [medium], #dos (Denial_of_Service) [medium], #data-exposure (Sensitive_Data_Exposure) [medium], #insecure-deser (Insecure_Deserialization) [medium], #child-proc-injection (Child_Process_Injection) [high], #info-disclosure (Information_Disclosure) [low], #tag-collision (Tag_Collision) [medium], #config-tamper (Config_Tampering) [medium]
**Controls:** #path-validation (Path_Validation), #input-sanitize (Input_Sanitization), #output-encoding (Output_Encoding), #key-redaction (Key_Redaction), #process-sandbox (Process_Sandboxing), #config-validation (Config_Validation), #resource-limits (Resource_Limits), #param-commands (Parameterized_Commands), #glob-filtering (Glob_Pattern_Filtering), #regex-anchoring (Regex_Anchoring), #prefix-ownership (Prefix_Ownership), #yaml-validation (YAML_Validation)

### Open Exposures (need @mitigates or @audit)

- #agent-launcher exposed to #prompt-injection [medium] (src/agents/launcher.ts:13)
- #agent-launcher exposed to #dos [low] (src/agents/launcher.ts:15)
- #agent-launcher exposed to #prompt-injection [high] (src/agents/prompts.ts:6)
- #llm-client exposed to #data-exposure [low] (src/analyze/index.ts:12)
- #llm-client exposed to #prompt-injection [medium] (src/analyze/llm.ts:17)
- #sarif exposed to #data-exposure [low] (src/analyzer/sarif.ts:15)
- #cli exposed to #cmd-injection [critical] (src/cli/index.ts:31)
- #init exposed to #data-exposure [low] (src/init/index.ts:12)
- #mcp exposed to #cmd-injection [high] (src/mcp/index.ts:4)
- #mcp exposed to #prompt-injection [medium] (src/mcp/server.ts:30)
- #mcp exposed to #data-exposure [medium] (src/mcp/server.ts:34)
- #suggest exposed to #dos [low] (src/mcp/suggest.ts:16)
- #parser exposed to #arbitrary-write [high] (src/parser/clear.ts:7)
- #tui exposed to #cmd-injection [high] (src/tui/commands.ts:11)
- #tui exposed to #prompt-injection [medium] (src/tui/commands.ts:15)

### Existing Data Flows (extend, don't duplicate)

- EnvVars -> #agent-launcher via process.env
- ConfigFile -> #agent-launcher via readFileSync
- #agent-launcher -> ConfigFile via writeFileSync
- UserPrompt -> #agent-launcher via launchAgent
- #agent-launcher -> AgentProcess via spawn
- AgentProcess -> #agent-launcher via stdout
- UserPrompt -> #agent-launcher via buildAnnotatePrompt
- ThreatModel -> #agent-launcher via model
- #agent-launcher -> AgentPrompt via return
- ThreatModel -> #llm-client via serializeModel
- ProjectFiles -> #llm-client via readFileSync
- #llm-client -> ReportFile via writeFileSync
- LLMConfig -> #llm-client via chatCompletion
- #llm-client -> LLMProvider via fetch
- LLMProvider -> #llm-client via response
- LLMToolCall -> #llm-client via createToolExecutor
- #llm-client -> NVD via fetch
- ProjectFiles -> #llm-client via readFileSync
- ThreatModel -> #sarif via generateSarif
- #sarif -> SarifLog via return
- ... and 48 more

### Model Stats

290 annotations, 16 assets, 15 threats, 12 controls, 60 exposures, 44 mitigations, 68 flows

<!-- guardlink:end -->