Threat model

What Keel protects, who it protects it from, where the trust boundaries sit, which control answers each threat and the file that implements it, what stays as residual risk, and how to verify every control from a fresh shell. SECURITY.md is the short public version; this page is the working one.

Assets

Actors

Trust boundaries

1. Documents in. Files cross from "content someone wrote" to "chunks the model may see". Controls at the boundary: the injection screen (quarantine), tags applied from the manifest, checksum idempotence, and the PII redactor for a pass before ingest. Under air-gap, remote URLs are refused at load.
2. Users to requests. A person becomes a User(user_id, tags). In the 0.1.x build identity is self-asserted through the user picker; the boundary that holds is the machine's login and the loopback bind. Everything downstream (retrieval, tools, log) treats the tags as authoritative.
3. Retrieval to generation. Only chunks that pass the ACL check and are not quarantined are fused, reranked and placed in the prompt. Below min_relevance the engine refuses without calling the model.
4. The model to tools. Everything the model emits is untrusted. A proposed tool call meets the policy (allowlist, argument rules, write flag), then the registry validates arguments against the tool's schema, then the tool's own guard runs (AST-only arithmetic, SELECT-only SQL under a read-only authoriser and a step budget, host allowlist for HTTP). Write tools stop at the approval queue.
5. Admin. Approvals, quarantine release, ledger verify and export sit behind require_admin: open on loopback, token beyond it. The policy file and the database are files on disk behind the operating system's permissions.
6. The box to the network. With KEEL_AIRGAP=1 the process refuses outbound connections other than loopback and the named allow list. In the Azure profile the boundary is the VNet and private endpoints when enabled, and managed identity for every call.

Threats and controls

Residual risks

• Self-asserted identity in the 0.1.x build. A person at the machine can pick another user in the picker. The compensating control is physical: one appliance per business, loopback only, on a machine with the business's own login. Per-person login is the next release.
• Novel injection phrasings. The screen is a heuristic layer with an optional judge; a passage written to slip past both can reach the prompt. The blast radius is bounded by the ACL (the model sees only what the user may see anyway), the tool policy and the approval queue.
• Model correctness. A fluent misreading is still possible. Citations and the refusal gate reduce it; the eval harness measures it; the person reading the answer decides.
• The database file. SQLite is unencrypted at rest. Disk encryption and file permissions carry this risk; backups need the same care.
• In-process air-gap. Other processes and unusual connection paths are outside the guard. A host firewall or a --network none container gives the hard boundary.
• Ledger tail. A shorter chain that ends earlier still verifies. Recording the head hash outside the machine at each backup closes this.
• Availability. No rate limits; a CPU-bound model can be kept busy by one user. Acceptable for a single-business appliance; a reverse proxy with limits when exposure grows.
• Supply chain. The GGUF model, the ONNX embedding models and the Python dependencies are downloaded artifacts. Pin versions, record checksums, and build the container from a staged model cache for air-gapped hosts.
• Reporting exports. sql_readonly protects the appliance from writes and from unlisted tables; it cannot know whether an allowlisted table itself holds personal rows. Allowlist aggregate views only.

How to verify each control

Every command runs from the repository root with the project interpreter (.venv\Scripts\python.exe on Windows, .venv/bin/python elsewhere) and needs no network and no model server; integration tests skip on their own when llama-server is absent.