@kaademos/secure-sdlc 1.0.2 → 1.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "secure-sdlc-agents",
+  "version": "1.0.0",
+  "description": "A team of AI security specialists embedded in your coding workflow. 8 agents covering every phase of the Secure SDLC: requirements, threat modelling, code review, IaC security, compliance, and release gating. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible tool.",
+  "author": {
+    "name": "Kaademos",
+    "url": "https://github.com/Kaademos"
+  },
+  "repository": "https://github.com/Kaademos/secure-sdlc-agents",
+  "license": "MIT",
+  "keywords": [
+    "security",
+    "appsec",
+    "sdlc",
+    "owasp",
+    "asvs",
+    "compliance",
+    "threat-modeling",
+    "secure-coding"
+  ],
+  "agents": [
+    ".claude/agents/product-manager.md",
+    ".claude/agents/appsec-engineer.md",
+    ".claude/agents/grc-analyst.md",
+    ".claude/agents/cloud-platform-engineer.md",
+    ".claude/agents/dev-lead.md",
+    ".claude/agents/release-manager.md",
+    ".claude/agents/security-champion.md",
+    ".claude/agents/ai-security-engineer.md"
+  ]
+}

package/CHANGELOG.md

@@ -8,6 +8,26 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [1.0.2]
 
+---
+
+## [1.1.0] — 2026-04-06
+
+### Added
+- **`.claude-plugin/plugin.json`** — Claude Code plugin marketplace manifest; agents now installable with a single `/plugin marketplace add Kaademos/secure-sdlc-agents` command (zero-dependency, no npm, no cloning)
+- **`skills/` directory** — 4 SKILL.md files in the agent-skills–compatible format for cross-ecosystem discoverability:
+  - `skills/security-and-hardening/` — secure coding, PR review, OWASP Top 10 prevention, severity gating
+  - `skills/threat-modeling/` — STRIDE + LINDDUN structured threat model workflow
+  - `skills/ai-security/` — OWASP LLM Top 10 2025, prompt injection, excessive agency, output validation
+  - `skills/compliance-and-audit/` — risk register, framework mapping (SOC 2, ISO 27001, GDPR, PCI DSS), audit evidence
+- **README — "Option 0"** plugin marketplace as the first and fastest install path (before git clone and npm)
+- **README — "The 4-Minute Problem"** concrete breach table replacing the generic problem statement — 5 real vulnerabilities a vibe-coded file upload misses, each mapped to the catching agent
+- **README — "Who Do You Call?"** ASCII decision tree covering every SDLC moment → correct agent → exact command
+
+### Changed
+- **README.md** — title tagline tightened to be specific and direct ("8 AI security specialists. Invoked at the exact phase where each vulnerability would have been caught.")
+- **`package.json` `files`** — added `skills/` and `.claude-plugin/` to the npm publish manifest
+
+
 ### Added
 - **npm package** `@kaademos/secure-sdlc` (root `package.json`) — global install via `npm install -g @kaademos/secure-sdlc`, `npx @kaademos/secure-sdlc`, semver releases;
 - **`secure-sdlc paths`** — prints `PACKAGE_ROOT` and MCP server path after install

package/README.md

@@ -6,22 +6,28 @@
 
 # Secure SDLC Agents
 
-A team of AI security specialists — embedded directly in your vibe coding workflow.
+**8 AI security specialists. Invoked at the exact phase where each vulnerability would have been caught.**
 
-They cover every phase of the Software Development Lifecycle: requirements, architecture,
-code review, infrastructure, compliance, and release gating. They work wherever you work:
-Claude Code, Cursor, Windsurf, Warp, and any tool that supports MCP.
+Requirements → threat modelling → code review → IaC → compliance → release gate.  
+Works in Claude Code, Cursor, Windsurf, Warp, and any MCP-compatible tool.
 
 ---
 
-## The problem this solves
+## The 4-Minute Problem
 
-When developers use AI tools to build fast, security becomes the thing that gets bolted on
-at the end — or skipped entirely. Threat models don't happen. ASVS requirements are never
-written. Compliance evidence is scrambled together the night before an audit.
+You asked Claude Code to build a file upload feature. It wrote working code in 4 minutes.
 
-This project makes the security team part of the build process from day one. Not a gate
-at the end, but a set of specialists you summon at the exact moment their expertise is needed.
+It missed:
+
+| Vulnerability | Severity | Which agent catches it |
+|---|---|---|
+| SVG file with embedded `<script>` stored and served without sanitisation | **CRITICAL** | `appsec-engineer` — MIME type validation, output encoding |
+| No file size limit or type allowlist | **HIGH** | `appsec-engineer` — input validation, magic byte checks |
+| S3 bucket provisioned with `public-read` ACL | **CRITICAL** | `cloud-platform-engineer` — IaC security review |
+| No rate limiting on the upload endpoint | **HIGH** | `appsec-engineer` — anti-automation controls |
+| Upload URL in API response leaks internal bucket path | **MEDIUM** | `dev-lead` — information disclosure review |
+
+Every one of these has appeared in real breach post-mortems. AI agents optimise for *working code*, not *secure code*. This project embeds the specialists that close that gap — at the exact phase where each issue would have been caught.
 
 ---
 
@@ -57,9 +63,46 @@ at the end, but a set of specialists you summon at the exact moment their expert
 
 ---
 
+## Who Do You Call?
+
+```
+What are you working on?
+│
+├── Starting a new feature?
+│   ├── product-manager  →  "Define security requirements for X using ASVS L2"
+│   └── grc-analyst      →  "Initialise risk register, map to SOC2 / GDPR / PCI-DSS"
+│
+├── Designing the architecture?
+│   ├── appsec-engineer          →  "Threat model this design using STRIDE"
+│   ├── cloud-platform-engineer  →  "Review IaC for this feature"
+│   └── ai-security-engineer     →  "Security review — feature calls an LLM"  ← always include this
+│
+├── Writing or merging code?
+│   ├── dev-lead       →  "Review PR #N for secure coding issues and dependency risks"
+│   └── appsec-engineer  →  "Triage SAST findings for PR #N"
+│
+├── Quick security question (any phase)?
+│   └── security-champion  →  "Is this pattern / library safe? Context: ..."
+│
+└── Ready to ship?
+    └── release-manager  →  "Run pre-release security checklist for vX.Y.Z"
+```
+
+---
+
 ## Quick start
 
-### Option A — Claude Code (zero dependencies)
+### Option 0 — Claude Code Plugin Marketplace (one command, nothing to install)
+
+```bash
+/plugin marketplace add Kaademos/secure-sdlc-agents
+```
+
+All 8 agents are immediately available in your session. No cloning, no npm, no file copying.
+
+---
+
+### Option A — Git clone (zero dependencies)
 
 ```bash
 git clone https://github.com/Kaademos/secure-sdlc-agents.git

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaademos/secure-sdlc",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Secure SDLC agent team — CLI to scaffold docs, hooks, CI, and MCP-ready security workflows",
   "type": "module",
   "bin": {
@@ -15,6 +15,8 @@
     "docs/templates",
     "hooks",
     "stacks",
+    "skills",
+    ".claude-plugin",
     "warp-workflows",
     ".github/workflows/secure-sdlc-gate.yml",
     ".cursor/rules",

package/skills/ai-security/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: ai-security
+description: >
+  Use when building any feature that calls an LLM API, processes user input sent to
+  a model, uses RAG or embeddings, deploys an AI agent with tool access, or makes
+  AI-generated output visible to users or downstream systems.
+---
+
+# AI Security
+
+## Overview
+
+This skill applies structured security analysis to AI and LLM-powered features.
+The threat categories here — prompt injection, excessive agency, output misuse,
+supply chain — did not exist before 2023 and are still being misunderstood by
+most developers shipping AI features today.
+
+**Working assumption: every model is a trust boundary, not a trusted component.**
+Model outputs must be treated as untrusted user input to every downstream system.
+
+**Reference framework:** OWASP Top 10 for LLMs 2025 (LLM01–LLM10).
+
+## When to Use
+
+- Any code that calls an LLM API (OpenAI, Anthropic, Google, Mistral, self-hosted)
+- Any feature that sends user-supplied content to a model
+- RAG systems, embeddings, vector databases, or retrieval pipelines
+- AI agents with tool access (file system, HTTP requests, database writes, email)
+- Features where model output is rendered in UI, executed as code, or used in queries
+- Selecting or integrating a third-party model, fine-tune, or embedding
+
+## Process
+
+### Step 1 — Map the attack surface
+
+Before finding vulnerabilities, enumerate:
+
+| Question | Why it matters |
+|---|---|
+| Who sends input to the model? | Determines direct injection risk |
+| What external sources feed the prompt context? | Determines indirect injection risk |
+| What tools / functions can the model invoke? | Determines excessive agency blast radius |
+| What happens to the model's output? | Determines output handling risk |
+| Is user PII sent to a third-party API? | Determines data leakage and legal risk |
+| Where does the model or its weights come from? | Determines supply chain risk |
+
+### Step 2 — Assess prompt injection risk (LLM01, LLM07)
+
+**Input trust classification:**
+
+| Input Source | Trust Level | Injection Risk |
+|---|---|---|
+| Authenticated user (UI) | LOW | Direct prompt injection |
+| Public / unauthenticated user | UNTRUSTED | Direct + jailbreak attempts |
+| Retrieved document (RAG) | UNTRUSTED | Indirect prompt injection |
+| Tool / function call result | MEDIUM | Injection via external API response |
+| Database query result | MEDIUM | Injection via poisoned records |
+| Web scraping / search | UNTRUSTED | Indirect injection |
+
+**Mitigations to verify:**
+- [ ] User input is structurally separated from system instructions (not just concatenated)
+- [ ] Retrieved content is sanitised before injection into prompt context
+- [ ] Known injection patterns are filtered (defence in depth — not a complete defence alone)
+- [ ] System prompt does not contain secrets — assume a motivated attacker can extract it
+- [ ] The model cannot override its own instructions via the user turn
+
+### Step 3 — Assess excessive agency (LLM06)
+
+Excessive agency is the most dangerous risk for agentic systems. A model tricked via
+prompt injection into misusing its tool access can exfiltrate data, delete records,
+or send external requests — all without the user's knowledge.
+
+**Review checklist:**
+- [ ] What write operations can the model trigger? Can it be tricked into deleting or exfiltrating?
+- [ ] Can the model send external HTTP requests, emails, or webhooks? Via injected instructions?
+- [ ] Does the model have access to credentials or secrets? Can they be extracted in output?
+- [ ] Are tool call parameters validated before execution — or does raw model output go to the function?
+- [ ] Is there a human-in-the-loop approval step for high-impact or irreversible operations?
+- [ ] Does the model have access to only what it needs for this specific task (least privilege)?
+
+**Key principle:** model outputs are untrusted input. Validate before acting. Require explicit
+human confirmation for destructive or high-value operations.
+
+### Step 4 — Assess output handling (LLM05)
+
+| Model output used as… | Risk | Required mitigation |
+|---|---|---|
+| Rendered in HTML / DOM | Stored XSS | DOMPurify, output encoding |
+| Executed as code | Remote code execution | Never execute model output directly |
+| Inserted into SQL queries | SQL injection | Parameterise all queries; validate schema |
+| Used in HTTP requests | SSRF | Validate and allowlist URLs from model output |
+| Passed to shell commands | Command injection | Never pass model output to shell |
+| Used as a file path | Path traversal | Validate against allowlist of permitted paths |
+| Used for access control decisions | Privilege escalation | Never use model output for authorisation alone |
+
+### Step 5 — Assess supply chain (LLM03) and data leakage
+
+**Supply chain:**
+- [ ] Model sourced from a known, reputable provider
+- [ ] Fine-tuning inputs (if any) were sanitised and reviewed before use
+- [ ] Embedding model is standard and well-audited — not a third-party unknown
+- [ ] Update policy defined: how will you know if a model you depend on has a security issue?
+
+**Data leakage:**
+- [ ] PII minimised before sending to external model APIs
+- [ ] Legal basis confirmed for sending user data to the model provider
+- [ ] Data residency requirements checked against the model API's guarantees
+- [ ] Model API calls (prompts + outputs) are logged for audit — but raw PII is not in logs
+
+### Step 6 — Produce the output document
+
+```markdown
+## AI Security Review: [Feature Name]
+
+### Attack Surface Summary
+[Inputs, model access, tools available, output usage]
+
+### Threat Findings
+
+| ID | OWASP LLM Category | Severity | Description | Mitigation |
+|----|--------------------|----------|-------------|------------|
+| AI-001 | LLM01: Prompt Injection | HIGH | [Description] | [Concrete fix] |
+
+### Mitigations Required Before Release
+[Priority list with owners and references]
+
+### Accepted Risks
+[Any risks accepted with justification and approver]
+```
+
+## Common Rationalizations
+
+| Excuse | Counter |
+|---|---|
+| "The model won't do harmful things — it's aligned" | Alignment is not a security boundary. Prompt injection bypasses alignment systematically. |
+| "Our users are trusted — no injection risk" | Indirect injection comes from retrieved documents, not users. Malicious content in your RAG source is an injection vector. |
+| "We validate the model output in the UI" | XSS prevention in the UI is correct but insufficient. Validate at every trust boundary, not just display. |
+| "It's a read-only agent — no write tools" | Is it truly read-only? Check every tool definition. HTTP GET requests can trigger side effects in external systems. |
+| "We use a well-known model — supply chain is fine" | Supply chain risk includes fine-tunes, LoRA adapters, embedding models, and model API intermediaries — not just the base model. |
+| "We'll add rate limiting later" | LLM cost exhaustion attacks (LLM10) are cheaper than traditional DoS. Rate limit before you ship. |
+
+## Red Flags
+
+- User-supplied text concatenated directly into the system prompt with no structural separation
+- Retrieved document content injected into the prompt without sanitisation
+- A model that can trigger HTTP requests, file writes, or external service calls without a human approval step for high-impact actions
+- Model output rendered in the DOM without sanitisation
+- Model output used in a SQL query, shell command, or file path without validation
+- API keys or secrets present in the system prompt
+- No per-user rate limiting on endpoints that trigger model calls
+- A third-party embedding model or fine-tune with no documented provenance
+
+## Verification
+
+Do not close this review until:
+
+- [ ] All LLM01–LLM10 categories have been explicitly assessed
+- [ ] Every HIGH/CRITICAL finding has a concrete mitigation with an owner
+- [ ] Model output handling is validated at every downstream trust boundary
+- [ ] Tool access follows least-privilege — model has only what it needs for this task
+- [ ] Rate limiting and cost controls are in place
+- [ ] AI security findings are reflected in the main threat model (`docs/threat-model.md`)
+- [ ] Any data leakage findings are reviewed by `grc-analyst` for GDPR/compliance implications

package/skills/compliance-and-audit/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: compliance-and-audit
+description: >
+  Use when a project requires a compliance framework mapping, when risks need formal
+  documentation, when audit evidence must be collected, or when producing a compliance
+  attestation before release. Applies to SOC 2, ISO 27001, GDPR, PCI DSS, NIST CSF,
+  and DORA.
+---
+
+# Compliance and Audit
+
+## Overview
+
+This skill maintains the governance, risk, and compliance (GRC) layer of the Secure SDLC.
+It translates security work into auditable, framework-aligned documentation that survives
+a real audit — not a self-assessment checklist filled in the night before.
+
+The discipline: compliance is a continuous process. Every security control implemented
+during Build and Test must be captured as evidence at the time it is implemented,
+not reconstructed six months later.
+
+## When to Use
+
+- A new project or feature processes regulated data (PII, payment data, health data)
+- A compliance gap analysis is required
+- Risks need to be formally accepted, transferred, or mitigated on record
+- Audit evidence must be collected for a specific control
+- Producing a compliance attestation before a release or audit
+- Responding to a customer security questionnaire or due diligence request
+
+## Process
+
+### Step 1 — Determine applicable frameworks
+
+Based on data classification and business context, identify which frameworks apply:
+
+| Framework | Applies when… |
+|---|---|
+| **SOC 2 Type II** | You process customer data and need to demonstrate trust to enterprise buyers |
+| **ISO/IEC 27001:2022** | Formal ISMS certification is required (often for EU/UK contracts) |
+| **NIST CSF 2.0** | US federal contracts or voluntary alignment with US security standards |
+| **PCI DSS v4.0** | Any feature handling payment card data |
+| **GDPR / UK GDPR** | Any processing of personal data of EU or UK residents |
+| **DORA** | Financial services entities operating in the EU |
+| **HIPAA** | Protected health information (PHI) in the US |
+| **OWASP ASVS** | Always — this is the technical requirements anchor for all other frameworks |
+
+### Step 2 — Produce the risk register
+
+Create or update `docs/risk-register.md` with every identified risk:
+
+```markdown
+| Risk ID | Description | Category | Likelihood | Impact | Inherent Risk | Control(s) | Residual Risk | Owner | Status | Due Date |
+|---------|-------------|----------|------------|--------|--------------|------------|--------------|-------|--------|----------|
+| R-001 | SQL injection in search endpoint | Application | High | Critical | Critical | Input validation, WAF, SAST | Medium | Dev Lead | Open | YYYY-MM-DD |
+| R-002 | Insider access to production DB | Access Control | Medium | High | High | RBAC, PAM, audit logs | Low | Cloud/Platform | Mitigated | — |
+```
+
+Every vulnerability found by any agent must appear here with an owner, severity, and status.
+Risks do not disappear — they are mitigated, accepted, or transferred, with documentation.
+
+### Step 3 — Map controls to frameworks
+
+Produce a control mapping table that connects ASVS requirements to applicable framework controls:
+
+```markdown
+| ASVS Ref | Requirement | SOC 2 | ISO 27001 | NIST CSF | PCI DSS |
+|----------|-------------|-------|-----------|----------|---------| 
+| V2.1.1 | Password complexity ≥ 12 chars | CC6.1 | A.8.5 | PR.AC-1 | Req 8.3 |
+| V6.1.1 | Encryption at rest (AES-256) | CC6.7 | A.8.24 | PR.DS-1 | Req 3.5 |
+| V9.1.1 | TLS 1.2+ for all external comms | CC6.7 | A.8.20 | PR.DS-2 | Req 4.2 |
+```
+
+### Step 4 — Collect audit evidence at time of implementation
+
+For every control validated during Build or Test, create an evidence record immediately:
+
+```markdown
+## Evidence Record: [Control ID]
+
+**Control:** [Framework] — [Reference] — [Control Name]
+**Evidence Type:** Test result / Configuration screenshot / Policy document / Log extract
+**Date Collected:** YYYY-MM-DD
+**Collected By:** [Who or which agent]
+**Description:** [What this demonstrates — be specific enough for an auditor who wasn't there]
+**Artefact:** [File path or link]
+**Review Status:** Pending / Approved
+```
+
+Evidence must be collected at implementation time. Evidence reconstructed after the fact
+fails audit scrutiny.
+
+### Step 5 — Risk acceptance process
+
+When a risk cannot be fully mitigated before release:
+
+1. Document the risk in full (likelihood, impact, inherent score, existing controls)
+2. Describe the residual risk after controls
+3. Obtain a written business justification
+4. Record the name and role of the approver (must be appropriate seniority for the risk level)
+5. Set a mandatory review date — accepted risks expire
+
+```markdown
+## Risk Acceptance: [Risk ID]
+
+**Risk:** [Description]
+**Inherent Risk:** [Score]
+**Mitigating Controls:** [What's already in place]
+**Residual Risk:** [Score after controls]
+**Business Justification:** [Why this risk is being accepted rather than fixed]
+**Accepted By:** [Name, Role]
+**Acceptance Date:** YYYY-MM-DD
+**Review Date:** YYYY-MM-DD
+```
+
+### Step 6 — Produce the release compliance attestation
+
+Before every release, write `docs/audit-evidence/compliance-attestation-vX.Y.Z.md`:
+
+```markdown
+## Compliance Attestation — Release vX.Y.Z
+
+**Date:** YYYY-MM-DD
+**Frameworks in scope:** [List]
+
+### Control Status Summary
+
+| Framework | Total Controls | Compliant | Gap | Accepted Risk |
+|-----------|---------------|-----------|-----|---------------|
+| SOC 2 | 22 | 20 | 1 | 1 |
+
+### Open Gaps
+[List with owner and remediation timeline]
+
+### Accepted Risks
+[List with business justification and approver]
+
+### Attestation
+All in-scope controls reviewed. Gaps and accepted risks formally acknowledged.
+Release is approved from a GRC perspective pending Release Manager sign-off.
+```
+
+## Common Rationalizations
+
+| Excuse | Counter |
+|---|---|
+| "We'll document compliance after we launch" | Auditors require evidence contemporaneous with the control implementation. Retrospective documentation is a finding. |
+| "We're too early-stage for formal compliance" | SOC 2 readiness takes 6–12 months. If you start when a customer requires it, you've already lost the deal. |
+| "We've accepted this risk before" | Risk acceptance is time-bound and context-specific. Prior acceptance does not carry forward to a new feature or a changed threat landscape. |
+| "The risk register is the security team's job, not mine" | Risk ownership belongs to the team generating the risk. Dev teams own application risks; Cloud teams own infrastructure risks. |
+| "Our pentest report counts as audit evidence" | Pentest evidence is one artefact. Auditors require evidence for each control, not a single document. |
+
+## Red Flags
+
+- A risk register that hasn't been updated since the last audit
+- Accepted risks with no expiry date — permanent acceptance is not a valid posture
+- Compliance controls documented but no evidence they were actually implemented
+- A feature handling PII with no GDPR Article 30 record of processing activity
+- Audit evidence collected in a rush the week before an audit, not at time of implementation
+- Framework mapping that lists "compliant" for controls that were never tested
+- Risk acceptance signed off by an engineer rather than appropriate business authority
+
+## Verification
+
+Do not close this phase until:
+
+- [ ] All applicable compliance frameworks identified and documented
+- [ ] Risk register is current — all findings from appsec-engineer and cloud-platform-engineer have entries
+- [ ] Control mapping table exists in `docs/` and reflects current ASVS requirements
+- [ ] Audit evidence collected for every control claimed as implemented
+- [ ] All accepted risks have a named approver, business justification, and review date
+- [ ] Compliance attestation document written and reviewed before release
+- [ ] `grc-analyst` has provided compliance context to `release-manager` for the go/no-go decision

package/skills/security-and-hardening/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: security-and-hardening
+description: >
+  Use when writing or reviewing code that handles user input, authentication, access
+  control, cryptography, error handling, file uploads, or dependency management.
+  Also activates when a pull request touches any security-sensitive component.
+---
+
+# Security and Hardening
+
+## Overview
+
+This skill enforces the secure coding standards and PR review discipline that prevent
+the most common vulnerability classes from reaching production. It covers OWASP Top 10
+categories, ASVS control requirements, and the review process that catches issues before
+they merge — not after they breach.
+
+## When to Use
+
+- Any code handling user-supplied input (forms, APIs, file uploads, query params)
+- Authentication, session management, or access control changes
+- Cryptographic operations — hashing, encryption, key management
+- Dependency additions or upgrades
+- Pull request review on any security-sensitive component
+- SAST finding triage and remediation
+
+## Process
+
+### Step 1 — Classify the security surface
+
+Before reviewing, identify which categories are in scope:
+
+| Surface | Key risks |
+|---|---|
+| Input handling | Injection (SQL, LDAP, OS command, template, XSS) |
+| Authentication | Weak passwords, missing MFA, session fixation |
+| Access control | IDOR, broken object-level auth, privilege escalation |
+| Cryptography | Weak algorithms, hardcoded keys, improper key storage |
+| File handling | Path traversal, type confusion, SVG XSS, unrestricted upload |
+| Dependencies | Known CVEs, unmaintained packages, licence risk |
+| Error handling | Stack trace leakage, verbose error messages |
+
+### Step 2 — Apply the PR security checklist
+
+- [ ] No hardcoded secrets, API keys, or credentials anywhere in the diff
+- [ ] All user-controlled inputs validated server-side (type, length, format, range)
+- [ ] SQL/NoSQL queries use parameterised statements — no string concatenation with input
+- [ ] Object-level authorisation checks present (not just resource-type checks)
+- [ ] New dependencies reviewed: CVE status, maintenance activity, licence, download count
+- [ ] Error messages returned to the client are generic; detail is server-side only
+- [ ] Log entries do not include PII, credentials, session tokens, or payment data
+- [ ] Cryptographic operations use approved algorithms (AES-256-GCM, Argon2id, SHA-256+)
+- [ ] File upload handlers validate MIME type, magic bytes, size, and destination path
+- [ ] ASVS requirements from `docs/security-requirements.md` are satisfied
+
+### Step 3 — Severity-gate the findings
+
+| Severity | Action |
+|---|---|
+| **CRITICAL** | Block merge immediately. No exceptions. Fix and re-review. |
+| **HIGH** | Block merge unless risk is formally accepted with CISO sign-off. |
+| **MEDIUM** | Must have fix or accepted-risk entry in risk register before release. |
+| **LOW / INFO** | Track in risk register. Does not block. |
+
+### Step 4 — Structure the review output
+
+```markdown
+## Security Review: PR #[N] — [Title]
+
+### CRITICAL / HIGH — Block merge
+- [Issue]: [Plain English description + CWE reference + concrete fix]
+
+### MEDIUM — Fix before release
+- [Issue]: [Description + remediation suggestion]
+
+### Positive observations
+- [Good security practice observed — reinforce it]
+```
+
+### Step 5 — Verify the fix
+
+After remediation:
+1. Confirm the root cause is fixed, not just the symptom.
+2. Confirm a regression test exists that would catch the same issue in future.
+3. For CRITICAL/HIGH: re-review the changed lines before marking resolved.
+4. Update `docs/sast-findings.md` with the resolution status.
+
+## Common Rationalizations
+
+| Excuse | Counter |
+|---|---|
+| "It's internal-only, not a real risk" | Internal endpoints are breached via SSRF, pivot attacks, and insider threat. Internal ≠ safe. |
+| "I'll add input validation later" | Injection vulnerabilities are introduced at write time. "Later" is too late once it ships. |
+| "The ORM handles SQL injection" | ORMs do not protect against raw queries, JSON operators, or second-order injection. Verify. |
+| "We'll rotate the hardcoded key before production" | Keys committed to git are already compromised. Rotate now; remove from history. |
+| "This dependency vulnerability isn't reachable" | Reachability analysis is hard. Upgrade unless you can prove the affected code path is never hit. |
+| "The client validates it too" | Client-side validation is UX. Server-side validation is security. Both are required. |
+
+## Red Flags
+
+- A function accepts user input and builds a query, command, or markup string by concatenation
+- Password storage using MD5, SHA-1, SHA-256 alone (without bcrypt/Argon2id/scrypt)
+- Any `eval()`, `exec()`, `subprocess.run(shell=True)` with user-controlled data
+- File path constructed from user input without strict allowlisting
+- `Authorization` header or session token logged anywhere
+- A new npm/pip/gem package added without a comment explaining what it does and why
+- `catch (e) {}` — swallowed errors that may be masking a security event
+
+## Verification
+
+Do not close this review until:
+
+- [ ] All CRITICAL and HIGH findings have a confirmed fix or documented accepted risk
+- [ ] The fix has been re-reviewed at the code level (not just "looks good")
+- [ ] Regression tests exist for any vulnerability classes found
+- [ ] `docs/sast-findings.md` is updated with finding status
+- [ ] `docs/risk-register.md` is updated if any risk was accepted

package/skills/threat-modeling/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: threat-modeling
+description: >
+  Use when a new feature, architecture, or significant design decision is being made.
+  Run before any code is written. Produces a structured STRIDE threat model and
+  architecture review that feeds directly into security requirements and PR review.
+---
+
+# Threat Modeling
+
+## Overview
+
+This skill runs a structured threat model against a proposed design or architecture.
+It applies STRIDE (and LINDDUN for privacy) to enumerate what can go wrong before
+any code exists to exploit. The output is a `docs/threat-model.md` that every other
+agent can reference throughout the SDLC.
+
+The discipline: spec the threats before you write the code. AI agents that skip this
+step produce features that are locally correct but architecturally broken.
+
+## When to Use
+
+- Starting a new feature or service
+- Changing authentication, authorisation, or data access patterns
+- Adding a third-party integration or external data source
+- Designing a new API surface
+- Before a penetration test (to scope it correctly)
+- When a security incident reveals a design-level gap
+
+## Process
+
+### Step 1 — Define the scope
+
+Document:
+- **Feature summary**: what it does, for whom, and why
+- **Data flows**: where data enters, where it goes, where it is stored, where it exits
+- **Trust boundaries**: which components trust which other components, and why
+- **External dependencies**: APIs, databases, third-party services, user inputs
+
+Draw or describe a simple data flow diagram. Even ASCII is sufficient.
+
+### Step 2 — Enumerate STRIDE threats
+
+For each component and data flow, systematically enumerate threats across all six categories:
+
+| Category | Question to ask |
+|---|---|
+| **Spoofing** | Can an attacker pretend to be a legitimate user, service, or system? |
+| **Tampering** | Can data be modified in transit, in storage, or during processing? |
+| **Repudiation** | Can a user deny having performed an action — and would logs prove otherwise? |
+| **Information Disclosure** | Can data be accessed by an unauthorised party or leaked in error messages? |
+| **Denial of Service** | Can an attacker exhaust resources — compute, memory, storage, rate limits? |
+| **Elevation of Privilege** | Can a lower-privilege user or process gain higher-privilege access? |
+
+Produce a threat table:
+
+```markdown
+| Component / Flow | Threat Category | Threat Description | Likelihood | Impact | Mitigation |
+|---|---|---|---|---|---|
+| Login endpoint | Spoofing | Credential stuffing via enumerable usernames | High | High | Account lockout, MFA |
+| JWT token | Tampering | Signature bypass via alg=none | Medium | Critical | Enforce alg allowlist; use RS256 |
+| User records API | Info Disclosure | IDOR — UUID in path param, no object-level auth | High | High | Verify resource ownership per request |
+```
+
+### Step 3 — Add LINDDUN for privacy (when PII is involved)
+
+If the feature processes personal data, extend the model:
+
+| Category | What to check |
+|---|---|
+| **Linking** | Can user records be correlated across sessions or services? |
+| **Identifying** | Can data reveal a user's identity when combined? |
+| **Non-repudiation** | Are users stuck with data they can't delete or correct? |
+| **Detecting** | Can an attacker infer sensitive facts from system behaviour? |
+| **Data disclosure** | Is PII exposed to parties who shouldn't see it? |
+| **Unawareness** | Are users informed about what data is collected and why? |
+| **Non-compliance** | Does the feature conflict with GDPR, CCPA, or applicable regulation? |
+
+### Step 4 — Prioritise and assign mitigations
+
+For each identified threat:
+1. Rate Likelihood (High / Medium / Low) and Impact (Critical / High / Medium / Low)
+2. Determine Inherent Risk = Likelihood × Impact
+3. Specify a concrete mitigation (not "add validation" — "validate MIME type and magic bytes server-side before accepting file")
+4. Assign an owner and target phase (Design / Build / Test)
+
+### Step 5 — Produce the output document
+
+Write `docs/threat-model.md` using this structure:
+
+```markdown
+## Threat Model: [Feature Name]
+
+**Date:** YYYY-MM-DD  
+**Feature:** [Brief description]  
+**ASVS Level:** L[1/2/3]  
+**Conducted by:** appsec-engineer (AI) + [human reviewer]
+
+### Data Flow Summary
+[Describe or diagram the data flows and trust boundaries]
+
+### STRIDE Threat Table
+[Full table from Step 2]
+
+### LINDDUN Privacy Threats (if applicable)
+[Full table from Step 3]
+
+### Architecture Review Checklist
+- [ ] Authentication enforced on all endpoints
+- [ ] Authorisation follows least-privilege; no IDOR vectors
+- [ ] All inputs validated server-side; output encoding in place
+- [ ] Sensitive data identified and encryption requirements confirmed
+- [ ] Third-party integrations reviewed for supply chain risk
+- [ ] Error handling does not leak internal state
+- [ ] Logging captures security events without logging secrets
+- [ ] Rate limiting and anti-automation controls present
+
+### Mitigations Required (prioritised)
+[Ordered list by severity]
+```
+
+## Common Rationalizations
+
+| Excuse | Counter |
+|---|---|
+| "We'll do threat modeling after we build the MVP" | Design-level flaws cost 10–100x more to fix after implementation. The MVP will have the flaw baked in. |
+| "It's a simple feature, no need for a threat model" | The features that skip threat modeling are the features that produce the breach post-mortems. |
+| "We've done this before, we know the risks" | Every feature has novel combinations of data, trust boundaries, and integrations. Past experience is input, not a substitute. |
+| "The threat model would just say the same things every time" | Then produce a short one quickly. If you can't identify any threats, you haven't looked hard enough. |
+| "Security will review it in staging" | Staging review catches implementation bugs. Architectural flaws require an architectural fix — which means redesign and rebuild. |
+
+## Red Flags
+
+- A feature accesses user data across multiple accounts without explicit object-level authorisation logic
+- An API accepts user-supplied IDs (UUIDs, integers) without verifying ownership
+- A new external API or third-party service is introduced without a supply chain review
+- Data flows across a trust boundary without an explicit authN/authZ check
+- Error responses return stack traces, internal hostnames, or database schemas
+- A "temporary" bypass of an authorisation check for development convenience
+- No logging on authentication events, privilege changes, or data access
+
+## Verification
+
+Do not close the threat model until:
+
+- [ ] All STRIDE categories have been explicitly considered (even if some yield no findings)
+- [ ] Every HIGH and CRITICAL threat has a named mitigation with an owner and a target phase
+- [ ] `docs/threat-model.md` has been written and linked from the feature spec
+- [ ] The threat model has been reviewed by a human with security knowledge — not just read
+- [ ] Findings are reflected in `docs/security-requirements.md` (via `product-manager` agent)
+- [ ] `docs/risk-register.md` is updated with any accepted risks