Verifica gli eventi di Access Transparency con il log di trasparenza

Scopri come verificare crittograficamente che nessun evento di Access Transparency sia stato rimosso o alterato dopo essere stato registrato nel log di trasparenza della tua organizzazione.

Come funziona il log di trasparenza

Un "transparency log" (log di trasparenza) è una tecnica per rendere un registro a prova di manomissione. Le voci vengono solo aggiunte in coda. Ogni volta che il log cresce, il suo operatore firma una breve dichiarazione, chiamata "checkpoint" (punto di controllo), che vincola ogni voce fino a quel momento tramite un hash dell'albero di Merkle. Chiunque conservi un checkpoint può in seguito richiedere la prova che il log attuale contenga ancora tutto ciò che quel checkpoint copriva, invariato e nello stesso ordine. Rimuovere o riscrivere una voce non può quindi passare inosservato a un verificatore che abbia conservato un checkpoint che copriva quella voce. Certificate Transparency e il database dei checksum dei moduli Go sono costruiti sulla stessa tecnica. C2SP tlog-tiles è una specifica aperta per servire un tale log come checkpoint firmati più tile statiche di hash e voci, memorizzabili nella cache, in modo che i client possano recuperare gli hash e calcolare ogni prova da soli.

Quando Access Transparency è abilitato, Anthropic mantiene un log di trasparenza per la tua organizzazione. È un registro di sola aggiunta, firmato crittograficamente, degli eventi di Access Transparency (anthropic_access e cmek_preserve). Ogni evento di questo tipo registrato per la tua organizzazione dopo la creazione del log viene aggiunto a esso. Il log segue il formato C2SP tlog-tiles, quindi gli strumenti costruiti per quello standard comprendono i suoi checkpoint, tile e prove.

• Un log per organizzazione. Il log di ogni organizzazione ha una stringa di origine fissa: axt.anthropic.com/<your organization UUID>. L'origine non cambia mai per tutta la vita dell'organizzazione.
• Ogni nuovo evento diventa una foglia. Quando un evento di Access Transparency diventa idoneo a comparire nel tuo Activity Feed, viene prima aggiunto al tuo log come foglia, e solo dopo servito nel feed. Una foglia è una serializzazione deterministica dei campi documentati dell'evento. L'evento nel tuo feed riporta transparency_log_leaf_index, la sua posizione a base zero nel tuo log.
• I checkpoint vincolano l'intera cronologia. Il log è un albero di Merkle. Ogni volta che cresce, Anthropic pubblica un checkpoint firmato: un breve documento di testo che indica l'origine del log, la sua dimensione attuale e l'hash radice che vincola ogni foglia. Ogni checkpoint riporta esattamente una firma dalla chiave di firma del log.
• Ne derivano due prove. Una prova di inclusione mostra che un evento specifico è presente nella sua posizione sotto un checkpoint. Una prova di consistenza mostra che un checkpoint successivo è un'estensione di sola aggiunta di uno precedente che hai salvato, quindi nulla tra i due è stato rimosso o modificato.
• Le chiavi di verifica sono servite in banda. L'endpoint delle chiavi di verifica restituisce le chiavi pubbliche che firmano i checkpoint. In una rotazione pianificata delle chiavi, la nuova chiave viene aggiunta a quell'elenco prima che inizi a firmare, e le chiavi precedenti restano elencate. I checkpoint che già possiedi continuano quindi a essere verificati.

Cosa dimostra il log di trasparenza

• I campi foglia di un evento che possiedi (elencati in Come un evento diventa una foglia) sono, byte per byte, ciò che Anthropic ha registrato nel log.
• Il log della tua organizzazione cresce soltanto. La verifica rispetto a un checkpoint che possiedi fallisce se un evento registrato nel log viene successivamente eliminato o riscritto lì. Fallisce anche se ti viene servita una cronologia diversa da quella che ti era stata servita in precedenza.
• Le nuove voci possono solo essere aggiunte in coda. Un evento non può essere inserito in una cronologia che hai già verificato.

Cosa non dimostra né cambia

• Non dimostra che ogni accesso sia stato registrato, né che un evento registrato descriva accuratamente l'accesso. Dimostra solo che ciò che Anthropic ha registrato nel log non è cambiato da allora.
• Non cambia cosa copre Access Transparency né quando arrivano gli eventi.
• I campi serviti al di fuori della foglia, come workspace_uuid e qualsiasi campo aggiunto in seguito, non sono coperti dalla prova.
• Una prova di inclusione vale per un evento che ti è stato servito. Non dimostra di per sé che il feed abbia elencato ogni foglia contenuta nel log. I bundle di voci del log contengono ogni foglia, quindi puoi leggere direttamente l'insieme completo degli eventi registrati quando ne hai bisogno.
• La presenza di transparency_log_leaf_index su un evento è un puntatore, non una prova. Verifica sempre l'inclusione prima di considerare un evento come registrato nel log.
• La protezione contro una cronologia riscritta deriva dai checkpoint che conservi. La firma di un checkpoint da parte di una chiave elencata in Impronte delle chiavi pubblicate dimostra che proviene dal log di Anthropic. Una prova di consistenza dal checkpoint che hai salvato l'ultima volta dimostra che la cronologia che hai già osservato è solo cresciuta.

Prima di iniziare

Ti servono:

• Una Compliance Access Key con lo scope read:compliance_activities, la stessa chiave e lo stesso scope che usi per l'Activity Feed. Una chiave dell'organizzazione padre può leggere il log di ciascuna organizzazione figlia iscritta indicando l'organizzazione figlia in ogni richiesta.
• L'UUID della tua organizzazione. Trovalo nella Claude Console in Settings > Organization. È lo stesso valore che l'Activity Feed serve come organization_uuid, ma prendilo dalla Console. Questo valore è ciò che rende un checkpoint tuo, quindi non deve provenire dall'API che stai verificando. Da esso derivi l'origine del tuo log come axt.anthropic.com/<organization UUID>. Deriva questa stringa da solo. Non leggerla da una risposta dell'API.
• Un luogo durevole in cui conservare l'ultimo checkpoint che hai verificato. Quel checkpoint salvato è ciò che trasforma "il log è consistente oggi" in "il log è stato consistente da quando hai iniziato a osservarlo".

Tempistiche

• Eventi: gli eventi di Access Transparency compaiono nel tuo Activity Feed entro due giorni lavorativi dall'accesso. Un evento entra nel log solo quando è idoneo a essere servito, quindi il log non rivela mai un evento in anticipo. Poiché il log viene scritto prima che il feed serva l'evento, una voce può comparire brevemente nel log prima che il suo evento compaia nel tuo feed. Questo intervallo non è una discrepanza.
• Checkpoint: un nuovo checkpoint viene pubblicato ogni volta che il tuo log cresce.
• Prove di inclusione: una prova per un evento appena servito è disponibile una volta pubblicato un checkpoint che copre la posizione dell'evento, normalmente molto poco dopo la comparsa dell'evento. Se ne richiedi una prima, ricevi un 404 e riprovi dopo un breve ritardo.
• Cadenza di verifica: esegui la verifica almeno una volta al giorno. Una cadenza oraria è ragionevole.
• Disiscrizione: se la tua organizzazione smette di usare Access Transparency, nulla viene eliminato. Il tuo log resta leggibile tramite gli stessi endpoint. Se Access Transparency viene riabilitato in seguito, lo stesso log continua.

Conservazione ed eliminazione

• Log di trasparenza: Anthropic non elimina voci dal tuo log, e il log non ha scadenza. Viene conservato se la tua organizzazione smette di usare Access Transparency e dopo l'eliminazione della tua organizzazione, perché la rimozione di voci è proprio la modifica che il log esiste per rilevare. I bundle di voci contengono i campi foglia di ogni evento, quindi quei campi vengono conservati per tutto il tempo in cui lo è il log.
• Activity Feed: gli eventi di Access Transparency nell'Activity Feed seguono la conservazione del feed. Le attività vengono conservate per 6 anni. Consulta Interrogare l'Activity Feed.
• Nessuna eliminazione da parte tua: gli endpoint del log di trasparenza sono di sola lettura. Non c'è modo di eliminare o modificare una voce.

Endpoint del log di trasparenza

Sei endpoint di sola lettura sono serviti sotto https://api.anthropic.com/v1/compliance/transparency_log/:

Checkpoint, tile e bundle di voci seguono esattamente il formato di trasmissione C2SP tlog-tiles. I due endpoint delle prove sono una comodità: ogni prova è calcolabile anche dalle tile, quindi non devi mai fidarti dell'output di un endpoint delle prove. Verifichi gli hash che restituisce rispetto a un checkpoint firmato.

Autenticazione e ambito

Invia la tua Compliance Access Key nell'header x-api-key e l'header anthropic-version, come per ogni richiesta alla Compliance API (consulta Versioning). La Compliance API deve essere abilitata per la tua organizzazione.

Non esiste un'autorizzazione separata per il log di trasparenza. Qualsiasi chiave in grado di leggere l'Activity Feed della tua organizzazione, per la tua organizzazione o per la sua organizzazione padre, può leggere l'intero log, inclusi i campi degli eventi nei suoi bundle di voci.

Ogni richiesta legge esattamente il log di un'organizzazione:

• Una chiave a livello di organizzazione legge il log della propria organizzazione. Il parametro di query organization_id è facoltativo. Se presente, deve indicare l'organizzazione della chiave stessa.
• Una chiave a livello di organizzazione padre deve passare organization_id, indicando un'organizzazione figlia.
• organization_id accetta l'ID con tag org_... o l'UUID dell'organizzazione.

Un 404 significa che non esiste un log che questa chiave possa leggere. Un'organizzazione al di fuori dell'ambito della chiave, un'organizzazione inesistente e un'organizzazione il cui log non è ancora stato creato sono deliberatamente indistinguibili. Il log di un'organizzazione che nel frattempo ha smesso di usare Access Transparency non rientra in questo caso: continua a essere servito.

Errori

Gli errori usano l'envelope di errore JSON standard della Compliance API su ogni endpoint, inclusi quelli testuali e binari. Consulta Errori per l'envelope e i tipi di errore condivisi.

Caching

Le risposte possono essere memorizzate nella cache solo dal client richiedente. Cache-Control include sempre private, e le risposte riportano Vary: x-api-key. Non mettere una cache condivisa davanti a questi endpoint. Le tile complete e i bundle di voci completi non cambiano mai e sono serviti con Cache-Control: private, max-age=604800, immutable. Tutto il resto, inclusi checkpoint, prove, chiavi, tile parziali ed errori, è servito con Cache-Control: private, no-store.

Leggi l'ultimo checkpoint

GET /v1/compliance/transparency_log/checkpoint

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/compliance/transparency_log/checkpoint" \
  --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  --header "anthropic-version: 2023-06-01"

La risposta è text/plain: una signed note C2SP. Le righe del corpo sono l'origine, la dimensione dell'albero in decimale e l'hash radice in base64. Segue una riga vuota, poi la riga della firma, che inizia con un trattino lungo (U+2014), indica l'origine e termina con un valore base64. I valori qui sono illustrativi:

axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b
1207
C6C4HzGRqDNlbu54LWCvpDX0NcB5DRTmLcjM4u5vWUI=

— axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b q83vATBFAiEAvL8m…(base64)…

• I primi quattro byte del valore della firma decodificato sono il key_hash della chiave di firma, che ti indica con quale voce dell'insieme delle chiavi di verifica verificare. I byte rimanenti sono una firma ECDSA P-256 ASN.1 DER sullo SHA-256 del corpo della nota: ogni byte prima della riga vuota, incluso il carattere di nuova riga finale del corpo.
• Un checkpoint può riportare righe aggiuntive dopo l'hash radice. Ignora le righe che non comprendi. Sono coperte dalla firma.
• Ignora una riga di firma il cui nome non è la tua origine o il cui hash della chiave non possiedi.
• Non memorizzare mai un checkpoint nella cache. Uno obsoleto nasconde la dimensione attuale del log, quindi gli eventi appena serviti sembrano non coperti.

Leggi le chiavi di verifica

GET /v1/compliance/transparency_log/keys

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/compliance/transparency_log/keys" \
  --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  --header "anthropic-version: 2023-06-01"

{
  "type": "transparency_log_keys",
  "origin": "axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b",
  "log_keys": [
    {
      "verifier_key": "axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b+<key_hash>+<base64 key>",
      "key_hash": "<8 lowercase hex digits>",
      "fingerprint": "<64 lowercase hex digits>",
      "algorithm": "ecdsa_p256_sha256",
      "public_key": "<base64 DER SubjectPublicKeyInfo>"
    }
  ]
}

Il key_hash copre solo i byte della chiave: sono i primi quattro byte dello SHA-256 sul SubjectPublicKeyInfo DER, che è la regola usata dalla codifica note-verifier ECDSA. Non è l'ID della chiave dipendente dal nome che il formato signed-note di base definisce per le chiavi Ed25519, quindi non cambia con l'origine. Una firma valida da parte di una chiave elencata in Impronte delle chiavi pubblicate dimostra che il checkpoint proviene dal servizio di log di trasparenza di Anthropic. La riga di origine all'interno del checkpoint firmato è ciò che lo lega alla tua organizzazione. Ecco perché confronti quella riga con l'origine che derivi da solo.

Le chiavi possono ruotare:

• Una rotazione è un passaggio netto. Da un certo checkpoint in poi, i nuovi checkpoint sono firmati dalla nuova chiave.
• In una rotazione pianificata, la nuova chiave compare in log_keys prima di firmare qualsiasi cosa, e le chiavi precedenti restano elencate. Un checkpoint che hai salvato prima della rotazione continua quindi a essere verificato.
• Un verificatore può recuperare l'insieme delle chiavi a ogni esecuzione o conservarlo localmente. Un verificatore che lo conserva localmente rilegge questo endpoint quando incontra una firma il cui key_hash non possiede.

Impronte delle chiavi pubblicate

Anthropic pubblica qui, al di fuori dell'API, l'impronta di ogni chiave che firma i checkpoint. Questo ti permette di confrontare una chiave che conservi localmente con una fonte che il percorso di distribuzione non può alterare. La chiave che possiedi può provenire da una precedente risposta di GET /keys o da strumenti che fissano la chiave.

Una rotazione pianificata viene annunciata su questa pagina almeno 30 giorni prima che la nuova chiave firmi il suo primo checkpoint. Durante quel periodo di preavviso la nuova chiave è elencata in log_keys e in questa tabella con la sua data di passaggio. Le chiavi ritirate restano elencate con le loro date di servizio. Una chiave che non compare in questa tabella non è legittima, qualunque cosa restituisca GET /keys. Tratta un checkpoint che non viene verificato con nessuna chiave elencata come un fallimento della verifica, e segnalalo al tuo referente Anthropic o al supporto Anthropic.

axt-verify include la chiave attuale in ogni release e non legge mai una chiave dall'API. Ogni release include esattamente una chiave. Alla data di passaggio, Anthropic inizia a firmare con la nuova chiave e pubblica la release di axt-verify che la include. Nella stessa data Anthropic riemette l'ultimo checkpoint di ogni organizzazione con la nuova chiave, anche per un log che non è cresciuto. Aggiorna alla data di passaggio. Eseguire la vecchia release dopo il passaggio fallisce con stato di uscita 1, e lo stesso accade eseguendo la nuova release prima di esso. Entrambi i fallimenti si risolvono una volta eseguita la release corrispondente. A un verificatore che mantieni tu stesso devi aggiungere la nuova impronta, con la sua data di passaggio, prima di quella data.

Recupera una prova di inclusione

GET /v1/compliance/transparency_log/inclusion?leaf_index={index}

curl --fail-with-body -sS -G \
  "https://api.anthropic.com/v1/compliance/transparency_log/inclusion" \
  --data-urlencode "leaf_index=41" \
  --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  --header "anthropic-version: 2023-06-01"

{
  "type": "transparency_log_inclusion_proof",
  "leaf_index": 41,
  "hashes": [
    "mUdyOWMp0zXIq0CDMvSYDUSBl9yAvnTZzdm51RwWpUM=",
    "yR6tDHkAhKvdQSLqQATVjXOo4GM3FDyiKF2XCKTtMUI=",
    "..."
  ],
  "checkpoint": "axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b\n42\nCsRlS31ITFHrX9GR5XjyPw8n0MkfrB8Yh2UDHl3Lr3E=\n\n— axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b q83vATBEAiB0…(base64)…\n"
}

Non esiste una ricerca per ID attività. Possiedi sempre l'indice, perché arriva con l'evento, e verifichi la prova rispetto ai byte dell'evento che hai recuperato dal feed.

Un 404 significa che l'ultimo checkpoint pubblicato non copre la posizione fornita:

• Per un indice letto da un evento servito, questo è transitorio. Un checkpoint che lo copre viene pubblicato a breve, quindi riprova dopo un breve ritardo.
• Lo stesso 404 risponde a qualsiasi altra posizione non coperta, come un indice che il feed non ha mai servito. Per una tale posizione non c'è alcuna garanzia che venga mai pubblicato un checkpoint che la copra. La risposta non indica in quale caso ti trovi.

Un leaf_index mancante o che non è un intero non negativo restituisce 400.

Recupera una prova di consistenza

GET /v1/compliance/transparency_log/consistency?from={size}

curl --fail-with-body -sS -G \
  "https://api.anthropic.com/v1/compliance/transparency_log/consistency" \
  --data-urlencode "from=1180" \
  --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  --header "anthropic-version: 2023-06-01"

{
  "type": "transparency_log_consistency_proof",
  "hashes": [
    "dGw0aPzu2N0pdc4C5ZAvNIbkXF7J6F9ZQLkPpV6v8Vg=",
    "9PSWm1T9RUmhjF6z6YQzB9CW6E2m2n3mK0aVgqf5Qm0=",
    "..."
  ],
  "checkpoint": "axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b\n1207\nC6C4HzGRqDNlbu54LWCvpDX0NcB5DRTmLcjM4u5vWUI=\n\n— axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b q83vATBFAiEAvL8m…(base64)…\n"
}

• La prova si estende sempre fino all'ultimo checkpoint pubblicato. Questa API non serve mai checkpoint storici: conservi tu quelli che ti vengono serviti.
• Un from uguale alla dimensione dell'albero dell'ultimo checkpoint restituisce la prova vuota.
• Un checkpoint posseduto con dimensione dell'albero 0 non necessita di una prova di consistenza, perché ogni log estende il log vuoto. In quel caso adotta direttamente l'ultimo checkpoint.
• Un from minore di 1, o maggiore della dimensione dell'albero dell'ultimo checkpoint, restituisce 400.
• Se il log non è più in grado di dimostrare di estendere un checkpoint che una volta ha firmato per te, trattalo come un fallimento della verifica, non come un errore di utilizzo.

Leggi una tile di hash

GET /v1/compliance/transparency_log/tile/{level}/{index}

Restituisce application/octet-stream: hash SHA-256 da 32 byte concatenati, secondo tlog-tiles. L'indirizzamento delle tile segue esattamente tlog-tiles, inclusa la grammatica del percorso {level} e {index}, la forma di indice x001/234 per alberi grandi e il suffisso di tile parziale .p/{width}. Le tile di hash sono l'unità a partire dalla quale i client tlog-tiles calcolano le prove da soli.

• Le tile complete sono immutabili e sono servite con Cache-Control: private, max-age=604800, immutable.
• Le tile parziali vengono sostituite man mano che l'albero cresce e sono servite con Cache-Control: private, no-store. Una volta che una tile si riempie, una richiesta per la sua forma parziale precedente può restituire 404 anche se la tile completa esiste. Ripiegare dalla tile parziale alla tile completa è compito del client, come specifica tlog-tiles, e i client standard lo fanno già.
• Un level, un index o una larghezza di tile parziale malformati restituiscono 400. Una posizione di tile oltre la dimensione attuale dell'albero restituisce 404.

Leggi un bundle di voci

GET /v1/compliance/transparency_log/tile/entries/{index}

Restituisce application/octet-stream: voci foglia consecutive, ciascuna preceduta dalla sua lunghezza uint16 big-endian, secondo tlog-tiles. I bundle di voci contengono il testo in chiaro degli eventi: i byte canonici di ogni evento di Access Transparency. Ecco perché l'intera superficie richiede lo scope dell'Activity Feed. Indirizzamento, forma parziale, caching ed errori sono identici a quelli delle tile di hash.

Il campo transparency_log_leaf_index sugli eventi dell'Activity Feed

Gli eventi anthropic_access e cmek_preserve su GET /v1/compliance/activities riportano transparency_log_leaf_index, un intero, ogni volta che l'evento ha una foglia. Gli altri tipi di attività non lo riportano mai.

• La chiave è assente, non null, quando l'evento non ha una foglia. Un verificatore robusto tratta allo stesso modo una chiave assente e un valore null.
• Un evento viene servito senza transparency_log_leaf_index solo in due casi. Il primo è mentre la tua organizzazione non è iscritta ad Access Transparency, cioè prima dell'iscrizione o tra una disiscrizione e una nuova iscrizione. Il secondo è quando l'evento è stato registrato prima della creazione del log della tua organizzazione. Per un'organizzazione iscritta prima dell'introduzione del log di trasparenza, ciò include la sua cronologia precedente. Una volta che il tuo log esiste e mentre sei iscritto, ogni evento viene aggiunto al log prima che il feed lo serva. Se un guasto impedisce al feed di conoscere l'indice, il feed ritarda l'evento anziché servirlo senza indice. L'evento non va perso: è già nel log e compare nel feed, indice incluso, una volta risolto il guasto. Un evento senza indice non è previsto quando è datato dopo la creazione del tuo log e ricade in un periodo in cui eri iscritto.
• Un indice presente è un puntatore, non una prova. Verifica l'inclusione prima di considerare l'evento come registrato nel log. L'anomalia da segnalare è un indice presente la cui prova di inclusione non può ancora essere recuperata molto tempo dopo che un checkpoint che lo copre avrebbe dovuto essere pubblicato.
• L'indice viene assegnato quando l'evento viene aggiunto al log e non è uno dei campi che compongono la foglia.

Come un evento diventa una foglia

Una voce foglia è il byte di versione dello schema 0x01 seguito dal JSON canonico di 11 campi. Il JSON segue RFC 8785 (JSON Canonicalization Scheme), e i campi sono presi dall'evento esattamente come l'Activity Feed lo serve:

• id, type, created_at, accessed_at, organization_id, organization_uuid, workspace_id, accessor_department e reason_code
• actor, con i suoi campi annidati type e email_address
• resource_details, con i suoi campi annidati type, id e parent

Le regole:

• I campi serviti al di fuori di quell'insieme, come workspace_uuid e lo stesso transparency_log_leaf_index, vengono ignorati.
• Un campo documentato che l'evento servito omette entra nella foglia come null. Una stringa vuota è distinta da null.
• actor e resource_details sono oggetti con esattamente le loro chiavi documentate quando l'evento servito li riporta. Nella versione 0x01, actor.email_address e resource_details.parent sono sempre null. Quando l'evento servito omette uno di questi oggetti o lo serve come null, l'intero valore è null nella foglia, non un oggetto di campi null. Molti eventi di accesso non riportano resource_details.
• I valori stringa, inclusi entrambi i timestamp e reason_code, sono presi byte per byte come serviti. Se ricavi nuovamente un timestamp da un'altra rappresentazione, riproduci esattamente la resa servita:
  • RFC 3339 UTC con suffisso Z.
  • created_at non ha cifre frazionarie quando i suoi microsecondi sono zero, ed esattamente sei altrimenti.
  • accessed_at ha zero, tre, sei o nove cifre frazionarie, il numero minimo che preserva esattamente i suoi nanosecondi.
• JSON canonico significa chiavi degli oggetti ordinate, nessuno spazio bianco non significativo ed escaping minimo delle stringhe. Nessun numero compare in alcun punto della foglia.
• L'hash della foglia è SHA-256(0x00 || entry) di RFC 6962. I nodi interni vengono calcolati come SHA-256(0x01 || left || right).
• Un verificatore rifiuta un byte di versione sconosciuto, e una foglia 0x01 il cui type non è uno dei due tipi di Access Transparency. Nuovi tipi di evento o modifiche alle regole vengono rilasciati con un nuovo byte di versione. Le foglie esistenti non vengono mai ricalcolate.

Ad esempio, questo evento di accesso come lo serve l'Activity Feed:

{
  "id": "activity_01GPXmAhizavrUuoXNn3tzeA",
  "type": "anthropic_access",
  "created_at": "2025-07-08T18:40:00Z",
  "accessed_at": "2025-07-08T18:39:58Z",
  "organization_id": "org_015gtSHLz269eTwgrH8NX5yk",
  "organization_uuid": "25f6429a-3293-49bf-afed-cb312911554b",
  "workspace_id": "wrkspc_01PaGUP2rbg1XDh7Z9W1CEpd",
  "workspace_uuid": "b6ce2143-1083-d4a7-247c-17530f55a076",
  "accessor_department": "Trust & Safety",
  "reason_code": "safety_review",
  "actor": { "type": "anthropic_actor", "email_address": null },
  "resource_details": { "type": "message", "id": "msg_01HXAMPLE12345678" },
  "transparency_log_leaf_index": 17
}

diventa questo JSON canonico. Ha esattamente le 11 chiavi documentate, ordinate, su una riga. workspace_uuid e transparency_log_leaf_index vengono esclusi, e resource_details.parent, assente dall'evento servito, entra come null:

{"accessed_at":"2025-07-08T18:39:58Z","accessor_department":"Trust & Safety","actor":{"email_address":null,"type":"anthropic_actor"},"created_at":"2025-07-08T18:40:00Z","id":"activity_01GPXmAhizavrUuoXNn3tzeA","organization_id":"org_015gtSHLz269eTwgrH8NX5yk","organization_uuid":"25f6429a-3293-49bf-afed-cb312911554b","reason_code":"safety_review","resource_details":{"id":"msg_01HXAMPLE12345678","parent":null,"type":"message"},"type":"anthropic_access","workspace_id":"wrkspc_01PaGUP2rbg1XDh7Z9W1CEpd"}

La voce foglia è il byte 0x01 seguito da quei byte UTF-8. Il suo hash foglia, SHA-256(0x00 || entry), è 6ro7vTcFq+sYDZiiGvZaFetUIoMSLig3DGDrCKK1HFU= in base64. Usa questo esempio come vettore di test per il tuo codice di canonicalizzazione.

Verifica il tuo log

La verifica viene eseguita sulla tua infrastruttura. Tutto ciò che l'API restituisce non è attendibile finché non viene verificato rispetto a due cose che possiedi tu stesso. La prima è l'origine che derivi dall'UUID della tua organizzazione. La seconda è il checkpoint che hai salvato nell'esecuzione precedente. Un'esecuzione di verifica completa fa quanto segue, in ordine:

1. Recupera l'insieme delle chiavi di verifica. Calcola tu stesso l'impronta di ogni chiave come SHA-256 della sua public_key decodificata da base64. Conserva solo le chiavi la cui impronta compare in Impronte delle chiavi pubblicate, insieme allo stato di ciascuna chiave lì indicato. Verifica un checkpoint appena recuperato solo con una chiave che quella tabella elenca come attuale in quella data. Accetta una chiave ritirata solo per un checkpoint che hai salvato prima della sua data di ritiro.
2. Stabilisci l'ultimo checkpoint. Alla prima esecuzione, recuperalo dall'endpoint del checkpoint. A ogni esecuzione successiva, richiedi una prova di consistenza dalla dimensione dell'albero che hai salvato. La risposta riporta l'ultimo checkpoint insieme alla prova.
3. Controlla prima la riga di origine del checkpoint. Confronta la sua prima riga, byte per byte, con l'origine che hai derivato. Rifiuta qualsiasi checkpoint la cui origine differisca, prima di fare qualsiasi altra cosa.
4. Verifica la firma del checkpoint. Trova la riga di firma con il nome della tua origine i cui primi quattro byte decodificati corrispondono al key_hash di una chiave attualmente valida che hai conservato. Verifica i byte rimanenti come firma ECDSA P-256 sullo SHA-256 del corpo della nota, usando la public_key di quella chiave. Se nessuna riga di firma corrisponde a una tale chiave, o la firma non viene verificata, rifiuta il checkpoint.
5. Dimostra la sola aggiunta. Se la nuova dimensione dell'albero è minore di quella che hai salvato, considera fallita la verifica. Se è uguale, gli hash radice devono corrispondere. Se è maggiore, verifica la prova di consistenza RFC 9162 dalla dimensione e dall'hash radice salvati alla nuova dimensione e al nuovo hash radice.
6. Dimostra che ogni evento è incluso. Leggi ogni evento di Access Transparency servito dall'Activity Feed. Per ciascuno nuovo, ricostruisci la sua foglia, calcolane l'hash e recupera la sua prova di inclusione. Segui il percorso di audit dal tuo hash foglia all'indice dell'evento fino all'hash radice del checkpoint. Una mancata corrispondenza significa che l'evento che ti è stato servito non è l'evento registrato dal log. La risposta della prova può riportare un checkpoint diverso da quello che possiedi. Collegalo alla tua cronologia con una prova di consistenza prima di verificare qualsiasi cosa rispetto a esso.
7. Ricontrolla ciò che hai visto in precedenza. Ogni volta che rileggi un evento, deve essere servito con lo stesso indice e gli stessi byte foglia di quando lo hai verificato. Nessun evento può perdere l'indice che aveva, e mentre sei iscritto nessun nuovo evento può comparire senza indice. Gli eventi serviti senza indice alla tua prima esecuzione sono la tua cronologia precedente al log. Un'esecuzione che rilegge solo gli eventi recenti ricontrolla solo quelli. Per ricontrollare quelli più vecchi, verifica di nuovo le copie che hai conservato (passaggio 8).
8. Salva il checkpoint che hai verificato e un registro di ogni evento che hai verificato. Sono la tua prova e il tuo punto di partenza per l'esecuzione successiva.

Verifica con axt-verify

axt-verify è il verificatore open source di Anthropic per questo log. È un singolo binario Go che esegui sulla tua infrastruttura. Ogni release ha integrata esattamente una chiave di firma del log da Impronte delle chiavi pubblicate, quindi non chiede mai all'API di quale chiave fidarsi. Quando Anthropic ruota la chiave, aggiorni alla release che include quella nuova alla data di passaggio. axt-verify deriva la tua origine dall'UUID dell'organizzazione che passi con --org, cioè quello che hai preso dalla Console in Prima di iniziare. Rifiuta qualsiasi checkpoint la cui riga di origine differisca.

Installalo con Go 1.26 o versioni successive. Legge la tua Compliance Access Key dalla variabile d'ambiente ANTHROPIC_COMPLIANCE_ACCESS_KEY, mai da un flag o da un file. Il comando run è quello da pianificare:

go install github.com/anthropics/axt-verify/cmd/axt-verify@latest

export ANTHROPIC_COMPLIANCE_ACCESS_KEY="<your Compliance Access Key>"
axt-verify --org 25f6429a-3293-49bf-afed-cb312911554b \
  --state /var/lib/axt-verify/25f6429a-3293-49bf-afed-cb312911554b.state \
  run

Ogni run recupera l'ultimo checkpoint e ne verifica la firma e la riga di origine. Poi dimostra che il log è un'estensione di sola aggiunta del checkpoint salvato dall'esecuzione precedente. Successivamente scorre le pagine degli eventi di Access Transparency nel tuo Activity Feed. Inizia sette giorni (in base a created_at) prima dell'evento più recente letto dall'esecuzione precedente, in modo che gli eventi elencati in ritardo o fuori ordine vengano comunque rilevati. Ricostruisce la foglia di ogni evento, ne verifica una prova di inclusione e confronta qualsiasi evento verificato in precedenza con ciò che aveva registrato allora. Infine, salva il nuovo checkpoint e il suo avanzamento nel file --state, da cui parte l'esecuzione successiva. Eseguilo almeno una volta al giorno. Una cadenza oraria è ragionevole. Con una chiave dell'organizzazione padre, esegui una copia per ogni organizzazione figlia, ciascuna con il proprio --org e il proprio file --state. Anche l'UUID di ogni organizzazione figlia proviene dalla Claude Console, non dalle risposte della Compliance API che stai verificando. Trovalo nella pagina Settings > Organization dell'organizzazione figlia o nell'elenco delle organizzazioni della tua organizzazione padre nella Console. axt-verify checkpoint esegue solo i passaggi del checkpoint e della sola aggiunta. axt-verify events FILE verifica eventi che già possiedi, come un campione di un revisore o una tua esportazione. Dimostra che ogni evento nel file è ancora registrato nel log sotto il checkpoint attuale. Non legge il feed né tocca il file di stato.

Da quella finestra deriva un limite: run rilegge solo gli ultimi sette giorni di eventi, quindi ricontrolla gli eventi serviti di recente (passaggio 7), non l'intera cronologia. Conserva gli eventi che esporti (consulta Conserva il tuo archivio di checkpoint). axt-verify events FILE dimostra in qualsiasi data successiva che quelle copie sono ancora registrate nel log, ma non rilegge il feed. Per rilevare un evento più vecchio rimosso dal feed o riscritto su di esso, riesporta quell'intervallo dall'Activity Feed e confrontalo con le copie che hai conservato. Puoi anche verificare la riesportazione stessa con axt-verify events FILE. La sovrapposizione di sette giorni è più lunga del tempo di consegna di due giorni lavorativi del feed, quindi un evento arrivato in ritardo ricade comunque nella finestra di un'esecuzione successiva. --overlap modifica la durata se necessario.

Se invece ti serve una tua implementazione, segui la checklist precedente con una libreria tlog-tiles che supporti le chiavi di nota ECDSA.

Interpreta il risultato

axt-verify stampa la tua origine, la dimensione dell'albero e l'hash radice del checkpoint che ha verificato, la dimensione dell'albero da cui è partito il controllo di sola aggiunta e un conteggio degli eventi per esito. Passa --json per ottenere lo stesso report come un oggetto JSON per riga. Ogni evento ha uno di quattro esiti:

• Verified: la foglia ricostruita dall'evento servito è registrata all'indice dell'evento nel log firmato.
• Pending: l'indice dell'evento è oltre l'ultimo checkpoint pubblicato. Questo è normale per un breve periodo dopo la comparsa di un evento. In run, axt-verify ricorda l'evento, lo verifica in un'esecuzione successiva una volta che un checkpoint lo copre, e lo fa fallire se ciò richiede più di 24 ore. events FILE non ha un'esecuzione successiva per risolverlo, quindi attende fino a un minuto che venga pubblicato un checkpoint che lo copra. Se non ne arriva nessuno, segnala l'evento come non ancora coperto e termina con lo stato di uscita 3. Eseguilo di nuovo più tardi. Se events FILE segnala lo stesso evento come non ancora coperto in due esecuzioni a distanza di almeno un giorno, trattalo come un fallimento della verifica ed effettua l'escalation come per lo stato di uscita 1.
• Not logged: l'evento è stato servito senza un indice. Un evento viene servito senza transparency_log_leaf_index solo mentre la tua organizzazione non è iscritta ad Access Transparency, oppure quando è stato registrato prima della creazione del log della tua organizzazione (consulta Il campo transparency_log_leaf_index sugli eventi dell'Activity Feed). axt-verify segnala tali eventi come non registrati e non fa fallire l'esecuzione a causa loro. Un evento senza indice non è previsto quando è datato dopo la creazione del tuo log e rientra in un periodo in cui eri iscritto. Esamina l'elenco degli eventi non registrati nel riepilogo dell'esecuzione o nell'output --json invece di affidarti solo allo stato di uscita.
• Failed: consulta lo stato di uscita 1.

Lo stato di uscita indica al tuo scheduler cosa è successo:

• 0: Nulla è fallito. Gli eventi non registrati vengono segnalati, non fatti fallire, e lo stesso vale per gli eventi in sospeso in run.

• 1: Un fallimento della verifica. Si tratta di un rilievo di sicurezza, non di un errore transitorio. Conserva il file di stato e l'output, e segnalalo al tuo referente Anthropic o al supporto Anthropic. Le cause sono:

  • Un checkpoint con l'origine errata, o una firma che non viene verificata con la chiave integrata nella tua release di axt-verify. Confronta il key_hash sulla riga della firma del checkpoint che fallisce con le Impronte delle chiavi pubblicate. Una chiave elencata lì con una data di passaggio per cui non hai effettuato l'aggiornamento significa che ti serve la release corrispondente. Una chiave non elencata lì è un rilievo di sicurezza, qualunque release tu esegua. In caso di questo errore, axt-verify stampa l'hash della chiave di ogni firma sul checkpoint servito e l'hash della chiave di cui si fida, ciascuno come otto cifre esadecimali. Quell'output è sufficiente per effettuare il confronto.
  • Un checkpoint che non è una signed note ben formata, ad esempio uno il cui hash radice non è di 32 byte.
  • Un log che si è ridotto, o che non può dimostrare di estendere il checkpoint che hai salvato. L'output riporta quindi entrambi i checkpoint e la prova, così che l'evidenza sia autosufficiente.
  • Due checkpoint firmati per la stessa dimensione dell'albero con hash radice diversi. L'output riporta entrambi i checkpoint.
  • Un file di checkpoint passato con --from la cui firma non viene verificata con la chiave integrata nella tua release di axt-verify, oppure un file --from o --from-trusted la cui origine non è la tua. Per un archivio firmato prima di una rotazione della chiave, consulta Conserva il tuo archivio di checkpoint.
  • Una prova di inclusione che non riproduce l'hash radice firmato per l'evento che ti è stato servito.
  • Un evento all'interno della finestra dell'esecuzione servito in modo diverso da come lo ha registrato un'esecuzione precedente: byte della foglia diversi, un indice diverso, o nessun indice dove ne aveva uno.
  • Un evento ancora in sospeso 24 ore dopo che l'esecuzione lo ha visto per la prima volta.
  • Una prova di inclusione rifiutata (400, 401 o 403) per un evento che il feed ti ha servito.
  • Una prova di inclusione restituita per un leaf_index diverso da quello richiesto.
  • In events FILE, un evento a un indice che l'ultimo checkpoint copriva già all'inizio del controllo, per il quale non viene servita alcuna prova di inclusione prima che scada l'attesa.
  • Un evento il cui organization_uuid non è l'UUID dell'organizzazione che hai passato con --org. Quando un'organizzazione padre esegue events FILE su un'esportazione che copre diverse organizzazioni figlie, ogni evento delle altre organizzazioni fallisce in questo modo, quindi suddividi prima l'esportazione per organizzazione e verifica ciascuna parte con il proprio --org.
  • Lo stesso id di attività a due indici diversi, o due volte allo stesso indice con contenuto diverso, all'interno di una singola esecuzione o di un singolo input di events FILE.
  • Un evento la cui foglia non può essere ricostruita: ad esempio, un campo documentato che non è una stringa, un nome di campo che compare due volte, o un type mancante o che è una variante non riconosciuta di un tipo Access Transparency. events FILE salta le righe di altri tipi di attività e non le fa fallire.

• 2: Un errore di utilizzo o di configurazione. Le cause sono:

  • Un flag mancante o malformato.
  • Nessuna ANTHROPIC_COMPLIANCE_ACCESS_KEY.
  • Una chiave che l'API rifiuta (401 o 403) prima che qualsiasi checkpoint sia stato verificato.
  • Un file di stato che non può essere letto o che appartiene a un'altra origine.

• 3: L'esecuzione non è stata completata. In run, ciò che era già stato verificato viene salvato nel file di stato. Esegui di nuovo. Le cause sono:

  • Un evento in events FILE il cui indice non è stato coperto da alcun checkpoint pubblicato entro l'attesa. Per un evento di questo tipo, l'esito Pending indica quando smettere di rieseguire ed effettuare l'escalation.
  • Errori di rete, limitazioni di velocità o errori del server che sono durati oltre i tentativi.
  • Una risposta inattesa.
  • Un file di stato o --save che non è stato possibile scrivere.

  Uno stato di uscita 3 con risposte 404 è previsto finché Anthropic non ha registrato un primo evento Access Transparency per la tua organizzazione, perché ogni endpoint del log di trasparenza restituisce 404 finché quell'evento non crea il log. Effettua l'escalation se gli endpoint del log di trasparenza restituiscono ancora 404 più di qualche giorno dopo che il tuo Activity Feed mostra per la prima volta un evento Access Transparency, indipendentemente dal fatto che quell'evento riporti un transparency_log_leaf_index. Quella combinazione non è prevista. Una volta che un'esecuzione è riuscita, effettua l'escalation di uno stato di uscita 3 che persiste.

Conserva il tuo archivio di checkpoint

L'evidenza più solida che puoi detenere è la tua registrazione di ciò che il log diceva in un determinato giorno. axt-verify --save FILE scrive il checkpoint verificato da un'esecuzione, alla lettera, e --from FILE in un'esecuzione successiva obbliga il log a dimostrare che estende ancora quel checkpoint. Archivia un checkpoint salvato in uno storage che controlli, ad esempio ogni giorno. Mesi dopo, una prova di consistenza dalla dimensione dell'albero di quel checkpoint archiviato deve ancora condurre a qualunque checkpoint il log serva, altrimenti la verifica fallisce. Le chiavi precedenti restano elencate nell'insieme delle chiavi di verifica dopo una rotazione pianificata, quindi un checkpoint archiviato continua a essere verificato. Con axt-verify, se la chiave che ha firmato un checkpoint archiviato è stata nel frattempo ruotata, passa quell'archivio con --from-trusted invece di --from. Conserva anche gli eventi. Gli eventi Access Transparency che esporti dal feed sono un input valido per axt-verify events FILE, che dimostra in qualsiasi data successiva che quelle copie sono ancora registrate nel log sotto il suo checkpoint attuale. Poiché events FILE non rilegge il feed, l'esportazione che conservi è anche il riferimento con cui confrontare una successiva riesportazione dello stesso intervallo.

Domande frequenti

Risorse correlate

• Access Transparency
• Interrogare l'Activity Feed
• Panoramica della Compliance API
• Errori
• axt-verify, il verificatore open source di Anthropic per il log di trasparenza
• C2SP tlog-tiles e C2SP signed note, i formati di trasmissione per tile, bundle di voci e checkpoint
• RFC 9162, gli algoritmi per l'albero di Merkle, la prova di inclusione e la prova di consistenza
• RFC 8785, il JSON Canonicalization Scheme usato per le foglie