Skip to content

Spec Threat Model

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Threat Model

Part of the Technical Specification. Requirement prefix: THR (threats) and TM (process). Method: STRIDE per element over the C4 container view, with trust boundaries. Reviewed with every ADR that changes a container or a boundary.

1. C4 system context

flowchart TB
  Dev[Developer or application<br/>calls the API with a key]
  Op[Operator<br/>issues keys, reads usage]
  API[ViaFrei API<br/>keyed, read-only REST]
  Store[(ViaFrei platform storage<br/>owned by the platform,<br/>read through the read contract)]
  MCP[ViaFrei MCP server<br/>same facts for AI assistants]
  Dev -->|HTTPS| API
  Op -->|operator tool| API
  API -->|reads| Store
  MCP -->|reads| Store
Loading

2. C4 container view with trust boundaries

flowchart LR
  subgraph TB0[Boundary 0: Internet, untrusted]
    C[Client]
  end
  subgraph TB1[Boundary 1: Edge]
    E[TLS edge<br/>certificates, coarse per-IP guard]
  end
  subgraph TB2[Boundary 2: API container]
    A[API service<br/>auth, gate, limits, admission, use cases]
    MC[Metrics listener<br/>loopback only]
    CLI[Operator tool<br/>key lifecycle]
  end
  subgraph TB3[Boundary 3: Data tier]
    RC[(Read contract<br/>read-only role)]
    AS[(Access store<br/>keys, plans, audit, usage)]
  end
  subgraph TB4[Boundary 4: Build and release]
    CI[CI pipeline]
    REG[Image registry]
  end
  C -->|HTTPS| E -->|HTTP on a private interface| A
  A -->|read-only, statement timeout| RC
  A -->|own role| AS
  CLI -->|own role| AS
  CI -->|signed image with provenance| REG -->|pull, verify signature| A
Loading
Boundary What crosses it Trust assumption
0 → 1 Untrusted HTTPS requests None; everything is validated
1 → 2 Requests with a forwarded-for header Only the edge is a trusted proxy (server.trusted_proxies)
2 → 3 Parameterised reads; access-store writes Storage enforces role privileges independently of the service
4 → 2 Container images Only signed images with verified provenance are deployed

3. STRIDE per element

ID Element STRIDE Threat Mitigation (requirement) Residual
THR-001 Client → edge Spoofing Use of a stolen key Key prefix and checksum for secret scanning, rotation, immediate revocation, usage anomaly alert (SEC-041, SEC-042, OPS-012) Medium until detected
THR-002 Client → edge Tampering Man-in-the-middle TLS 1.2+/1.3 only, HSTS (PROT-002, NFR-SEC-001) Low
THR-003 Client → edge Denial of service Volumetric flood Edge per-IP guard, per-IP bucket, early refusal (RATE-001) Medium (no scrubbing service)
THR-004 API service Spoofing Key guessing 256-bit secrets, uniform 401, failure limit (SEC-003, SEC-052) Low
THR-005 API service Tampering Cursor or parameter manipulation to widen a query Signed cursors bound to filters; schema validation; bounded areas (ENV-023, NFR-SEC-002, FR-LOC-006) Low
THR-006 API service Repudiation Key holder denies usage Hourly usage per key; audit of lifecycle actions (RATE-014, SEC-044) Low
THR-007 API service Information disclosure Data served outside its licence Gate in the query plus post-check, default deny (SEC-030 to SEC-032) Low
THR-008 API service Information disclosure Internal names, stack traces or versions in errors Problem detail rules, scope lint, header rules (ERR-004, LIC-010, PROT-032) Low
THR-009 API service Information disclosure Keys in logs Redaction, planted-secret test (NFR-OBS-004) Low
THR-010 API service Denial of service Expensive queries (huge areas, long windows) Size and area limits, bounded windows, 2 s deadline with storage-side cancel, admission (NFR-SIZE-001, NFR-PERF-002) Low
THR-011 API service Denial of service Cache poisoning or cache blow-up Cache key includes the permitted-family set; byte-bounded cache; private responses (PROT-040, PROT-044) Low
THR-012 API service Elevation of privilege Calling an operation outside the plan's scope One scope per operation, checked before parameters (SEC-020, PROT-061) Low
THR-013 Metrics listener Information disclosure Metrics exposed publicly Loopback or operator network only (NFR-OBS-002) Low
THR-014 Read contract Tampering Injection writes to storage Read-only role, read-only transactions, parameterised statements (NFR-SEC-003, NFR-SEC-004) Very low
THR-015 Read contract Denial of service API starves other readers Connection limit and statement timeout at the role; pool = permits (NFR-CAP-002) Low
THR-016 Access store Information disclosure Theft of the key table Only MACs stored; pepper held outside the store (SEC-010) Low
THR-017 Access store Tampering Audit records altered Append-only for the service role (SEC-045) Low
THR-018 Operator tool Elevation of privilege Unauthorised key issue Tool runs only on the host with the access-store role; later console behind passkeys; every action audited (SEC-044) Low
THR-019 Build and release Tampering Compromised dependency or build Pinned actions, dependency review, SBOM, signed images, SLSA provenance, verification at deploy (SSC-001 to SSC-012) Medium (ecosystem risk)
THR-020 Browser client Information disclosure Key exposed in a browser app Documentation warning, CORS allow-list, per-key quotas limit damage (PROT-053, PROT-050) Accepted

Requirements

ID Requirement Verification
TM-001 The threat model MUST be reviewed with every change to a container, a trust boundary or the authentication model, and at least once per minor release. Review
TM-002 Every threat with residual risk above "low" MUST appear in the risk register ([[Spec: Risks, Assumptions and Constraints Spec-Risks-Assumptions-Constraints]]).
TM-003 Every mitigation MUST name a requirement id with a test. Review

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally