From 1d25fc925e29138c1b1f212a2c7fbd507e93c4c2 Mon Sep 17 00:00:00 2001 From: Imran Siddique Date: Thu, 20 Aug 2026 17:58:45 -0700 Subject: [PATCH] docs: give the site its own landing page instead of a repo index cmcp.agentrust-io.com opened on docs/README.md, a page written for someone browsing the repository rather than someone arriving at the docs site: a reading order by file path, a spec index with issue numbers, and a scope note saying implementation lives elsewhere "(link TBD)" while cmcp-runtime is published on PyPI. - Adds docs/index.md as the landing page, matching the shape Agent Manifest and TRACE use. - Renames docs/README.md to docs/spec-index.md and puts it in the nav. The spec file table, schema table, conformance tests and glossary are worth keeping; they were just not a homepage. - Corrects the "(link TBD)" scope note. - Points the README Documentation badge at cmcp.agentrust-io.com rather than the github.io URL that redirects to it. - Lets the social card titles use the homepage title. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_013EQx4N5BzTQbY8kvXUsdkY --- README.md | 4 +- docs/index.md | 72 ++++++++++ docs/{README.md => spec-index.md} | 217 +++++++++++++----------------- mkdocs.yml | 5 +- overrides/main.html | 4 +- 5 files changed, 176 insertions(+), 126 deletions(-) create mode 100644 docs/index.md rename docs/{README.md => spec-index.md} (69%) diff --git a/README.md b/README.md index 2ab5bcd5..870f0a90 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,8 @@ ### Enforce MCP tool policy inside a TEE, where the agent it governs cannot reach it

- - Documentation + + Documentation

diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..0bdc6ab1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,72 @@ +--- +title: The secure, confidential way to run MCP +description: cMCP is a hardware-attested MCP runtime. Every tool call an agent makes passes through a TEE-isolated gateway that evaluates it against a Cedar policy and emits a signed TRACE receipt a verifier can check without trusting the operator. +--- + +# cMCP + +cMCP (Confidential MCP) is a hardware-attested runtime for the Model Context Protocol. Every MCP tool call an agent makes passes through a TEE-isolated gateway that evaluates it against a Cedar policy bundle and produces a TRACE claim: a signed, hardware-attested artifact a verifier can check without trusting the operator. + +**Prove that the policy you describe in documents is the policy that actually ran on your traffic.** + +!!! tip "TL;DR" + - MCP authenticates the caller. It does not constrain what a tool call may do, and it leaves no evidence of what it did. + - cMCP runs the tool call inside a TEE, decides it against Cedar, and emits a signed receipt for every call. + - Install with `pip install cmcp-runtime`, or follow the [guided quickstart](https://agentrust-io.com/quickstart/) and watch a policy block a real data leak in about ten minutes. + - Two bounds worth stating up front: the plaintext guarantee holds where the egress policy denies telemetry and APM endpoints, and the receipt is hardware-attested when the gateway runs in a TEE and signed-only in software mode. + +```bash +pip install cmcp-runtime +``` + +## The gap it closes + +An agent calling a tool over MCP presents a token. The token says who is calling. It does not say what the call is allowed to touch, and once the call returns there is no artifact proving what actually happened. + +Software-only enforcement does not close this. A privileged operator can change a policy between the approval that was reviewed and the traffic that ran, and then write the log that describes it. The log is authored by the system being audited. + +cMCP moves the decision and the evidence inside a TEE. The policy bundle is measured, the decision happens where the operator cannot reach it, and the receipt is signed by a key that never leaves the enclave. Phase 1 attests the agent-to-tool boundary on the consumer side, in the runtime. Phase 2 attests it on the provider side, in the server. + +## Where to start + +
+ +- __Run it__ + + --- + + Write one policy, watch it block a tool call, and verify the receipt it produced. + + [Quick Start](quickstart.md) + +- __Understand it__ + + --- + + The component model, trust boundaries, and how a tool call becomes a signed claim. + + [How It Works](concepts.md) + +- __Read the spec__ + + --- + + Problem taxonomy, the thirteen threat shapes, and the Phase 1 and Phase 2 coverage matrix. + + [SPEC.md](SPEC.md) + +- __Check the bounds__ + + --- + + What is attested against real silicon, what is parsed, and what is not appraised at all. + + [Limitations](https://github.com/agentrust-io/cmcp/blob/main/LIMITATIONS.md) + +
+ +## How it fits the rest of the stack + +cMCP is the enforcement layer of the AgenTrust chain. [Agent Manifest](https://manifest.agentrust-io.com) declares what an agent is and what it may do before it runs. cMCP enforces that at the tool-call boundary. [TRACE](https://trace.agentrust-io.com) is the evidence format the receipts are written in, and [cA2A](https://ca2a.agentrust-io.com) carries the same guarantees across agent-to-agent hops. + +Issues in this repository track specification decisions rather than implementation bugs. To propose a change, open an issue describing the problem with the current spec, then submit a pull request. See [Contributing](https://github.com/agentrust-io/cmcp/blob/main/CONTRIBUTING.md). diff --git a/docs/README.md b/docs/spec-index.md similarity index 69% rename from docs/README.md rename to docs/spec-index.md index 12109ce4..80512f00 100644 --- a/docs/README.md +++ b/docs/spec-index.md @@ -1,123 +1,100 @@ --- -title: The secure, confidential way to run MCP +title: Specification index +description: Every cMCP specification file, what it covers, which phase it belongs to, and the schemas and conformance tests that go with it. --- -# cMCP Spec - -cMCP Runtime is a hardware-attested MCP (Model Context Protocol) runtime. Every MCP tool call an agent makes passes through a TEE-isolated gateway that evaluates it against a Cedar policy bundle and produces a TRACE Claim: a signed, hardware-attested proof artifact a verifier can check without trusting the operator. - -Phase 1 attests the agent-to-tool boundary on the consumer side (the runtime). Phase 2 attests it on the provider side (the server). Together they close the proof gap that software-only runtimes leave open: "prove that the policy you describe in documents is the policy that actually ran on your traffic." - -This repository contains the product specification. Implementation lives in a separate repo. - ---- - -## Start here - -**Understanding the problem space:** -Read SPEC.md. It defines the four problems (P1 data leakage, P2 unsanctioned tools, P3 provable governance, P4 supply chain), the 13 threat shapes, and the coverage matrix showing what Phase 1 closes vs. what Phase 2 closes. - -**Implementing the runtime (Phase 1):** -Read in this order: -1. SPEC.md : problem context and scope -2. docs/spec/component-model.md : what you are building and where trust boundaries are -3. docs/spec/transport.md : how the runtime intercepts MCP traffic -4. docs/spec/attestation.md : how TEE attestation works and how to produce TRACE Claims -5. docs/spec/cedar-policy.md : the policy engine, bundle format, and enforcement modes -6. docs/spec/failure-modes.md : what happens when things go wrong -7. schemas/ : machine-readable schemas to validate your outputs against - -**Contributing to the spec:** -Issues in this repo track spec decisions, not implementation bugs. Each issue corresponds to a specific design question. When a spec file resolves an issue, the issue is closed with a reference to the relevant file. To propose a change, open an issue describing the problem with the current spec, then submit a PR. - ---- - -## Spec File Index - -| File | Covers | Phase | Status | Issues | -|------|--------|-------|--------|--------| -| docs/SPEC.md | Problem taxonomy, coverage matrix, Phase 1/2 scope | 1+2 | Draft v0.1 | - | -| docs/spec/component-model.md | All MCP components, trust levels, hardware vs. software boundaries | 1+2 | Draft v0.1 | #43 | -| docs/spec/transport.md | HTTP/SSE scope, stdio gap, SPIFFE-to-TEE binding spike | 1 | Draft v0.1 | #20, #21 | -| docs/spec/attestation.md | TEE provider detection, audit chain, key management, catalog pinning | 1 | Draft v0.1 | #5, #6, #23, #33, #38 | -| docs/spec/cedar-policy.md | Policy bundle format, Cedar examples, enforcement modes, provenance | 1 | Draft v0.1 | #4, #7, #26, #39, #41 | -| docs/spec/tool-identity.md | Server identity binding, catalog schema, collision detection | 1 | Draft v0.1 | #40 | -| docs/spec/failure-modes.md | Runtime failure scenarios, decision table, log formats | 1 | Draft v0.1 | #22 | -| docs/spec/call-graph.md | Tag-propagation model, observability limits, cross-boundary policy | 1 | Draft v0.1 | #35 | -| docs/spec/session-policy.md | Session sensitivity state machine, egress policy, session reset | 1 | Draft v0.1 | #36 | -| docs/spec/response-inspection.md | 4-stage response inspection pipeline, injection patterns | 1 | Draft v0.1 | #37 | -| docs/spec/error-codes.md | Central error code registry for all runtime and verification errors | 1+2 | Draft v0.1 | - | -| docs/spec/threat-model.md | Assets, adversaries, STRIDE analysis per component | 1 | Draft v0.1 | #18, #24 | -| docs/spec/verification-library.md | cmcp-verify Python library interface and per-provider verification steps | 1 | Draft v0.1 | #25 | -| docs/spec/mcp-spec-strategy.md | MCP spec monitoring and attestation extension contribution window | 1+2 | Draft v0.1 | #30 | -| docs/spec/proxy-security.md | Phase 2 proxy parser fuzzing DoD | 2 | Draft v0.1 | #34 | -| docs/spec/phase2-server.md | Provider-side attestation, 5 unique properties, streaming proxy, multi-tenant | 2 | Draft v0.1 | #17, #28, #29, #32, #42 | -| docs/testing/benchmarks.md | Latency targets and benchmark methodology | 1 | Draft v0.1 | #27 | -| docs/testing/soak-test.md | 72-hour soak test plan | 1 | Draft v0.1 | #31 | - ---- - -## Schema Files - -Machine-readable schemas in `schemas/` let implementations validate their outputs before shipping. - -| File | What it validates | Use with | -|------|------------------|---------| -| schemas/trace-claim.schema.json | TRACE Claim JSON (draft-07) | jsonschema, ajv, any JSON Schema validator | -| schemas/audit-entry.schema.json | Single audit chain entry | jsonschema, ajv | -| schemas/catalog-entry.schema.json | Tool catalog entry | jsonschema, ajv | -| schemas/cedar-schema.cedarschema | Cedar entity types and context attributes | cedar-policy CLI: `cedar validate` | - -To validate a TRACE Claim: -``` -ajv validate -s schemas/trace-claim.schema.json -d your-trace-claim.json -``` - -To validate Cedar policies: -``` -cedar validate --schema schemas/cedar-schema.cedarschema --policies policies/ -``` - ---- - -## Conformance Tests - -`tests/conformance/README.md` defines the conformance test suite: 22 test cases across 6 groups (ATTEST, POLICY, AUDIT, FAIL, INSP, TRACE). Each case specifies: -- Input conditions -- Expected behavior (pass/fail, error code, field values) -- The spec section it validates - -A conforming implementation passes all MUST-level tests. SHOULD-level tests indicate higher-quality conformance. - ---- - -## Contributing - -**Spec versioning:** All files use `Status: Draft/Review/Accepted/Superseded` plus a version number (e.g. `v0.1`). Stability is `Unstable` until v1.0. - -**Process:** -1. Open an issue describing the spec gap or design question -2. Discuss in the issue : the issue body captures the decision context -3. Submit a PR with the spec change, referencing the issue -4. PR is merged when the spec change is accepted - -**Scope:** This repo is spec-only. Implementation bugs go in the implementation repo (link TBD). Spec issues are about design decisions, not code behavior. - ---- - -## Glossary - -| Term | Definition | -|------|-----------| -| TRACE Claim | The signed, hardware-attested proof artifact produced by the runtime per session | -| TEE | Trusted Execution Environment (TPM, SEV-SNP, TDX, or OPAQUE Managed) | -| SPIFFE SVID | Short-lived cryptographic identity issued by SPIRE after TEE attestation succeeds | -| Cedar | The policy language used for tool call authorization | -| Audit chain | The append-only hash-chained log of all runtime decisions, signed with a TEE-sealed key | -| Session sensitivity | The maximum sensitivity level seen in any tool response within the current session | -| Tag-propagation | The runtime's mechanism for tracking sensitivity across calls based on observable events | -| Catalog entry | The runtime's approved record for one tool: name, server identity, approved definition | -| Attestation report | The hardware-produced evidence that a specific binary ran in a specific TEE at a specific time | -| policy_bundle_hash | SHA-256 of the canonical Cedar policy bundle, measured into the TEE at startup | -| tool_catalog_hash | SHA-256 of the canonical tool catalog, measured into the TEE at startup | -| Call graph | Per-session record of tool calls and temporal adjacency edges (approximation, not data provenance) | +# Specification index + +This page lists every specification file in the repository, what it covers, which phase it belongs to, and the schemas and conformance tests that go with it. For what cMCP is and where to start reading, see the [home page](index.md). + +Issues in this repository track specification decisions rather than implementation bugs. Each issue corresponds to a design question, and is closed with a reference to the spec file that resolves it. + +## Spec File Index + +| File | Covers | Phase | Status | Issues | +|------|--------|-------|--------|--------| +| docs/SPEC.md | Problem taxonomy, coverage matrix, Phase 1/2 scope | 1+2 | Draft v0.1 | - | +| docs/spec/component-model.md | All MCP components, trust levels, hardware vs. software boundaries | 1+2 | Draft v0.1 | #43 | +| docs/spec/transport.md | HTTP/SSE scope, stdio gap, SPIFFE-to-TEE binding spike | 1 | Draft v0.1 | #20, #21 | +| docs/spec/attestation.md | TEE provider detection, audit chain, key management, catalog pinning | 1 | Draft v0.1 | #5, #6, #23, #33, #38 | +| docs/spec/cedar-policy.md | Policy bundle format, Cedar examples, enforcement modes, provenance | 1 | Draft v0.1 | #4, #7, #26, #39, #41 | +| docs/spec/tool-identity.md | Server identity binding, catalog schema, collision detection | 1 | Draft v0.1 | #40 | +| docs/spec/failure-modes.md | Runtime failure scenarios, decision table, log formats | 1 | Draft v0.1 | #22 | +| docs/spec/call-graph.md | Tag-propagation model, observability limits, cross-boundary policy | 1 | Draft v0.1 | #35 | +| docs/spec/session-policy.md | Session sensitivity state machine, egress policy, session reset | 1 | Draft v0.1 | #36 | +| docs/spec/response-inspection.md | 4-stage response inspection pipeline, injection patterns | 1 | Draft v0.1 | #37 | +| docs/spec/error-codes.md | Central error code registry for all runtime and verification errors | 1+2 | Draft v0.1 | - | +| docs/spec/threat-model.md | Assets, adversaries, STRIDE analysis per component | 1 | Draft v0.1 | #18, #24 | +| docs/spec/verification-library.md | cmcp-verify Python library interface and per-provider verification steps | 1 | Draft v0.1 | #25 | +| docs/spec/mcp-spec-strategy.md | MCP spec monitoring and attestation extension contribution window | 1+2 | Draft v0.1 | #30 | +| docs/spec/proxy-security.md | Phase 2 proxy parser fuzzing DoD | 2 | Draft v0.1 | #34 | +| docs/spec/phase2-server.md | Provider-side attestation, 5 unique properties, streaming proxy, multi-tenant | 2 | Draft v0.1 | #17, #28, #29, #32, #42 | +| docs/testing/benchmarks.md | Latency targets and benchmark methodology | 1 | Draft v0.1 | #27 | +| docs/testing/soak-test.md | 72-hour soak test plan | 1 | Draft v0.1 | #31 | + +--- + +## Schema Files + +Machine-readable schemas in `schemas/` let implementations validate their outputs before shipping. + +| File | What it validates | Use with | +|------|------------------|---------| +| schemas/trace-claim.schema.json | TRACE Claim JSON (draft-07) | jsonschema, ajv, any JSON Schema validator | +| schemas/audit-entry.schema.json | Single audit chain entry | jsonschema, ajv | +| schemas/catalog-entry.schema.json | Tool catalog entry | jsonschema, ajv | +| schemas/cedar-schema.cedarschema | Cedar entity types and context attributes | cedar-policy CLI: `cedar validate` | + +To validate a TRACE Claim: +``` +ajv validate -s schemas/trace-claim.schema.json -d your-trace-claim.json +``` + +To validate Cedar policies: +``` +cedar validate --schema schemas/cedar-schema.cedarschema --policies policies/ +``` + +--- + +## Conformance Tests + +`tests/conformance/README.md` defines the conformance test suite: 22 test cases across 6 groups (ATTEST, POLICY, AUDIT, FAIL, INSP, TRACE). Each case specifies: +- Input conditions +- Expected behavior (pass/fail, error code, field values) +- The spec section it validates + +A conforming implementation passes all MUST-level tests. SHOULD-level tests indicate higher-quality conformance. + +--- + +## Contributing + +**Spec versioning:** All files use `Status: Draft/Review/Accepted/Superseded` plus a version number (e.g. `v0.1`). Stability is `Unstable` until v1.0. + +**Process:** +1. Open an issue describing the spec gap or design question +2. Discuss in the issue : the issue body captures the decision context +3. Submit a PR with the spec change, referencing the issue +4. PR is merged when the spec change is accepted + +**Scope:** Issues here are about specification design decisions. Runtime bugs belong on the [cmcp-runtime](https://pypi.org/project/cmcp-runtime/) implementation, in the [issue tracker](https://github.com/agentrust-io/cmcp/issues) under an implementation label. + +--- + +## Glossary + +| Term | Definition | +|------|-----------| +| TRACE Claim | The signed, hardware-attested proof artifact produced by the runtime per session | +| TEE | Trusted Execution Environment (TPM, SEV-SNP, TDX, or OPAQUE Managed) | +| SPIFFE SVID | Short-lived cryptographic identity issued by SPIRE after TEE attestation succeeds | +| Cedar | The policy language used for tool call authorization | +| Audit chain | The append-only hash-chained log of all runtime decisions, signed with a TEE-sealed key | +| Session sensitivity | The maximum sensitivity level seen in any tool response within the current session | +| Tag-propagation | The runtime's mechanism for tracking sensitivity across calls based on observable events | +| Catalog entry | The runtime's approved record for one tool: name, server identity, approved definition | +| Attestation report | The hardware-produced evidence that a specific binary ran in a specific TEE at a specific time | +| policy_bundle_hash | SHA-256 of the canonical Cedar policy bundle, measured into the TEE at startup | +| tool_catalog_hash | SHA-256 of the canonical tool catalog, measured into the TEE at startup | +| Call graph | Per-session record of tool calls and temporal adjacency edges (approximation, not data provenance) | diff --git a/mkdocs.yml b/mkdocs.yml index 0619688f..b3265ed0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -78,7 +78,7 @@ plugins: secure version of MCP, this is the AgenTrust runtime for it. sections: Getting started: - - README.md + - index.md - quickstart.md - concepts.md - configuration.md @@ -149,8 +149,9 @@ extra_css: - https://agentrust-io.com/design-system.css nav: - - Home: README.md + - Home: index.md - Quick Start: quickstart.md + - Specification index: spec-index.md - How It Works: concepts.md - Configuration: configuration.md - Tutorials: diff --git a/overrides/main.html b/overrides/main.html index 43dfee08..1210646d 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -15,7 +15,7 @@ - + @@ -24,7 +24,7 @@ - +