Evidence Room | Developer Docs

L'Evidence Room (/evidence-room) è il luogo in cui l'attività degli agenti governati si trasforma in prove pronte per l'audit. Compila record firmati, lineage di esecuzione e stato delle policy in artefatti portabili e a prova di manomissione, che puoi consegnare a un revisore esterno e che il revisore può verificare sul proprio portatile, offline — controllando le firme, ogni hash degli artefatti e la Merkle root propria del bundle — senza alcuna connessione attiva a KLA. Questa pagina è destinata ai responsabili di compliance, rischio e audit che stanno costruendo un fascicolo di prove, e agli operatori della piattaforma che lo esportano e lo condividono.

L'Evidence Room consuma l'output della pipeline Evidence-by-Default: gli span OpenTelemetry confluiscono nel KLA Collector (che redige le informazioni di identificazione personale, o PII), poi nel registro crittografico append-only ImmuDB. Ogni bundle esportato è sigillato con hash e firme in modo che qualsiasi manomissione successiva del suo contenuto sia rilevabile offline.

Sealed Evidence Bundle

Un Sealed Evidence Bundle è l'oggetto di esportazione centrale: un file .zip autosufficiente che racchiude tutto il necessario per ricostruire e dimostrare una porzione di storia degli agenti.

Contenuto	Cosa dimostra
Record JSON firmati	Le esatte azioni dell'agente, le chiamate agli strumenti e i costi che si sono verificati
Lineage Record	La traccia completa, passo dopo passo, di ogni esecuzione governata
Stato delle policy	Quale policy pack era attivo e la decisione restituita: `allow`, `warn`, `require_approval` o `block`
Esiti del Decision Desk	Qualsiasi approvazione umana o Escalation che ha risolto una decisione `require_approval`
Merkle proof e ancoraggio al registro	La Merkle root degli artefatti propria del bundle, più l'ancoraggio al registro immudb e la relativa proof conservata per questo manifest

🛡️ Important

Un **Lineage Record** è il nome che KLA assegna a una singola traccia end-to-end dell'esecuzione di un agente. Raggruppare un Lineage Record con la relativa decisione di policy e l'esito del Decision Desk produce una narrazione completa e difendibile per una singola esecuzione, in un unico file.

Verifica indipendente

Questo è il senso dell'Evidence Room: gran parte della verifica viene eseguita offline, senza riporre fiducia nei sistemi attivi di KLA. Un revisore verifica le firme SEK e TEK, conferma l'hash e la dimensione di ogni artefatto e ricalcola la Merkle root propria del bundle — interamente sul proprio portatile, senza necessità di accesso alla rete. Il bundle contiene anche l'ancoraggio al registro immudb e una ricevuta OpenTimestamps su Bitcoin per questo manifest; offline, il verificatore conferma che questi siano presenti e che siano vincolati al manifest (la verifica completa dell'inclusione nel registro e la conferma on-chain richiedono rispettivamente lo stato firmato del registro e la blockchain Bitcoin).

kla evidence verify \
  --bundle evidence-room_acme-prod_exp_9f2c_v1.zip \
  --out ./report

Il verificatore conferma le firme SEK e TEK, ricalcola la Merkle root propria del bundle e controlla che l'ancoraggio al registro immudb e la ricevuta OpenTimestamps siano vincolati a questo manifest, poi scrive un file verification-report.json e un report HTML leggibile da una persona. Il codice di uscita 0 significa che tutti i controlli offline sono stati superati.

flowchart LR
  A["Attività dell'agente"] --> B["KLA Collector<br/>redazione PII"]
  B --> C["Registro ImmuDB<br/>Merkle proof"]
  C --> D["Sealed Evidence Bundle"]
  D --> E["Il revisore verifica offline"]

Job di esportazione e link di condivisione sicuri

Gli insiemi di prove possono coprire mesi di attività, perciò le esportazioni vengono eseguite come job asincroni. Definisci l'ambito (un intervallo di date, un agente o un singolo Lineage Record), metti in coda l'esportazione e ne monitori il completamento senza mantenere aperta una sessione.

curl -X POST https://api.kla.digital/v1/evidence.export \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-tenant-id: acme-prod" \
  -d '{"agent":"refund-approver","from":"2026-01-01","to":"2026-03-31"}'

Quando il bundle è pronto, genera un link di condivisione sicuro: un URL di download a tempo limitato e con accesso circoscritto, che puoi inviare a un regolatore o revisore esterno senza dovergli predisporre un account KLA. Il destinatario scarica il bundle e lo verifica con i passaggi descritti sopra.

💡 Tip

I link di condivisione hanno un ambito definito e una scadenza. Imposta la finestra più breve compatibile con il calendario di revisione del revisore: il link si revoca automaticamente alla scadenza.

Control Mapping e Control Pack

Le prove grezze rispondono alla domanda cosa è successo. I revisori hanno bisogno di sapere anche quale requisito viene soddisfatto. Il Control Mapping collega i singoli segnali di governance (una decisione di policy, un'approvazione, un evento di redazione) a clausole specifiche di un framework di compliance.

Un Control Pack è un'esportazione orientata alla compliance: un Sealed Evidence Bundle organizzato attorno a un framework anziché a un intervallo temporale. KLA fornisce mapping per i regimi più comuni:

EU AI Act, Allegato IV: i requisiti di documentazione tecnica per i sistemi di IA ad alto rischio, mappati sulle istruzioni dei tuoi agenti, sui controlli di policy e sull'audit trail.
SOC 2: i criteri di change management, controllo degli accessi e monitoraggio, comprovati da Release, record del Decision Desk e Lineage continuo.

Un Control Pack ti consente di rispondere a una richiesta di documentazione tecnica ai sensi dell'EU AI Act o a una revisione SOC 2 Type II con un unico file verificabile, anziché con una cartella di screenshot. Usa il Lineage Explorer per indagare su una specifica esecuzione, quindi esportala direttamente nell'Evidence Room come parte del pack.