diff --git a/DOCUMENTATION_INDEX.md b/DOCUMENTATION_INDEX.md index 6402ca1..16a603f 100644 --- a/DOCUMENTATION_INDEX.md +++ b/DOCUMENTATION_INDEX.md @@ -82,6 +82,7 @@ scope-honesty box and makes no compliance/regulatory claim. | [`docs/SPEC.md`](docs/SPEC.md) | **MCP Lock Format v1** — the vendor-neutral, self-contained format specification any tool can implement: on-disk `warden.lock` schema, RFC 8785 (JCS) canonicalization, SHA-256 `sha256:` hashing, `overall_digest` construction, the normative drift class + severity table, the optional per-tool inspection block, and a Conformance section + worked example. `WARDEN_LOCK_SCHEMA.md` is the mcp-warden implementation of this format | | [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) | **(v0.1)** Positioning, trust model (TOFU + `--approve`), assets/actors, the four threat classes (MCP-DRIFT / MCP-CAPSURF / MCP-SECRET / MCP-SUPPLY), explicit out-of-scope limits, deliberate cuts | | [`docs/THREAT_MODEL_V2.md`](docs/THREAT_MODEL_V2.md) | **(v0.2)** Addendum extending the v0.1 model: T-RESULT vectors, the defends (BLOCK) / monitors (fuzzy) / still-does-NOT-defend (T-BEHAVE) table, runtime trust-model notes, retained + added cuts, shadow-default positioning | +| [`docs/AGENT_TRUST_KERNEL.md`](docs/AGENT_TRUST_KERNEL.md) | **(DSE-714, design contract)** Normative invariants for the future deterministic Agent Trust Kernel: trust boundaries, complete mediation, default deny, non-overridable critical classes, evidence-before-effect, offline operation, residual risks, and bindings for DSE-715 through DSE-717. MCP-Warden v1.1 is explicitly not yet ATK-conformant | | [`docs/WARDEN_LOCK_SCHEMA.md`](docs/WARDEN_LOCK_SCHEMA.md) | **mcp-warden implementation of [`docs/SPEC.md`](docs/SPEC.md) (MCP Lock Format v1).** `warden.lock` format, RFC 8785 canonicalization + SHA-256 hashing, field/entry/overall digests, the normative drift definition + severities; **§5.1/§6.2 structural schema diff** (normalized per-tool `schema_skeleton`, `schema_version` 3 — skeleton added at v2, in-document `$ref` resolution at v3 (#29), granular `WRD-DRIFT-SCHEMA-*` taxonomy + severities, v1 fallback); **§8.1/§8.2 (v0.3, #19)** structured out-of-digest provenance (`pinner` / `attestations` / `rotation_count`, `PROVENANCE_VERSION`, B4 `bound_digest` format) + `lock rotate` digest-invariant semantics + the #16 signing implication; **§11 (v0.2)** optional per-tool inspection policy (`expected_output_charset` / `may_return_urls` / `secret_echo_applies`, fail-safe defaults, digest impact) | | [`docs/WARDEN_LOCK_EXAMPLE.md`](docs/WARDEN_LOCK_EXAMPLE.md) | Illustrative full `warden.lock` + a post-`lock rotate` `pin` block (archived from WARDEN_LOCK_SCHEMA §9 to keep that core doc under the line cap) | | [`docs/CHECKS.md`](docs/CHECKS.md) | The deterministic `WRD-*` static-check catalog (capability/secret/supply/robustness), the shared tokenizer, severity→SARIF mapping, redaction rule, CUT list. **Reused by v0.2** `WRD-RES-SECRET-ECHO` (the `WRD-SEC-*` patterns + redaction) | @@ -91,6 +92,12 @@ scope-honesty box and makes no compliance/regulatory claim. | [`docs/GUARD_PROXY_V3.md`](docs/GUARD_PROXY_V3.md) | **(v0.3)** The proxy-hardening contract: `notifications/cancelled`/`progress` untouched passthrough (§1), subprocess-lifecycle edge cases — server-crash `-32002` synthesis, client-disconnect process-group teardown, truncated/oversized-frame fail-open (§2), Windows experimental degradation (§3), the full v0.3 block-flag scheme + precedence (§4), and **(#21) `--strict` fail-CLOSED mode — terminate on an inspection-layer error, `-32003` non-retriable, exit `3` (§5)** | | [`docs/SIGNING.md`](docs/SIGNING.md) | **(v0.3, #16)** Sigstore keyless signing + verification of `warden.lock`: the optional `[sigstore]` extra, the deterministic `mcp-warden-lock-digest/v1` statement that binds ONLY `overall_digest` (survives `lock rotate`), `pin --sign` / `check --verify` usage, the **fixed-sidecar** verify contract (pointer field never trusted), the full fail-closed matrix, the TUF-cache/offline caveat, and the two accepted trade-offs (rotate-replay + committed-fixture coverage gap + refresh steps) | +## Non-normative design and implementation plans + +| Plan | Purpose | +|---|---| +| [`docs/plans/2026-07-18-agent-trust-kernel-design.md`](docs/plans/2026-07-18-agent-trust-kernel-design.md) | **Non-normative execution record.** Records the DSE-714 design decision and verification plan; binding requirements live in `docs/AGENT_TRUST_KERNEL.md` | + --- ## Community & contribution diff --git a/SYSTEM_CONTEXT_DIAGRAM.md b/SYSTEM_CONTEXT_DIAGRAM.md index 4121330..3108414 100644 --- a/SYSTEM_CONTEXT_DIAGRAM.md +++ b/SYSTEM_CONTEXT_DIAGRAM.md @@ -19,6 +19,13 @@ integrity drift between two EXISTING locks by reusing `compute_drift` (no captur logic) plus a separate informational provenance section. It never prints raw `server.command`/`args` (secret-safe); default exit 0, `--exit-code` → 1 on integrity drift only. +> **Agent Trust Kernel status (DSE-714):** [`docs/AGENT_TRUST_KERNEL.md`](docs/AGENT_TRUST_KERNEL.md) +> is the normative contract for a future deterministic reference monitor. It is **design-only** +> until DSE-715 through DSE-717 implement provenance/taint, PDP/PEP complete mediation, and +> signed evidence-before-effect. The current `guard` path is not represented as ATK-conformant. +> In C1, the dashed ATK edge and `Future Agent Trust Kernel runtime` node are conceptual +> documentation scope only—not a deployed component, shipped data flow, or implementation claim. + > `conclave` (the 4-model adversarial council referenced in `docs/THREAT_MODEL.md`) > is a **dev-time design reviewer** that shaped this contract. It is **NOT** a > runtime dependency and is never invoked by `pin`/`check`/`policy`. @@ -53,9 +60,14 @@ flowchart TB subgraph dev["Dev-time (design review only)"] conclave["conclave\n4-model adversarial council\n(NOT a runtime dependency)"] specs["docs/ security contract\nTHREAT_MODEL · WARDEN_LOCK_SCHEMA\nCHECKS · POLICY_MODEL"] + atk["AGENT_TRUST_KERNEL\nDSE-714 design contract"] conclave -. "critiques / shapes" .-> specs + conclave -. "security review" .-> atk end + future["Future Agent Trust Kernel runtime\nDSE-715–717 · NOT IMPLEMENTED"] + atk -. "governs future conformance" .-> future + subgraph ci["CI pipeline (GitHub Actions / local)"] warden["mcp-warden CLI\npin · check · policy · lock rotate · diff"] end diff --git a/docs/AGENT_TRUST_KERNEL.md b/docs/AGENT_TRUST_KERNEL.md new file mode 100644 index 0000000..494cfcf --- /dev/null +++ b/docs/AGENT_TRUST_KERNEL.md @@ -0,0 +1,480 @@ +# Agent Trust Kernel — Normative Security Contract + +**Status:** Design contract (DSE-714). Implementation conformance is pending DSE-715, +DSE-716, and DSE-717. +**Scope:** Deterministic reference monitor beneath agents and protocol adapters. +**Document owner:** Security. Changes require threat-model review. + +> **Current-product boundary:** MCP-Warden v1.1 does **not** claim conformance with this +> contract. Its shipped `guard` runtime intentionally has opt-outs and fail-open paths, and +> it does not yet provide universal provenance, complete mediation, bounded authority, or +> evidence-before-effect. Those differences remain honest product limits until downstream +> implementation and conformance work closes them. + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are normative. + +--- + +## 1. Purpose and security claim + +The Agent Trust Kernel (ATK) is a deterministic, client-agnostic reference monitor. It +decides whether an agent-related capability may execute, enforces that decision before the +effect, and emits tamper-evident evidence. Its security claim is deliberately narrow: + +- all external content and software enter untrusted; +- only verified deterministic policy may grant bounded authority; +- every security-relevant operation is mediated immediately before execution or release; +- uncertainty denies or quarantines instead of silently allowing; and +- AI may advise, but can never become an authority source. + +This contract defines the non-bypassable rules. It does not define a user interface, hosted +control plane, protocol-specific adapter, or semantic AI classifier. + +## 2. Trust model + +### 2.1 Trusted computing base + +This list is exhaustive: the trusted computing base (TCB) comprises only: + +- the host operating-system and hardware mechanisms that enforce process isolation, protected + storage, key protection, trusted time, and monotonic counters; +- the kernel runtime and its protected process boundary; +- the policy decision point (PDP) and policy enforcement point (PEP); +- canonicalization, hashing, signature verification, and approved cryptographic libraries; +- explicitly configured trust roots, protected signing keys, and verified policy/rule bundles; +- TCB-owned trusted time: a monotonic, non-rollback source plus an authenticated epoch/freshness + source, together with protected sequence and revocation state used by a decision; +- the append-only decision-receipt log plus the independent fallback evidence log and its + protected monotonic counter; and +- an evidence-store-independent fail-closed recovery latch (poison state). + +Compromise of the TCB, trust-root keys, or an authorized policy administrator is a residual +boundary, not a defended threat. + +Trusted time MUST be bound to the TCB's identity and protected configuration so it cannot be +substituted or influenced without TCB compromise. A new monotonic reading below the +TCB-protected last-accepted reading is rollback. An authenticated epoch/freshness reading that +disagrees with the monotonic-derived epoch beyond a signed or configured tolerance is +inconsistent. Either condition MUST deny every decision that consumes freshness, validity, +expiry, revocation, generation ordering, or any temporally bounded authority input, as MUST an +unavailable epoch/freshness source. Caller-, source-, transport-, and model-supplied timestamps +are untrusted evidence: they MUST NOT establish or repair authoritative time, freshness, lease +validity, ordering, or expiry. + +TCB-protected monotonic counters, highest-accepted generation floors, and the recovery latch +MUST survive process and host restart and MUST resist rollback through VM, container, disk, or +filesystem snapshots. Conforming implementations MUST anchor that state in a TPM, HSM, or an +equivalent rollback-resistant protected store outside the rollback domain being defended. A +platform that cannot provide this property is nonconformant and MUST remain fail closed. + +Adapters are explicitly outside the TCB. They are untrusted, verified-external components that +MUST remain enclosed by the TCB-owned PEP for every operation. A conformance report, test pass, +or signed adapter claim is evidence, not authority; the runtime MUST verify the adapter and its +signed manifest and enforce the PEP on each operation rather than trust a prior pass result. + +### 2.2 Protected assets + +| Asset | Required protection | +|---|---| +| Authority state | Policy, rules, trust roots, leases, revocations, critical-class floor, and governance history retain integrity, freshness, and rollback resistance | +| Identity and context | Subject, agent, device, session, adapter, source, publisher, purpose, and policy-administrator claims are authenticated and bound to the decision | +| Protected data and secrets | Reads, transformations, disclosures, and communications are mediated; outputs and evidence reveal only the minimum authorized content | +| Executable supply chain | Kernel, adapters, bundles, dependencies, and canonicalizers load only at verified identities and versions | +| Decision evidence | Canonical decision inputs, verdicts, receipts, and transparency-log ordering remain attributable, tamper-evident, and replay-resistant | +| Availability | Fail-closed behavior preserves safety under component or network failure, while recovery exposes no normal protected capability | + +### 2.3 Authoritative identities and roles + +An identity claim is data until authenticated by configured deterministic trust material. The +kernel MUST distinguish and bind these principals rather than infer or collapse them: + +| Identity or role | Permitted authority | +|---|---| +| User/subject | Requests only capabilities explicitly granted to that authenticated subject | +| Agent | Acts only within the subject's bounded delegation; cannot delegate through content | +| Device and session | Supply authenticated execution context, freshness, and anti-replay binding | +| Adapter | Translates a named protocol at a verified version; has no independent authority | +| Content source | Supplies provenance claims and data, never policy or authority | +| Bundle publisher/signer | Attests a specific digest and identity; does not by itself authorize execution | +| Policy administrator | Publishes signed policy within an assigned governance scope; cannot weaken the kernel's critical floor at runtime | +| Recovery administrator | Authorizes recovery repairs and exit after fresh integrity verification; cannot publish policy unless that separate role is also assigned | +| Trust-root or receipt signer | Authenticates the artifact type and key scope assigned to it; signatures are not interchangeable across roles | + +### 2.4 Untrusted inputs and actors + +The kernel MUST treat these as untrusted until verified by deterministic rules: + +- agents and model output; +- protocol adapters, their manifests, and their conformance outputs; +- MCP servers, tools, prompts, resources, results, and source-provided identity claims; +- software bundles, packages, repositories, metadata, manifests, and dependencies; +- web content, documents, email, database text, plugin metadata, and agent messages; +- transport payloads and storage outside the protected receipt/key boundary; and +- human-authored content that is not a signed governance artifact from an authorized role. + +An attacker may craft malformed, oversized, nested, ambiguous, or adversarial inputs; inject +instructions; lie in metadata; replay, reorder, delay, or drop messages; exploit +canonicalization confusion; fingerprint clients; induce network or offline failure; and seek +direct adapter/tool bypasses. The model does not assume an attacker can break approved +cryptography without compromising the TCB. + +### 2.5 Named threat classes + +| Threat | Mandatory control | Residual boundary | +|---|---|---| +| Confused deputy or context substitution | ATK-04, ATK-07, and ATK-09 bind the exact subject, agent, session, purpose, arguments, and operation at the PEP | A correctly authorized capability may still be misused within its bound scope | +| Authority laundering through content, transforms, or agents | ATK-01, ATK-02, ATK-05, and ATK-07 prevent content or lineage from acquiring transferable authority | Deterministic rules may miss malicious semantics that do not alter authority inputs | +| Malicious or substituted bundle | ATK-03 and ATK-11 verify identity, dependency closure, policy binding, freshness, and rollback state before load | Compromised trusted publisher or trust-root keys remain outside the defended boundary | +| Mediation bypass, adapter drift, or adapter TOCTOU | ATK-04 requires structurally enforced mediation and conformance gates disable any unmediated, racy, or nonconformant path | Only TCB compromise remains residual; a structurally unenforceable boundary is nonconformant, not an accepted risk | +| Replay, rollback, or stale authorization | ATK-09 and ATK-11 make generation, sequence, freshness, and expiry explicit and fail closed | Offline revocation lag is accepted only inside the configured freshness window | +| Receipt or evidence tamper | ATK-10 through ATK-12 require canonical signed receipts, ordering, redaction, and tamper detection | Evidence-log deletion can deny service; it cannot authorize an effect | + +## 3. Normative invariants + +### ATK-01 — Untrusted by default + +Every software bundle and external content item MUST enter with an explicit untrusted state. +Absence of provenance, a familiar publisher name, prior exposure, or model confidence MUST +NOT create trust or authority. + +### ATK-02 — Monotonic provenance and taint + +Every transformation MUST create a canonical content envelope containing the content hash, +source claims, parent hashes, transform identity and version, and taint state. A transform MAY +remove a named taint dimension only when an independently signed governance rule binds the +exact transform identity and version, the affected taint dimension, and the required evidence. +Envelope provenance fields and source claims are descriptive or corroborating evidence only; +they MUST NOT authorize taint removal by themselves. Content meaning, model output, and semantic +classification are never sufficient positive evidence for taint removal or authority, including +when referenced by a signed governance rule. Sanitization MUST NOT confer authority, erase +lineage, turn data into policy, or remove, downgrade, or override any mandatory critical class +or critical-floor outcome. + +### ATK-03 — Verified execution identity + +No executable bundle or adapter MAY load until its digest, signature, version, dependency +identity, and policy binding verify against configured trust roots. Source-provided metadata +is evidence to verify, never authority. Material drift MUST require reapproval. + +### ATK-04 — Complete mediation + +Every security-relevant operation—including a read, disclosure, transformation, +communication, or external effect—MUST pass through the PEP immediately before execution or +release. The PEP MUST consume the PDP decision bound to the exact subject, context, +operation, capability, arguments, protected data, destination, and policy generation. A +direct adapter, tool, storage, or protocol path around the PEP is nonconformant and MUST be +disabled. Mediation MUST be structurally enforced so a conforming adapter has no alternate +operation-to-sink path. An adapter TOCTOU window or host boundary that cannot enforce this +ordering is a conformance failure, not an accepted residual risk. Dynamic, reflected, or plugin +handler registration MUST match the signed authoritative operation manifest before the handler +is enabled; a missing or mismatched registration MUST be rejected and the adapter disabled. + +### ATK-05 — Deterministic authority + +Only signed, versioned, deterministic rules and governance artifacts may affect authority. +Model output and semantic classifiers MAY contribute untrusted evidence that signed +deterministic policy consumes for advisory or more-restrictive outcomes. They MUST NOT +directly modify policy, trust state, a decision, an override, or a receipt, and MUST NOT grant, +expand, restore, or override authority. No governance rule may treat content or model semantics +as sufficient positive evidence to grant authority or remove taint. + +### ATK-06 — Default deny under uncertainty + +Missing, malformed, unknown, unsupported, expired, revoked, ambiguous, timed-out, rolled-back, +or internally errored authority inputs MUST produce deny or quarantine. They MUST NOT produce +implicit allow, shadow-only enforcement, automatic downgrade, or a permissive fallback. A +candidate policy or rule MUST be validated in isolated staging before activation. A malformed, +invalid, stale, or unauthorized candidate MUST be rejected without changing a fresh known-good +active policy and MUST NOT by itself trigger recovery-only mode. Failure of active policy or +engine integrity, or absence of any valid current policy, MUST deny and enter recovery-only mode. + +### ATK-07 — Least and bounded privilege + +An allow or limit decision MUST bind the subject, agent, device, session, data scope, +capability, normalized arguments, purpose, policy/rule versions, and a finite lease. Any +binding mismatch, expiry, or revocation MUST deny. Authority MUST NOT be transferable through +content or agent messages. + +### ATK-08 — Non-overridable criticality + +A critical deterministic finding MUST NOT become allow through agent advice, a human +per-decision override, adapter flags, `--audit-only`, or category opt-outs. Runtime governance +MAY add or strengthen critical classes, but MUST NOT remove, downgrade, or exempt the kernel's +mandatory critical floor. Changing that floor requires a reviewed security-contract and +kernel-version change; an ordinary signed governance action cannot change it or override an +affected decision. + +### ATK-09 — Canonical and explicit decision input + +All facts that can change a decision—including time, freshness, sequence, policy/rule +versions, trust material, revocation state, and normalized arguments—MUST be explicit +canonical inputs. Hidden environment state is forbidden. Identical inputs MUST yield +byte-identical unsigned canonical decision payloads and stable reason codes. Signature and +certificate bytes are outside this determinism claim, but every signature MUST verify against +the exact fixed unsigned payload and an authorized signer identity. Authoritative time MUST +come only from the TCB-owned trusted-time sources in §2.1; caller timestamps remain untrusted +evidence. Missing, inconsistent, or rolled-back trusted time MUST deny every decision that +consumes freshness, validity, expiry, revocation, generation ordering, or any temporally bounded +authority input. + +### ATK-10 — Evidence before effect + +The kernel MUST produce an unsigned canonical receipt payload for every allow, limit, deny, +quarantine, override, revoke, and expiry decision, then sign that exact payload with an +authorized receipt-signer identity. Signature or certificate bytes MAY vary; the unsigned +canonical payload MUST NOT. Before the PEP invokes an allowed or limited operation, or an +operation permitted by a non-critical override, that receipt MUST be durably appended; signing +or append failure MUST convert the outcome to deny. Deny, quarantine, revoke, and expiry MUST +still enforce if their primary receipt attempt fails; logging failure MUST NEVER turn a negative +decision into allow. The kernel MUST then enter evidence-degraded recovery-only mode and attempt +an independent durable append-only fallback event bound to a TCB-protected monotonic counter and +a stable failure reason code. If both primary and fallback evidence persistence fail, the kernel +MUST set the TCB-protected, evidence-store-independent fail-closed recovery latch before emitting +only a minimal secret-safe local signal. If the latch cannot be set or read, the implementation +MUST remain fail closed and is nonconformant. + +The recovery latch MUST survive every restart and snapshot restore; process or host restart MUST +NOT clear it. Startup MUST NOT enter normal operation unless the primary and fallback evidence +paths are healthy, the latch is readable and clear, and any previously latched recovery has +completed an explicit authenticated recovery exit. Every permitted non-critical override MUST +identify its authorized actor, scope, reason, and finite expiry in the decision and receipt. + +### ATK-11 — Anti-replay and anti-rollback + +Policies, rules, leases, bundles, revocation snapshots, receipts, and logs MUST bind generation, +sequence, freshness, and expiry as applicable. Stale, replayed, truncated, reordered, or +rolled-back authority MUST fail closed. For each artifact class, the TCB MUST durably retain the +highest accepted generation and its identity digest. A cached artifact is eligible offline only +while its signed validity/freshness bounds hold and its generation is greater than or equal to +that protected floor; an equal generation MUST match the protected digest. A generation below +the floor is rollback and MUST deny. The possible existence or temporary unavailability of an +unknown newer generation is not rollback and does not invalidate an otherwise eligible cached +artifact. If the protected floor is unavailable or inconsistent, the kernel MUST deny rather +than infer history. + +### ATK-12 — Secret-safe outputs + +Errors, receipts, logs, metrics, and agent-facing explanations MUST expose stable reason codes +and the minimum redacted evidence required for review. They MUST NOT emit raw secrets, +protected content, untrusted exception text, or hidden policy detail that creates a practical +evasion oracle. Agent-facing reasons MUST come from a coarse, reviewed reason-code allowlist and +MUST NOT reveal internal rule identifiers, match thresholds, scoring details, or other tuning +information that enables iterative evasion. + +## 4. Non-overridable critical classes + +The baseline critical set MUST include: + +- integrity, signature, trust-root, or canonicalization failure; +- policy, rule, lease, receipt, log, sequence, replay, or rollback tamper; +- invalid, expired, or revoked identity or authority; +- provenance laundering or an untrusted attempt to modify authority or policy; +- PDP, PEP, or adapter bypass, conformance failure, or internal decision uncertainty; +- credential or secret exfiltration; +- deterministic private-network SSRF or exfiltration; and +- unapproved executable, dependency, bundle, or capability drift. + +Fuzzy prompt-injection findings are not automatically critical authority signals. They MAY +quarantine content under a signed deterministic policy, but a model's confidence score alone +cannot place or remove an item in the critical set. +This baseline is the kernel's mandatory critical floor. Runtime policy may extend it or make +its outcomes stricter, but cannot remove, downgrade, exempt, or reclassify any listed class. +Any baseline taxonomy reclassification requires review of this security contract and a kernel +version change; an ordinary governance update is insufficient. + +## 5. Fail-closed decision matrix + +**Quarantine** confers no authority: quarantined content or software MUST remain isolated. +Inspection is limited to mediated hash/digest verification, signature verification, schema +validation, and canonicalization checks. Quarantine MUST NOT render, execute, import, or make +network requests; disclose protected data; alter policy; or approve the quarantined item. + +Candidate policies and rules MUST be validated in isolated staging. A malformed, invalid, +unauthorized, or stale candidate is rejected while the fresh known-good active policy continues; +candidate rejection alone MUST NOT enter recovery-only mode. + +**Recovery-only mode** is entered automatically and fail closed only when active policy or +engine integrity fails, no valid current policy exists, a verified internal integrity error +occurs, or an evidence-path failure requires it. Entry MUST NOT depend on prior administrator +authentication or a successful signature operation, because denial and containment cannot wait +for either. Entry confers no authority, MUST deny every normal request, and MUST create critical +evidence through the primary receipt path or the independent fallback where available. During +recovery, only authenticated integrity diagnostics and repair using verified artifacts are +permitted. A Recovery Administrator MAY repair only with a pre-approved recovery artifact whose +exact identity and digest verify against protected recovery authority. That role MUST NOT author, +modify, or substitute policy during recovery. Exit requires BOTH an authenticated Recovery +Administrator action AND successful integrity verification against fresh trusted artifacts. The +Recovery Administrator gains no policy-publishing authority unless separately assigned that +role outside recovery. Normal requests remain denied until both exit conditions hold; diagnostic +output MUST be minimal and redacted. + +| Condition | Required result | +|---|---| +| Missing/malformed provenance or unknown schema/version | Quarantine content; deny authority and effects | +| Bundle digest/signature/identity mismatch | Quarantine bundle; never load | +| Malformed, invalid, stale, or unauthorized candidate policy/rule | Reject in isolated staging; keep the fresh known-good active policy; do not enter recovery | +| Active policy/rule/engine integrity failure, no valid current policy, or verified internal integrity error | Deny; automatically enter recovery-only mode and attempt critical evidence | +| Missing/expired/revoked subject, purpose, capability, or lease | Deny | +| Taint loss or untrusted attempt to alter authority/policy | Deny; emit critical finding | +| Critical deterministic rule match | Deny or quarantine; no override | +| Uninspectable or over-cap effect-bearing input | Deny or quarantine; never pass through | +| Adapter correlation/conformance failure | Disable adapter; deny | +| Allow/limit/override receipt signing or append failure | Convert to deny; do not invoke operation; attempt the deny receipt path | +| Deny/quarantine/revoke/expiry primary receipt failure | Enforce the result; enter evidence-degraded recovery-only mode; append an independent monotonic fallback event | +| Independent fallback append failure after primary evidence failure | Set the independent recovery latch; remain fail closed; emit a minimal safe local signal; never resume normal requests until explicit authenticated recovery | +| Recovery latch unavailable, unreadable, unsettable, or rolled back | Remain fail closed; platform is nonconformant | +| Valid cached offline artifact at/above the TCB-protected generation floor | Decide normally within signed validity/freshness bounds; equal generation must match the protected digest | +| Artifact generation below the durable highest accepted generation | Deny as rollback | +| Unknown newer generation unavailable | Continue with an otherwise eligible cached artifact; absence of knowledge is not rollback | +| Missing/stale trust root, trusted time, revocation state, or policy offline | Deny; never trust caller time, fetch implicitly, or downgrade | + +## 6. Offline operation + +The decision path MUST perform no network I/O. Operators MUST pre-provision signed policy and +rule bundles, trust roots, protected keys, revocation snapshots, freshness bounds, and the +authenticated epoch/freshness state through a separate authenticated synchronization operation. +That synchronization is outside evaluation; evaluation MUST NOT fetch time or authority state. +Cached material MAY be used only while its explicit validity and freshness requirements hold and +its generation is not below the TCB-protected highest generation previously accepted. An equal +generation MUST match the protected identity digest. Unavailability of an unknown newer +generation does not by itself invalidate eligible cached material; a generation below the +durable floor is rollback and MUST deny. + +Authenticated synchronization is a separate operation from evaluation. Missing trust +material, unavailable or untrustworthy TCB-owned time, an expired snapshot, or a stale policy +MUST deny. Caller timestamps cannot cure that failure. An offline +node cannot learn about revocations newer than its permitted freshness window; that lag is an +accepted, bounded residual risk. + +## 7. Reference decision flow + +```mermaid +flowchart LR + ingress["Untrusted content or capability request"] + envelope["Canonical envelope\nprovenance + taint"] + pdp["Deterministic PDP\npolicy + explicit context"] + verdict{"decision"} + receipt["Sign + append permit receipt"] + blockedReceipt["Attempt non-permit receipt"] + evidenceDegraded["Evidence-degraded\nrecovery-only mode"] + fallback["Independent durable fallback\nmonotonic counter"] + latch["TCB-protected fail-closed\nrecovery latch"] + safeSignal["Minimal secret-safe\nlocal signal"] + pep["PEP immediately before effect"] + effect["Capability effect"] + blocked["Deny or quarantine\nsecret-safe reason"] + + ingress --> envelope --> pdp --> verdict + verdict -- "deny / quarantine / revoke / expiry" --> blockedReceipt + blockedReceipt -- durable --> blocked + blockedReceipt -- "primary receipt failure: still enforce" --> evidenceDegraded + evidenceDegraded --> fallback + fallback -- durable --> blocked + fallback -- failure --> latch --> safeSignal --> blocked + verdict -- "allow / limit / non-critical override" --> receipt + receipt -- "failure: convert to deny" --> blockedReceipt + receipt -- durable --> pep --> effect +``` + +No adapter may connect `ingress`, `envelope`, or `pdp` directly to `effect`. + +## 8. Explicit cuts + +The kernel deliberately does not provide: + +- LLM or semantic adjudication as enforcement authority; +- a guarantee that an authorized tool behaves safely within its granted capability; +- protection after host, TCB, trust-root, signing-key, or authorized-admin compromise; +- perfect secret, prompt-injection, or encrypted-content detection; +- network-dependent or automatic trust-root refresh in the decision path; +- post-effect remediation as a substitute for pre-effect mediation; or +- a claim that provenance proves source claims are true—provenance proves recorded lineage. + +## 9. Residual risks + +Accepted residual risks include trusted-administrator abuse, TCB/key compromise, misuse within +an allowed capability, offline revocation lag, deterministic-rule false negatives, +availability loss caused by fail-closed behavior, and false source claims preserved faithfully +by provenance. Invalid candidate artifacts alone cannot deny service while a fresh known-good +active policy remains valid. Attacker-induced denial of service is an accepted residual only +when active authority or evidence state is corrupted or exhausted, forcing fail-closed entry +into recovery-only mode and authenticated administrator recovery. Adapter TOCTOU and structurally +unenforceable mediation are conformance failures and are not accepted residual risks. + +## 10. Downstream implementation bindings + +Every invariant has exactly one primary implementation owner. Secondary bindings identify the +components that must consume or enforce the primary owner's contract. + +| Invariant | Primary owner | Secondary bindings | Required deliverable | +|---|---|---|---| +| ATK-01 | DSE-715 | DSE-716 | Explicit untrusted ingress state; PDP/PEP rejects missing state | +| ATK-02 | DSE-715 | DSE-716, DSE-717 | Canonical lineage and taint propagation; independently signed transform authority; receipt lineage | +| ATK-03 | DSE-716 | DSE-715, DSE-717 | Bundle identity fields from 715; structurally enforced load gate; receipt binding | +| ATK-04 | DSE-716 | DSE-717 | Structurally complete mediation and instrumented operation-to-sink proof; evidence sink integration | +| ATK-05 | DSE-716 | DSE-715, DSE-717 | Deterministic authority inputs; AI evidence cannot grant/expand authority; signed rule binding | +| ATK-06 | DSE-716 | DSE-715, DSE-717 | Fail-closed decision/error matrix across envelope, PDP/PEP, and evidence paths | +| ATK-07 | DSE-716 | DSE-715, DSE-717 | Bounded subject/context/operation/lease binding preserved in envelopes and receipts | +| ATK-08 | DSE-716 | DSE-717 | Non-overridable enforcement of the mandatory critical floor; rule schema may only strengthen it | +| ATK-09 | DSE-716 | DSE-715, DSE-717 | Canonical inputs plus TCB-owned trusted time, sequence, freshness, and stable reasons | +| ATK-10 | DSE-717 | DSE-716 | Evidence-before-effect, independent negative-decision fallback, and persistent recovery latch integrated with the PEP | +| ATK-11 | DSE-717 | DSE-715, DSE-716 | Receipt/log anti-replay and anti-rollback bound to envelope and decision generations in rollback-resistant state | +| ATK-12 | DSE-717 | DSE-715, DSE-716 | Secret-safe envelopes, decisions, receipts, fallback events, metrics, and explanations | + +The implementation dependency order is **DSE-715 → DSE-716 → DSE-717**: 715 defines the +envelope consumed by 716; 716 establishes the structural PEP boundary used by 717's +evidence-before-effect path. DSE-717 MUST NOT be considered complete until DSE-716's ATK-04 +mediation conformance gates pass. No downstream ticket may weaken an invariant silently. A +proposed exception requires a security-contract change and review before implementation. + +## 11. Conformance gates + +A component or adapter may claim ATK conformance only through a mechanically executable suite. +Each adapter MUST publish a finite manifest enumerating every security-relevant operation and +its authorized sink. That manifest MUST be the runtime's authoritative operation allowlist: +unlisted operations are rejected, and the harness MUST prove a bijection between manifest +entries and registered handlers/sinks, including handlers registered dynamically, through +reflection, or by plugins. The suite MUST instrument both registration and execution, drive the +manifest through an instrumented PEP/sink harness, use a fixed versioned malformed-input corpus, +plant a unique secret through every untrusted input channel named in §2.4, and byte-scan every +serialized output channel. Automated evidence MUST prove: + +1. Golden vectors produce byte-identical unsigned canonical decision payloads and unsigned + canonical receipt payloads from identical explicit inputs. Randomized signature or + certificate bytes MAY differ, but each signature verifies against the exact fixed payload and + an authorized identity. +2. Every operation in the finite adapter manifest reaches its sink only after the instrumented + PEP records the exact bound decision; missing, extra, or alternate sink paths fail the suite. +3. Every case in the fixed malformed corpus—including unknown, expired, revoked, replayed, + oversized, ambiguous, and untrustworthy-time inputs—cannot + produce an unauthorized read, disclosure, transformation, communication, or external + effect. +4. A protected monotonic backward step denies; unavailable epoch/freshness time denies every + decision that consumes freshness, validity, expiry, revocation, generation ordering, or any + temporally bounded authority input; and a caller timestamp contradicting trusted time is + ignored and cannot change the verdict. +5. Candidate-policy tests reject malformed/invalid candidates without disturbing a fresh + known-good active policy, while active-policy/engine integrity failure or no valid current + policy enters recovery-only mode. +6. Every critical class resists agent, human, adapter, audit-only, and opt-out override attempts. + A model-confidence input MUST NOT relax a deterministic deny into allow. +7. Transformations cannot silently drop taint, erase lineage, gain authority, use source + provenance as taint-removal authorization, or remove/override the mandatory critical floor. +8. Evaluation performs no network I/O; a valid cached artifact at or above the protected + generation floor works, an artifact below it denies as rollback, and unavailability of an + unknown newer generation does not create a false rollback. +9. Policy, receipt, fallback event, and log tamper/truncate/reorder/replay/rollback cases fail + closed. Total primary-plus-fallback evidence failure sets the independent recovery latch; + failure to set or read it remains fail closed and fails conformance. Restart does not clear a + set latch, and normal startup requires healthy evidence paths, a readable cleared latch, and + explicit authenticated recovery exit after any latched failure. +10. Process and host restart plus VM, container, disk, and filesystem snapshot-rollback tests + cannot reduce a protected monotonic counter or generation floor or clear a recovery latch. + The suite MUST exercise the selected TPM, HSM, or equivalent rollback-resistant store; a + platform that cannot preserve these properties fails conformance. +11. A byte-for-byte scan confirms the distinct secret planted through each §2.4 input channel + never appears in any serialized decision, error, receipt, fallback event, log, metric, or + agent-facing explanation. + +Until those gates exist and pass, documentation MUST use **design contract** or +**implementation pending**, never **ATK-conformant**. diff --git a/docs/THREAT_MODEL.md b/docs/THREAT_MODEL.md index 97cb520..12b542b 100644 --- a/docs/THREAT_MODEL.md +++ b/docs/THREAT_MODEL.md @@ -16,6 +16,10 @@ It operates entirely on **definitions** — the `(name, description, inputSchema metadata returned by `tools/list`, `resources/list`, and `prompts/list` — never on runtime tool **behavior** or tool **results**. +> **Forward contract:** [`AGENT_TRUST_KERNEL.md`](AGENT_TRUST_KERNEL.md) defines a separate, +> future non-bypassable reference-monitor contract. It does not retroactively change this +> v0.1 contract or imply that the current product is ATK-conformant. + This distinction is the single most important thing in this document. An earlier "runtime firewall" design was critiqued by a 4-model adversarial council. The council's central finding was that **definition integrity is not behavioral @@ -304,6 +308,8 @@ because of time, but because they are net-negative: ## 8. Related documents +- `AGENT_TRUST_KERNEL.md` — **DSE-714 design contract:** future deterministic reference-monitor + invariants and downstream bindings; implementation conformance is pending DSE-715–717. - `WARDEN_LOCK_SCHEMA.md` — baseline format, canonicalization, hashing, drift definition. - `CHECKS.md` — the deterministic static-check catalog (IDs, rules, severities, SARIF). - `POLICY_MODEL.md` — argument-level policy shapes, constraints, lint + sample evaluation. diff --git a/docs/THREAT_MODEL_V2.md b/docs/THREAT_MODEL_V2.md index a812e1f..a9376b6 100644 --- a/docs/THREAT_MODEL_V2.md +++ b/docs/THREAT_MODEL_V2.md @@ -11,6 +11,11 @@ and §8 (the honest availability/UX-risk callout). > default** instead of shadow; the **fuzzy** monitor tier stays **opt-in**. §8 states the > availability/UX risk of default-blocking plainly and names the opt-out. +> **Forward contract:** [`AGENT_TRUST_KERNEL.md`](AGENT_TRUST_KERNEL.md) intentionally requires +> stronger fail-closed, complete-mediation behavior than this shipped runtime contract. The +> current `guard` opt-outs and fail-open paths remain accurately documented here and are not +> ATK-conformant until DSE-715 through DSE-717 close those gaps. + > Read `THREAT_MODEL.md` first. The v0.1 trust model (TOFU + `--approve`), assets/actors, > the four definition-level threat classes, and the deliberate cuts are unchanged. This > addendum closes one named v0.1 gap — `T-RESULT` — and is explicit about what it still does @@ -245,6 +250,8 @@ flag scheme + precedence: `GUARD_PROXY.md` §5 and `GUARD_PROXY_V3.md` §4. ## 9. Related documents +- [`AGENT_TRUST_KERNEL.md`](AGENT_TRUST_KERNEL.md) — DSE-714 design contract for the future + deterministic reference monitor; does not replace this shipped MCP runtime contract. - [`THREAT_MODEL.md`](THREAT_MODEL.md) — v0.1 base threat model (still authoritative). - [`RESULT_INSPECTION.md`](RESULT_INSPECTION.md) — the `WRD-RES-*` result-inspection catalog (catalog unchanged in v0.3; default posture updated). diff --git a/docs/plans/2026-07-18-agent-trust-kernel-design.md b/docs/plans/2026-07-18-agent-trust-kernel-design.md new file mode 100644 index 0000000..b16473a --- /dev/null +++ b/docs/plans/2026-07-18-agent-trust-kernel-design.md @@ -0,0 +1,116 @@ +# Agent Trust Kernel Contract Implementation Plan + +> **Status:** Non-normative execution record. The binding security requirements live in +> `docs/AGENT_TRUST_KERNEL.md`. + +**Goal:** Define the non-bypassable, deterministic security contract that DSE-715, +DSE-716, and DSE-717 must implement. + +**Architecture:** Add one normative umbrella contract for the future Agent Trust Kernel +without rewriting MCP-Warden's shipped v0.1-v1.1 security contracts. Cross-link the new +contract from the documentation index, system context, and existing threat models, and +state clearly that the current runtime is not yet kernel-conformant. + +**Tech Stack:** Markdown security contracts, Mermaid system context, repository link and +consistency checks. + +--- + +## Validated design + +Three approaches were considered: + +1. **New normative umbrella contract (selected).** Keeps the kernel's fail-closed, + non-bypassable rules separate from the current product's intentional opt-outs and + fail-open paths. This is the only approach that avoids overstating shipped behavior. +2. **Extend `THREAT_MODEL_V2.md`.** Rejected because that document is a historical MCP + result-inspection contract and deliberately permits behavior that the kernel forbids. +3. **Implement schemas/APIs first.** Rejected because DSE-715 through DSE-717 would otherwise + encode incompatible assumptions before the governing invariants exist. + +The new contract will define twelve stable `ATK-*` invariants, the trusted computing base, +untrusted inputs, attacker capabilities, fail-closed outcomes, non-overridable critical +classes, offline evaluation, explicit cuts, residual risks, and downstream ticket mappings. +It is a design contract only; conformance remains pending DSE-715 through DSE-717. + +### Task 1: Add the normative Agent Trust Kernel contract + +**Files:** +- Create: `docs/AGENT_TRUST_KERNEL.md` + +**Step 1:** Define status, scope, normative language, and current nonconformance warning. + +**Step 2:** Add `ATK-01` through `ATK-12` with unique, testable requirements. + +**Step 3:** Add exhaustive trust boundaries, trusted-time ownership, attacker model, +structurally enforced mediation, fail-closed and evidence-degraded recovery matrices, +critical classes, provenance authority, offline contract, explicit cuts, and residual risks. + +**Step 4:** Assign one primary owner and secondary bindings to every invariant, record the +DSE-715 → DSE-716 → DSE-717 dependency order, and gate DSE-717 completion on ATK-04. + +**Step 5:** Define mechanically executable conformance around authoritative finite adapter +manifests with handler/sink bijection, an instrumented PEP/sink harness, a fixed malformed +corpus, and planted-secret byte scans. + +### Task 2: Integrate the contract without rewriting shipped guarantees + +**Files:** +- Modify: `DOCUMENTATION_INDEX.md` +- Modify: `SYSTEM_CONTEXT_DIAGRAM.md` +- Modify: `docs/THREAT_MODEL.md` +- Modify: `docs/THREAT_MODEL_V2.md` + +**Step 1:** Add the new contract to the security-contract index. + +**Step 2:** Add a dashed, design-only kernel boundary to the system context. + +**Step 3:** Add short relationship notes to both threat models that preserve their existing +scope and point forward to the kernel contract. + +### Task 3: Verify the contract + +**Files:** +- Verify: `docs/AGENT_TRUST_KERNEL.md` +- Verify: `DOCUMENTATION_INDEX.md` +- Verify: `SYSTEM_CONTEXT_DIAGRAM.md` +- Verify: `docs/THREAT_MODEL.md` +- Verify: `docs/THREAT_MODEL_V2.md` + +**Step 1:** Run an invariant/mapping scan. + +Run: `rg -n 'ATK-(0[1-9]|1[0-2])|DSE-71[5-7]' docs/AGENT_TRUST_KERNEL.md` + +Expected: all twelve invariant IDs and all three downstream ticket IDs are present. + +**Step 2:** Validate changed Markdown links and Mermaid diagrams explicitly. + +Run: a local-link validator across the six changed Markdown files, then: +`mmdc -i docs/AGENT_TRUST_KERNEL.md -o /private/tmp/mcp-warden-dse714-atk.md` and +`mmdc -i SYSTEM_CONTEXT_DIAGRAM.md -o /private/tmp/mcp-warden-dse714-system.md`. + +Expected: every relative link resolves to an existing file and Mermaid CLI renders every +diagram without a syntax error. + +**Step 3:** Run documentation and whitespace checks. + +Run: `/private/tmp/mcp-warden-docs-dse714/bin/mkdocs build --strict --site-dir /private/tmp/mcp-warden-dse714-site && git diff --check` + +Expected: both commands exit 0. + +**Step 4:** Run the full repository suite. + +Run: `PYTHONPATH=src /Users/ernestprovo/dev/mcp-warden/.venv/bin/python -m pytest -q` + +Expected: zero failures. + +### Task 4: Publish for review + +**Step 1:** Stage only the five contract/integration files plus this plan. + +**Step 2:** Commit as `docs: define Agent Trust Kernel contract (DSE-714)`. + +**Step 3:** Push `codex/dse-714-agent-trust-kernel` and open a draft PR to `main`. + +**Step 4:** Add the PR link and verification evidence to DSE-714, then move the ticket to +`In Review`; do not mark it Done before review/merge.