Task: Generate SECURITY.md — Threat Model & Controls

Task: Generate SECURITY.md — Threat Model & Controls

Objective

Produce a SECURITY.md that serves as the single source of truth for the system's threat model and the controls that address it: assets worth protecting, hostile actor classes with capability assumptions, trust boundaries inherited from INTERFACES, a data-flow diagram flagging every boundary crossing, a STRIDE-driven threat catalogue under stable THREAT-NN IDs, mitigations under stable MIT-NN IDs tied to concrete implementation locations, authentication and authorization models (role inventory, permission model, enforcement points, use-case-to-permission map), secret management, input validation and output encoding per trust boundary, abuse prevention, supply-chain security, incident response, and an explicit residual-risk register. An agent reading this document alone can — for any endpoint, saga, or data store — name the threats it faces, the mitigations that cover them, the enforcement point for each authorization check, and the residual risks the business has accepted, without opening another file.

SECURITY.md consolidates what older guidance split into THREAT_MODEL.md and a controls catalogue, because the two are always read together: a threat without a mitigation is noise, a mitigation without the threat it addresses is incomplete. The defining discipline — and the commonest failure — is every THREAT-NN has at least one MIT-NN addressing it or an explicit residual-risk acceptance, and every MIT-NN names a concrete implementation location. Orphan threats are modelling aspirations; orphan mitigations are controls with no owner.

Inputs

1. ARCHITECTURE.md (required) — § 2 Components, cross-component flows, and deployment shape frame assets, trust boundaries, and the DFD; ADR-NN on zero-trust, segmentation, or secret-storage informs §§ 7–9.
2. DOMAIN.md (required) — § 1 Glossary supplies vocabulary; §§ 4–6 supply asset candidates; § 9 Invariants Index supplies invariants whose violation is itself a security event.
3. INTERFACES.md (required) — § 1 Boundaries is authoritative for § 3 Trust Boundaries and DFD crossings; § 3 Authentication, § 4 Idempotency, § 6 Endpoints supply the auth scheme, replay semantics, and endpoint inventory this document annotates.
4. Surface IAs (required — one per existing surface: WEB_IA.md, CLI_IA.md, MOBILE_IA.md, TUI_IA.md, VOICE_IA.md) — auth UX, form-validation contract, error visibility policy; § 7 and § 10 cite IA flows.
5. USE_CASES.md (required) — § 1 Actors map to § 2.1 Authorized Actors; § 2 Use Cases with stable UC-NN IDs drive the § 8 use-case-to-permission map.
6. ERRORS.md (optional — required if produced) — § 3 Error Code Registry supplies security-signal codes (AUTHN_FAILED, AUTHZ_DENIED, RATE_LIMITED) cited in §§ 5, 8, 11.
7. DATA.md (optional — if produced) — § 8 sensitive-column inventory informs § 1 and § 10; retention policies inform § 14.
8. OPERATIONS.md (optional) — § 9 storage locations and § 13 paging rules cite it; absence surfaces as open questions.
9. QUALITY.md (optional) — § 6 alerts cited from § 13; security-specific detection rules live here, not in QUALITY.
10. Existing SECURITY.md (auto-discovered — only if refining) — read fully. Every assigned THREAT-NN and MIT-NN is permanent; retired entries retain their row with (retired — superseded by {new-id}).

Read all required inputs end-to-end. Truncated reads cause two specific failure modes: trust boundaries missing from § 3 (INTERFACES § 1 not fully read) and authorization rules missing UC-NN references (USE_CASES not fully read).

Workflow

Construction proceeds in eight phases: assets and actors, trust boundaries and DFD, STRIDE enumeration, mitigations, auth models, secrets and validation, abuse and supply chain and IR, residual risks and validation. Phases are sequential — later phases cite IDs from earlier phases — but revisit earlier phases if a later one reveals a missing asset, an un-mitigated threat, or an elided boundary.

Before Phase 3, read references/stride-checklist.md for the per-element × per-STRIDE-category prompts applied to every DFD element. The checklist owns systematic enumeration; the workflow below describes what to do with its output.

Phase 1: Assets & Actors

§ 1 Assets enumerates what the system protects. Derive from DOMAIN §§ 4–6 (entities and aggregates representing protected state), DATA § 8 when present (sensitive columns), and INTERFACES § 6 (anything an endpoint reads or writes that matters to the business). Each entry fills the Output Format template: name (DOMAIN canonical form), CIA classification each rated low/medium/high, location citing ARCHITECTURE § 2 components, owning bounded context, exposure.

§ 2 Actors has two groups. Authorized actors are a one-to-one map of USE_CASES § 1 — never invent new ones here, never drop one. Unauthorized / hostile classes cover archetypes relevant to the system: anonymous attacker, authenticated-but-unauthorized user, compromised dependency, malicious insider, supply-chain attacker, nation-state where relevant. Capability assumptions (network-only? authenticated? on-host? build-pipeline access?) frame every threat that cites the actor.

Phase 2: Trust Boundaries & Data Flow Diagram