audit-security

name	audit-security
description	Performs a multi-agent security audit checking authentication, input validation, data exposure, and infrastructure. This skill should be used when the user asks to "audit security", "run a security review", "check for vulnerabilities", "security scan", "check auth", "find security issues", or "harden security", or when the transmute-pipeline agent reaches Stage 6A of the pipeline.
version	1.0.0

Security Audit — Stage 6A

Read the detailed guide at ${CLAUDE_SKILL_ROOT}/references/audit-security-detailed-guide.md for the complete audit procedures, teammate spawn prompts, vulnerability fix patterns, and report templates.

Lead a multi-agent security audit of the complete codebase against BRD security requirements and PRD security specifications. Identify vulnerabilities and fix them.

Stage Sequence (recommended ordering): Stage 5B → (6A (this stage) ‖ 6B ‖ 6C) → 6E → 6F → 6G → 6D → 6H → 6V → 6R → 6P/6P-R → 7 (Deploy). Note: 6A, 6B, and 6C run in parallel (each in a separate session). If running in parallel, commit 6A changes as soon as 6A completes to avoid config file conflicts — see CLAUDE.md § "Stage 6 ordering".

Prerequisite Checks

Before any audit work, verify:

1. Check that ./plancasting/_audits/implementation-completeness/report.md exists and shows PASS or CONDITIONAL PASS. If missing, STOP: 'Stage 5B report not found — run Stage 5B before starting Stage 6 audits. Proceeding without 5B wastes effort on incomplete code.' (Override: if the operator explicitly confirms 5B was intentionally skipped, proceed with a WARN in the report noting unverified implementation completeness.)
2. If 5B shows FAIL, STOP — the codebase has unresolved implementation gaps that must be fixed before security auditing. If CONDITIONAL PASS, note the documented Category C issues — skip security auditing for those incomplete features.
3. Read ./CLAUDE.md and ./plancasting/tech-stack.md for project conventions.
4. Read the relevant PRD sections for implementation context.

Inputs

Read and reference these files throughout the audit:

• Codebase: Backend directory and ./src/ (adapt paths per tech stack)
• Tech Stack: ./plancasting/tech-stack.md
• Security Requirements: ./plancasting/brd/13-security-requirements.md
• Compliance Requirements: ./plancasting/brd/12-regulatory-and-compliance-requirements.md
• PRD Security Architecture: ./plancasting/prd/10-system-architecture.md (auth/authz section)
• PRD API Specs: ./plancasting/prd/12-api-specifications.md (auth scheme, rate limiting)
• Project Rules: ./CLAUDE.md

Check ./plancasting/tech-stack.md for the Session Language setting. Generate all reports and user-facing output in that language. Keep code, technical identifiers, and file names in English.

Stack Adaptation

Prompts reference Convex + Next.js as defaults. Adapt all paths and patterns to the actual stack in plancasting/tech-stack.md:

• convex/ becomes your backend directory
• convex/schema.ts becomes your schema/migration files
• Convex functions become your backend functions/endpoints
• src/app/ becomes your frontend pages directory

Read CLAUDE.md Part 2 (Backend Rules, Frontend Rules) for project-specific conventions.

Package Manager: Commands use bun run as default. Replace with your project's package manager as specified in CLAUDE.md.

Known Failure Patterns

1. Severity deflation: Agent marks everything as "Medium" to avoid escalation. Use clear definitions: Critical = data breach possible without auth, High = privilege escalation possible, Medium = defense-in-depth gap, Low = best practice deviation.
2. Symptom fixing: Agent adds auth check to a function but doesn't notice the function is also exported publicly. Fix root cause, not symptoms.
3. Regression from security fixes: Agent adds auth check that breaks a legitimate unauthenticated flow. ALWAYS verify fixes don't break existing tests.
4. Skipping generated files' consumers: Agent correctly skips _generated/ but also skips files that import from _generated/ — these may contain security-relevant code.
5. Missing CORS/CSP checks: Focusing only on code-level auth while ignoring HTTP-level security headers.
6. Blind framework trust: Agent assumes a framework handles security correctly without verification (e.g., 'Next.js handles CSRF'). ALWAYS verify framework security defaults are actually enabled in configuration.
7. Zero-day normalization: Agent marks an unpatched CVE as 'acceptable risk' without documenting threat model justification. ALWAYS document: 'We accept this risk because [mitigation] is in place.'

Phase 1: Analysis and Planning

Complete these steps before spawning any teammates:

1. Read ./CLAUDE.md, ./plancasting/tech-stack.md, and all security/compliance requirements from BRD/PRD.
2. Build a Security Checklist mapping each BRD security requirement (SR-xxx) to specific code patterns to verify. For each entry include: (a) Scope — affected files/functions, (b) Check — what to verify, (c) Code pattern — correct implementation example, (d) Status — "Not checked yet".
3. Write ./plancasting/_audits/security/checklist.md with the full checklist.
4. Create a task list for all teammates with dependency tracking.

Scope Boundary — Rate Limiting: See Teammate 4 for the 6A/6G rate limiting scope boundary.

Phase 2: Spawn Audit Teammates

Spawn 4 parallel teammates. Each teammate's prompt must include the security checklist and instructions to read CLAUDE.md first.

Teammate 1: auth-auditor

Scope: Authentication and authorization.

• Scan every exported backend function (excluding generated code). Verify auth checks are called where required. Flag mutations/actions modifying data without auth. Flag queries returning sensitive data without auth. Verify role/permission checks match BRD requirements.
• Check authorization logic for horizontal and vertical privilege escalation.
• Review middleware/route protection for completeness and role-based access.
• Adapt auth checks to the stack's auth pattern (session-based, JWT-based, or auth provider SDK). For JWT: verify JWKS endpoint security, alg whitelist (reject alg: none), audience/issuer validation, JWKS cache headers, token expiry validation.
• Fix each vulnerability with inline comment: // SECURITY FIX: [description] — SR-xxx

Teammate 2: input-validation-auditor

Scope: Input validation and injection prevention.

• Verify ALL backend function arguments use proper validators. Flag overly permissive validators (e.g., v.any()). Verify string length constraints and typed ID validators.
• Scan form components for client-side validation consistency with server.
• Check for XSS vectors: unsafe innerHTML usage, unescaped user content, file upload validation.
• Fix each vulnerability found.

Teammate 3: data-exposure-auditor

Scope: Data leakage and privacy.

• Flag queries returning entire documents when subsets suffice. Flag queries returning sensitive fields (email, phone, payment info) unnecessarily. Verify PII is not logged or exposed in error messages.
• Verify error messages do not leak internal details (stack traces, table names, query patterns).
• Check for sensitive data in localStorage/sessionStorage, hardcoded API keys, improperly prefixed env vars.
• Fix each issue found.

Teammate 4: infrastructure-security-auditor

Scope: HTTP security headers, CORS, CSP, dependencies, rate limiting, audit logging.

• Verify Content-Security-Policy, HSTS, X-Frame-Options, X-Content-Type-Options, and Referrer-Policy.
• Check CORS configuration — flag Access-Control-Allow-Origin: *. Verify credentials mode is correctly configured.
• Run dependency vulnerability scan. For Bun projects: use bunx audit-ci, npx better-npm-audit audit, or npx snyk test. For npm/yarn: npm audit. For pnpm: pnpm audit. If none can be installed, document that scanning could not be performed and recommend manual review. Flag critical/high severity issues and known CVEs. Verify lock file integrity.
• Rate Limiting — 6A/6G Scope Boundary: Rate limiting for AUTH endpoints (login, signup, password reset, forgot password, MFA challenge/verify, token refresh, session management — logout, session revocation) is Stage 6A's responsibility — implement these now. Rate limiting for DATA-MUTATION endpoints (create, update, delete, file uploads) is Stage 6G's responsibility. Flag data-mutation rate limiting gaps for Stage 6G to implement.
  • Edge case classifications: Password change = AUTH (6A). User profile update = DATA-MUTATION (6G). Email verification re-send = AUTH (6A). MFA device management = AUTH (6A). Invitation acceptance = AUTH (6A). Account linking = AUTH (6A). Signup = AUTH (6A). Password-reset email send = AUTH (6A, auth flow).
  • If Stage 6G report already exists (./plancasting/_audits/resilience/report.md), verify no scope overlap. If ambiguous, flag as a decision point for the lead to reconcile.
• Verify security-sensitive operations are logged and logs contain no sensitive data.
• Fix each issue found.

Unfixable Violation Protocol

When a violation cannot be fixed without architectural changes or would break another feature:

1. Document the full conflict with evidence (what the violation is, what fixing it would break).
2. Mark as REQUIRES HUMAN DECISION — do not attempt fixes that create regressions.
3. Include recommended approach and estimated effort.
4. If CRITICAL severity (e.g., architectural security flaw, missing encryption at rest, broken auth model): the audit MUST recommend NOT LAUNCHING until resolved. Document required architectural changes and estimated remediation scope. Record in ./plancasting/_audits/security/unfixable-violations.md (separate file from report.md) AND summarize in the main report.md under a "Blocking Issues" section — critical violations block Stage 6H. Use these headings in the unfixable violations file: ### [Issue ID], **Severity**: [CRITICAL/HIGH], **Description**: [what the issue is], **Evidence**: [code location and proof], **Recommended Approach**: [how to fix with architectural changes], **Estimated Effort**: [hours/days].
5. Continue with remaining fixable violations.

Phase 3: Coordination

• Facilitate cross-team findings: auth gaps inform input-validation checks; PII exposure informs auth requirements; CSP gaps inform data-exposure risk; rate limiting gaps inform brute-force risk.
• Resolve file conflicts: first teammate to complete claims the file; second must re-read before applying changes. If both changes are in different functions/sections, both apply. If they touch the same code block, the lead decides — security correctness over team structure.

Phase 4: Review and Report

1. Run the full test suite using commands from CLAUDE.md (e.g., bun run typecheck, bun run lint, bun run build, bun run test, bun run test:e2e). Fix any test failures caused by security changes.
2. If unfixable violations were documented, verify ./plancasting/_audits/security/unfixable-violations.md exists and is referenced from report.md.

CRITICAL: The ## Gate Decision heading in the generated report is parsed by Stage 6H. Use this EXACT heading — do not rename or restructure it.

3. Generate ./plancasting/_audits/security/report.md containing:

   • Executive summary
   • Vulnerabilities by category and severity (Critical/High/Medium/Low)
   • Fixes applied with code references
   • BRD security requirement compliance matrix (SR-xxx to Pass/Fail)
   • Infrastructure security results (HTTP headers, CORS, CSP, dependencies, rate limiting, audit logging)
   • Data-Mutation Rate Limiting Gaps (for Stage 6G): List all data-mutation endpoints flagged by Teammate 4 that lack rate limiting. Format: - [endpoint] ([reason]). Stage 6G reads this section.
   • Remaining risks requiring human decision
   • Recommendations for ongoing security practices

   Gate Decision

   [PASS | CONDITIONAL PASS | FAIL]

   • PASS: All Critical and High severity vulnerabilities fixed; all tests pass; no unfixable blocking issues
   • CONDITIONAL PASS: All Critical fixed; remaining High issues documented with mitigations; Stage 6H review required
   • FAIL: Critical vulnerabilities remain unresolved; blocks Stage 6H

4. Output summary: total vulnerabilities found, total fixed, total requiring human review.

Phase 5: Shutdown

1. Request shutdown for all teammates.
2. Verify all file modifications are saved and committed.

Severity Definitions

Use these consistently — do not deflate:

• Critical: Data breach possible without authentication
• High: Privilege escalation possible
• Medium: Defense-in-depth gap
• Low: Best practice deviation

Critical Rules

1. NEVER mark a vulnerability as "acceptable risk" without documenting specific threat model justification.
2. NEVER delete a security test to make the suite pass — fix the vulnerability instead.
3. NEVER introduce new auth bypass patterns as part of a fix.
4. ALWAYS run the full test suite after security changes — security fixes that break functionality are not fixes.
5. ALWAYS verify custom API routes have CSRF protection for state-changing operations.
6. ALWAYS check for secrets in git history: git log --all -p -G "(sk-|sk_|Bearer |password=|PRIVATE KEY|AWS_SECRET|STRIPE_SECRET|DATABASE_URL=|-----BEGIN|api[_-]?key|client[_-]?secret)" --max-count=500. For large repos add --since='6 months ago'. Use -G with regex alternation, NOT multiple -S flags (git only processes the last -S flag, silently ignoring earlier ones). If ANY secret is found, document as CRITICAL in ./plancasting/_audits/security/unfixable-violations.md requiring immediate key rotation — secrets in git history cannot be fixed by code changes alone. This is a pipeline blocker: do NOT proceed to Stage 6H until key rotation is confirmed by the operator. Verify .env.local.example contains only placeholder values (no real API keys, no real passwords).
7. ALWAYS verify SSRF blocklist: check all outbound fetch() or HTTP client calls triggered by user input. Reject private IP ranges (10.x, 172.16-31.x, 192.168.x), localhost (127.0.0.1, ::1), link-local (169.254.x, fe80::/10), IPv6 unique local (fc00::/7), and cloud metadata endpoints (169.254.169.254).
8. ALWAYS verify rate limiting on auth endpoints. Flag data-mutation gaps for Stage 6G. See the 6A/6G scope boundary: 6A = auth-protecting endpoints; 6G = data-mutation endpoints. Do NOT implement data-mutation rate limiting in Stage 6A.
9. Use commands from CLAUDE.md for running tests.
10. Reference Stage 5B output to avoid auditing stub/incomplete features.
11. For safety-critical rules and pipeline-level security constraints, see CLAUDE.md § Pipeline Execution Guide → Safety-Critical Rules (or execution-guide.md if CLAUDE.md defers to it).