docs: publish threat model & trust boundaries (#118)#162
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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: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.Cross-linked from
SECURITY.md(expands the existing snapshot), the docs index (Reference + Proof Pack), andLIMITATIONS.md(no longer "forthcoming"). Claims grounded ininternal/{gateway,evidence,secrets,policy,classifier}.Closes #118.
Test plan
Note
Low Risk
Documentation-only change; no runtime, auth, or data-path behavior is modified.
Overview
Publishes
docs/reference/threat-model.mdso 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 forTALON_SIGNING_KEY/TALON_SECRETS_KEY/TALON_ADMIN_KEY, and a clear HMAC does/does not prove section.Cross-links replace “forthcoming” in
LIMITATIONS.mdwith a link to the new doc, pointSECURITY.mdat the full model from the existing snapshot, and index the page under Reference and Proof Pack indocs/README.md.Reviewed by Cursor Bugbot for commit b0bf9f3. Configure here.