Skip to content

docs: publish threat model & trust boundaries (#118)#162

Merged
sergeyenin merged 1 commit into
mainfrom
docs/threat-model-118
Jun 3, 2026
Merged

docs: publish threat model & trust boundaries (#118)#162
sergeyenin merged 1 commit into
mainfrom
docs/threat-model-118

Conversation

@sergeyenin
Copy link
Copy Markdown
Contributor

@sergeyenin sergeyenin commented Jun 3, 2026

Summary

Adds a published threat model (proof-bar area 3) so an enterprise security reviewer can map Talon's boundaries without contacting us.

  • docs/reference/threat-model.md — STRIDE-style:
    • Mermaid data-flow diagram of the gateway path with the host/binary trust zone.
    • Six trust boundaries: caller↔gateway, gateway↔provider, gateway↔MCP tool, operator↔host/process, admin plane, and at-rest SQLite stores.
    • Assets table, per-boundary controls, and a STRIDE threats/mitigations table with explicit residual risk.
    • Key management: TALON_SIGNING_KEY / TALON_SECRETS_KEY / TALON_ADMIN_KEY — location, "set explicitly in production" (defaults are per-machine derived), rotation semantics (historical evidence verifies only under its original signing key), and blast radius.
    • HMAC does/does not prove (integrity under key custody, not correctness; symmetric, not third-party non-repudiation).

Cross-linked from SECURITY.md (expands the existing snapshot), the docs index (Reference + Proof Pack), and LIMITATIONS.md (no longer "forthcoming"). Claims grounded in internal/{gateway,evidence,secrets,policy,classifier}.

Closes #118.

Test plan

  • Claim-discipline guard passes.
  • All referenced source files and doc links verified to resolve.
  • Docs workflow (link check + claim guard) passes in CI.
  • Mermaid diagram renders on GitHub.

Note

Low Risk
Documentation-only change; no runtime, auth, or data-path behavior is modified.

Overview
Publishes docs/reference/threat-model.md so reviewers can map Talon’s gateway attack surface without maintainer contact. The doc adds a Mermaid data-flow diagram, six trust boundaries, an assets table, per-boundary controls, a STRIDE threats/mitigations table (with residual risk), operator key guidance for TALON_SIGNING_KEY / TALON_SECRETS_KEY / TALON_ADMIN_KEY, and a clear HMAC does/does not prove section.

Cross-links replace “forthcoming” in LIMITATIONS.md with a link to the new doc, point SECURITY.md at the full model from the existing snapshot, and index the page under Reference and Proof Pack in docs/README.md.

Reviewed by Cursor Bugbot for commit b0bf9f3. Configure here.

Add a STRIDE-style threat model so a security reviewer can map Talon's
boundaries without contacting us:

- docs/reference/threat-model.md: data-flow diagram of the gateway path,
  six trust boundaries (caller, provider, MCP tool, host/process, admin
  plane, at-rest stores), an assets table, per-boundary controls, a STRIDE
  threats/mitigations table, key-management assumptions (signing/secrets/
  admin keys: location, set-explicitly-in-prod, rotation, blast radius),
  and the integrity-not-correctness statement for the HMAC signature.

Cross-linked from SECURITY.md (expands the existing snapshot), the docs
index (Reference + Proof Pack), and LIMITATIONS.md (no longer
"forthcoming"). Claims are grounded in internal/{gateway,evidence,secrets,
policy,classifier}.

Closes #118
@sergeyenin sergeyenin merged commit 4bb4d5f into main Jun 3, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Publish threat model & trust boundaries

1 participant