---
name: security
description: Security review and documentation
summary: "Conducts a security review of your entire system — OWASP Top 10 coverage, input validation rules for every user-facing field, data classification, secrets management, CORS policy, rate limiting, and a threat model covering all trust boundaries."
phase: "quality"
order: 950
dependencies: [review-operations]
outputs: [docs/security-review.md]
reads: [system-architecture, api-contracts, database-schema]
conditional: null
knowledge-base: [security-best-practices]
---

## Purpose
Conduct a security review of the entire system design. Document security
controls, threat model, auth/authz approach, data protection, secrets
management, and dependency audit strategy. The review covers OWASP Top 10
analysis specific to this project's stack and architecture, plus STRIDE
threat modeling across all trust boundaries.

## Inputs
- docs/system-architecture.md (required) — attack surface
- docs/api-contracts.md (optional) — auth/authz boundaries
- docs/database-schema.md (optional) — data protection needs
- docs/operations-runbook.md (required) — secrets and deployment security

## Expected Outputs
- docs/security-review.md — security review and controls document

## Quality Criteria
- (mvp) OWASP top 10 addressed for this specific project
- (mvp) Every API endpoint has authentication and authorization requirements specified
- (mvp) Auth/authz boundaries defined and consistent with API contracts
- (mvp) Input validation rules defined for each user-facing field: data type, maximum length, regex pattern (where applicable), and rejection error message
- (deep) Data classified by sensitivity with handling requirements
- (mvp) Secrets management strategy documented with rotation policy (no hardcoded secrets in code)
- (deep) CORS policy explicitly configured per origin (not wildcard in production)
- (deep) Rate limiting defined for public-facing endpoints with specific thresholds
- (deep) Threat model covers all trust boundaries
- (deep) Dependency audit strategy documented (automated scanning, update cadence)
- (deep) Dependency audit integrated into CI
- (deep) Secret rotation testing documented (how to rotate each secret type without downtime)

## Methodology Scaling
- **deep**: Full threat model (STRIDE). OWASP analysis per component.
  Data classification matrix. Secrets rotation plan. Penetration testing
  scope. Compliance checklist (if applicable).
- **mvp**: Key security controls. Auth approach. No secrets in code.
  Basic input validation strategy.
- **custom:depth(1-5)**:
  - Depth 1: key security controls and auth approach.
  - Depth 2: add secrets management strategy and basic input validation.
  - Depth 3: add threat model (basic STRIDE) and data classification.
  - Depth 4: full threat model with OWASP analysis per component and compliance checklist.
  - Depth 5: full security review with penetration testing scope, dependency audit strategy, and advanced controls.

## Mode Detection
Check for docs/security-review.md. If it exists, operate in update mode: read
existing security controls and threat model, diff against current system
architecture and API contracts. Preserve existing threat model entries, auth
decisions, and data classification. Add new threat boundaries for new
components. Update auth requirements if API contracts changed.

## Update Mode Specifics
- **Detect prior artifact**: docs/security-review.md exists
- **Preserve**: threat model entries, data classification matrix, auth/authz
  decisions, secrets management strategy, dependency audit configuration,
  compliance checklist items
- **Triggers for update**: architecture added new components (new attack surface),
  API contracts changed auth requirements, database schema changed data
  sensitivity, operations runbook changed deployment security
- **Conflict resolution**: if a new component introduces a trust boundary
  that conflicts with existing auth approach, document both and flag for
  user decision; never weaken existing security controls without approval

## Adoption Mode Specifics
- **Codify from repo evidence**: controls as-implemented — auth middleware
  and session handling from the code, input validation at trust boundaries,
  secrets handling (env files, vaults, CI secrets), dependency audit state
  (`npm audit` / `pip-audit` output), and any existing SECURITY.md policy.
  The threat model covers the system that exists, with evidence per
  control.
- **Interview only for**: risk appetite and compliance obligations (they are
  not in the code), known past incidents, and which of the pre-existing gaps
  the user wants prioritized.
- **Do not**: file long-standing accepted risks as new blockers without
  marking them pre-existing; propose rewrites of working auth flows —
  record gaps with evidence and severity instead; weaken or "simplify" any
  existing control.