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.mdPart III owns a populated copy atdocs/<domain>/security/<subsystem>-threat-model.md. The header above is mandatory; reviewers fromeng-platformandeng-securitymust 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>/...andapps/<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.
[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.
[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.mdand 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.
- [FILL IN: e.g. "Attacker forges JWT with
tier=enterpriseclaim."] - [FILL IN: e.g. "BFF accepts the JWT; quota middleware reads tier from JWT
instead of
tenant_db."] - [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-securityhas approved the PR (or a linked review doc). -
eng-platformhas 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
CriticalorHighrow 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.