Claude Platform Docs
管理存取透明度

使用透明度日誌驗證 Access Transparency 事件

使用 Compliance API 提供的已簽署檢查點與 Merkle 證明,驗證沒有任何 Access Transparency 事件在提交至日誌後遭到移除或竄改。

了解如何以密碼學方式驗證,沒有任何 Access Transparency 事件在提交至您組織的透明度日誌後遭到移除或竄改。

透明度日誌的運作方式

「Transparency log」(透明度日誌)是一種讓紀錄具備竄改可察覺性的技術。條目只會被附加。每當日誌增長時,其營運者會簽署一份簡短的聲明,稱為「checkpoint」(檢查點),透過 Merkle 樹雜湊對目前為止的所有條目做出承諾。任何保留檢查點的人,之後都可以要求證明目前的日誌仍然包含該檢查點所涵蓋的所有內容,且未經變更、順序相同。因此,對於保留了涵蓋某條目之檢查點的驗證者而言,移除或改寫該條目不可能不被察覺。Certificate Transparency 與 Go 模組校驗和資料庫都建立在相同的技術之上。C2SP tlog-tiles 是一份開放規格,用於以已簽署的檢查點加上靜態、可快取的雜湊與條目圖塊(tile)來提供此類日誌,讓用戶端可以擷取雜湊並自行計算每一個證明。

啟用 Access Transparency 後,Anthropic 會為您的組織維護一個透明度日誌。它是 Access Transparency 事件(anthropic_access 與 cmek_preserve)的僅附加、經密碼學簽署的記錄。在日誌建立後,您的組織所記錄的每個此類事件都會附加至其中。此日誌遵循 C2SP tlog-tiles 格式,因此為該標準建構的工具可以解析其檢查點、圖塊與證明。

  • 每個組織一個日誌。 每個組織的日誌都有固定的 origin 字串:axt.anthropic.com/<your organization UUID>。在組織存續期間,origin 永不變更。
  • 每個新事件都會成為一個葉節點。 當 Access Transparency 事件符合出現在您 Activity Feed 上的條件時,它會先以葉節點(leaf)的形式附加到您的日誌,之後才會在摘要中提供。葉節點是事件已記載欄位的確定性序列化結果。您摘要中的事件帶有 transparency_log_leaf_index,即它在您日誌中從零起算的位置。
  • 檢查點對整個歷史做出承諾。 日誌是一棵 Merkle 樹。每當它增長時,Anthropic 都會發布一個已簽署的檢查點:一份簡短的文字文件,說明日誌的 origin、目前大小,以及對每個葉節點做出承諾的根雜湊。每個檢查點都恰好帶有一個來自日誌簽署金鑰的簽章。
  • 隨之而來的兩種證明。 「Inclusion proof」(包含證明)顯示特定事件在某檢查點下存在於其位置。「Consistency proof」(一致性證明)顯示較新的檢查點是您所保存之較早檢查點的僅附加延伸,因此兩者之間沒有任何內容被移除或變更。
  • 驗證金鑰以頻內方式提供。 驗證者金鑰端點會回傳簽署檢查點的公開金鑰。在計畫性的金鑰輪替中,新金鑰會在開始簽署之前加入該清單,而較早的金鑰仍會保留在清單中。因此,您已持有的檢查點仍可持續通過驗證。

透明度日誌能證明什麼

  • 您所持有事件的葉節點欄位(列於事件如何成為葉節點)逐位元組與 Anthropic 提交至日誌的內容相同。
  • 您組織的日誌只會增長。如果已提交至日誌的事件之後在日誌中被刪除或改寫,針對您所持有檢查點的驗證就會失敗。如果提供給您的歷史與先前提供給您的不同,驗證也會失敗。
  • 新條目只能被附加。事件無法被插入您已驗證過的歷史中。

它無法證明或改變什麼

  • 它無法證明每一次存取都有被記錄,也無法證明已記錄的事件準確描述了該次存取。它只能證明 Anthropic 提交至日誌的內容自那之後未曾變更。
  • 它不會改變 Access Transparency 涵蓋的範圍或事件送達的時間。
  • 任何葉節點版本都未包含的已提供欄位(例如 workspace_uuid)不在證明涵蓋範圍內。之後新增至事件的欄位,只有在某個葉節點版本納入它之後才會受到涵蓋。
  • 包含證明是針對提供給您的事件。它本身無法證明摘要列出了日誌所持有的每一個葉節點。日誌的條目套件包含每一個葉節點,因此在需要時,您可以直接讀取完整的已提交事件集合。
  • 事件上出現 transparency_log_leaf_index 只是一個指標,而非證明。在將事件視為已提交至日誌之前,請務必驗證其包含性。
  • 防範歷史遭改寫的保護來自您所保留的檢查點。檢查點由已發布的金鑰指紋中所列金鑰簽署,證明它來自 Anthropic 的日誌。從您上次保存的檢查點出發的一致性證明,則證明您已觀察到的歷史只有增長。

開始之前

您需要:

  • 具有 read:compliance_activities 範圍的 Compliance Access Key,與您用於 Activity Feed 的金鑰與範圍相同。父組織金鑰可以在每個請求中指定子組織,以讀取每個已註冊子組織的日誌。
  • 您組織的 UUID。您可以在 Claude Console 的組織頁面(platform.claude.com/settings/organization)找到它。它與 Activity Feed 以 organization_uuid 提供的值相同,但請從 Console 取得。這個值是讓檢查點屬於您的依據,因此它不得來自您正在驗證的 API。您可以由它推導出日誌的 origin:axt.anthropic.com/<organization UUID>。請自行推導此字串,不要從 API 回應中讀取。
  • 一個可持久保存您上次驗證之檢查點的地方。這個已保存的檢查點,能將「日誌今天是一致的」轉變為「自您開始監看以來,日誌一直是一致的」。

時間

  • 事件: Access Transparency 事件會在存取發生後 2 個工作天內出現在您的 Activity Feed 上。事件只有在符合提供條件後才會進入日誌,因此日誌絕不會提前揭露事件。由於日誌在摘要提供事件之前寫入,某個條目可能會在其事件出現在您的摘要中之前短暫出現在日誌中。這段落差並非不一致。
  • 檢查點: 每當您的日誌增長時,就會發布新的檢查點。
  • 包含證明: 新提供事件的證明,會在涵蓋該事件位置的檢查點發布後提供,通常在事件出現後很快就會發布。如果您提早請求,會收到 404,請稍候再重試。
  • 驗證頻率: 請至少每天執行一次驗證。每小時一次是合理的。
  • 取消註冊: 如果您的組織停止使用 Access Transparency,不會刪除任何內容。您的日誌仍可透過相同的端點讀取。如果之後再次啟用 Access Transparency,會延續同一份日誌。

保留與刪除

  • 透明度日誌: Anthropic 不會從您的日誌中刪除條目,日誌也沒有到期日。即使您的組織停止使用 Access Transparency,或在您的組織被刪除之後,日誌仍會保留,因為移除條目正是日誌存在所要偵測的變更。條目套件保存每個事件的葉節點欄位,因此這些欄位會與日誌保留同樣長的時間。
  • Activity Feed: Activity Feed 上的 Access Transparency 事件遵循摘要的保留政策。活動會保留 6 年。請參閱查詢 Activity Feed。
  • 您無法刪除: 透明度日誌端點為唯讀。無法刪除或修改條目。

透明度日誌端點

在 https://api.anthropic.com/v1/compliance/transparency_log/ 下提供六個唯讀端點:

端點回傳
GET /checkpoint最新的已簽署檢查點
GET /keys驗證者金鑰集
GET /inclusion單一事件的包含證明
GET /consistency從您持有的檢查點到最新檢查點的一致性證明
GET /tile/{level}/{index}Merkle 雜湊圖塊
GET /tile/entries/{index}葉節點位元組的條目套件

檢查點、圖塊與條目套件完全遵循 C2SP tlog-tiles 傳輸格式。兩個證明端點是為了方便而提供:每個證明也都可以從圖塊計算出來,因此您永遠不必信任證明端點的輸出。您會針對已簽署的檢查點驗證它所回傳的雜湊。

驗證與範圍

如同每個 Compliance API 請求,請在 x-api-key 標頭中傳送您的 Compliance Access Key,並附上 anthropic-version 標頭(請參閱版本控制)。您的組織必須已啟用 Compliance API。

沒有獨立的透明度日誌權限。任何能讀取您組織 Activity Feed 的金鑰(無論屬於您的組織或其父組織),都能讀取您的整份日誌,包括其條目套件中的事件欄位。

每個請求恰好讀取一個組織的日誌:

  • 組織層級的金鑰讀取其所屬組織的日誌。organization_id 查詢參數為選用。若有提供,它必須指定該金鑰所屬的組織。
  • 父組織層級的金鑰必須傳入 organization_id,指定一個子組織。
  • organization_id 接受 org_... 標記 ID 或組織 UUID。

404 表示沒有此金鑰可讀取的日誌。超出金鑰範圍的組織、不存在的組織,以及日誌尚未建立的組織,刻意設計為無法區分。已停止使用 Access Transparency 之組織的日誌不屬於此情況:它會持續被提供。

錯誤

每個端點(包括文字與二進位端點)的錯誤都使用標準的 Compliance API JSON 錯誤封裝。有關封裝格式與共用錯誤類型,請參閱處理 Compliance API 錯誤。

狀態在此介面上的意義
400organization_id 格式錯誤,或使用父組織金鑰時省略了它、未啟用 Compliance API、查詢參數未知,或個別端點的驗證失敗
401API 金鑰遺失或無效
403金鑰缺少所需的範圍
404沒有此金鑰可讀取的日誌,或個別端點的「未涵蓋」與「超出樹範圍」情況
429已達速率限制。這些端點共用 Compliance API 以父組織為單位的速率限制。請遵守 retry-after
503日誌暫時無法使用。請以退避方式重試

快取

回應僅可由發出請求的用戶端快取。Cache-Control 一律包含 private,且回應帶有 Vary: x-api-key。請勿在這些端點前放置共用快取。完整圖塊與完整條目套件永遠不會改變,並以 Cache-Control: private, max-age=604800, immutable 提供。其他所有內容,包括檢查點、證明、金鑰、部分圖塊與錯誤,都以 Cache-Control: private, no-store 提供。

讀取最新的檢查點

GET /v1/compliance/transparency_log/checkpoint

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/compliance/transparency_log/checkpoint" \
  -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  -H "anthropic-version: 2026-10-21"

回應為 text/plain:一份 C2SP signed note。本文各行依序為 origin、十進位的樹大小,以及 base64 根雜湊。接著是一個空白行,然後是簽章行,它以長破折號(em dash,U+2014)開頭,指明 origin,並以 base64 值結尾。此處的值僅供說明:

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

— axt.anthropic.com/25f6429a-3293-49bf-afed-cb312911554b q83vATBFAiEAvL8m…(base64)…
  • 解碼後簽章值的前 4 個位元組是簽署金鑰的 key_hash,它告訴您要使用驗證者金鑰集中的哪個條目進行驗證。其餘位元組是針對 note 主體之 SHA-256 的 ASN.1 DER ECDSA P-256 簽章:即空白行之前的每個位元組,包括主體結尾的換行字元。
  • 檢查點可以在根雜湊之後帶有額外的行。請忽略您不理解的行。它們都在簽章的涵蓋範圍內。
  • 請忽略名稱不是您的 origin,或其金鑰雜湊不在您持有範圍內的簽章行。
  • 切勿快取檢查點。過時的檢查點會隱藏日誌目前的大小,使新提供的事件看起來未被涵蓋。

讀取驗證者金鑰

GET /v1/compliance/transparency_log/keys

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/compliance/transparency_log/keys" \
  -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  -H "anthropic-version: 2026-10-21"
{
  "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>"
    }
  ]
}
欄位類型說明
typestring一律為 transparency_log_keys
originstring此日誌每個檢查點所帶有的 origin 行。僅供參考:請將檢查點與您自行推導的 origin 比對,而非與此欄位比對
log_keysarray先列出簽署新檢查點的金鑰,接著是日誌提供的其他所有金鑰,由新到舊排列。永不為空
log_keys[].verifier_keystring以 C2SP note-verifier 字串表示的金鑰,<origin>+<key_hash>+<base64 key>,可被支援 ECDSA note 金鑰的 tlog-tiles 工具接受(例如 Go 的 github.com/transparency-dev/formats 模組)。base64 部分解碼後為演算法位元組 0x02,後接 DER 編碼的公開金鑰
log_keys[].key_hashstring八個小寫十六進位數字。將此金鑰對應至檢查點簽章行的 4 位元組選擇器。它是 fingerprint 的前 4 個位元組,並非身分識別
log_keys[].fingerprintstring64 個小寫十六進位數字:DER SubjectPublicKeyInfo 的 SHA-256
log_keys[].algorithmstring金鑰類型,目前為 ecdsa_p256_sha256。可能會新增其他值。請略過您不支援其演算法的金鑰
log_keys[].public_keystring以 base64 DER SubjectPublicKeyInfo 表示的公開金鑰

key_hash 只涵蓋金鑰位元組:它是 DER SubjectPublicKeyInfo 之 SHA-256 的前 4 個位元組,這是 ECDSA note-verifier 編碼所使用的規則。它並非基本 signed-note 格式為 Ed25519 金鑰定義的、依名稱而定的金鑰 ID,因此不會隨 origin 改變。由已發布的金鑰指紋中列出的金鑰所做的有效簽章,證明該檢查點來自 Anthropic 的透明度日誌服務。已簽署檢查點內的 origin 行才是將它綁定至您組織的依據。這就是您要將該行與您自行推導的 origin 比對的原因。

金鑰可能會輪替:

  • 輪替是一次切換。從某個檢查點開始,新的檢查點會由新金鑰簽署。
  • 在計畫性輪替中,新金鑰會在簽署任何內容之前出現在 log_keys 中,而較早的金鑰仍會保留在清單中。因此,您在輪替前保存的檢查點仍可持續通過驗證。
  • 驗證者可以在每次執行時擷取金鑰集,或在本機保存。在本機保存金鑰集的驗證者,在遇到其 key_hash 不在持有範圍內的簽章時,會重新讀取此端點。

已發布的金鑰指紋

Anthropic 在此(API 之外)發布每個簽署檢查點之金鑰的指紋。這讓您可以將本機持有的金鑰與提供路徑無法竄改的來源進行比對。您持有的金鑰可能來自先前的 GET /keys 回應,或來自固定金鑰的工具。

金鑰雜湊SHA-256 指紋演算法開始簽署日期狀態
1dff5fe41dff5fe420d49743fe444a04fc17f818eea856699dec2ebbc24df15602c74a58ecdsa_p256_sha2562026-08-17目前的簽署金鑰

計畫性輪替會在新金鑰簽署其第一個檢查點前至少 30 天於本頁公告。在該通知期間,新金鑰會連同其切換日期列於 log_keys 與此表格中。已退役的金鑰會連同其服務日期保留在清單中。未出現在此表格中的金鑰都不是合法的,無論 GET /keys 回傳什麼。請將無法在任何已列出金鑰下通過驗證的檢查點視為驗證失敗,並向您的 Anthropic 客戶代表或 Anthropic 支援回報。

axt-verify 在每個版本中內建目前的金鑰,且絕不從 API 讀取金鑰(請參閱使用 axt-verify 進行驗證)。每個版本恰好內建一把金鑰。在切換日期,Anthropic 會開始以新金鑰簽署,並發布內建該金鑰的 axt-verify 版本。在同一天,Anthropic 會以新金鑰重新簽發每個組織的最新檢查點,即使該日誌並未增長。請在切換日期升級。在切換後執行舊版本會以結束狀態 1 失敗,在切換前執行新版本也一樣。只要您執行對應的版本,這兩種失敗都會消除。您自行維護的驗證者需要在該日期之前加入新指紋及其切換日期。

擷取包含證明

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

參數類型說明
leaf_indexinteger,必填事件在日誌中的位置:即 Activity Feed 在該事件上提供的 transparency_log_leaf_index。必須大於或等於零
organization_idstring,選用請參閱驗證與範圍
curl --fail-with-body -sS -G \
  "https://api.anthropic.com/v1/compliance/transparency_log/inclusion" \
  --data-urlencode "leaf_index=41" \
  -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  -H "anthropic-version: 2026-10-21"
{
  "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"
}
欄位類型說明
typestring一律為 transparency_log_inclusion_proof
leaf_indexinteger事件在日誌中的位置,從請求中回傳
hashes字串陣列稽核路徑的 base64 兄弟節點雜湊,從葉節點往上排列至根
checkpointstring最新的已簽署檢查點,即證明所依據驗證的檢查點。它帶有樹大小

無法依活動 ID 查詢。您一定持有索引,因為它隨事件一起送達,而您會針對從摘要擷取的事件位元組檢查證明。

404 表示最新發布的檢查點未涵蓋所提供的位置:

  • 對於您從已提供事件上讀取的索引,這是暫時性的。涵蓋的檢查點很快就會發布,因此請稍候再重試。
  • 相同的 404 也會回應任何其他未涵蓋的位置,例如摘要從未提供過的索引。對於此類位置,不保證會發布涵蓋它的檢查點。回應不會說明您屬於哪種情況。

leaf_index 遺失或不是非負整數時,會回傳 400。

擷取一致性證明

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

參數類型說明
frominteger,必填您所持有之較早檢查點的樹大小。必須至少為 1,且不超過最新檢查點的樹大小
organization_idstring,選用請參閱驗證與範圍
curl --fail-with-body -sS -G \
  "https://api.anthropic.com/v1/compliance/transparency_log/consistency" \
  --data-urlencode "from=1180" \
  -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  -H "anthropic-version: 2026-10-21"
{
  "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"
}
欄位類型說明
typestring一律為 transparency_log_consistency_proof
hashes字串陣列base64 證明雜湊,依 RFC 9162 順序排列
checkpointstring最新的已簽署檢查點,即證明所延伸至的檢查點。它帶有樹大小
  • 證明一律延伸至最新發布的檢查點。此 API 從不提供歷史檢查點:您需要自行保留提供給您的檢查點。
  • from 等於最新檢查點的樹大小時,會回傳空證明。
  • 持有的檢查點樹大小為 0 時不需要一致性證明,因為每份日誌都是空日誌的延伸。在這種情況下,請直接採用最新的檢查點。
  • from 小於 1,或大於最新檢查點的樹大小時,會回傳 400。
  • 如果日誌無法再證明它延伸了曾經為您簽署的檢查點,請將其視為驗證失敗,而非使用錯誤。

讀取雜湊圖塊

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

傳回 application/octet-stream:串接的 32 位元組 SHA-256 雜湊,如 tlog-tiles 所規範。圖塊定址完全遵循 tlog-tiles,包括 {level} 與 {index} 路徑語法、用於大型樹的 x001/234 索引形式,以及部分圖塊後綴 .p/{width}。雜湊圖塊是 tlog-tiles 用戶端自行計算證明的單位。

  • 完整圖塊不可變,並以 Cache-Control: private, max-age=604800, immutable 提供。
  • 部分圖塊會隨著樹的增長而被取代,並以 Cache-Control: private, no-store 提供。一旦圖塊填滿,即使完整圖塊存在,請求其較早的部分形式也可能回傳 404。從部分圖塊退回至完整圖塊是用戶端的工作,如 tlog-tiles 所規定,標準用戶端已經會這麼做。
  • level、index 或部分圖塊寬度格式錯誤時,會回傳 400。超出目前樹大小的圖塊位置會回傳 404。

讀取條目套件

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

傳回 application/octet-stream:連續的葉節點條目,每個條目前綴其大端序 uint16 長度,如 tlog-tiles 所規範。條目套件包含事件明文:每個 Access Transparency 事件的標準位元組。這就是整個介面需要 Activity Feed 範圍的原因。定址、部分形式、快取與錯誤皆與雜湊圖塊相同。

Activity Feed 事件上的 transparency_log_leaf_index 欄位

GET /v1/compliance/activities 上的 anthropic_access 與 cmek_preserve 事件,只要該事件有葉節點,就會帶有整數 transparency_log_leaf_index。其他活動類型從不帶有此欄位。

  • 當事件沒有葉節點時,該鍵會不存在,而非 null。 穩健的驗證者會以相同方式處理不存在的鍵與 null 值。
  • 事件僅在兩種情況下會在沒有 transparency_log_leaf_index 的情況下提供。 第一種是您的組織未註冊 Access Transparency 期間,亦即註冊之前,或在取消註冊與重新註冊之間。第二種是事件在您組織的日誌建立之前被記錄。對於在透明度日誌推出之前即已註冊的組織,這包括其較早的歷史。一旦您的日誌存在且您處於註冊狀態,每個事件都會在摘要提供它之前附加至日誌。如果故障導致摘要無法取得索引,摘要會延遲該事件,而不是在沒有索引的情況下提供它。事件不會遺失:它已經在日誌中,並會在故障排除後連同索引出現在摘要上。若無索引的事件之日期晚於您日誌的建立時間,且落在您處於註冊狀態的期間內,則不應出現此情況。
  • 存在的索引只是指標,而非證明。 在將事件視為已提交至日誌之前,請先驗證其包含性。值得呈報的異常,是存在索引但在涵蓋的檢查點早應發布之後很久,仍無法擷取其包含證明。
  • 索引是在事件附加到日誌時指派的,並不屬於構成葉節點的欄位。

事件如何成為葉節點

葉節點條目由一個結構描述版本位元組,後接該版本欄位的標準 JSON 所組成。JSON 遵循 RFC 8785(JSON Canonicalization Scheme),欄位則完全依照 Activity Feed 提供的事件取得。

葉節點版本是一組固定的欄位,每個欄位為必要或選用。

版本 0x01 有 11 個必要欄位,沒有選用欄位:

  • id、type、created_at、accessed_at、organization_id、organization_uuid、workspace_id、accessor_department 與 reason_code
  • actor,及其巢狀的 type 與 email_address
  • resource_details,及其巢狀的 type、id 與 parent

版本 0x02 有相同的 11 個必要欄位,以及一個選用欄位:

  • user_profile_id,即被存取或保留之資料建立時所屬的使用者設定檔的 ID

一旦您的日誌開始寫入某個版本,它就會以該版本寫入每個新葉節點,直到開始寫入下一個版本為止,即使事件沒有該版本的任何選用欄位也是如此。針對新的葉節點版本進行升級說明了您的日誌何時可以開始寫入新版本。葉節點一旦寫入便永不變更,因此會永久保持其版本。因此,一個日誌可以保存多個版本的葉節點。Activity Feed 或證明端點提供的任何內容都不會說明葉節點屬於哪個版本(只有條目套件中葉節點自身的位元組會說明),而您也不需要知道:以下規則的最後一條說明了要為事件重建哪些條目。

規則如下:

  • 版本欄位集以外的已提供欄位(例如 workspace_uuid 與 transparency_log_leaf_index 本身)會被忽略。
  • 已提供事件省略或以 null 提供的必要欄位,會以 null 進入葉節點。空字串與 null 不同。
  • 選用欄位只有在已提供事件將其作為字串(包括空字串)時才會進入葉節點,並以該字串進入。當已提供事件省略它或以 null 提供它時,葉節點完全不會有該鍵。選用欄位在葉節點中絕不為 null。若已提供事件的選用欄位為任何其他 JSON 值,請拒絕該事件。
  • 當已提供事件帶有 actor 與 resource_details 時,它們是恰好具有其記載之鍵的物件。actor.email_address 與 resource_details.parent 一律為 null。當已提供事件省略其中一個物件或以 null 提供它時,整個值在葉節點中為 null,而非由 null 欄位組成的物件。許多存取事件不帶有 resource_details。
  • 字串值,包括兩個時間戳記與 reason_code,都逐位元組依提供的內容取得。如果您從其他表示法重新推導時間戳記,請完全重現所提供的呈現方式:
    • 帶有 Z 後綴的 RFC 3339 UTC。
    • created_at 在其微秒為零時沒有小數位數,否則恰好有六位。
    • accessed_at 有零、三、六或九位小數位數,取能精確保留其奈秒的最短位數。
  • 標準 JSON 表示物件鍵已排序、沒有無意義的空白,且字串跳脫最少化。葉節點中任何地方都不會出現數字。
  • 葉節點雜湊為 RFC 6962 的 SHA-256(0x00 || entry)。內部節點的雜湊為 SHA-256(0x01 || left || right)。
  • 讀取葉節點條目(例如從條目套件讀取)的驗證者,會拒絕未知的版本位元組,以及 type 不屬於兩種 Access Transparency 類型之一的葉節點。新欄位、新事件類型與規則變更會以新的版本位元組推出。既有葉節點永不重新雜湊。
  • 請在欄位包含已提供事件以字串形式具有之每個選用欄位的每個葉節點版本下(若事件沒有任何選用欄位,則為每個版本)重建已提供事件的條目,且不在其他任何版本下重建。如果事件的包含證明符合其中任一個的葉節點雜湊,該事件即驗證通過。如果在提供給您的事件中,某個選用欄位被移除、新增或變更,則無論日誌保存的是哪個葉節點,該事件在任何以包含該欄位之葉節點版本重建的驗證者上都會驗證失敗。

例如,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
}

會變成以下標準 JSON。它恰好有 11 個必要鍵,經排序並位於同一行。workspace_uuid 與 transparency_log_leaf_index 被移除,而已提供事件中不存在的 resource_details.parent 則以 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"}

此事件沒有選用欄位,因此其版本 0x02 與版本 0x01 條目保存相同的 JSON,僅在第一個位元組不同。版本 0x02 條目是位元組 0x02 後接這些 UTF-8 位元組。其葉節點雜湊 SHA-256(0x00 || entry) 以 base64 表示為 1iKC1LbEakcNTfp8OwW4LtItQu4+/K/pzaDDLVIA5XE=。版本 0x01 條目是位元組 0x01 後接相同的位元組,其葉節點雜湊為 6ro7vTcFq+sYDZiiGvZaFetUIoMSLig3DGDrCKK1HFU=。

同一事件若帶有選用欄位提供(此處為 "user_profile_id": "uprof_01H7Z9W1CEpdPaGUP2rbg1XD"),其版本 0x02 JSON 有 12 個鍵。選用鍵與其他鍵一起排序,位於 type 與 workspace_id 之間:

{"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","user_profile_id":"uprof_01H7Z9W1CEpdPaGUP2rbg1XD","workspace_id":"wrkspc_01PaGUP2rbg1XDh7Z9W1CEpd"}

其版本 0x02 條目(唯一需要重建的條目)是位元組 0x02 後接這些 UTF-8 位元組,其葉節點雜湊為 onAlpkDfdXmHPvbffiTpHAgBacf/mJCzTfNDibDrYp4=。請將這三個雜湊作為您自己標準化程式碼的測試向量。

驗證您的日誌

驗證在您自己的基礎架構上執行。API 回傳的所有內容在針對您自行持有的兩樣東西驗證之前,都是不受信任的。第一樣是您從組織 UUID 推導出的 origin。第二樣是您在上次執行時保存的檢查點。完整的驗證執行會依序進行以下步驟:

  1. 擷取驗證者金鑰集。自行計算每把金鑰的指紋,即其 base64 解碼後 public_key 的 SHA-256。只保留指紋出現在已發布的金鑰指紋中的金鑰,並一併記錄每把金鑰在該處的狀態。只在該表格列為當日目前金鑰的金鑰下驗證新擷取的檢查點。只有對於您在退役日期之前保存的檢查點,才接受已退役的金鑰。
  2. 確立最新的檢查點。第一次執行時,從檢查點端點擷取。之後每次執行時,從您保存的樹大小請求一致性證明。回應會連同證明一起帶有最新的檢查點。
  3. 先檢查檢查點的 origin 行。將其第一行與您推導出的 origin 逐位元組比對。在進行任何其他動作之前,拒絕任何 origin 不同的檢查點。
  4. 驗證檢查點的簽章。找出以您的 origin 命名、且解碼後前四個位元組等於您所保留之目前有效金鑰 key_hash 的簽章行。使用該金鑰的 public_key,將其餘位元組作為對 note 本文之 SHA-256 的 ECDSA P-256 簽章進行驗證。如果沒有簽章行與此類金鑰相符,或簽章未通過驗證,請拒絕該檢查點。
  5. 證明僅附加。如果新的樹大小小於您保存的大小,則失敗。如果相等,根雜湊必須相符。如果較大,請驗證從您保存的大小與根雜湊到新大小與根雜湊的 RFC 9162 一致性證明。
  6. 證明每個事件都已包含。讀取 Activity Feed 提供的每個 Access Transparency 事件。對於每個新事件,重建需為其重建的每個葉節點、對每個葉節點進行雜湊,並擷取其包含證明。從事件索引處的每個葉節點雜湊沿稽核路徑向上走到檢查點的根雜湊。如果其中一個能重現根雜湊,該事件即驗證通過。如果沒有任何一個能重現,提供給您的事件就不是日誌所提交的事件。證明回應可能帶有與您持有之檢查點不同的檢查點。在據以驗證任何內容之前,請先檢查其 origin 行與簽章(步驟 3 與 4),並以一致性證明將其連結至您的歷史(步驟 5)。
  7. 重新檢查您先前看過的內容。每當您再次讀取某個事件時,它必須以與您驗證時相同的索引與相同的葉節點位元組提供。任何事件都不得失去其原有的索引,且在您處於註冊狀態期間,任何事件都不得在沒有索引的情況下新出現。第一次執行時在沒有索引的情況下提供的事件,是您日誌建立前的歷史。只重新讀取近期事件的執行,只會重新檢查那些事件。若要重新檢查較舊的事件,請再次驗證您保留的副本(步驟 8)。
  8. 保存您驗證過的檢查點,以及您驗證過之每個事件的紀錄。它們是您的證據,也是下次執行的起點。

針對新的葉節點版本進行升級

每個 axt-verify 版本只會重建在該版本發布時已定義的葉節點版本。請假設一旦能重建某個新版本的發布版推出後,您的日誌隨時可能開始寫入該新版本。請在該發布版推出後立即安裝。

葉節點版本會重建該版本的 axt-verify 發布版
0x01每個發布版
0x02v0.2.0 及更新版本

axt-verify version 會印出您所執行的發布版。新安裝會取得最新的發布版。如果表格最後一列不包含您的發布版,請升級到該列中的發布版。如果尚未有任何此類發布版推出,請在其推出後立即升級:

  1. 以您先前的安裝方式安裝最新發布版(即使用 axt-verify 進行驗證中的 go install 指令)。
  2. 繼續照舊執行:相同的 --org、相同的 --state 檔案、相同的排程。

預期情況:

  • 在您的日誌開始寫入新版本之前。 較新的發布版會照舊驗證您的日誌,因為它也會重建較早的葉節點版本。
  • 在您的日誌開始寫入新版本之後,且使用不會重建該版本的發布版時。 該發布版會將每個葉節點為該版本的事件回報為驗證失敗,結束狀態為 1,即使該事件不含該版本的任何選用欄位也是如此。您的發布版所能重建之版本的葉節點不受影響,它們會照舊通過驗證。一旦您在同一個 --state 檔案上執行能重建該版本的發布版,這些失敗就會消除,而僅附加檢查會從您上次執行結束之處繼續。
  • 如果您退回到較早的發布版。 請勿將較新發布版已儲存的狀態檔案提供給較早的發布版。較早的發布版會將每個正在等待檢查點的事件回報為驗證失敗。如果您可能需要退回到較早的發布版,請在首次執行較新發布版之前複製狀態檔案,並將該副本提供給較早的發布版。

您自行維護的驗證者,需要在您的日誌開始寫入新版本之前,從事件如何成為葉節點取得該版本的欄位,以及決定要重建哪些條目的規則。

使用 axt-verify 進行驗證

如果您已經依排程執行 axt-verify,請先閱讀針對新的葉節點版本進行升級。

axt-verify 是 Anthropic 為此日誌提供的開源驗證者。它是單一 Go 二進位檔,您可以在自己的基礎設施上執行。每個發布版都內建了已發布的金鑰指紋中恰好一把日誌簽署金鑰,因此它從不向 API 詢問要信任哪把金鑰。當 Anthropic 輪替金鑰時,您需在切換日期升級到攜帶新金鑰的發布版。axt-verify 會根據您以 --org 傳入的組織 UUID(即您在開始之前中從 Console 取得的 UUID)推導出您的 origin。它會拒絕任何 origin 行不同的檢查點。

請使用 Go 1.26 或更新版本安裝。它從 ANTHROPIC_COMPLIANCE_ACCESS_KEY 環境變數讀取您的 Compliance Access Key,從不從旗標或檔案讀取。run 命令是要排程執行的命令:

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

每次 run 都會擷取最新的檢查點,並驗證其簽章與 origin 行。接著它會證明日誌是前一次執行所儲存之檢查點的僅附加延伸。然後它會逐頁讀取您 Activity Feed 上的 Access Transparency 事件。它會從前一次執行所讀取之最新事件的 7 天前(依 created_at)開始,以便仍能擷取延遲列出或順序錯亂的事件。它會重建每個要為該事件重建的葉節點,根據這些葉節點驗證包含證明,並將先前已驗證過的任何事件與當時記錄的內容進行比較。最後,它會將新的檢查點及其進度儲存到 --state 檔案,下一次執行會從這裡開始。請至少每天執行一次,每小時執行一次也是合理的。若使用父組織金鑰,請為每個子組織各執行一個副本,每個副本都有自己的 --org 和 --state 檔案。每個子組織的 UUID 同樣來自 Claude Console,而非來自您正在驗證的 Compliance API 回應。要找到它,請在 Console 側邊欄底部的帳戶選單中切換到該子組織,然後開啟組織頁面(platform.claude.com/settings/organization)。您也可以在 Console 中父組織的組織清單裡找到它。axt-verify checkpoint 只執行檢查點和僅附加步驟。axt-verify events FILE 會驗證您已持有的事件,例如稽核人員的樣本或您自己的匯出。它會證明檔案中的每個事件在目前的檢查點下仍已提交至日誌。它不會讀取摘要,也不會動到狀態檔案。

該時間窗口帶來一項限制:run 只會重新讀取最近 7 天的事件,因此它重新檢查的是最近提供的事件(步驟 7),而非您的完整歷史。請保留您匯出的事件(請參閱保留您自己的檢查點封存)。axt-verify events FILE 可在日後任何時間證明這些副本仍已提交至日誌,但它不會重新讀取摘要。若要偵測較舊事件是否已從摘要移除或在摘要上被改寫,請從 Activity Feed 重新匯出該範圍,並與您保留的副本進行比較。您也可以使用 axt-verify events FILE 驗證重新匯出的內容本身。7 天的重疊期比摘要的 2 個工作天交付時間更長,因此延遲抵達的事件仍會落在後續執行的時間窗口內。如有需要,可使用 --overlap 變更該期間。

如果您需要改用自己的實作,請使用支援 ECDSA note 金鑰的 tlog-tiles 函式庫,並遵循前述的檢查清單。

解讀結果

axt-verify 會印出您的 origin、它所驗證之檢查點的樹大小與根雜湊、僅附加檢查起始的樹大小,以及依結果分類的事件計數。傳入 --json 可將相同的報告以每行一個 JSON 物件的形式輸出。每個事件會有以下四種結果之一:

  • 已驗證(Verified): 從所提供事件重建的葉節點已提交至已簽署日誌中該事件的索引位置。
  • 待處理(Pending): 該事件的索引超出最新發布的檢查點。在事件出現後的短時間內,這是正常的。在 run 中,axt-verify 會記錄該事件,在後續執行中一旦有檢查點涵蓋它便會進行驗證,若超過 24 小時則判定失敗。events FILE 沒有後續執行可以解決此情況,因此它會等待最多一分鐘,讓涵蓋該事件的檢查點發布。如果沒有發布,它會將該事件回報為尚未涵蓋,並以結束狀態 3 結束。請稍後再次執行。如果 events FILE 在相隔至少一天的兩次執行中都將同一事件回報為尚未涵蓋,請將其視為驗證失敗,並比照結束狀態 1 進行呈報。
  • 未記錄(Not logged): 該事件在提供時沒有索引。只有在您的組織尚未註冊 Access Transparency 時,或事件記錄於您組織的日誌建立之前時,事件才會在沒有 transparency_log_leaf_index 的情況下提供(請參閱 Activity Feed 事件上的 transparency_log_leaf_index 欄位)。axt-verify 會將此類事件回報為未記錄,且不會因此使執行失敗。若事件的日期晚於您的日誌建立時間,且落在您已註冊的期間內,則不應出現沒有索引的事件。請檢閱執行摘要或 --json 輸出中的未記錄清單,而不要僅依賴結束狀態。
  • 失敗(Failed): 請參閱結束狀態 1。

結束狀態會告訴您的排程器發生了什麼事:

  • 0: 沒有任何失敗。未記錄的事件會被回報而非判定失敗,run 中的待處理事件也是如此。

  • 1: 驗證失敗。如果每個新事件都因其包含證明無法重現已簽署的根雜湊而失敗,請先排除是否使用了無法重建您日誌最新葉節點版本的發布版,如本清單中對應項目所述。如果不是此原因,或遇到任何其他失敗,請將其視為安全性發現,而非暫時性錯誤。請保留狀態檔案和輸出,並回報給您的 Anthropic 客戶代表或 Anthropic 支援。原因包括:

    • 檢查點的 origin 錯誤,或簽章無法以您 axt-verify 版本內建的金鑰驗證。請將失敗檢查點簽章行上的 key_hash 與已發布的金鑰指紋進行比對。若該處列出的金鑰帶有您尚未因應升級的切換日期,表示您需要對應的版本。若金鑰未列於該處,無論您執行哪個版本,都屬於安全性發現。發生此失敗時,axt-verify 會印出所提供檢查點上每個簽章的金鑰雜湊,以及其所信任金鑰的金鑰雜湊,各為八個十六進位數字。這些輸出足以進行比對。
    • 檢查點不是格式正確的 signed note(簽署註記),例如根雜湊不是 32 位元組。
    • 日誌縮小了,或無法證明其延伸自您所保存的檢查點。此時輸出會包含兩個檢查點與證明,因此證據本身即可成立。
    • 同一樹大小有兩個根雜湊不同的簽署檢查點。輸出會包含這兩個檢查點。
    • 以 --from 傳入的檢查點檔案,其簽章無法以您 axt-verify 版本內建的金鑰驗證,或 --from 或 --from-trusted 檔案的 origin 不屬於您。對於在金鑰輪替前簽署的封存,請參閱保留您自己的檢查點封存。
    • 包含證明無法為您所收到的事件重現已簽署的根雜湊。無法重建某葉節點版本的發布版,會對每個葉節點為該版本的事件回報此錯誤。如果每個新事件同時以此方式失敗,請先檢查您是否執行最新的 axt-verify 發布版(請參閱針對新的葉節點版本進行升級)。如果不是,請複製狀態檔案,保留該副本和輸出,然後在原始的 --state 檔案上執行最新發布版。一旦您執行能重建該版本的發布版,這些失敗就會消除。如果您已在執行最新發布版,或升級後失敗仍然存在,則屬於安全性發現。
    • 執行時間範圍內的事件,其提供方式與先前執行所記錄的不同:葉節點位元組不同、索引不同,或原本有索引卻沒有索引。
    • 事件在執行首次看到它的 24 小時後仍處於待處理狀態。
    • 對於摘要提供給您的事件,包含證明遭到拒絕(400、401 或 403)。
    • 傳回的包含證明所對應的 leaf_index 與所請求的不同。
    • 在 events FILE 中,某事件的索引在檢查開始時已被最新檢查點涵蓋,但在等待時間結束之前都未提供其包含證明。
    • 事件的 organization_uuid 不是您以 --org 傳入的組織 UUID。當父組織對涵蓋多個子組織的匯出執行 events FILE 時,其他每個組織的事件都會以此方式失敗,因此請先依組織拆分匯出,再以各自的 --org 驗證每個部分。
    • 在單次執行或單一 events FILE 輸入中,同一活動 id 出現在兩個不同的索引,或在同一索引出現兩次但內容不同。
    • 事件的葉節點無法重建:例如,某個已記載的欄位不是字串、某個欄位名稱出現兩次,或 type 缺失或是 Access Transparency 類型中無法辨識的變體。events FILE 會略過其他活動類型的資料列,且不會將其判定為失敗。
  • 2: 使用方式或設定錯誤。原因包括:

    • 旗標缺失或格式錯誤。
    • 沒有 ANTHROPIC_COMPLIANCE_ACCESS_KEY。
    • 在任何檢查點驗證之前,API 拒絕了金鑰(401 或 403)。
    • 狀態檔案無法讀取,或屬於其他 origin。
  • 3: 執行無法完成。在 run 中,已驗證的內容會保存至狀態檔案。請再次執行。原因包括:

    • events FILE 中某事件的索引在等待時間內未被任何已發布的檢查點涵蓋。對於此類事件,待處理結果說明了何時應停止重新執行並進行呈報。
    • 網路錯誤、速率限制或伺服器錯誤持續超過重試次數。
    • 非預期的回應。
    • 狀態檔案或 --save 檔案無法寫入。

    在 Anthropic 為您的組織記錄第一個 Access Transparency 事件之前,出現伴隨 404 回應的結束狀態 3 是預期中的,因為在該事件建立日誌之前,每個透明度日誌端點都會傳回 404。如果在您的 Activity Feed 首次顯示 Access Transparency 事件的數天後,透明度日誌端點仍傳回 404,無論該事件是否帶有 transparency_log_leaf_index,都請進行呈報。這種組合並不在預期之中。一旦某次執行成功,若結束狀態 3 持續出現,請進行呈報。

保留您自己的檢查點封存

您所能持有的最有力證據,是您自己對日誌在特定日期內容的記錄。axt-verify --save FILE 會逐字寫入執行所驗證的檢查點,而在之後的執行中使用 --from FILE 會要求日誌證明其仍延伸自該檢查點。請將保存的檢查點封存在您所控制的儲存空間中,例如每日一次。數個月後,從該封存檢查點之樹大小出發的 一致性證明仍必須能導向日誌所提供的任何檢查點,否則驗證就會失敗。在計畫性輪替後,先前的金鑰仍會列於驗證者金鑰集中,因此封存的檢查點仍可持續驗證。使用 axt-verify 時,若簽署封存檢查點的金鑰已被輪替淘汰,請以 --from-trusted 而非 --from 傳入該封存。也請保留事件。您從摘要匯出的 Access Transparency 事件是 axt-verify events FILE 的有效輸入,可在之後任何日期證明這些副本在目前的檢查點下仍已提交至日誌。由於 events FILE 不會重新讀取摘要,您保留的匯出也是您用來比對之後重新匯出同一範圍時的參考依據。

常見問題

這個頁面有幫助嗎?