Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Closes #<!-- n -->

## Security (if applicable)
<!-- Threat model: what is protected, from whom, how it is tested. -->
Threat-model rows added or changed (`docs/architecture/threat-model.md`), or "none":

## Risks

Expand Down
3 changes: 2 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ When two documents contradict each other, the higher item wins. A contradiction
|---|---|---|
| 1 | Product laws — [`product/laws.md`](product/laws.md) §1 (laws 1, 2, 3, 5 rank above the other laws) | Owner |
| 2 | Anti-patterns — [`product/laws.md`](product/laws.md) §2 | Owner |
| 3 | Security model — [`architecture/security.md`](architecture/security.md) | Owner |
| 3 | Security model — [`architecture/security.md`](architecture/security.md), with its threat model [`architecture/threat-model.md`](architecture/threat-model.md) | Owner |
| 4 | Accepted ADRs — [`adr/`](adr/README.md) (a later ADR supersedes an earlier one only if it says so explicitly) | Owner |
| 5 | Design principles — [`product/laws.md`](product/laws.md) §3 | Owner |
| 6 | Architecture, process and module documents — [`architecture/`](architecture/), [`process/`](process/), [`modules/`](modules/README.md), [`roadmap.md`](roadmap.md) | Owner |
Expand All @@ -32,6 +32,7 @@ When two documents contradict each other, the higher item wins. A contradiction
| Architecture | [`architecture/semantic-engine.md`](architecture/semantic-engine.md) | The core: pipeline, correctness, parity with SEF, capabilities S1–S6, conformance corpus |
| Architecture | [`architecture/transformation.md`](architecture/transformation.md) | Sources, SQL models, incremental loading, freshness, audits, DuckLake |
| Architecture | [`architecture/security.md`](architecture/security.md) | Identity, roles, groups, page/row/column security, audit, AI access |
| Architecture | [`architecture/threat-model.md`](architecture/threat-model.md) | STRIDE threat model of every reachable surface, its inventory and its gaps |
| Architecture | [`architecture/frontend.md`](architecture/frontend.md) | Components, the matrix, dashboards, design direction |
| Architecture | [`architecture/traceability.md`](architecture/traceability.md) | Receipts, lineage, run records, reproducibility, caching |
| Modules | [`modules/README.md`](modules/README.md) | **Context packs**: what to read for each module and phase |
Expand Down
29 changes: 29 additions & 0 deletions docs/architecture/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,3 +137,32 @@ column_policies:
## 6. Security conformance suite

`conformance/security/` contains negative tests that must always fail to access data: page access bypass, row-policy removal through filters, LOD and context modifiers, cache reuse across users with different permissions, export of hidden columns, possible-values leakage, MCP queries outside permissions, missing-attribute fail-closed, and the Direct Query cases of ADR-0027 §6 on every enabled engine. It runs on every pull request that touches `semantic`, `access`, `dashboards`, `mcp` or `server`.

## 7. Threat model

[`threat-model.md`](threat-model.md) is the STRIDE model of every reachable surface. Each threat there is tied to a rule in this document, an ADR or a law, and to the test that proves it, or it is declared as a `gap:`.

**The rule.** The model changes in the same pull request that changes a surface:
- **New surfaces:** a new HTTP path, package or contract directory gets an `inventory` line, and a new surface gets its section.
- **CI:** the `threat-model` check fails when the inventory and the repository disagree.
- **Phase end:** at each phase end, the model covers every surface the phase added and every `gap:` row is listed in the release issue.

## 8. Trust model: the instance administrator

The instance administrator is trusted with identities, not with data (§3.1). Even so, three paths let an administrator come to act as a user who has data access:
- resetting that user's password and signing in with the temporary password;
- linking an OIDC identity the administrator controls to that user;
- creating a user they control and making it a project's first Builder.

Each path is audited (`user.password_reset`, `user.oidc_linked`, `user.created`, `membership.added`), and none is refused. Their evaluation before production is in `threat-model.md` (`TM-ACCESS-14` to `TM-ACCESS-16`).

## 9. Secrets, files and supply chain

- **Secrets** come only from the environment, named by `connections.yaml`. A literal password in a project file is refused without being echoed. No secret reaches an error, a run record or a log.
- **Files the server reads** from a project are regular files, never symbolic links, and bounded in size and nesting. The static files it serves stay inside the web build.
- **Logs** are JSON lines, one event per line.
- **Supply chain.**
- Every workflow action is pinned by commit SHA.
- A workflow is read-only unless its job lists its write permissions.
- Every build makes and checks an SBOM.
- A release publishes its wheels and SBOM with attestations, and only the publish job signs.
Loading
Loading