halo-record

변조 방지 AI 에이전트용 런타임 레코드: 공급업체가 실행하지만 편집할 수 없는 감사 추적.

에이전트가 수행하는 모든 작업(도구 호출, 모델 호출, 데이터 접근, 승인)은 추가 전용 구조의 해시 체인 로그에 하나의 레코드로 기록됩니다. 체인의 체크포인트를 보유한 모든 당사자는 생성자를 신뢰하지 않고도 그 뒤의 레코드가 변경된 적이 없음을 검증할 수 있습니다. 고객의 보안 팀이 "에이전트가 우리 데이터로 무엇을 했나요?"라고 묻는다면, 긴 문단 대신 링크 하나를 건네면 됩니다. 보안 검토는 이미 SOC 2 체크리스트 옆에 AI 질문을 포함하고 있으며, 오늘날에는 서면 보증으로도 통과합니다. 이 프로젝트가 거는 내기는 그러한 관행이 오래가지 못할 것이라는 점입니다.

레코드 형식은 개방되어 있으며 누구나 자유롭게 구현할 수 있습니다. 이 패키지는 참조 구현으로, 레코더, 검증기, 위트니스 클라이언트, 리포트 서버를 포함합니다.

이 코드를 신뢰할 수 있는 이유

이 패키지는 에이전트 내부에 레코더를 설치하도록 요청합니다. 이를 맹신해서는 안 됩니다:

• 런타임 의존성 제로. 표준 라이브러리만 사용합니다. pip install halo-record는 정확히 하나의 패키지만 설치합니다.
• 네트워크 호출 없음. 옵트인 방식이며 레코드 수와 체인 지문만 수신하는 위트니스를 제외하고는 네트워크 호출이 없습니다. 레코드 내용은 인프라를 벗어나지 않습니다.
• 원시 입력은 절대 레코드에 들어가지 않습니다. 인자는 해시되어 수정된 요약본으로만 저장되며, 원시 값은 절대 저장되지 않습니다. 수정(redaction)은 최선형(best-effort) 방식입니다(일반적인 비밀값 및 PII 형식에 대한 정규식). 방어 심층화로 간주하되, 보장으로 여기지는 마세요.
• 감사하기에 충분히 작은 코드. 약 4,300줄의 Python. 오후에 전부 읽을 수 있습니다.
• Apache-2.0.

60초 데모

에이전트가 필요 없습니다. uv를 사용하면 설치할 것이 없습니다:

uvx --from halo-record halo demo --serve

또는 전통적인 방식:

pip install halo-record
halo demo --serve

두 방법 모두 고객 2곳을 둔 가상의 서포트 에이전트 공급업체를 생성하고, 체인을 위트니싱하며, 고객별로 게이트된 Runtime Report를 제공하고, 브라우저에서 운영자 콘솔을 엽니다. 그런 다음 변조 테스트를 시도해 보세요: .jsonl 파일 중 하나에서 한 줄을 삭제하고 새로고침하면 리포트가 이를 감지합니다.

자신의 에이전트 레코드 작성

경계에서 단 한 줄:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records every tool call to ./audit.jsonl

log=을 지정하지 않으면 레코드는 ~/.halo/my-agent.jsonl에 저장됩니다(에이전트당 하나의 체인). 또는 이미 실행 중인 도구용 어댑터를 사용하세요(아래 매트릭스 참조). 그런 다음 리포트를 렌더링합니다:

halo report audit.jsonl -o report.html    # one chain -> self-verifying HTML
halo serve ./records --port 8721          # all tenants, gated per customer

퀵스타트는 브라우저에서 자신의 에이전트 Runtime Report를 볼 때 끝납니다. JSONL 파일은 얻었지만 리포트가 없다면 문제가 있는 것입니다: 이슈를 열어 주세요.

이미 실행 중인 도구와 연결

모든 레코드는 source 태그를 포함하므로 리포트는 각 증거가 어떻게 수집되었는지를 공개합니다. 캡처된 레코드와 수집된 레코드는 동일한 체인에 존재합니다.

OpenTelemetry GenAI 스팬을 생성하는 모든 것(CrewAI, LlamaIndex, 그리고 OTel 계측을 갖춘 대부분의 에이전트 프레임워크)은 OTel 어댑터를 통해 체인에 포함됩니다. 또한 TypeScript 패키지는 Vercel AI SDK와 JS 에이전트 생태계용 네이티브 어댑터를 제공합니다. 사용 중인 스택용 어댑터가 없나요? 이슈를 열어 주세요. 대부분의 어댑터는 약 100줄 정도입니다.

코딩 에이전트 레코드 작성

Claude Code는 모든 도구 호출 후 PostToolUse 훅을 실행합니다. 이를 halo hook에 연결하면 파일 쓰기, 셸 명령, MCP 커넥터 호출 등 각 작업이 로컬 체인의 레코드가 됩니다. 코드 변경 없이 설정 항목 하나만 추가하면 됩니다:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

이를 ~/.claude/settings.json에 추가하면 레코드는 ~/.halo/audit.jsonl에 저장됩니다($HALO_LOG로 재정의 가능). 데이터, 네트워크 또는 외부 상태를 건드리지 않는 순수 오케스트레이션 도구는 건너뜁니다. 체인은 사고(thinking)가 아닌 신뢰 경계 작업을 기록합니다. HALO_HASH_ONLY=1을 설정하면 요약 없이 콘텐츠 해시만 기록합니다. HALO_AGENT_VERSION(선택적으로 HALO_AGENT_MODEL)을 설정하면 모든 레코드를 생성한 에이전트 빌드에 바인딩합니다. 감사관이 특정 기간에 실행된 버전을 물어볼 때, 내보내기는 기억이 아닌 열(column) 단위로 답합니다.

리포트가 "이 실행은 어떤 규칙 하에 이루어졌나?"라는 질문에 답해야 한다면, HALO_AUTHORITY_FILE을 세션의 유효 권한(authority)에 대한 JSON 스냅샷으로 설정하세요. 프라이버시를 안전하게 유지하세요: 원시 프롬프트, 비공개 정책 텍스트, 비밀값, 전체 도구 스키마가 아닌 해시와 참조만 포함합니다.

{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}

HALO_AUTHORITY_FILE=./authority.json halo hook

스냅샷은 작업 레코드와 동일한 해시 체인에 봉인됩니다. 좋은 기본값은 시작 시 세션 수준 스냅샷 하나를 만든 다음, 규칙, Skills, 훅, MCP 도구 레지스트리 또는 컴팩션 정책이 변경될 때 새 스냅샷을 만드는 것입니다. 긴 세션을 가볍게 유지하기 위해, 동일한 authority.snapshot_id를 가진 연속 레코드는 첫 번째 전체 스냅샷 이후 컴팩션됩니다: 이후 레코드는 {"snapshot_id": "...", "same_as_previous": true}만 유지합니다. 포인터는 계속 해시 체인에 연결되지만, 부피가 큰 refs/omissions/stale-if 블록은 모든 작업에서 반복되지 않습니다. 그런 다음 평소처럼:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

사후 작업 훅을 노출하는 모든 에이전트 런타임은 동일한 명령을 사용할 수 있습니다 — 훅은 stdin에서 JSON으로 이벤트 하나를 읽고 레코드 하나를 추가합니다.

무결성 vs. 완전성 (이 부분을 읽으세요)

각 계층이 증명하는 바를 정확히 파악하세요. 서로 다른 주장이며, 바로 그 차이가 핵심입니다:

자가 보유 체인은 확립된 헤드에 대한 무결성을 증명합니다: 누군가 이미 보유한 체인 헤드가 주어지면, 그 뒤에 있는 레코드의 모든 편집, 재정렬, 삭제가 감지 가능해집니다. 그 자체로는 — 운영자 외부의 누군가가 헤드를 보기 전까지는 — 체인은 내부 일관성만 증명할 뿐 기록(history)을 증명하지 못합니다: 운영자가 레코드를 삭제하고 다시 봉인하면 새 파일도 검증을 통과합니다. 체인은 헤드가 운영자의 통제를 벗어나는 순간 역사적으로 커밋됩니다.

이것이 바로 위트니스입니다: 운영자 외부의 당사자가 체인의 주기적 지문(개수와 헤드 해시, 그 외에는 아무것도 없음)을 보유합니다. 체크포인트는 커밋된 기록의 재작성을 감지 가능하게 만들며, 누락된 체크포인트 자체도 가시적인 이벤트입니다:

halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

한 가지 더 경계를 분명히 하자면, 체인과 위트니스 모두 모든 실제 작업이 레코더를 통과했음을 증명하지 않습니다. 이것은 캡처 완전성(capture completeness) — 레코더가 스택의 어디에 위치하는지(네이티브 계측, 훅, 게이트웨이 수집)에 관한 속성이며, 어떤 해시와도 무관합니다. 레코드에 source 태그가 있는 것은 바로 이 때문입니다.

누구나 위트니스를 실행할 수 있습니다. 직접 실행하는 위트니스는 당신에게 기록을 커밋합니다. 고객에게 커밋하려면 고객이 신뢰할 이유가 있는 위트니스가 필요합니다. 프로토콜은 어느 쪽이든 개방되어 있습니다.

호스팅되고 인정받는 위트니스가 이 프로젝트의 지속 가능한 운영 방식입니다. 얼리 액세스: [email protected].

컴플라이언스 스택에서의 위치

halo-record는 인증이 아닌 증거 계층입니다. 평가 프레임워크가 서로 다른 표현으로 계속 요구하는 아티팩트를 생성합니다:

• 보안 설문지 및 SOC 2 검토: 스크린샷과 설명 대신 검증 가능한 Runtime Report로 AI 관련 섹션에 답변합니다.
• AIUC-1: 표준의 책임성(Accountability) 통제가 요구하는 변조 방지 로깅(E015.4)과 권한 부여 이벤트를 포함한 전체 실행 체인 레코드(E015.2)를 생성합니다. 감사 시점에 재구성되는 것이 아니라 지속적인 런타임 증거입니다.
• OWASP (GenAI Security Project): OWASP Top 10 for Agentic Applications 2026 및 LLM Top 10에서 다루는 에이전트 행동 위험 — 목표 하이재킹, 도구 오용, 신원 및 권한 남용 — 에 대한 런타임 증거로, 에이전트가 어떤 도구와 데이터로 실제 무엇을 했는지를 기록합니다.
• AARM (CSA): AARM이 명시한 변조 방지 작업 영수증(R5/R6)을 생성합니다 — 체인으로 연결되고 독립적으로 위트니싱됩니다. halo-record는 영수증 계층이며, 완전한 AARM 시스템을 위해 집행 게이트웨이와 함께 사용하세요. AARM.md 참조.
• Agentic Trust Controls: ATC의 증거 통제 뒤에 있는 런타임 레코드 — 변조 방지 작업 로깅(RBM-03)과 권한 증명(AID-05)이 하나의 체인 레코드에 포함되며, 그 너머에 위트니스 계층이 있습니다. ATC.md 참조.
• EU AI Act: 고위험 AI 시스템에 대한 로깅 및 기록 보존 의무.
• ISO 42001 / NIST AI RMF: 경영 시스템 통제 뒤에 있는 운영 증거.

이 중 어느 것도 그 자체로 무언가를 인증하지 않습니다. 평가자에게 검증 가능한 무언가를 제공할 뿐입니다. 경계 — halo-record가 의도적으로 수행하지 않는 것과 검토자가 물을 때 무엇이라고 답해야 하는지 — 는 LIMITS.md에 문서화되어 있습니다.

CLI

halo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo anchor   witness a chain head, or --check completeness
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook

무결성 모델

레코드의 해시를 계산하려면: integrity.hash를 제외한 레코드에 integrity.prev_hash를 이전 레코드의 해시로 설정한 다음, RFC 8785(JSON Canonicalization Scheme)로 정규화하고 바이트를 SHA-256으로 해시합니다. 첫 번째 레코드의 prev_hash는 64개의 0입니다. 검증은 모든 해시를 다시 계산하고 모든 링크를 확인합니다. 비밀값이 필요 없습니다. 그것이 핵심입니다.

검증자가 알아차리지 못하고 체인을 변조할 수 있다고 생각하시나요? 시도와 결과는 여기 있습니다.

전체 필드 참조: halo-record.schema.json

TypeScript

동일한 레코더가 Node용으로 제공됩니다: halo-record-ts. 동일한 체인 형식, 동일한 위트니스 프로토콜. 두 언어 중 어느 것으로 작성된 레코드도 두 검증기 중 어느 것으로든 검증할 수 있습니다.

기여

이슈, 토론, 풀 리퀘스트를 환영합니다. 기본 규칙은 CONTRIBUTING.md를 참조하세요(요약: 테스트 필수, 작은 PR, 스키마 변경은 먼저 논의).

라이선스

Apache-2.0