Repository navigation
Spec Threat Model
mavrovde edited this page Nov 1, 2026
·
1 revision
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.
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
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
| 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 |
| 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 |
| 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 |
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference