docs(threat-model): expand §9 into the authoritative threat model - #5
Merged
Conversation
The last Phase 0 deliverable. Expands the constitution's §9 seed into what
Setonix defends, against whom, and — the part that earns its keep — the
obligations the design is therefore bound to discharge.
Five assets, five adversaries, six trust boundaries (the seed's four plus
app/store from RFC-0001 and driver/hardware-DMA from the userspace-driver
decision), and twenty numbered obligations O-1..O-20. The numbering is the
point: an RFC for the capability table or the IPC fast path cites "this
mechanism discharges O-3 and O-4 at B1" and is checked against exactly
that, the same way rejected RFCs and superseded clauses are kept rather
than erased.
Every obligation carries an honest status. Three are Built today — kernel
memory safety (O-6, the unsafe policy the compiler enforces), the pinned
verified build (O-19), signed commits (O-20). Most are Designed: the
capability, isolation, broker, store and update obligations are the
specification the coming phases are measured against, not descriptions of
a system that already holds the line. Two are Deferred with stated reasons
— DMA confinement (O-18) cannot hold without an IOMMU, and that is a
hardware precondition, not a bug. §8 maps obligations to roadmap phases so
the three-of-twenty ratio is stated, not hidden.
Out of scope (§7) expands the seed's three exclusions with reasoning and
what would bring each in, and adds two the kernel structurally cannot
police: the consenting user (the broker informs, it cannot decide) and
whole-system flooding (the deployment's problem, not the kernel's).
Assumptions (§10) name what the model does not itself defend — sound
crypto, faithful silicon, a correctly-programmed IOMMU — so a reader knows
what a conclusion rests on.
Also, from a completeness sweep of the retired docs repository, two pieces
of guidance that described practices already followed but were written down
nowhere here: CONTRIBUTING gains "Amending the constitution" (no stale
clause, check cross-references, never renumber a cited section) and STYLE
gains a "Tables" rule. README and SECURITY pointers to the threat model go
from "to come" to live links.
CONSTITUTION TOUCHED — needs the maintainer's eye:
- The Status line said the threat model was "the last outstanding Phase 0
deliverable"; it would be false the moment this merges, so it now reads
"Phase 0 is complete". A factual status marker, not a clause, but it is
constitution text and yours to confirm or reword.
- §9's header still reads "(seed — to be expanded)". Left exactly as is:
whether to reword it now that the expansion exists is your call, and
§9's clauses are untouched and remain the seed and summary the document
expands.
Verified: spelling, markdown and pin gates clean across 52 files. Docs-only,
no Rust touched, so the build and boot are unaffected; CI runs the full
suite regardless.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The maintainer authorised the two constitutional touches flagged when the
threat model landed. Both are factual or pointer updates, not changes to
any clause, and both are logged in docs/CHANGELOG because constitutional
amendments always are.
- Status line: no longer calls the threat model "the last outstanding
Phase 0 deliverable" — false now that it exists — and states Phase 0
complete. (Already on this branch; confirmed as wanted.)
- §9 header: "(seed — to be expanded)" becomes "(seed; expanded in
docs/threat-model.md)". §9's body is untouched and remains the seed and
summary the full document expands; the header just stops promising an
expansion that now exists.
Gates clean across 52 files; no Rust touched.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
18 tasks
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
1 participant
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
The last Phase 0 deliverable. Expands the constitution's §9 seed into
docs/threat-model.md: five assets, five adversaries, six trust boundaries, and twenty numbered obligations O-1…O-20 the design must discharge. RFCs will cite obligations by number ("discharges O-3 at B1") and be checked against them — the capability, IPC and app-format designs are about to be argued on paper, and this is the paper they are argued against (§5.5).Every obligation carries an honest status: Built (3 today — memory safety, pinned build, signed commits), Designed (most), Deferred (2, with stated hardware preconditions). §8 maps them to roadmap phases so the three-of-twenty ratio is stated, not hidden — a threat model that described defences the code lacks would be the exact 'document that lies' failure we keep avoiding.
Also folds in two bits recovered from the retired docs repo (your ask): CONTRIBUTING § Amending the constitution, STYLE § Tables — both practices already followed, written down nowhere until now. Threat-model pointers in README/SECURITY go live.
Two lines, flagged rather than assumed:
Which pillar does this serve?
All five — the model is organised around defending each. But it is documentation toil (AI-first, §5.3); the design decisions it records are the constitution's, not new.
Borrow Ledger
No code. Lineage named throughout (seL4, KeyKOS/EROS, Fuchsia, Plan 9, QNX, Nix, Haiku), per the ledger's habit.
unsaferegisterunsafeblocks: None (documentation only)Checklist
docs/CHANGELOG.mdupdated🤖 Generated with Claude Code