From dd1beb1c50d527fece1ccf6a82010ee42774487a Mon Sep 17 00:00:00 2001 From: Imran Siddique Date: Fri, 5 Jun 2026 16:05:30 -0700 Subject: [PATCH] =?UTF-8?q?chore:=20OSS=20readiness=20=E2=80=94=20governan?= =?UTF-8?q?ce=20docs,=20CI=20hardening,=20GitHub=20config?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aligns cmcp with agent-manifest OSS standards for the June 23 launch. Governance docs: - LICENSE (MIT — was missing, README only said MIT) - CONTRIBUTING.md (DCO, dev setup, commit format, security-critical paths) - CODE_OF_CONDUCT.md (Contributor Covenant v2.1) - SECURITY.md (private disclosure, SLAs, scope/out-of-scope) - CHANGELOG.md (Keep a Changelog format, v0.1.0 initial entries) - GOVERNANCE.md (contributor ladder, decision-making, AAIF upstream) - MAINTAINERS.md (reviewer/maintainer criteria, current roster) - ADOPTERS.md, ROADMAP.md, NOTICE (placeholders + v0.2/v1.0 targets) GitHub configuration: - CODEOWNERS (security-reviewers required on audit/, tee/, policy/) - dependabot.yml (weekly pip + Actions, max 5 PRs) - PULL_REQUEST_TEMPLATE.md (security impact field required) - ISSUE_TEMPLATE/ (bug report, feature request, config.yml) CI hardening (.github/workflows/): - ci.yml: matrix extended to 3.11/3.12/3.13 on ubuntu+windows; added bandit + pip-audit security scan step; coverage upload to Codecov - publish.yml: OIDC trusted publishing to PyPI on v* tags - codeql.yml: weekly CodeQL with security-extended queries - scorecard.yml: weekly OpenSSF Scorecard, SARIF → GitHub Security tab pyproject.toml: - classifiers (Alpha, MIT, Python 3.11/3.12/3.13, Security, AI, Typed) - bandit[toml] + pip-audit added to dev deps - [tool.bandit], [tool.coverage.run], [tool.coverage.report] sections README.md: - badges (CI, license, PyPI, Python, OpenSSF Scorecard) - architecture diagram updated to GatewayClaim envelope field names - status section updated; Contributing + Security links added Co-Authored-By: Claude Sonnet 4.6 --- .github/CODEOWNERS | 13 ++++ .github/ISSUE_TEMPLATE/bug_report.md | 42 +++++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 +++ .github/ISSUE_TEMPLATE/feature_request.md | 25 +++++++ .github/PULL_REQUEST_TEMPLATE.md | 26 +++++++ .github/dependabot.yml | 19 +++++ .github/workflows/ci.yml | 15 +++- .github/workflows/codeql.yml | 39 +++++++++++ .github/workflows/publish.yml | 47 +++++++++++++ .github/workflows/scorecard.yml | 37 ++++++++++ ADOPTERS.md | 7 ++ CHANGELOG.md | 21 ++++++ CONTRIBUTING.md | 85 +++++++++++++++++++++++ GOVERNANCE.md | 78 +++++++++++++++++++++ LICENSE | 21 ++++++ MAINTAINERS.md | 38 ++++++++++ NOTICE | 28 ++++++++ README.md | 27 ++++--- ROADMAP.md | 34 +++++++++ SECURITY.md | 40 +++++++++++ pyproject.toml | 24 +++++++ 21 files changed, 664 insertions(+), 13 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/codeql.yml create mode 100644 .github/workflows/publish.yml create mode 100644 .github/workflows/scorecard.yml create mode 100644 ADOPTERS.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.md create mode 100644 LICENSE create mode 100644 MAINTAINERS.md create mode 100644 NOTICE create mode 100644 ROADMAP.md create mode 100644 SECURITY.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..8921115e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,13 @@ +# Default owners for all files +* @agentrust-io/maintainers + +# Security-sensitive paths require security-reviewers sign-off +src/cmcp_gateway/audit/ @agentrust-io/security-reviewers @agentrust-io/maintainers +src/cmcp_gateway/tee/ @agentrust-io/security-reviewers @agentrust-io/maintainers +src/cmcp_gateway/policy/ @agentrust-io/security-reviewers @agentrust-io/maintainers + +# CI/CD workflow changes +.github/workflows/ @agentrust-io/maintainers + +# Package configuration +pyproject.toml @agentrust-io/maintainers diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..1c47bf1c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,42 @@ +--- +name: Bug report +about: Defect in gateway behavior +labels: bug +assignees: '' +--- + +## cmcp-gateway version + + + +## Python version + + + +## TEE provider + + + +## Reproduction steps + +1. +2. +3. + +## Expected behavior + + + +## Actual behavior + + + +## Relevant logs or TRACE Claim output + +``` + +``` + +## Conformance test ID (if applicable) + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..1edf5600 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/agentrust-io/cmcp/security/advisories/new + about: Report a security vulnerability via GitHub Security Advisories. Do not open a public issue. + - name: Design discussion + url: https://github.com/agentrust-io/cmcp/discussions + about: Start a design discussion or ask a broad question in GitHub Discussions before opening an issue. + - name: Trace spec proposal + url: https://github.com/agentrust-io/trace-spec/issues/new + about: Propose a change to the cMCP trace specification in the trace-spec repo. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..06d440c7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,25 @@ +--- +name: Feature request +about: Propose a new capability +labels: enhancement +--- + +## Problem statement + + + +## Proposed solution + + + +## Alternatives considered + + + +## Security/TEE impact + + + +## Spec alignment + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..e0eefb82 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +## What + + + +## Why + + + +## Security impact + + + +## Test plan + +- [ ] `pytest` passes +- [ ] `ruff check` passes +- [ ] `mypy` passes +- [ ] Manual test performed (describe steps below if applicable) + + + +## DCO sign-off + +- [ ] I certify that I wrote or have the right to submit this contribution, and I agree to the + Developer Certificate of Origin (https://developercertificate.org). diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..eb38669e --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,19 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + open-pull-requests-limit: 5 + ignore: + - dependency-name: "*" + update-types: + - "version-update:semver-major" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + open-pull-requests-limit: 5 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e6c22eb4..fbf1590c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,10 +8,11 @@ on: jobs: test: - runs-on: ubuntu-latest + runs-on: ${{ matrix.os }} strategy: matrix: - python-version: ["3.11", "3.12"] + python-version: ["3.11", "3.12", "3.13"] + os: [ubuntu-latest, windows-latest] steps: - uses: actions/checkout@v4 @@ -23,6 +24,9 @@ jobs: - name: Install dependencies run: pip install -e ".[dev]" + - name: Security scan + run: pip install bandit pip-audit && bandit -r src/ -c pyproject.toml && pip-audit + - name: Lint run: ruff check src/ tests/ @@ -30,4 +34,9 @@ jobs: run: mypy src/cmcp_gateway/ - name: Test - run: pytest tests/unit/ -v --tb=short + run: pytest tests/unit/ -v --tb=short --cov=src --cov-report=xml + + - name: Upload coverage report + uses: codecov/codecov-action@v4 + with: + fail_ci_if_error: false diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 00000000..648ce4ab --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,39 @@ +name: CodeQL + +on: + push: + branches: + - main + pull_request: + branches: + - main + schedule: + - cron: '15 3 * * 0' + +permissions: + actions: read + contents: read + security-events: write + +jobs: + analyze: + name: Analyze (python) + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: python + queries: +security-extended + + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: /language:python diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..9be948b2 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,47 @@ +name: Publish to PyPI + +on: + push: + tags: + - "v*" + +permissions: + contents: read + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python 3.11 + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install hatchling + run: pip install hatchling + + - name: Build package + run: python -m hatchling build + + - name: Upload dist artifact + uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + + publish: + needs: build + runs-on: ubuntu-latest + environment: pypi + steps: + - name: Download dist artifact + uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + + - name: Publish to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 00000000..a7bd807d --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,37 @@ +name: OpenSSF Scorecard + +on: + branch_protection_rule: + schedule: + - cron: '30 4 * * 1' + push: + branches: + - main + +permissions: + security-events: write + id-token: write + contents: read + actions: read + +jobs: + scorecard: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + persist-credentials: false + fetch-depth: 0 + + - name: Run Scorecard + uses: ossf/scorecard-action@v2 + with: + results_file: scorecard-results.sarif + results_format: sarif + publish_results: true + + - name: Upload SARIF + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: scorecard-results.sarif diff --git a/ADOPTERS.md b/ADOPTERS.md new file mode 100644 index 00000000..967174e6 --- /dev/null +++ b/ADOPTERS.md @@ -0,0 +1,7 @@ +# Adopters + +Organizations using cMCP in production or evaluation. Open a PR to add your organization. + +| Organization | Use Case | Since | +|---|---|---| +| Your org here | - | - | diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..4afd3b82 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,21 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.0] - 2026-06-23 + +### Added + +- Initial TEE gateway with provider support for TPM, SEV-SNP, TDX, and Opaque +- Cedar policy enforcement for request authorization at the gateway layer +- TRACE Claim generation using the `GatewayClaim` envelope from `agentrust-trace` +- `cmcp-verify` standalone verifier for validating TRACE Claims offline +- Audit chain with Ed25519 signing for tamper-evident log integrity + +[Unreleased]: https://github.com/agentic-ai-foundation/cmcp-agentrust/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/agentic-ai-foundation/cmcp-agentrust/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..bc8e79d4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,85 @@ +# Contributing to cMCP + +Thank you for contributing. This document covers everything you need to get started. + +## 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. + +## Developer certificate of origin + +All commits must include a `Signed-off-by` line. This is a lightweight way to certify you wrote the code or have the right to contribute it. No CLA required. + +``` +git commit -s -m "feat: your change" +``` + +The sign-off certifies the [Developer Certificate of Origin v1.1](https://developercertificate.org/). + +## Development setup + +Requires Python 3.11+. + +```bash +git clone https://github.com/agentrust-io/cmcp +cd cmcp +pip install -e ".[dev]" +``` + +## Running checks locally + +```bash +ruff check src/ tests/ # lint +mypy src/cmcp_gateway/ # type check +bandit -r src/ -c pyproject.toml # security scan +pytest tests/unit/ -v # unit tests +``` + +All four must pass before a PR is mergeable. + +## Commit format + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +feat: add sev-snp provider +fix: correct nonce encoding in RuntimeInfo +docs: clarify TRACE profile envelope structure +test: add coverage for stale attestation path +refactor: extract _build_policy helper +``` + +Keep commits small and focused. One logical change per commit. Do not bundle unrelated fixes. + +## Pull request process + +1. Branch from `main`: `git checkout -b feat/your-change` +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 +6. Squash if the commit history is noisy; preserve meaningful commits + +## Security-critical components + +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 + +## Reporting security vulnerabilities + +Do **not** open a public issue. Use [GitHub Security Advisories](https://github.com/agentrust-io/cmcp/security/advisories/new) for private disclosure. See [SECURITY.md](SECURITY.md). + +## Code conventions + +- 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 +- Tests live in `tests/unit/` and follow the existing `test_.py` naming + +## Questions + +Open a [GitHub Discussion](https://github.com/agentrust-io/cmcp/discussions) for design questions or proposals before writing code. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..4d7cbaf4 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,78 @@ +# Governance + +This document describes how cMCP is governed: who holds what role, how decisions are made, and how the project relates to its upstream foundation. + +--- + +## Upstream governance body + +cMCP is a project of the **Agentic AI Foundation**. The Foundation sets the overall direction for the agentrust-io ecosystem, holds the project's trademarks, and provides a neutral venue for resolving disputes that cannot be resolved within the project itself. Foundation policies supersede this document where they conflict. + +--- + +## Project lead + +The project lead is responsible for the technical direction of cMCP, final say on architecture decisions, and representing the project to the Foundation. + +| Name | Affiliation | GitHub | +|------|-------------|--------| +| Imran Siddique | Opaque Systems | @imransiddique | + +The project lead role is subject to Foundation confirmation. Succession is decided by a 2/3 maintainer vote, ratified by the Foundation. + +--- + +## Roles and contributor ladder + +### Contributor + +Anyone who opens a pull request, files a substantive issue, or otherwise participates in the project. No formal requirements. All contributors must sign off commits under the Developer Certificate of Origin (see [CONTRIBUTING.md](CONTRIBUTING.md)). + +### Reviewer + +A Contributor who has had **3 or more pull requests merged** may be nominated for Reviewer by any existing Maintainer. Reviewers can approve pull requests and are expected to provide timely, substantive code review. Reviewer status is confirmed by lazy consensus among Maintainers (no objection within 5 business days). + +Reviewers do not have merge access but their approval counts toward the merge requirements in CONTRIBUTING.md. + +### Maintainer + +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. + +**Inactive Maintainers** (no meaningful activity for 6 months) may be moved to emeritus status by a 2/3 maintainer vote after a 2-week notice period. Emeritus Maintainers retain their history and credit but lose merge access. + +--- + +## Decision-making + +### Day-to-day changes (lazy consensus) + +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. + +For security-critical paths (as defined in CONTRIBUTING.md), two Maintainer approvals are required. + +### Breaking changes and governance changes (explicit vote) + +The following require an **explicit vote** rather than lazy consensus: + +- Any change to a public API that is not backward-compatible +- Changes to the TRACE Claim schema +- Changes to this GOVERNANCE.md or CONTRIBUTING.md +- Addition or removal of a Maintainer +- Changes to the relationship with the Agentic AI Foundation + +An explicit vote is conducted by opening a GitHub Discussion tagged `vote`. It runs for **7 calendar days**. Each Maintainer has one vote. Participation is voluntary; abstentions do not count against quorum. A simple majority of votes cast decides the outcome, except where this document specifies a higher threshold. + +### Dispute resolution + +If a PR or proposal reaches an impasse, any Maintainer may call for a formal vote. If the vote does not resolve the dispute, the project lead makes the final call. If the dispute involves the project lead, the matter is escalated to the Agentic AI Foundation for binding resolution. A 2/3 majority of Maintainers is required to override a project lead decision through Foundation escalation. + +--- + +## Amendments + +Changes to this document require an explicit vote (see above) and ratification by the Agentic AI Foundation. diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..ecf1b704 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Agentic AI Foundation contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000..0e965721 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,38 @@ +# Maintainers + +## Current Maintainers + +| Name | GitHub | Affiliation | Role | +|------|--------|-------------|------| +| Imran Siddique | @imransiddique | Opaque Systems | Project Lead | + +## Roles + +**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. + +## Becoming a Reviewer + +To be considered for reviewer status you must: + +- Have 3 or more pull requests merged into the repository +- Demonstrate working familiarity with TEE (Trusted Execution Environment) concepts and security primitives relevant to the project +- Be nominated by an existing maintainer + +## Becoming a Maintainer + +To be considered for maintainer status you must: + +- Have held reviewer status for at least 60 days +- Have reviewed 10 or more pull requests +- Be nominated by an existing maintainer +- Be approved by a majority vote of the current maintainers + +## Emeritus + +Maintainers who are no longer active may move to emeritus status. Emeritus maintainers are listed here for recognition but do not hold merge rights or voting privileges. + +## Changes to This File + +Changes to MAINTAINERS.md must be approved by at least one existing maintainer. diff --git a/NOTICE b/NOTICE new file mode 100644 index 00000000..9684e723 --- /dev/null +++ b/NOTICE @@ -0,0 +1,28 @@ +cMCP - Confidential MCP Gateway + +Copyright 2026 Agentic AI Foundation contributors + +This project is licensed under the MIT License. + + +Third-Party Dependencies +------------------------ + +cryptography + License: Apache 2.0 + https://github.com/pyca/cryptography + +PyYAML + License: MIT + https://github.com/yaml/pyyaml + +agentrust-trace + License: Apache 2.0 + +Pydantic + License: MIT + https://github.com/pydantic/pydantic + +Cedar (policy engine) + License: Apache 2.0 + https://github.com/cedar-policy/cedar diff --git a/README.md b/README.md index c1a94d7a..2f5cee08 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ # cMCP — Confidential MCP Gateway +[![CI](https://github.com/agentrust-io/cmcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/agentrust-io/cmcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/cmcp-gateway)](https://pypi.org/project/cmcp-gateway/) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/agentrust-io/cmcp/badge)](https://scorecard.dev/viewer/?uri=github.com/agentrust-io/cmcp) + Hardware-attested policy enforcement for MCP tool calls. Every tool call is intercepted, evaluated against a Cedar policy bundle, and enforced by a policy engine running inside a Trusted Execution Environment (TEE). The policy bundle hash is measured into the hardware attestation report before any code runs. ```yaml @@ -30,14 +32,15 @@ cmcp start --config cmcp-config.yaml ## Architecture ``` -Agent → cMCP Gateway → Cedar Policy Engine (TEE) → Tool - ↓ - TRACE Claim Output - - policy_bundle_hash - - enforcement_mode - - audit_chain_root - - trust_score - - tee_public_key +Agent -> cMCP Gateway -> Cedar Policy Engine (TEE) -> Tool + | + GatewayClaim (TRACE Profile) + +-- trace.eat_profile + +-- trace.runtime.platform + measurement + +-- trace.policy.bundle_hash + +-- trace.cnf.jwk (Ed25519 confirmation key) + +-- gateway.audit_chain (root/tip/length) + +-- signature (Ed25519 over canonical JSON) ``` ## Hardware Providers @@ -51,8 +54,12 @@ Agent → cMCP Gateway → Cedar Policy Engine (TEE) → Tool ## Status -Private. Launching at CC Summit June 23, 2026. See [agentrust-io](https://github.com/agentrust-io) for release timeline. +Developer preview. Launching at CC Summit, June 23 2026. See [ROADMAP.md](ROADMAP.md) for what is planned. ## License -MIT \ No newline at end of file +MIT + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: [SECURITY.md](SECURITY.md). diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..db5b45ea --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,34 @@ +# cMCP Roadmap + +## 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. + +- TEE attestation support (quote generation and basic verification) +- Cedar policy engine integration for request authorization +- TRACE Claim generation from attestation evidence +- Standalone verifier CLI for offline claim inspection + +## v0.2 — Candidates + +Provider-specific attestation verification: +- TPM2 quote verification +- AMD SEV-SNP attestation report parsing and verification +- Intel TDX attestation report parsing and verification + +Server integration: +- Session-scoped TRACE Claim emission wired into `server.py` request lifecycle +- Claim correlation across multi-turn sessions + +Observability: +- OpenTelemetry spans for Cedar policy decisions (allow/deny with policy id) +- Structured policy audit log export + +Transparency: +- Transparency log integration for TRACE Claim anchoring (write and lookup) + +## v1.0 — Stable Targets + +- Stable `GatewayClaim` schema with documented versioning guarantees +- Full RATS/EAT conformance (RFC 9334, draft-ietf-rats-eat) +- SLSA Level 3 build provenance for cMCP release artifacts diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..f482a256 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,40 @@ +# Security Policy + +## Reporting a Vulnerability + +**Do not open a public GitHub issue for security vulnerabilities.** + +Report vulnerabilities privately via [GitHub Security Advisories](https://github.com/agentrust-io/cmcp/security/advisories/new). You will receive a confirmation within 2 business days and a triage decision within 5 business days. + +## Response SLAs + +| Severity | Definition | Fix Target | +|----------|------------|------------| +| Critical | Remote code execution, attestation bypass, signing key extraction, audit chain forgery | 30 days from confirmed report | +| High / Medium / Low | All other confirmed vulnerabilities | 90 days from confirmed report | + +Timeline starts when the issue is confirmed as a valid vulnerability, not on initial receipt. We will communicate progress at least every 14 days during active remediation. + +## Scope + +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 + +## 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) +- Theoretical weaknesses in TEE threat models that are already acknowledged in public literature +- Issues in third-party MCP tool implementations invoked through the gateway + +If you are unsure whether an issue is in scope, report it anyway and we will triage. + +## Credit + +Reporters of confirmed, in-scope vulnerabilities will be acknowledged by name (or handle, if preferred) in the release notes of the fix. We will not publish details of the report without your consent. If you prefer to remain anonymous, say so in your advisory submission and we will honor that. diff --git a/pyproject.toml b/pyproject.toml index c6fde0b6..4b0f1f9c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,6 +8,18 @@ version = "0.1.0" description = "Hardware-attested MCP gateway — TEE-enforced policy and TRACE Claim generation" readme = "README.md" license = { text = "MIT" } +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Topic :: Security", + "Topic :: Scientific/Engineering :: Artificial Intelligence", + "Typing :: Typed", +] requires-python = ">=3.11" dependencies = [ "cryptography>=42.0", @@ -29,6 +41,8 @@ dev = [ "ruff>=0.4", "mypy>=1.10", "types-pyyaml", + "bandit[toml]>=1.7", + "pip-audit>=2.6", ] [project.scripts] @@ -51,6 +65,16 @@ target-version = "py311" select = ["E", "F", "W", "I", "UP", "B", "C4", "PIE", "T20", "RET", "SIM"] ignore = ["E501"] +[tool.bandit] +skips = ["B101"] + +[tool.coverage.run] +source = ["src"] +omit = ["*/cli.py"] + +[tool.coverage.report] +fail_under = 70 + [tool.mypy] python_version = "3.11" strict = true