cmcp

<p align="center">
  <img src="https://raw.githubusercontent.com/agentrust-io/cmcp/HEAD/docs/assets/icon.svg" width="96" height="96" alt="cMCP"/>
</p>

# cMCP: Runtime MCP riservato

Aggiornamenti della community e contributi in evidenza: [AgenTrust su LinkedIn](https://www.linkedin.com/company/agentrust-io/).

### Applica la policy degli strumenti MCP all'interno di un TEE, dove l'agente che governa non può raggiungerla

<p align="center">
  <a href="https://cmcp.agentrust-io.com">
    <img src="https://img.shields.io/badge/Documentation-cmcp.agentrust--io.com-7c3aed?style=for-the-badge" alt="Documentation" height="36">
  </a>
</p>

<p align="center">
  <strong>
    <a href="#quick-start">Avvio rapido</a> ·
    <a href="#how-it-works">Architettura</a> ·
    <a href="#configuration">Configurazione</a> ·
    <a href="#cli-reference">CLI</a> ·
    <a href="https://github.com/agentrust-io/cmcp/blob/main/CHANGELOG.md">Changelog</a>
  </strong>
</p>

[![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-runtime)](https://pypi.org/project/cmcp-runtime/) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/agentrust-io/cmcp/badge)](https://scorecard.dev/viewer/?uri=github.com/agentrust-io/cmcp) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat)](https://discord.gg/grgzFEHgkj)

> **Developer Preview** - presentato al Confidential Computing Summit, 23 giugno 2026. Potrebbero esserci modifiche incompatibili prima della v1.0. Consulta [STATUS.md](https://github.com/agentrust-io/cmcp/blob/main/STATUS.md) per sapere esattamente cosa è disponibile oggi rispetto a ciò che è in roadmap.

**cMCP (Confidential MCP Runtime) è un gateway open-source che verifica ogni chiamata a uno strumento effettuata da un agente AI rispetto alle regole che scrivi, e può essere eseguito su hardware isolato che l'agente non può manomettere.** Gli agenti AI utilizzano strumenti (database, CRM, email, API interne) inviando richieste chiamate tool call, solitamente tramite MCP, il Model Context Protocol. cMCP si interpone nel percorso di queste chiamate, verifica ciascuna rispetto alle tue regole (scritte nel linguaggio di policy Cedar) e blocca quelle che le regole vietano. Può essere eseguito all'interno di un TEE (trusted execution environment: hardware che mantiene la memoria di un programma isolata persino dal proprietario della macchina), dove l'agente che governa non può raggiungerlo. Ogni sessione termina con una ricevuta firmata, un TRACE Claim, che chiunque può verificare senza doversi fidare di chi ha eseguito il gateway. La ricevuta è supportata da un report hardware quando il gateway viene eseguito in un TEE, ed è solo firmata (senza prova hardware) in modalità software. Non hai familiarità con questi termini? Consulta [i termini, in parole semplici](https://agentrust-io.com/#plain-terms).

> **TL;DR:** Punta il tuo agente verso il cMCP Gateway. Verifica ogni chiamata a uno strumento rispetto alle tue regole Cedar, blocca o oscura (sostituisce) ciò che le regole negano, e ti fornisce una ricevuta firmata che mostra se qualcuno l'ha alterata. Esegui `pip install cmcp-runtime` e inizia in modalità software su qualsiasi computer; nessun hardware speciale richiesto.

Il tuo agente chiama Snowflake, Salesforce, una dozzina di API. Cosa gli impedisce di divulgare i dati di un cliente durante una di queste chiamate? Se un'autorità di regolamentazione lo chiedesse, potresti dimostrare che non è accaduto?

---

## Il problema

Un agente chiama uno strumento. Il motore di policy dice consenti. La chiamata allo strumento passa.

Niente di tutto ciò dimostra che il motore di policy stesso non sia stato compromesso. La governance MCP solo software non può garantire:

- Che la policy Cedar su disco sia quella che è stata eseguita. Un amministratore malevolo può sostituire il bundle dopo l'approvazione; il controllo dell'hash viene eseguito all'interno dello stesso sistema operativo controllato dall'amministratore.
- Che la decisione di consenso/rifiuto non sia stata invertita in memoria. Una CVE della supply chain nel valutatore viene eseguita nello stesso spazio di indirizzi dell'attaccante.
- Che il registro di audit rifletta ciò che è realmente accaduto. Qualsiasi parte in possesso della chiave di firma software può ricostruire a posteriori una catena di audit valida.

Il piano di controllo che governa le chiamate agli strumenti deve essere eseguito dove non può essere raggiunto dal processo che governa.

Applicazione delle policy con attestazione hardware per le chiamate agli strumenti MCP. Ogni chiamata a uno strumento viene intercettata, valutata rispetto a un bundle di policy Cedar e applicata da un motore di policy in esecuzione all'interno di un Trusted Execution Environment (TEE). Prima di servire una singola chiamata a uno strumento, il gateway misura il proprio codice installato, il bundle di policy e la configurazione nel report di attestazione hardware, e riattesta ogni volta che il bundle viene ricaricato.

In un deployment hardware, il cMCP Runtime elabora i payload delle chiamate agli strumenti all'interno del TEE. Ciò che l'host e il provider di connettività possono leggere dipende anche dalla policy di egress, e il server degli strumenti upstream è un componente separato al di fuori del TEE. La modalità software (`CMCP_DEV_MODE`) non fornisce alcun isolamento hardware. [LIMITATIONS.md](https://github.com/agentrust-io/cmcp/blob/main/LIMITATIONS.md) elenca ciò che cMCP non impedisce.

---

## Avvio rapido

```bash
pip install cmcp-runtime
```

Crea `cmcp-config.yaml`:

```yaml
attestation:
  provider: auto
  enforcement_mode: advisory   # advisory eases first-run tuning; the default is `enforcing`
listen_addr: "127.0.0.1:8443"  # pin loopback: dev mode runs without a bearer token
policy_bundle_path: ./policies/
catalog_path: ./catalog.json
```

`listen_addr` non è opzionale qui. `CMCP_DEV_MODE=1` salta deliberatamente il
requisito del bearer token per permetterti di provare rapidamente, e il bind predefinito è
comunque `0.0.0.0:8443`. Nella 0.3.0 quella combinazione attivava un gateway
non autenticato su ogni interfaccia della tua macchina. Dalla 0.4.0 viene rifiutata: la modalità
dev senza token può effettuare il bind solo su un indirizzo di loopback, e un bind non-loopback richiede
`CMCP_BEARER_TOKEN`. Fissa esplicitamente `listen_addr` e la configurazione sarà corretta in
entrambi i casi.

Avvia il gateway:

```bash
CMCP_DEV_MODE=1 cmcp start --config cmcp-config.yaml
```

Effettua una chiamata a uno strumento:

```bash
curl -X POST http://localhost:8443/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"salesforce.contacts","arguments":{"query":"Acme Corp"},"_cmcp":{"session_id":"s1","workflow_id":"demo-agent"}}}'
```

Preferisci una versione guidata? [agentrust-io.com/quickstart](https://agentrust-io.com/quickstart/)
percorre lo stesso percorso in circa dieci minuti su un laptop, senza hardware e senza
registrazione: installa, scrivi una regola Cedar `forbid`, osserva una chiamata a uno strumento restituire 403
`POLICY_DENY` prima che raggiunga un upstream, poi verifica la ricevuta firmata.

Consulta [docs/quickstart.md](https://github.com/agentrust-io/cmcp/blob/main/docs/quickstart.md) per la procedura completa: policy Cedar, catalogo degli strumenti, primo TRACE Claim e verifica (nessun TEE hardware richiesto).

---

## Come funziona

1. L'agente invia ogni chiamata a uno strumento al cMCP Gateway invece che direttamente ai server MCP.
2. All'avvio, prima di servire traffico, il gateway misura il proprio codice installato, il bundle di policy Cedar e la configurazione. Su SEV-SNP, TDX e Azure CVM il digest è vincolato in `report_data`; sul livello TPM viene esteso in un indice NV certificato. Un ricaricamento della policy attiva una nuova attestazione.
3. Ogni chiamata a uno strumento in ingresso viene valutata dal motore di policy Cedar in esecuzione all'interno del TEE. Il risultato è allow, deny o redact. La chiamata e la sua decisione vengono aggiunte alla catena di audit sigillata dall'hardware.
4. Al termine della sessione il gateway produce un TRACE Claim: un artefatto firmato e attestato dall'hardware che registra quali strumenti sono stati eseguiti, quale policy ha deciso ogni chiamata e l'intera catena di audit. Un verificatore controlla tutto ciò senza fidarsi dell'operatore.

```
Agent -> cMCP Runtime -> 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)
```

---

## Provider hardware

| Provider | Piattaforma | Garanzia | Note |
|---|---|---|---|
| `tpm` | TPM 2.0 / vTPM (Azure, AWS, GCP Trusted Launch) | Media | Quote TPM locale |
| `sev-snp` | AMD SEV-SNP (Azure DCasv5, AWS C6a Nitro) | Alta | AMD KDS |
| `tdx` | Intel TDX (Azure DCedsv5, GCP C3) | Alta | Intel PCS |
| `gpu-cc` _(v0.2)_ | NVIDIA H100/H200/Blackwell (modalità CC) | Alta | NVIDIA Remote Attestation Service (NRAS) |

Ordine di rilevamento automatico dei provider: `azure-cvm -> tpm -> sev-snp -> tdx`. Viene selezionato il primo provider il cui `detect()` ha esito positivo. Se non viene rilevato alcun provider hardware, il gateway si avvia solo con `CMCP_DEV_MODE=1` (un fallback software-only non attestato) e altrimenti rifiuta di avviarsi.

```python
from cmcp_runtime.config import TEEProvider

# Auto-detect (default)
# attestation.provider: auto  ->  azure-cvm -> tpm -> sev-snp -> tdx
# (software-only is used only under CMCP_DEV_MODE=1)

# Explicit hardware selection
# attestation.provider: sev-snp
```

## Modalità di applicazione

| Modalità | Comportamento | Caso d'uso |
|---|---|---|
| `enforcing` | I rifiuti della policy restituiscono HTTP 403; la chiamata non viene inoltrata | Produzione |
| `advisory` | I rifiuti della policy vengono registrati; la chiamata procede | Prima distribuzione, ottimizzazione della policy |
| `silent` | La policy viene valutata ma nulla viene registrato o bloccato | Baseline |

Il valore predefinito è `enforcing`. Imposta `enforcement_mode: advisory` in `cmcp-config.yaml` per utilizzare la modalità advisory.

---

## Configurazione

Riferimento completo di `cmcp-config.yaml`:

```yaml
attestation:
  provider: auto                    # auto | tpm | sev-snp | tdx | software-only
  enforcement_mode: enforcing       # enforcing | advisory | silent
  validity_seconds: 86400           # attestation freshness window (default: 24 hours)
  staleness_policy: fail_closed     # fail_closed | warn_only
  expected_measurement: ~           # pin a specific PCR/measurement (optional)

policy_bundle_path: policies/       # directory containing .cedar files and manifest.json
catalog_path: catalog.json          # approved tool catalog

listen_addr: "127.0.0.1:8443"     # tokenless dev mode is loopback-only; set CMCP_BEARER_TOKEN before binding wider
max_response_size_bytes: 2097152    # 2 MB default
policy_reload_interval_seconds: 0   # >0 with a pinned CMCP_POLICY_HASH refuses to start, see docs/spec/policy-hot-reload.md
```

Variabili d'ambiente:

| Variabile | Effetto |
|---|---|
| `CMCP_DEV_MODE=1` | Usa un provider TEE solo software; nessun hardware richiesto |
| `CMCP_BEARER_TOKEN` | Richiede questo bearer token su tutte le richieste in ingresso |

---

## Riferimento CLI

| Comando | Flag | Descrizione |
|---|---|---|
| `cmcp start` | `--config PATH` (obbligatorio) | Avvia il gateway |
| `cmcp validate-config` | `--config PATH` (obbligatorio) | Convalida `cmcp-config.yaml` senza avviarlo |
| `cmcp validate-bundle` | `--bundle-path PATH` (obbligatorio), `--expected-hash sha256:<hex>` (obbligatorio) | Verifica l'hash di un bundle Cedar prima del deployment |
| `cmcp verify` | `CLAIM_FILE` (obbligatorio); `--policy-hash`, `--catalog-hash`, `--max-age`, `--trusted-key`, `--trusted-tpm-ca`, `--audit-bundle`, `--agent-manifest`, `--agent-manifest-trust-anchor` | Verifica un TRACE Claim firmato (firma, schema, freschezza, catena di audit, hash fissati e trust anchor) |

---

## TRACE Claims

Un `GatewayClaim` è l'unità di prova consegnata a un auditor, a un'autorità di regolamentazione o a un verificatore a valle. Viene prodotto per sessione (o per chiamata, in modo configurabile) e firmato con una chiave che non lascia mai il TEE.

| Campo | Descrizione |
|---|---|
| `trace.eat_profile` | URI del profilo EAT: `tag:agentrust-io.com,2026:trace-v0.2` |
| `trace.runtime` | Piattaforma TEE e misurazione hardware registrate all'avvio dell'enclave |
| `trace.policy.bundle_hash` | SHA-256 del bundle Cedar caricato all'avvio; la modifica di qualsiasi file di policy cambia questo valore |
| `trace.cnf.jwk` | Chiave pubblica Ed25519 associata alla chiave di firma del TEE |
| `trace.tool_transcript` | Vista per chiamata derivata dalla catena di audit: `hash` (si lega alla punta della catena di audit), `call_count` e `entries` che preservano la privacy (nome dello strumento, classe di dati, decisione) |
| `gateway.audit_chain` | Radice e punta del log di audit concatenato tramite hash; verificabile senza rieseguire le singole voci |
| `signature` | Ed25519 sul JSON canonico dell'intero corpo del claim (RFC 8785) |

(Questa tabella è un riepilogo dei campi più utilizzati.)

La verifica con la libreria `cmcp_verify` non richiede di fidarsi dell'operatore. Il verificatore controlla la firma rispetto alla chiave legata al TEE, l'hash del bundle di policy rispetto al valore approvato e la coerenza interna della catena di audit.

Lo schema normativo è [`schemas/trace-claim.schema.json`](https://github.com/agentrust-io/cmcp/blob/main/schemas/trace-claim.schema.json), e [docs/quickstart.md](https://github.com/agentrust-io/cmcp/blob/main/docs/quickstart.md) mostra un esempio completo. Consultare [docs/spec/verification-library.md](https://github.com/agentrust-io/cmcp/blob/main/docs/spec/verification-library.md) e la [specifica TRACE](https://trace.agentrust-io.com) per il protocollo di verifica completo.

---

## Allineamento agli standard

| Standard | Copertura |
|---|---|
| OWASP Agentic AI Top 10 | MCP10 (fuga di dati tramite chiamate agli strumenti), MCP02 (strumenti non autorizzati), MCP08 (governance dimostrabile), MCP04 (supply chain) |
| NIST SP 800-207 | Policy decision point all'interno del TEE; nessuna fiducia implicita nell'identità del workload |
| EU AI Act Art. 12, 15 | Registrazioni di audit per ogni decisione (Art. 12); controlli di cybersecurity supportati dal TEE (Art. 15) |
| DORA Art. 9 | Catena di attestazione; conservazione del log di audit tramite `gateway.audit_chain` |
| RATS/EAT RFC 9711 | `GatewayClaim` è un EAT; il campo `eat_profile` identifica il profilo TRACE |

---

## Sicurezza

| Strumento | Cosa verifica |
|---|---|
| ruff | Linting di stile e import su ogni PR |
| bandit | Linting di sicurezza Python su ogni PR |
| pip-audit | Scansione delle vulnerabilità delle dipendenze su ogni PR |
| mypy | Controllo statico dei tipi su ogni PR |
| CodeQL | SAST Python, query security-extended, settimanale |
| OpenSSF Scorecard | Punteggio settimanale, caricamento SARIF |

Consultare [SECURITY.md](https://github.com/agentrust-io/cmcp/blob/main/SECURITY.md) per la segnalazione delle vulnerabilità e gli SLA di risposta. Consultare [LIMITATIONS.md](https://github.com/agentrust-io/cmcp/blob/main/LIMITATIONS.md) per i confini espliciti dell'ambito, inclusi i rischi residui per la cattura del payload APM, l'iniezione di configurazione a runtime e la supply chain P4.1 (typosquat) che la Fase 1 non chiude.

---

## Documentazione

| Pagina | Descrizione |
|---|---|
| [docs/quickstart.md](https://github.com/agentrust-io/cmcp/blob/main/docs/quickstart.md) | Da zero al primo TRACE Claim in meno di 30 minuti |
| [docs/configuration.md](https://github.com/agentrust-io/cmcp/blob/main/docs/configuration.md) | Riferimento completo alla configurazione con tutti i campi e i valori predefiniti |
| [docs/confinement.md](https://github.com/agentrust-io/cmcp/blob/main/docs/confinement.md) | Sandbox sperimentale per agenti Linux, test di bypass e ipotesi di fiducia |
| [docs/SPEC.md](https://github.com/agentrust-io/cmcp/blob/main/docs/SPEC.md) | Specifica del prodotto: tassonomia dei problemi, architettura, matrice di copertura |
| [docs/spec/threat-model.md](https://github.com/agentrust-io/cmcp/blob/main/docs/spec/threat-model.md) | Analisi STRIDE, modello dell'avversario, rischi residui |
| [docs/spec/cedar-policy.md](https://github.com/agentrust-io/cmcp/blob/main/docs/spec/cedar-policy.md) | Riferimento al linguaggio di policy Cedar e schema |
| [docs/testing/benchmarks.md](https://github.com/agentrust-io/cmcp/blob/main/docs/testing/benchmarks.md) | Benchmark di latenza e throughput per provider TEE |

---

## FAQ

### Cos'è cMCP?

cMCP (Confidential MCP Runtime) è un gateway open-source che applica la policy sulle chiamate agli strumenti MCP all'interno di un Trusted Execution Environment hardware. Intercetta ogni chiamata a uno strumento, la valuta rispetto a un bundle di policy Cedar, applica la decisione (consenti, nega o oscura) e registra la chiamata in una catena di audit sigillata dall'hardware.

### In cosa cMCP è diverso dalla governance MCP puramente software?

La governance puramente software esegue il motore di policy nello stesso sistema operativo che un operatore o una CVE della supply chain può raggiungere, quindi non può dimostrare che la policy eseguita fosse quella approvata né che la decisione non sia stata alterata in memoria. cMCP esegue il motore di policy all'interno di un TEE e misura il proprio codice e il bundle Cedar nel report di attestazione hardware prima di servire una singola chiamata, così il piano di controllo non è raggiungibile dal processo che governa.

### Serve hardware speciale per provarlo?

No. Imposta `CMCP_DEV_MODE=1` per usare il provider TEE puramente software ed eseguire l'intera quickstart senza un TEE hardware. I provider hardware (TPM, AMD SEV-SNP, Intel TDX) vengono usati in produzione.

### Cos'è un TRACE Claim?

Un TRACE Claim (un `GatewayClaim`) è un artefatto firmato e attestato dall'hardware prodotto per ogni sessione. Registra quali strumenti sono stati eseguiti, quale policy ha deciso ogni chiamata, l'hash del bundle Cedar e la catena di audit, ed è firmato con una chiave Ed25519 che non lascia mai il TEE. Un verificatore lo controlla con la libreria `cmcp_verify` senza doversi fidare dell'operatore.

### Quali provider TEE sono supportati?

TPM 2.0 / vTPM, AMD SEV-SNP e Intel TDX, con il confidential computing per GPU NVIDIA previsto per la v0.2. L'ordine di rilevamento automatico è Azure confidential VM, poi TPM 2.0 / vTPM, poi AMD SEV-SNP, poi Intel TDX; il provider puramente software viene usato solo con CMCP_DEV_MODE=1.

### Con quale licenza è distribuito cMCP?

MIT.

---

## Contribuire

[CONTRIBUTING.md](https://github.com/agentrust-io/cmcp/blob/main/CONTRIBUTING.md) · [GOVERNANCE.md](https://github.com/agentrust-io/cmcp/blob/main/GOVERNANCE.md) · [Discussions](https://github.com/orgs/agentrust-io/discussions)

Unisciti alla community su [Discord](https://discord.gg/grgzFEHgkj).

Usi cMCP in produzione? Aggiungi la tua organizzazione a [ADOPTERS.md](https://github.com/agentrust-io/cmcp/blob/main/ADOPTERS.md).

---

## Licenza

MIT - vedi [LICENSE](https://github.com/agentrust-io/cmcp/blob/main/LICENSE).