/threat-modeling

name: threat-modeling
description: This skill should be used when the user asks to "create a threat model", "define security goals", "generate a data flow diagram", "write security definitions", "perform an initial security assessment", or needs to produce threat model artifacts for new features or architecture changes.

Bitwarden's Engagement Model

Bitwarden follows a 4-phase engagement model for security work. This skill primarily supports Phase 1 (engineering-owned) and assists with Phase 2-4 artifacts.

Phase 1: Initial Security Assessment (Engineering Team)

1. Check Bitwarden's Architecture Decision Records for existing decisions covering the system or components under review (see `${CLAUDE_PLUGIN_ROOT}/references/adr-alignment.md`) — a threat model should align with already-accepted architecture, not silently re-derive or contradict it 2. Create data flow diagrams (Mermaid) 3. Define security requirements separate from product requirements 4. Propose security definitions (threat model + security goals) 5. Identify initial threats using STRIDE (see `references/stride-framework.md`)

Phase 2: AppSec Team Review (AppSec + Engineering)

• Share data flow diagrams and security definitions in advance
• Walk through system architecture collaboratively
• Validate or refine proposed security definitions
• Identify additional threats, assess risk
• Avoid assuming external mitigations exist

Phase 3: Implementation (Engineering Team)

• Implement necessary security mitigations
• Create Jira follow-up work for threats without existing protections
• Include security considerations in sprint planning

Phase 4: Testing & Validation (Engineering + AppSec)

• Verify mitigations work as intended
• Adopt adversarial mindset during code review
• Test hypotheses (e.g., "Can I bypass SSO?") by working backwards
• Update security definitions as the system evolves

Security Definitions

Security Definitions (SDs) are Bitwarden's formal construct for communicating the security posture of a system. Each definition has three components: a **threat model** (attacker capabilities), **security goals** (what the system guarantees), and an **accepted goal status** (honest assessment of whether the goal is currently met).

Use Bitwarden's standard vocabulary when writing definitions — see `references/bitwarden-vocabulary.md` for the full glossary. Align security goals with Bitwarden's security principles (P01-P06) — see `references/security-principles.md`.

Threat Model Component

Describe attacker capabilities AND limitations — what they can and cannot do. Always state both sides to scope the definition precisely:

• "Attacker can run a user space process after the user's client has logged out" + "Attacker does not have access to secure storage mechanisms"
• "Attacker has database access and can read and write to the Send table" + "Attacker does not have access to the ASP.NET Core Data Protection encryption keys"

Include concrete examples where helpful (e.g., "An example for this is a stolen device"). Don't assume external mitigations are in place — even if obtaining an auth token is difficult, still explore what happens if an attacker has one.

Apply these rules when scoping the threat model:

• **Prune dominated threats.** If the attacker capability you're describing is strictly weaker than one already accepted as out-of-scope, delete the SD — its residual-risk statement collapses to a tautology like "equivalent to full user-account compromise". See `references/writing-quality-sds.md` for the dominated-threat anti-pattern and the term **Dominated Threat** in `references/bitwarden-vocabulary.md`.
• **Include passive observers, not just adversaries.** For any secret or protected data that crosses into an external service (LLM provider, log aggregator, analytics pipeline, training-data collector), write at least one SD whose attacker is **honest-but-curious**. Confidentiality harms often arise from _visibility_, not malice — an adversarial framing alone misses the baseline concern. See the **Passive Observer** vocabulary entry.
• **Verify "attacker does not have X" against the target platforms.** Every limitation must be factually true on every OS/runtime in scope. Common pitfall: assuming kernel-level privileges are required for a capability that is actually unprivileged on Linux and Windows (e.g., reading another process's environment). If the limit isn't true, the SD is mis-scoped.

Security Goals Component

State concise, testable guarantees about what cannot happen given the threat model. Reference specific assets (tokens, keys, vault data):

• "Valid tokens cannot be accessed by attacker after the user's client has logged out"
• "Attacker cannot retrieve any decrypted MasterKeys that do not belong to them"
• "Attacker can perform reads on encrypted email addresses lists only"

Every goal carries a **Rationale** — three pieces, one line each:

• **Principle** — which Bitwarden principle (P01–P06) the goal enforces. See `references/security-principles.md`.
• **Asset** — the specific data, key, or token being protected.
• **Harm** — the user-visible consequence if the goal is violated (e.g., "master password exposed to third-party LLM provider and potentially their training pipeline").

A goal without a rationale is a claim, not a requirement. Rationales let reviewers judge whether the goal is load-bearing or can be cut.

Two additional rules on goal framing:

• **Reality-check goals against runtime.** Goals that claim a secret is "cleared from memory", "zeroized", or "not retained" are unenforceable in garbage-collected, string-interned runtimes (JavaScript, .NET, JVM, Python). If the runtime cannot uphold the goal, restate it in terms of what the runtime _can_ guarantee (scope minimization, short-lived references, process isolation), or mark Accepted Goal Status as explicitly not met and link the systemic limitation. Do not write goals the language cannot back.
• **Pre