Skip to content

docs(limitations): add explicit boundaries guide based on #117 feedback #169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
naffee wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(limitations): add explicit boundaries guide based on #117 feedback #169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ed5701
docs(limitations): add explicit boundaries guide based on #117 feedback
naffee Jun 3, 2026
958740f
Merge upstream main to resolve conflicts
naffee Jun 3, 2026
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
73 changes: 31 additions & 42 deletions LIMITATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,48 @@
# Limitations
# Talon Security Boundaries & Limitations

Talon provides policy enforcement, routing controls, PII handling, and signed evidence records for AI gateway traffic. It does not determine legal compliance for an operator, and it does not prove that a downstream model, tool, or human decision was correct.

This page states plainly where Talon's claims stop. It applies to the network gateway / proxy path that every request flows through.
This document serves as an explicit boundaries guide so that operators and security teams can accurately evaluate Talon's trust model.

## Capability status
---

| Status | Capabilities |
|--------|--------------|
| **Available now** | OpenAI-compatible proxy governance; input and output PII scanning; OPA policy allow/deny decisions; HMAC-signed evidence records; `talon audit verify` |
| **Partial today** | EU routing and data sovereignty in the gateway path: a non-compliant route is **denied with signed evidence**, not silently re-routed across providers ([`internal/llm/router.go`](internal/llm/router.go)). The gateway proxy and the `talon run` router can differ on routing behavior. |
| **Roadmap** | Runtime tool **execution** interception via the MCP proxy; a filled-in auditor RoPA / EU AI Act Annex IV pack; broader trust mesh / agent-to-agent governance |
## Current Status Overview

This table is the source of truth for capability claims. If a demo or doc describes a "partial" item, it should not be presented as generally available.
| Capability | Status | Description |
| :--- | :--- | :--- |
| **Available Now** | ✅ | Proxy governance, input/output PII scan, policy decision, signed evidence, audit verify. |
| **Partial Today** | 🟡 | EU routing proof is currently deny/allow evidence, not silent rerouting. |
| **Roadmap** | ⏳ | Runtime tool execution interception, full auditor pack, broader trust mesh/A2A. |

## Compliance boundary
---

- Talon provides supporting controls and evidence — for example, framework-mapped reports via `talon compliance report`. A report is a control-mapping summary, not a completed legal filing.
- The operator remains responsible for the legal and compliance determination.
- We use "supports evidence for GDPR Art. X" style wording, never "GDPR compliant" or "makes you compliant" (the built-in article mappings live in [`internal/compliance/mapping.go`](internal/compliance/mapping.go)).
- PII detection is regex- and heuristic-based. It supports GDPR Art. 32-style controls but does not guarantee complete recall.
## 1. Compliance Boundary

## Evidence boundary
**Talon provides supporting controls and evidence.**
- The operator remains entirely responsible for legal and compliance determinations.
- Talon produces cryptographic receipts that assist with audits. It does not make an organization automatically compliant with GDPR, NIS2, or the EU AI Act.

A valid signature proves that this evidence record was signed with the deployment's configured key and — assuming that key remains protected — has not been modified since signing. It does not prove that the policy, model response, tool result, or operator decision was correct.
## 2. Evidence Boundary

- Verify a record with `talon audit verify <id>` or `talon audit verify --file <export>` — see [evidence store](docs/explanation/evidence-store.md).
- The signature covers the canonical JSON of the stored fields ([`VerifyRecord`](internal/evidence/store.go)). It is not instance attestation, and it does not vouch for upstream provider behavior.
**HMAC proves record integrity and tamper evidence.**
- The signature proves that the request passed through the gateway and that the logged payload was not maliciously altered after the fact.
- It **does not** prove that the policy configured was correct, that the model's response was safe or hallucination-free, or that the operator configured the right security controls.

## Tool-governance boundary
## 3. Tool-Governance Boundary

- Today, forbidden tools are stripped from request bodies before forwarding ([`internal/gateway/tool_filter.go`](internal/gateway/tool_filter.go)); the README "pre-execution filter" wording reflects this.
- Talon does not prevent the same tool from being invoked on a separate path that does not pass through Talon.
- Not yet: runtime execution interception or per-execution MCP tool-call governance with a signed deny.
- "Tool governance: Yes" in the README comparison means request-body filtering today, not runtime execution control.
**Today: Forbidden tools are filtered from request bodies before forwarding.**
- Talon prevents the model from ever seeing forbidden tools by stripping them from the initial request JSON.
- **Not yet:** Talon does not currently provide runtime execution interception or full MCP tool-call governance. These are planned for future roadmap epics.

## Isolation boundary
## 4. Isolation Boundary

- Talon applies process-level controls inside a single binary. It is not an OS or kernel sandbox, and it does not ship a gVisor, Kubernetes-operator, or container-escape isolation layer — these are deliberate non-goals for the current scope.
- Host hardening remains the operator's responsibility.
- LLM and MCP providers and any external tools are separate trust boundaries. Talon does not secure vendor infrastructure.
**Talon provides process-level controls only.**
- Talon is **not** an OS-level or kernel sandbox.
- External tools and providers remain completely separate trust boundaries and must be secured accordingly.

## Deployment and key-management assumptions
## 5. Deployment and Key-Management Assumptions

- Custody, rotation, and backup of `TALON_SIGNING_KEY` are operator responsibilities ([`NewSigner`](internal/evidence/signature.go) requires a key of at least 32 bytes).
- Provider registry and EU routing claims depend on accurate configuration (`.talon.yaml` and gateway config).
- Air-gapped deployment and an auditor-grade export pack are roadmap items unless explicitly documented as live.
- When Talon sits on the critical path, availability and failover are not yet claimed as production-grade.

## Further reading

- [ROADMAP.md](ROADMAP.md) — public anti-goals, wedge focus, and phased direction
- [SECURITY.md](SECURITY.md) — security boundaries and threat-model snapshot
- [Evidence store](docs/explanation/evidence-store.md) — how records are created, signed, and verified
- [Evidence integrity specification](docs/reference/evidence-integrity-spec.md) — byte-exact fields, serialization, signing, and independent verification
- [Threat model](docs/reference/threat-model.md) — attack surface, trust boundaries, and key-management assumptions
- [Reproducible benchmarks](docs/reference/benchmarks.md) — run `make benchmarks` on your hardware; retry/fallback overhead not included until Epic #113 lands.
- [Sample auditor pack](examples/auditor-pack/README.md) — example signed export and compliance report (`make auditor-pack`)
**Evidence signing depends on operator-controlled key handling.**
- The cryptographic guarantees of Talon's evidence records rely on the operator securing the signing keys.
- Provider registry and routing claims depend entirely on accurate provider configuration by the operator.
- Air-gapped deployments and full auditor-pack claims should be considered roadmap items unless marked as explicitly live.
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
[Quickstart](docs/tutorials/proxy-quickstart.md) ·
[Docker demo](examples/docker-compose/README.md) ·
[Dashboard](docs/reference/gateway-dashboard.md) ·
[Limitations](LIMITATIONS.md) ·
[Releases](https://github.com/dativo-io/talon/releases/latest)

Talon is a single Go binary that sits in front of OpenAI, Anthropic, AWS Bedrock, Azure OpenAI, and any OpenAI-compatible client. Change one URL and every request is policy-checked, PII-scanned, cost-tracked, and written to a tamper-evident, HMAC-signed evidence record — same SDK, same response shape, governed path. Built for EU teams that need real governance signals for GDPR, NIS2, DORA, and the EU AI Act. Apache 2.0.
Expand Down Expand Up @@ -331,6 +332,7 @@ Artifacts a skeptical reviewer can grep in one session:
- [Documentation index](docs/README.md)
- [60-second demo](docs/tutorials/quickstart-demo.md)
- [Your first governed agent](docs/tutorials/first-governed-agent.md)
- [Talon Security Boundaries & Limitations](LIMITATIONS.md)
- [What Talon does to your request](docs/explanation/what-talon-does-to-your-request.md)
- [Policy cookbook](docs/guides/policy-cookbook.md)
- [Provider registry](docs/reference/provider-registry.md)
Expand Down