Skip to content

docs(repo): the STRIDE threat model and the rule that keeps it current (#244) - #487

Merged
eribertocz merged 6 commits into
mainfrom
docs/244-threat-model
Nov 15, 2026
Merged

eribertocz merged 6 commits into
mainfrom
docs/244-threat-model

Conversation

@eribertocz

@eribertocz eribertocz commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Part of #244 (PR 1 of 2: the model and the rule; the threat-model check follows in PR 2).

Files and purposes

File Change Purpose
docs/architecture/threat-model.md new The STRIDE threat model of every reachable surface, its machine-read inventory and its gaps.
docs/architecture/security.md §7, §8, §9 added §7 points to the model and states the rule that keeps it current. §8 "Trust model: the instance administrator". §9 "Secrets, files and supply chain", which states rules the code already enforces and the model cites.
docs/roadmap.md §2, one item The phase-end rule for the threat model.
.github/pull_request_template.md Security section, one line Asks which threat-model rows the PR adds or changes.
docs/README.md two rows Indexes the model next to security.md, at the same rank.

Shared governance files touched, for coordination with #486: .github/pull_request_template.md (one appended line). This PR does not touch tools/ci/checks.toml or the ruleset; PR 2 will.

Case matrix

# Criterion Evidence
1 Six surfaces are modelled, each with assets, trust boundaries, entry points and one row or n/a: row per STRIDE category: http-api, access, project, lake, sources, build. The five required surfaces plus access, which the Owner's addition requires. 74 rows; every surface covers all 6 categories (script output below).
2 Every Rule exists, every Verification has an allowed form, and every openapi.yaml path is an entry point of http-api. All 28 paths are listed. Every security.md §n resolves to a heading, every ADR file exists, and every test path exists.
3 The inventory lists every HTTP path, package and contract directory. Compared with the repository, nothing is missing or extra.
4 roadmap.md §2, security.md and the PR template carry the rule. See the diff.
5 Every gap: row is listed. Next section.

The check of PR 2 (threat_model.py) was run against this commit and exits 0. The per-surface counts below come from the earlier ad hoc script:

inventory: missing set() extra set()
rows 74, duplicate IDs [], bad Rule/Verification []
per surface, STRIDE categories covered: 6 6 6 6 6 6

n/a: <reason> form. The Owner approved it on 2026-11-15, but only for threats that truly do not apply. No row uses it now: TM-SOURCES-3 cites audit evidence, and TM-BUILD-5 is a gap:.

Gaps found, for the Owner to decide which become issues

Row Gap Options
TM-ACCESS-14 The administrator can reset a user's password and sign in as that user. (a) the target confirms or is notified; (b) a reset cannot sign in until the user sets a password through a separate channel; (c) a two-person rule or break-glass flag; (d) an alert; (e) accept the documented risk.
TM-ACCESS-15 The administrator can link an OIDC identity they control to a user. (a) the target confirms or is notified; (b) a two-person rule or break-glass flag; (c) an alert; (d) accept the documented risk.
TM-ACCESS-16 The administrator can create a user and make it a project's first Builder. (a) a two-person rule when the project already holds data; (b) an alert; (c) accept the documented risk.
TM-ACCESS-19 The log test does not check the session id issued at sign-in, nor that the password change succeeded. Extend test_sign_in_http.py with both.
TM-SOURCES-3 No test records the query event of an answer read from ClickHouse or an existing lake. A delivery test on each Direct Query engine.
TM-SOURCES-9 No case covers masked or hidden members on ClickHouse or an existing lake. The columns scenarios on every Direct Query engine.
TM-HTTP-15 No request body size limit is applied before parsing. A limit at the server, or a documented limit at the reverse proxy.
TM-HTTP-18 No test asserts that a text filter or parameter value is bound, and not inlined into the compiled SQL. A test with a sentinel value on every engine adapter.
TM-HTTP-8 No test asserts that a newline or control character in a logged value stays inside its JSON line. A test on JsonFormatter with such values.
TM-BUILD-5 No documented way exists to release without the hosted runners. A documented local release procedure with the same attested artifacts, or accepting a delay bounded by the outage.
TM-BUILD-4 No secret scanner runs on pull requests. A scanner as a required check, or GitHub secret scanning with push protection.

The three TM-ACCESS gaps go to the release issue that precedes server mode in production. They are not fixed in #244. No issue is opened for any gap until the Owner decides (AGENTS.md §4).

Reviewer pass

First pass: changes requested. Second pass: one new finding (N-B1), fixed by splitting TM-HTTP-5 and declaring the injection test as gap TM-HTTP-18.

First pass details: B1–B10 and N1–N8 are fixed in the second commit. Nine rows cited evidence that did not prove the threat; each now cites the test that does, or is a gap: or a roadmap: row. Rows with several pieces of evidence are split. Missing threats are added: injection, path traversal of static files, session fixation and log injection. Every Rule now states its rule.

Third pass (fresh Reviewer, commit c36371f): findings F1–F6 fixed. F1 adds a cursor row with its own test. F2 limits the Direct Query row to row policies and adds column policies as a gap. F3 turns the Direct Query read record into a gap. F4 splits passwords from session ids. F5 turns the server-log row into a gap. F6 updates the counts.

Laws touched

  • Law 3, security by design: every reachable surface is analysed, and each threat has a rule and a test or a declared gap.
  • A6, no silent failures: the rule makes a new surface without analysis fail (enforced by PR 2).

Risk tier

B (documentation). Governed paths (docs/, PR template): owner-merge. Reviewer pass: one independent pass on the accuracy of every row's Verification.

https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf


Generated by Claude Code

#244)

One threat model for every reachable surface (HTTP API, access, project,
lake, sources, build), each threat tied to its rule and its test or a
declared gap; the instance administrator's identity powers made explicit;
the phase-end rule in the roadmap, security.md and the PR template.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
@eribertocz eribertocz added owner-merge Touches governed paths; only the Owner merges type:docs Documentation module:repo status:in-review Pull request awaiting verification risk:B labels Nov 15, 2026 — with Claude
Claude Code and others added 5 commits November 14, 2026 23:29
…244)

Reviewer findings B1-B10 and N1-N8: precise verifications, split rows,
missing threats added, rules stated in security.md §9.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
Owner review: source reads are audited (Direct Query and runs, each with
its evidence); a release without hosted runners is a declared gap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
Fresh review F1-F6: cursor and password rows split with their tests;
Direct Query records, Direct Query column policies and the sign-in session
id in the log declared as gaps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
@eribertocz
eribertocz merged commit 999a145 into main Nov 15, 2026
60 of 61 checks passed
@eribertocz
eribertocz deleted the docs/244-threat-model branch November 15, 2026 12:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

module:repo owner-merge Touches governed paths; only the Owner merges risk:B status:in-review Pull request awaiting verification type:docs Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant