Every Feature Ships with a Threat Model

Threat modeling starts while each CrispyVibe feature is still being designed. That way, mitigations become part of the architecture before implementation begins.

Every feature ships with a threat model. It’s how we build confidence.

The four-document convention

Every feature in CrispyVibe is defined by exactly four documents:

specs/features/{domain}/{feature-name}/
  spec.md              ← What it does (requirements, scenarios)
  technical-design.md  ← How it's built (architecture, data flow)
  threat-model.md      ← What we protect against (attacks, mitigations)
  usage-guide.md       ← How the user uses it

The threat model isn’t an appendix added later. It sits alongside the spec as an equal. Whether the feature is a theme picker or an SSH remote session, its security surface is recorded before implementation.

Anatomy of a threat model

Each threat model follows a consistent structure:

1. Overview — what the feature touches and its boundaries
2. Trust boundaries — where data crosses privilege levels
3. Attack surfaces — what’s exposed
4. Threats — each with a vector, impact, likelihood, and mitigation
5. Residual risks — what we’ve accepted and why
6. NFR compliance — how the feature satisfies cross-cutting requirements

Every threat gets a tracked ID (F046-T01, F046-T02, …) that links back to the feature spec. Those IDs make threats and mitigations auditable and traceable across the codebase.

Example: protecting credentials

Terminal Scroll Assist includes threat F046-T06:

Vector: User types a password at a hidden prompt (sudo, ssh, read -s). Input recording could capture these keystrokes and surface them via history navigation.

Impact: Credential disclosure within the app’s in-memory state.

Likelihood: High — password prompts are a daily occurrence.

Mitigation: recordInput() validates screen visibility before publishing. On Enter, it reads the terminal render buffer and checks if the typed text appears on screen. Terminals disable echo for secret input, so hidden text is invisible in the buffer and is automatically excluded from recording.

That threat surfaced during spec writing, before implementation began. Its mitigation then became part of the architecture.

NFR traceability

Mitigations link to the non-functional requirements (NFRs) that apply to the feature:

When a threat model says “Linked NFR: SEC-Data-Protection,” it points to a requirement with its own verification criteria. If that NFR evolves, its references show which feature documents need review and help keep the linked requirements consistent.

How the convention affects development

Threats surface during spec writing. The credential capture threat above led to a mitigation in the feature architecture before implementation.

Mitigations become implementation requirements for AI agents. The code follows the spec, so including the threat model puts each mitigation into the implementation contract.

Security context stays with the code. If someone later modifies the input recording system, its threat model remains in the feature folder for reference.

Security review starts during design. The threat model is a design document that the whole team can contribute to and learn from.

The process

1. Write the spec — define requirements and scenarios
2. Write the threat model — identify trust boundaries, attack surfaces, threats
3. Link to NFRs — connect mitigations to applicable cross-cutting requirements
4. Write the technical design — architecture incorporates mitigations naturally
5. Implement — code follows the design, which already includes security
6. Verify — NFR compliance table serves as a confidence checklist

This convention is part of the development workflow. AI agents produce all four documents, and a feature is considered complete when it has them.

The result

CrispyVibe has 45+ threat models across every feature domain: terminals, editors, AI agents, browser, SSH, file explorer, authentication, and platform services. The repository defines 8 NFR categories, and each threat model links to the ones that apply. Every security decision is documented, traceable, and reviewable.

Each threat model records what was considered, what is protected, and which residual risks were accepted. Keeping those decisions with the feature documentation makes later review easier.

Thirty minutes of threat modeling per feature buys you confidence that compounds forever.

In practice, the four-document convention adds about 30 minutes per feature. It keeps security decisions visible and traceable from the start.

Every feature ships with a threat model. Reviewers can trace each mitigation from the feature spec to the NFR verification criteria.