Halo：開源防篡改執行時證據，適用於 AI 代理

可驗證的 AI 代理行為稽核追蹤

Halo 是一個開源專案，提供 AI 代理的防篡改執行時記錄。它會為代理執行的每一項操作（包括工具呼叫、模型呼叫、資料存取與批准）建立只能追加、雜湊鏈結的日誌，使任何人都能在不必信任產生日誌的供應商的前提下，驗證日誌未被更改。

此系統將證明責任從書面保證與螢幕截圖轉移至可驗證的技術實體，專為滿足安全審查、SOC 2 清單以及新興 AI 法規的需求而設計。

核心技術架構

雜湊鏈結完整性模型

為確保記錄在未被偵測的情況下無法被編輯或重新排序，Halo 採用雜湊鏈結機制。每筆記錄的雜湊是透過取出該記錄（不含自身雜湊），將 integrity.prev_hash 設為前一筆記錄的雜湊，並使用 RFC 8785（JSON 正規化方案）對資料進行正規化後，再套用 SHA-256 計算得到。鏈中的第一筆記錄的 prev_hash 為 64 個零。

完整性 vs. 完備性

在日誌的完整性與完備性之間有一個關鍵的區別：

完整性： 自持鏈證明在記錄建立後未有任何編輯或重新排序。
完備性： 自持鏈無法證明操作員沒有刪除整段日誌（例如「糟糕的一天」）並重新封印鏈，或是根本未寫入記錄。

為了解決完備性問題，Halo 引入了 見證者。見證者是一個外部實體，持有鏈的定期指紋（記錄數量與最新雜湊）。透過將檢查點錨定至見證者，用戶即可驗證日誌是完整的，且未被截斷或遺漏。

安全與隱私設計

為了降低引入漏洞或洩漏敏感資料的風險，Halo 以嚴格的安全姿態構建：

零執行時相依性： Python 實作僅使用標準函式庫，意味著 pip install halo-record 只會安裝一個套件。
無網路呼叫： 除了可選的見證者客戶端外，記錄器不會發出任何網路請求。記錄內容永遠不會離開本地基礎設施。
個人資訊遮蔽（PII Redaction）： 原始輸入永不寫入記錄。參數會被雜湊並以遮蔽摘要方式儲存。雖然專案使用基於正規表達式的遮蔽機制來處理常見機密與個資格式，以作為深度防禦措施，但此方式並非絕對保證的過濾器。
可稽核性： 程式碼基礎規模小（約 4,300 行 Python），使安全團隊能在短時間內審核整個專案。

整合與生態系支援

框架相容性

Halo 可透過多種方式整合至 AI 代理工作流程：

原生記錄器： 使用 from halo import trace 包裝代理的入口點。
遙測收集： 支援 OpenTelemetry GenAI spans，讓其與 CrewAI、LlamaIndex 等框架相容。
適配器： 已提供原生適配器，支援 LiteLLM 回呼、LangChain/LangGraph 回呼、OpenAI Agents SDK 鉤子，以及透過 halo-record-ts TypeScript 套件的 Vercel AI SDK。

記錄程式編寫代理

對於如 Claude Code 等工具，Halo 透過 PostToolUse 鉤子整合。只要在 ~/.claude/settings.json 檔案中加入特定指令，即可將每次檔案寫入、Shell 指令與 MCP 連接器呼叫記錄至本地鏈，且不需修改代理的核心程式碼。

合規映射

Halo 作為多項全球 AI 合規與安全框架的證據層：

SOC 2 與安全問卷： 用可驗證的執行時報告取代文字說明與螢幕截圖。
歐盟 AI 法案（EU AI Act）： 提供高風險 AI 系統所需的日誌與記錄保存。
OWASP GenAI 安全專案： 記錄實際代理行為，以提供針對過度自主與工具濫用等風險的證據。
AARM（CSA）： 產生雲端安全聯盟規範的防篡改行動收據（R5/R6）。
ISO 42001 / NIST AI RMF： 為管理系統控制提供作業證據。

CLI 參考

指令	目的
`halo verify`	驗證結構與雜湊鏈；失敗時返回非零退出碼，以供 CI/CD 整合使用。
`halo report`	將鏈渲染為自我驗證的 HTML 執行時報告。
`halo serve`	透過 HTTP 提供每個租戶的報告，並以客戶範圍的存取權限服務。
`halo anchor`	為鏈的最新節點提供見證，或對照見證者檢查完備性。
`halo hook`	專為 Claude Code 的 `PostToolUse` 鉤子設計。