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
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ assignees: ''

## Conformance test ID (if applicable)

<!-- Prefix with ATTEST, POLICY, AUDIT, or TRACE e.g. ATTEST-007, POLICY-003 -->
<!-- Prefix with ATTEST, POLICY, AUDIT, or TRACE: e.g. ATTEST-007, POLICY-003 -->
32 changes: 16 additions & 16 deletions CHARTER.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Technical Charter cMCP
# Technical Charter: cMCP

**Proposed hosting**: Agentic AI Foundation (AAIF).
**Status**: Pre-acceptance draft effective upon host organization acceptance.
**Status**: Pre-acceptance draft: effective upon host organization acceptance.

> **Note for external contributors:** This charter is a working draft and has not yet been accepted by a host organization. Governance terms, IP policy, and trademark ownership described here are proposed, not final. Do not assume binding foundation commitments until formal acceptance.

Expand All @@ -11,18 +11,18 @@

## 1. Mission

The cMCP project develops and maintains an open implementation of the Confidential MCP (Model Context Protocol) gateway hardware-attested policy enforcement for AI agent tool calls. The mission is to make tool-call authorization cryptographically verifiable by any party, without trusting the operator, without requiring closed infrastructure, and without vendor lock-in to any silicon vendor, cloud provider, or AI platform.
The cMCP project develops and maintains an open implementation of the Confidential MCP (Model Context Protocol) gateway: hardware-attested policy enforcement for AI agent tool calls. The mission is to make tool-call authorization cryptographically verifiable by any party, without trusting the operator, without requiring closed infrastructure, and without vendor lock-in to any silicon vendor, cloud provider, or AI platform.

## 2. Scope

The project includes:

- **cMCP Gateway** the reference open-source implementation of the confidential gateway, including the gRPC/HTTP proxy, policy engine, and hardware attestation bridge.
- **Hardware Provider API** the normalized interface (`BaseProvider`) for integrating TEE platforms (TPM, AMD SEV-SNP, Intel TDX, and others).
- **Python SDK** the `cmcp-gateway` package and client libraries for policy authoring and runtime integration.
- **TRACE integration** built-in emission of TRACE Trust Records for every attested tool call (see [agentrust-io/trace-spec](https://github.com/agentrust-io/trace-spec)).
- **Agent Manifest binding** verification of agent identity via Agent Manifest at tool-call time (see [agentrust-io/agent-manifest](https://github.com/agentrust-io/agent-manifest)).
- **Integration examples** working examples across financial services, healthcare, and multi-tenant SaaS deployment patterns.
- **cMCP Gateway**: the reference open-source implementation of the confidential gateway, including the gRPC/HTTP proxy, policy engine, and hardware attestation bridge.
- **Hardware Provider API**: the normalized interface (`BaseProvider`) for integrating TEE platforms (TPM, AMD SEV-SNP, Intel TDX, and others).
- **Python SDK**: the `cmcp-gateway` package and client libraries for policy authoring and runtime integration.
- **TRACE integration**: built-in emission of TRACE Trust Records for every attested tool call (see [agentrust-io/trace-spec](https://github.com/agentrust-io/trace-spec)).
- **Agent Manifest binding**: verification of agent identity via Agent Manifest at tool-call time (see [agentrust-io/agent-manifest](https://github.com/agentrust-io/agent-manifest)).
- **Integration examples**: working examples across financial services, healthcare, and multi-tenant SaaS deployment patterns.

Out of scope: AI model governance beyond tool-call enforcement, hardware TEE platform SDKs, network-level policy outside the MCP protocol boundary, and MCP server implementations themselves.

Expand Down Expand Up @@ -59,18 +59,18 @@ Use of "cMCP-compatible" to describe a gateway deployment requires that the impl

cMCP builds on and does not replace:

- **MCP (Model Context Protocol, Anthropic)** the underlying tool-call protocol that cMCP extends with attestation
- **TRACE** ([agentrust-io/trace-spec](https://github.com/agentrust-io/trace-spec)) governance record emitted per attested tool call
- **Agent Manifest** ([agentrust-io/agent-manifest](https://github.com/agentrust-io/agent-manifest)) agent identity bound at tool-call time
- **SPIFFE / SPIRE** workload identity for gateway and agent services
- **RATS / EAT (RFC 9711)** attestation evidence format
- **OPA / Cedar** policy engine integration surface
- **MCP (Model Context Protocol, Anthropic)**: the underlying tool-call protocol that cMCP extends with attestation
- **TRACE** ([agentrust-io/trace-spec](https://github.com/agentrust-io/trace-spec)): governance record emitted per attested tool call
- **Agent Manifest** ([agentrust-io/agent-manifest](https://github.com/agentrust-io/agent-manifest)): agent identity bound at tool-call time
- **SPIFFE / SPIRE**: workload identity for gateway and agent services
- **RATS / EAT (RFC 9711)**: attestation evidence format
- **OPA / Cedar**: policy engine integration surface

## 7. Transition timeline

| Milestone | Target |
|---|---|
| v0.1 developer preview CC Summit announcement | June 2026 |
| v0.1 developer preview: CC Summit announcement | June 2026 |
| Hardware provider API stabilization, TRACE v0.2 integration | Q3 2026 |
| AAIF project proposal submission | Q3 2026 |
| v1.0 stable release under TSC governance | 2027 |
Expand Down
12 changes: 6 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Thank you for contributing. This document covers everything you need to get star

## Before you start

cMCP is a hardware-attested policy gateway. Changes to the TEE boundary, signing path, audit chain, or TRACE Claim generation require extra care these are security-critical components. When in doubt, open an issue first.
cMCP is a hardware-attested policy gateway. Changes to the TEE boundary, signing path, audit chain, or TRACE Claim generation require extra care: these are security-critical components. When in doubt, open an issue first.

## Developer certificate of origin

Expand Down Expand Up @@ -54,7 +54,7 @@ Keep commits small and focused. One logical change per commit. Do not bundle unr
## Pull request process

1. Branch from `main`: `git checkout -b feat/your-change`
2. Write tests for new behaviour the test suite must pass
2. Write tests for new behaviour: the test suite must pass
3. Run all four checks locally (see above)
4. Open a PR against `main` with the template filled in
5. At least one maintainer must approve before merge
Expand All @@ -64,9 +64,9 @@ Keep commits small and focused. One logical change per commit. Do not bundle unr

Changes to these paths require two maintainer approvals and a comment explaining the security impact:

- `src/cmcp_gateway/audit/` signing, audit chain, TRACE Claim generation
- `src/cmcp_gateway/tee/` TEE provider integration
- `src/cmcp_gateway/policy/` Cedar policy evaluation
- `src/cmcp_gateway/audit/`: signing, audit chain, TRACE Claim generation
- `src/cmcp_gateway/tee/`: TEE provider integration
- `src/cmcp_gateway/policy/`: Cedar policy evaluation

## Reporting security vulnerabilities

Expand All @@ -77,7 +77,7 @@ Do **not** open a public issue. Use [GitHub Security Advisories](https://github.
- Python 3.11+ syntax throughout (`X | Y`, `match`, etc.)
- `ruff` enforces style; do not add `# noqa` without a comment explaining why
- `mypy --strict` on `src/cmcp_gateway/`; new public functions need type annotations
- No comments that describe *what* the code does only *why* when non-obvious
- No comments that describe *what* the code does: only *why* when non-obvious
- Tests live in `tests/unit/` and follow the existing `test_<module>.py` naming

## Questions
Expand Down
4 changes: 2 additions & 2 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Reviewers do not have merge access but their approval counts toward the merge re

### Maintainer

A Reviewer who has held that role for **at least 60 days** and has demonstrated sustained contributionsconsistent review activity, issue triage, or code may be nominated for Maintainer by any existing Maintainer. Maintainer status requires explicit approval by 2/3 of current Maintainers.
A Reviewer who has held that role for **at least 60 days** and has demonstrated sustained contributions: consistent review activity, issue triage, or code: may be nominated for Maintainer by any existing Maintainer. Maintainer status requires explicit approval by 2/3 of current Maintainers.

Maintainers have merge access to `main` and are collectively responsible for the health of the project.

Expand All @@ -48,7 +48,7 @@ Maintainers have merge access to `main` and are collectively responsible for the

### Day-to-day changes (lazy consensus)

Most decisionsfeature additions, bug fixes, documentation, refactors are made by **lazy consensus on pull requests**. A PR is mergeable when:
Most decisions: feature additions, bug fixes, documentation, refactors: are made by **lazy consensus on pull requests**. A PR is mergeable when:

- At least one Maintainer has approved it, and
- No Maintainer has raised a blocking objection within **5 business days** of the last substantive change.
Expand Down
4 changes: 2 additions & 2 deletions MAINTAINERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@

## Roles

**Reviewer** triages issues, reviews pull requests, and approves changes within their area of expertise.
**Reviewer**: triages issues, reviews pull requests, and approves changes within their area of expertise.

**Maintainer** holds merge rights, participates in roadmap decisions, and is responsible for the health of the project.
**Maintainer**: holds merge rights, participates in roadmap decisions, and is responsible for the health of the project.

## Becoming a Reviewer

Expand Down
6 changes: 3 additions & 3 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# cMCP Roadmap

## v0.1 Initial Release (June 2026)
## v0.1: Initial Release (June 2026)

Scope: Minimal viable trust layer for MCP servers, sufficient for early adopters to evaluate the attestation and policy model.

Expand All @@ -9,7 +9,7 @@ Scope: Minimal viable trust layer for MCP servers, sufficient for early adopters
- TRACE Claim generation from attestation evidence
- Standalone verifier CLI for offline claim inspection

## v0.2 Released (June 2026)
## v0.2: Released (June 2026)

Provider-specific attestation verification:
- TPM2 quote verification
Expand All @@ -27,7 +27,7 @@ Observability:
Transparency:
- Transparency log integration for TRACE Claim anchoring (write and lookup)

## v1.0 Stable Targets
## v1.0: Stable Targets

- Stable `GatewayClaim` schema with documented versioning guarantees
- Full RATS/EAT conformance (RFC 9334, draft-ietf-rats-eat)
Expand Down
12 changes: 6 additions & 6 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,17 @@ Timeline starts when the issue is confirmed as a valid vulnerability, not on ini

The following components are in scope:

- **TEE attestation path** measurement of policy bundle hash into hardware attestation report; attestation verification logic for TPM 2.0, AMD SEV-SNP, Intel TDX, and OPAQUE Managed Runtime providers
- **Signing key handling** hardware-sealed key generation, storage, and use; any path by which a signing key could be extracted or used outside the enclave
- **Cedar policy enforcement** correctness of allow/deny decisions; policy bundle loading and hash verification inside the enclave; enforcement mode handling
- **Audit chain** integrity of TRACE claim output fields (`policy_bundle_hash`, `audit_chain_root`, `tee_public_key`); any path by which a valid audit entry could be forged or suppressed
- **TEE attestation path**: measurement of policy bundle hash into hardware attestation report; attestation verification logic for TPM 2.0, AMD SEV-SNP, Intel TDX, and OPAQUE Managed Runtime providers
- **Signing key handling**: hardware-sealed key generation, storage, and use; any path by which a signing key could be extracted or used outside the enclave
- **Cedar policy enforcement**: correctness of allow/deny decisions; policy bundle loading and hash verification inside the enclave; enforcement mode handling
- **Audit chain**: integrity of TRACE claim output fields (`policy_bundle_hash`, `audit_chain_root`, `tee_public_key`); any path by which a valid audit entry could be forged or suppressed

## Out of Scope

The following are not eligible for a coordinated disclosure:

- Bugs in TEE firmware or hardware microcode (AMD, Intel, or cloud provider trust anchor issues) report those directly to the relevant vendor
- Vulnerabilities in the upstream Cedar policy language engine that are not specific to cMCP's integration report those to the [Cedar project](https://github.com/cedar-policy/cedar)
- Bugs in TEE firmware or hardware microcode (AMD, Intel, or cloud provider trust anchor issues): report those directly to the relevant vendor
- Vulnerabilities in the upstream Cedar policy language engine that are not specific to cMCP's integration: report those to the [Cedar project](https://github.com/cedar-policy/cedar)
- Theoretical weaknesses in TEE threat models that are already acknowledged in public literature
- Issues in third-party MCP tool implementations invoked through the gateway

Expand Down
22 changes: 11 additions & 11 deletions docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ The key difference:
| | Log | TRACE Claim |
|---|---|---|
| Who produces it | Agent process or operator | TEE firmware + cMCP runtime |
| Can it be edited post-hoc? | Yes | No signature would fail |
| Can the operator forge it? | Yes | No signing key never leaves the TEE |
| Can it be edited post-hoc? | Yes | No: signature would fail |
| Can the operator forge it? | Yes | No: signing key never leaves the TEE |
| Who can verify it? | Anyone with read access | Anyone with the public key (no trust in operator) |

A TRACE Claim is a [TRACE Trust Record](https://trace.agentrust-io.com) with a `GatewayClaim` envelope. The envelope adds the session summary and audit chain. The inner trust record follows the TRACE v0.1 spec.
Expand All @@ -44,7 +44,7 @@ Every cMCP TRACE Claim makes four categories of assertion:

## Hardware attestation: why the claim is trustworthy

The signing key for a cMCP TRACE Claim is generated inside the TEE and never leaves it. The TEE also measures its own state at boot recording a SHA-384 digest of the firmware, the Cedar policy bundle, and the tool catalog into a PCR/measurement register.
The signing key for a cMCP TRACE Claim is generated inside the TEE and never leaves it. The TEE also measures its own state at boot: recording a SHA-384 digest of the firmware, the Cedar policy bundle, and the tool catalog into a PCR/measurement register.

This means:

Expand Down Expand Up @@ -85,7 +85,7 @@ The TRACE Claim records `audit_chain.root` (the first entry hash) and `audit_cha

**Why this matters:** An auditor who has the individual audit log entries can recompute the chain tip and verify it matches the TRACE Claim. If any entry was modified, deleted, or reordered, the recomputed tip will not match. The audit log is self-certifying.

The audit chain does not need to be stored on-chain or in a third-party system. The signed TRACE Claim is sufficient to detect tampering after the fact as long as the claim itself was not forged (which the hardware attestation prevents).
The audit chain does not need to be stored on-chain or in a third-party system. The signed TRACE Claim is sufficient to detect tampering after the fact: as long as the claim itself was not forged (which the hardware attestation prevents).

See [Spec: Call Graph](spec/call-graph.md) for the full chain construction.

Expand All @@ -95,11 +95,11 @@ See [Spec: Call Graph](spec/call-graph.md) for the full chain construction.

Cedar is an authorization policy language designed to be auditable. cMCP uses it for three reasons:

**1. The policy is versioned and hash-bound.** The SHA-256 of the policy bundle is measured into the TEE at startup. Every TRACE Claim carries that hash. An auditor can compare the hash in a claim to the policy bundle in the repository and prove which policy was active for a given session even if the policy was later changed.
**1. The policy is versioned and hash-bound.** The SHA-256 of the policy bundle is measured into the TEE at startup. Every TRACE Claim carries that hash. An auditor can compare the hash in a claim to the policy bundle in the repository and prove which policy was active for a given session: even if the policy was later changed.

**2. Policy effects are data, not code.** Cedar policies are declarative and cannot execute arbitrary code. A `forbid` rule can block a tool call; it cannot read files or make network requests. This means policy review is tractable: the policy file is the complete specification of what the agent is allowed to do.

**3. Cedar supports fine-grained context conditions.** Policies can condition on session attributes like `session_max_sensitivity`, `workflow_id`, or `data_class`. This enables dynamic policy enforcement without code changes the same binary can enforce different rules for different tenant configurations.
**3. Cedar supports fine-grained context conditions.** Policies can condition on session attributes like `session_max_sensitivity`, `workflow_id`, or `data_class`. This enables dynamic policy enforcement without code changes: the same binary can enforce different rules for different tenant configurations.

Example: this policy blocks `salesforce.contacts` once PII has entered the session:

Expand Down Expand Up @@ -152,8 +152,8 @@ The signed claim ties together: hardware identity (attestation), policy version

## Next steps

- [Quickstart](quickstart.md) run a cMCP gateway locally in under 30 minutes
- [Configuration](configuration.md) full configuration reference
- [Tutorial: Cedar policy walkthrough](tutorials/cedar-policy-walkthrough.md) write and test policies
- [Tutorial: Verify a TRACE claim](tutorials/verifying-a-trace-claim.md) verify a claim without trusting the operator
- [Spec: Component Model](spec/component-model.md) detailed architecture
- [Quickstart](quickstart.md): run a cMCP gateway locally in under 30 minutes
- [Configuration](configuration.md): full configuration reference
- [Tutorial: Cedar policy walkthrough](tutorials/cedar-policy-walkthrough.md): write and test policies
- [Tutorial: Verify a TRACE claim](tutorials/verifying-a-trace-claim.md): verify a claim without trusting the operator
- [Spec: Component Model](spec/component-model.md): detailed architecture
Loading