Eve library

Threat Model — `<SUBSYSTEM-NAME>`

Guide

Revision 1

On this page

Status: Draft | Active | Deprecated  Date: <YYYY-MM-DD>  Owner: eng-<domain>  Reviewers: eng-platform, eng-security  Backlog item: <V1-P2-NNNN>  Methodology: STRIDE

This file is the V1-P2-0373 threat-model template. Every Tier-A subsystem in docs/releases/v1/specs/todos-p2.md Part III owns a populated copy at docs/<domain>/security/<subsystem>-threat-model.md. The header above is mandatory; reviewers from eng-platform and eng-security must sign off (PR approval) before the doc moves from Draft to Active. Empty [FILL IN] blocks are not acceptable in an Active threat model.

1. Subsystem at a glance#

  • Purpose. [FILL IN: one-sentence summary, identical to §1 of the subsystem's runbook.]
  • Code locations. [FILL IN: libs/<x>/... and apps/<x>/... paths.]
  • External callers. [FILL IN: every domain or external client.]
  • External dependencies. [FILL IN: every vendor API + every shared infrastructure component.]
  • Operating runbook. [FILL IN: link to the subsystem's runbook generated from runbook-template.md (V1-P2-0372).]
  • Cross-references.
    • architecture-overview.md — the canonical Phase-2 data flows; this threat model focuses only on the flows that pass through this subsystem.
    • isis-cost-tracking-contract.md — for any subsystem that issues paid provider calls, the cost-tracking contract is the authoritative quota policy.
    • crypto-replacement-targets.md — for subsystems that currently use stub crypto, this lists the migration path that this threat model must require by the time it goes Active.

2. Assets#

A threat model is a list of bad things that could happen to the assets this subsystem processes. List every asset at the granularity an attacker would target.

Asset Classification Description Owner Impact if compromised
[FILL IN: e.g. "User session tokens"] [FILL IN: Restricted/Confidential/Internal/Public] [FILL IN] [FILL IN: domain] [FILL IN: account takeover, session hijack]
[FILL IN] [FILL IN] [FILL IN] [FILL IN] [FILL IN]

Classification levels.

  • Restricted — secrets, keys, password hashes, payment credentials. Loss is "stop the world" severity.
  • Confidential — user-private data (PII, conversations, biometrics, generated content with provenance).
  • Internal — non-public configuration and operational state.
  • Public — published platform data (course catalog, marketplace listings).

3. Trust boundaries#

Reproduce or reference the trust boundaries documented in architecture-overview.md § Trust boundaries. Then document any subsystem-specific boundaries.

text
[FILL IN: subsystem-specific trust-boundary diagram. Use ASCII or
Mermaid. Mark every boundary that an attacker must cross to reach an
asset listed in §2. Annotate each boundary with the authentication
mechanism (JWT / mTLS / signed event / Vault token) and the
authorisation mechanism (RBAC scope / tenant ownership check).]

4. Data flow diagram#

A DFD is the visualisation of how data, requests, and credentials move through the subsystem. Mark every place data crosses a trust boundary (§3) — those are the canonical attack surfaces.

text
[FILL IN: Mermaid or ASCII DFD. Each node is a process / data store;
each edge is a data flow labelled with what is on the wire (request
shape, encoding, auth mechanism). Trust boundaries are annotated
where edges cross them.]

Tip. Copy the relevant slice from architecture-overview.md and specialise. If the subsystem is part of the LLM gateway flow, copy the "Caller → IsisLLMClient → Provider" diagram and mark every credential store and trust boundary on it.

5. STRIDE threat analysis#

For each STRIDE category, list every applicable threat. A category with zero threats must be justified — at minimum write _Not applicable because <reason>_. Empty categories are a code smell that the analysis is incomplete.

5.1 Spoofing — pretending to be someone else#

ID Threat Affected asset Vector Likelihood Severity Mitigation Detection
S1 [FILL IN: e.g. "Forged JWT bypasses BFF auth"] [FILL IN: ref §2 row] [FILL IN: e.g. "Stolen JWT signing key + replay before expiry"] [FILL IN: Low/Med/High] [FILL IN] [FILL IN: e.g. "JWT signed by auth-orchestrator only; key in Vault, rotated every 90d; aud + iss claim binding to tenant"] [FILL IN: e.g. "Sigma rule on auth log; anomaly detection on iss mismatch"]
S2 [FILL IN] [FILL IN] [FILL IN] [FILL IN] [FILL IN] [FILL IN] [FILL IN]

5.2 Tampering — altering data in transit or at rest#

ID Threat Affected asset Vector Likelihood Severity Mitigation Detection
T1 [FILL IN: e.g. "Subscriber projects forged event"] [FILL IN] [FILL IN: e.g. "Compromised producer service publishes spoofed event with arbitrary payload"] [FILL IN] [FILL IN] [FILL IN: e.g. "Event envelopes signed by source domain (V1-P2-0176 crypto replacement); subscriber verifies signature before applying; reject on bad signature"] [FILL IN: e.g. "Counter alert on signature_verification_failed"]
T2 [FILL IN] [FILL IN] [FILL IN] [FILL IN] [FILL IN] [FILL IN] [FILL IN]

5.3 Repudiation — denying having performed an action#

ID Threat Affected asset Vector Likelihood Severity Mitigation Detection
R1 [FILL IN: e.g. "User denies submitting a generation request that consumed quota"] [FILL IN] [FILL IN: "Audit gap — request not logged with user identity"] [FILL IN] [FILL IN] [FILL IN: "BFF logs every request with correlationId + userId + idempotency key; logs immutable for 90d in Loki"] [FILL IN: "Customer support tooling correlates correlationId to the audit row"]

5.4 Information Disclosure — exposing data to unauthorised parties#

ID Threat Affected asset Vector Likelihood Severity Mitigation Detection
I1 [FILL IN: e.g. "Cross-tenant query in domain DB"] [FILL IN] [FILL IN: "Missing tenant_id filter in query lets one tenant read another's rows"] [FILL IN] [FILL IN] [FILL IN: "Drizzle query helpers always inject tenant_id from request context (V1-P2-0233); RLS enforced at PostgreSQL layer; integration test asserts cross-tenant fetch returns 0 rows"] [FILL IN: "Query log scans for missing tenant_id filter; anomaly alert on per-tenant row counts"]
I2 [FILL IN: e.g. "Vendor API key leak in logs"] [FILL IN] [FILL IN: "Stack trace or error response includes the bearer token"] [FILL IN] [FILL IN] [FILL IN: "@oshun/http-client redacts Authorization headers in logs by default; pino redact config covers known secret keys; external-api-guard (V1-P2-0358) enforces wrapped calls"] [FILL IN: "Loki query alert on Authorization-header-shape strings"]

5.5 Denial of Service — making the subsystem unavailable#

ID Threat Affected asset Vector Likelihood Severity Mitigation Detection
D1 [FILL IN: e.g. "Per-tenant cost-quota bypass"] [FILL IN] [FILL IN: "Bug or stub in cost-tracking middleware (V1-P2-0005) lets one tenant consume the platform-wide cost ceiling"] [FILL IN] [FILL IN] [FILL IN: "Quota check is enforced at gateway layer; deterministic-mode unit test asserts refusal at boundary; platform-wide ceiling per runbook §7.2 short-circuits before vendor call"] [FILL IN: "Cost-quota burn panel (Grafana isis/generation-pipeline.json); per-tenant burn-rate alert"]
D2 [FILL IN: e.g. "Subscriber backlog stalls projection"] [FILL IN] [FILL IN: "Slow downstream blocks all subscribers on the same consumer group"] [FILL IN] [FILL IN] [FILL IN: "Per-event-type consumer group; idempotent handlers; PXSEEK / XAUTOCLAIM for stalled members"] [FILL IN: "Stream lag alert at 10× SLO; runbook §10 playbook"]

5.6 Elevation of Privilege — gaining unauthorised access#

ID Threat Affected asset Vector Likelihood Severity Mitigation Detection
E1 [FILL IN: e.g. "Free-tier tenant escalates to Enterprise quota"] [FILL IN] [FILL IN: "Tenant claim in JWT not re-checked on every quota call"] [FILL IN] [FILL IN] [FILL IN: "Tier resolution from authoritative tenant_db per request (cache TTL ≤ 60s); cost-tracking middleware refuses on missing tier"] [FILL IN: "Audit log scan for tier transitions outside the upgrade flow"]
E2 [FILL IN: e.g. "Worker container reads another domain's secrets"] [FILL IN] [FILL IN: "Vault role mis-bound to wider scope"] [FILL IN] [FILL IN] [FILL IN: "Vault roles scoped per service; least-privilege ACL; CI scan on Vault policy diffs"] [FILL IN: "Vault audit log alert on cross-domain secret reads"]

6. Threat scenarios#

A scenario is a step-by-step walk-through of how an attacker chains threats from §5. Document at least three high-priority scenarios (one per "loss-of-everything" asset).

6.1 Scenario — [FILL IN: short title, e.g. "Cost-quota bypass via free-tier escalation"]#

Pre-conditions. [FILL IN: e.g. "Attacker has a free-tier tenant and a stolen JWT signing key from a separate compromise."]

Steps.

  1. [FILL IN: e.g. "Attacker forges JWT with tier=enterprise claim."]
  2. [FILL IN: e.g. "BFF accepts the JWT; quota middleware reads tier from JWT instead of tenant_db."]
  3. [FILL IN: e.g. "Attacker burns the daily platform-wide cost ceiling in 4 minutes via parallel LLM calls."]

Impact. [FILL IN: e.g. "$1,500 vendor cost; legitimate tenants served 503 until cap is raised; status-page incident."]

Mitigations engaged. [FILL IN: refer to S1 + E1 + D1 from §5.]

Residual risk. [FILL IN: state what's still possible after the mitigations land. e.g. "If JWT key leaks AND tenant_db is unreachable (graceful-degradation path), middleware fails-open to JWT tier — risk reduced to ≤ a vendor outage window."]

6.2 Scenario — [FILL IN]#

…

6.3 Scenario — [FILL IN]#

…

7. Risk register#

The risk register is the executive-summary view: every threat from §5 plotted on the L×S matrix.

ID Threat (1-line) Likelihood Severity Risk Owner Status Linked PRs / tickets
S1 [FILL IN] [FILL IN] [FILL IN] [FILL IN: L×S → Low/Med/High/Critical] [FILL IN] [FILL IN: Open / Mitigating / Closed / Accepted] [FILL IN: V1-P2-NNNN, PR#NNNN]

Risk policy.

  • Critical (L=High, S=High) — block release until mitigated.
  • High — must have a backlog ticket and a target sprint.
  • Medium — quarterly review; can ship with documented residual risk.
  • Low — annual review; tracked in this register only.
  • Accepted — explicit business-stakeholder sign-off required, with the rationale captured in §8.

8. Accepted risks#

Risks that the business has explicitly chosen to accept rather than mitigate. Each line requires sign-off from eng-security and the domain lead.

ID (§7) Rationale Accepted by Date Re-review trigger
[FILL IN] [FILL IN] [FILL IN: name + role] [FILL IN] [FILL IN: e.g. "On the next vendor SLA renegotiation"]

If §8 is empty, write _None — every threat in §7 is being actively mitigated._

9. Security controls inventory#

Cross-cutting controls that mitigate multiple threats from §5. List every control, where it lives, and the threats it covers.

Control Location Threats mitigated Verification
@oshun/http-client retry + circuit breaker + telemetry libs/shared/http-client/ I2, D1, D2 (vendor-side disclosure / DoS) external-api-guard CI workflow (V1-P2-0358)
Allow-listed stub-indicator scanner scripts/stub-indicator-scan.sh + .github/workflows/stub-indicator-scan.yml T1, I1 (forged stub data leaking into prod) stub-indicator-scan CI (V1-P2-0350/0351)
Test-coherence reporting scripts/test-coherence-check.mjs T1, S1 (test asserting only shape — would pass against stub) test-coherence-check CI (V1-P2-0352)
Cost-tracking quota middleware libs/isis/llm-providers/quota.ts D1, E1 (cost DoS, tier escalation) Integration test in domain CI
Vault-scoped secret roles infra/vault/policies/<domain>.hcl I2, E2 (secret leak, cross-domain access) Vault audit log + Terraform CI
Event envelope signing (post V1-P2-0176) libs/aje/sign T1 (event tampering) Subscriber CI integration test
[FILL IN: subsystem-specific control] [FILL IN] [FILL IN] [FILL IN]

10. Detection and monitoring#

Every mitigation in §5 should reference an alert or audit query that catches the threat if it materialises. Aggregate them here.

Signal Threat IDs Where it fires Runbook anchor
[FILL IN: e.g. "auth.log → iss_mismatch_count"] S1 [FILL IN: e.g. "Loki query in oshun/platform-overview.json"] [FILL IN: link to runbook §9 row]
[FILL IN] [FILL IN] [FILL IN] [FILL IN]

For incident-response procedures (paging, IC, comms), use the runbook generated from runbook-template.md (V1-P2-0372). The threat model lives one level higher — it tells you what could go wrong; the runbook tells you what to do when it does.

11. Cryptography#

For subsystems on the V1-P2-0176 crypto-replacement path, document where each primitive currently sits and where it's heading.

Use case Today Target Migration ticket
[FILL IN: e.g. "User session token signing"] [FILL IN: e.g. "stub HMAC in libs/aje/sign"] [FILL IN: e.g. "Ed25519 via libsodium binding"] [FILL IN: V1-P2-NNNN]

If §11 is empty for this subsystem, write _Subsystem does not handle cryptographic primitives directly; see crypto-replacement-targets.md (V1-P2-0176) for the platform-wide migration plan._

12. Verification — threat-model completeness#

Before the threat model is marked Active, the domain owner must verify:

  • Every [FILL IN] placeholder above has been replaced with a concrete value.
  • All six STRIDE categories in §5 have at least one row, OR an explicit _Not applicable because <reason>_ justification.
  • At least three §6 scenarios are written, each ending in a "Residual risk" statement.
  • Every row in §7 maps to a backlog ticket (Open or Mitigating) or an §8 accepted-risk row with sign-off.
  • Every §9 control row has a verification source (CI workflow name, test path, or audit query) that a reviewer can execute.
  • eng-security has approved the PR (or a linked review doc).
  • eng-platform has approved the PR.

A threat model that fails any of these checks is Status: Draft and cannot be cited as authoritative during a security review.

13. Re-review cadence#

Living document — review at:

  • Quarterly — refresh §7 risk register, §8 accepted risks, §10 detection coverage.
  • On significant change — any of the following triggers an immediate review:
    • New external dependency added in §1.
    • Trust boundary in §3 changes shape.
    • A Critical or High row is added to §7.
    • A scenario in §6 fires in production.

14. Change log#

Date Author Change
<YYYY-MM-DD> <github handle> Initial fill from docs/releases/p2/threat-model-template.md (V1-P2-0373).

This template is the source of truth for threat-model structure. When the template changes, every existing threat model is reviewed within 30 days for sections that need backfill. The §14 change-log is the audit trail.