
AI 에이전트를 위한 변조 방지 감사 추적: 해시 체인 방식의 런타임 레코드, 의존성 없음, 누구나 검증 가능.
변조 감지 가능한 AI 에이전트용 감사 추적 — 해시 체인으로 연결된 런타임 레코드로, 고객이 직접 확인할 수 있는 런타임 보고서로 렌더링됩니다.
계측이 캡처하는 모든 작업(도구 호출, 모델 호출, 데이터 접근, 승인)은 추가 전용 해시 체인 로그에서 하나의 런타임 레코드가 되며, 런타임 보고서는 해당 체인을 HTML 페이지로 렌더링한 것으로, 리더의 브라우저에서 해시 체인을 다시 계산하고 검증한 레코드로부터 표시 내용을 렌더링합니다(페이지 자체 코드에 의존하지 않는 검증을 위해서는 JSONL에 대해 halo verify를 실행하십시오). 해당 체인의 체크포인트를 보유한 모든 당사자는 이를 생성한 주체를 신뢰하지 않고도 해당 체크포인트까지의 레코드가 생성 이후 변경되지 않았음을 검증할 수 있습니다 — 이 체크포인트가 핵심 요소입니다: 체인 자체만으로는 기록기를 운영하는 주체를 제외한 모든 이에 대해 변조 감지가 가능합니다(LIMITS.md §1). 고객의 보안 팀이 "귀하의 에이전트가 우리 데이터로 무엇을 했습니까?"라고 물을 때, 문단 대신 링크를 건네면 됩니다. 보안 검토는 이미 SOC 2 체크리스트 옆에서 AI 관련 질문을 하고 있으며, 점점 더 많은 질문이 ISO 42001, EU AI Act의 기록 보관 조항, 고객 자체 설문지에서 나오고 있습니다. 오늘날에는 서면 보증만으로도 통과됩니다. 이 프로젝트의 배경이 되는 가설은 그것이 오래가지 않을 것이라는 점입니다.
"포렌식 분야에서 20년을 일하다 보면 증거는 상대방이 확인할 수 있을 때만 증거라는 것을 배웁니다... 신뢰를 요구하는 AI 제품이 넘치는 분야에서 [Halo]는 신뢰를 불필요하게 만들도록 설계된 드문 제품입니다."
Johannes Stillig, Tidebreak AI 창립자 겸 CEO이자 사모 투자 사무소의 그룹 CISO
Help Net Security에 소개됨 · 해당 주 Show HN 출시 상위 4% · 다섯 가지 통제 항목에 대해 Agentic Trust Controls에 등재됨
레코드 형식은 개방되어 있으며 무료로 구현할 수 있습니다. 이 패키지는 참조 구현입니다: 기록기, 검증기, 증인 클라이언트, 보고서 서버.
halo-record를 사용 중이거나 고려 중이신가요? 누구이며 어떤 목적인지 알려주세요 → Who's using halo-record?
귀하는 에이전트 내부에 기록기를 설치하라는 요청을 받고 있습니다. 그것을 믿음으로 받아들여서는 안 됩니다:
pip install halo-record는 정확히 하나의 패키지만 설치합니다.halo serve --verify-email(일회용 코드와 보고서의 대상 이름을, $HALO_SMTP_HOST에 설정한 서버를 통해 SMTP로, 보고서 열람자가 입력한 주소로 전송). 이들은 직접 호출하지 않는 한 모두 꺼져 있으며, 그 외의 레코드 내용은 여러분의 인프라를 벗어나지 않습니다.summaries=False)는 요약을 전혀 남기지 않습니다. 마스킹은 최선의 노력(일반적인 시크릿 및 PII 형식에 대한 정규식과 엔트로피 포괄 규칙)이므로, 심층 방어로 취급해야 하며 보장으로 여겨서는 안 됩니다. summary 외에 제공하는 결과 필드도 동일한 패턴으로 스캔 및 마스킹되지만, 200자로 잘리지는 않습니다(LIMITS §13).각 계층이 증명하는 것 — 이 프로젝트의 핵심적인 구분(LIMITS.md §1): 여러분이 직접 보유한 체인은 이미 누군가가 보유한 헤드를 기준으로 레코드가 편집되지 않았음을 증명합니다. 운영자 외부에 보관된 체크포인트만이 어떤 레코드도 제거되지 않았음을 증명합니다. 그리고 어떤 해시도 모든 행동이 포착되었음을 증명하지 못합니다.
| 주장 | 자체 보유 체인 | + 외부 체크포인트 | + 신뢰할 수 있는 포착 |
|---|---|---|---|
| 확립된 아티팩트에 대한 편집 탐지 | ✔ | ✔ | ✔ |
| 커밋된 이력의 재작성 탐지 | — | ✔ | ✔ |
| 누락/지연된 체크포인트 탐지 | — | ✔ (합의된 주기) | ✔ |
| 모든 행동이 기록되었음을 증명 | — | — | 포착 경계에 따라 다름 |
설치 전에 하나 살펴보기: 샘플 Runtime Report — 가상의 데이터, 실제 체인이며, 열면 스크립트가 내장된 레코드의 해시 체인을 브라우저에서 다시 계산합니다.
에이전트가 필요하지 않습니다. uv를 사용하면 설치할 것이 없습니다:
uvx --from halo-record halo demo --serve
또는 고전적인 방법:
pip install halo-record
halo demo --serve
둘 중 하나는 두 고객을 둔 가상의 지원 에이전트 벤더를 스캐폴딩하고, 체인을 목격하며(운영자 외부의 한 곳을 대신하는 로컬 witness 파일 포함 — LIMITS.md §1 참조), 게이트가 적용된 Runtime Reports를 제공하고, 브라우저에서 운영자 콘솔을 엽니다. 그런 다음 변조 테스트를 시도해 보세요: .jsonl 파일 중 하나에서 한 줄을 삭제하고 다시 로드하세요. 보고서가 이를 잡아냅니다.
경계에서 한 줄:
from halo_record import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls
from halo import ... 편의 심(shim)도 함께 제공되지만, PyPI의 halo 이름은 무관한 터미널 스피너 패키지에 속해 있으며, 해당 패키지가 설치되어 있으면 임포트에서 우선권을 갖습니다. halo_record는 모호하지 않으므로 예제에서는 이를 사용합니다.
log=가 없으면 레코드는 ~/.halo/my-agent.jsonl로 저장됩니다(에이전트당 하나의 체인). 래퍼는 실행 경계를 봉인하며, 증거는 호출별 레코드에 남습니다. 프레임워크 어댑터(아래 매트릭스)로 이를 캡처하거나, 명시적으로 캡처할 수 있으며 후자는 위임 링크가 어떻게 연결되는지도 보여줍니다:
from halo_record import Recorder, record_call
rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call: # one sealed record per tool call
call.result = crm.lookup("acct-9")
with record_call(rec, "payments.refund", {"amount": 120},
parent_id=rec.last_record_id()) as call: # child links to the action that spawned it
call.result = payments.refund(120)
그런 다음 보고서를 렌더링합니다:
halo report audit.jsonl -o report.html # one chain -> HTML that re-verifies in the browser
halo serve ./records --port 8721 # all tenants, gated per customer
0.2.45에서 처음 제공된 디렉터리를 업그레이드하시나요? halo serve는 시작 시 이전의 각 grant를 다시 읽습니다. 레코드에 subject id가 없는 파일(예: agent.jsonl 같은 일반 Recorder 파일)에 대한 grant는 격리되며, 매 시작 시 이를 재발급하는 halo grant 명령과 함께 출력됩니다 — LIMITS.md §17, "Serving a directory first served by 0.2.45"를 참조하세요.
퀵스타트는 브라우저에서 자신의 에이전트의 Runtime Report를 보고 있을 때 끝납니다. JSONL 파일만 받고 보고서가 없다면 뭔가 잘못된 것입니다: 이슈를 열어 주세요.
가드레일이나 정책 계층이 해당 작업을 검사했다면, 그 판정이 레코드에 실려 갈 수 있습니다 — 게이트가 무엇을 결정했는지 기록하는 선택적 블록으로, 다른 모든 필드와 마찬가지로 해시 체인에 봉인됩니다:
from halo_record import build
build("tool_call", "security", tool="payments.refund",
verification={"status": "allowed", "verifier": "gate/1.2",
"policy_ref": "sha256:1f3a...",
"checked_at": "2026-08-01T12:00:00Z"})
한 가지 명명 관련 참고 사항: 이 패키지는 record 함수(데코레이터)를 내보내며, 이 함수는 패키지 객체에서 halo_record.record 모듈을 가립니다. 내부 요소를 사용하려면 import halo_record.record as record 대신 모듈 경로에서 직접 가져오십시오 — from halo_record.record import build.
이는 다음과 같이 레코드에 봉인됩니다:
"verification": {"status": "allowed", "verifier": "gate/1.2", "policy_ref": "sha256:1f3a...", "checked_at": "2026-08-01T12:00:00Z"}
record_call(...)는 동일한 verification= 키워드를 받습니다. status는 블록 내에서 필수이며, verifier, policy_ref, checked_at은 선택 사항입니다. 각 상태의 의미는 다음과 같습니다:
| 상태 | 게이트가 보고하는 내용 | 작업이 실행되었는가? |
|---|---|---|
allowed | 작업을 허용함 | 예 — 작업이 진행됨 |
blocked | 작업을 거부함 | 이 필드가 아니라 통합에 의해 결정됨 — 레코드에 여전히 결과가 담길 수 있으며, 차단 자체만으로 실행되지 않았음을 증명하지는 않음 |
modified | 실행 전에 작업을 변경함 — action.input은 수정 후 실행된 그대로의 작업을 설명함 | 예, 변경된 형태로 |
unverified | 실행되었으나(또는 참조되었으나) 판정을 내리지 않음 — 아무런 검증 주장도 하지 않은 것을 의미하는 블록 부재와는 구별됨 | 예 — 판정 없이 작업이 진행됨 |
이 블록은 운영자의 통합 코드에 의해 제공되며, 게이트가 말했다고 보고하는 내용을 기록합니다 — principal과 동일한 신뢰 태세입니다(LIMITS 참조). 봉인은 상태가 사후에 편집되지 않았음을 증명하지만, 검사가 발생했는지, 판정이 올바른지, 또는 차단된 작업이 실행되지 않았는지를 증명하지는 않습니다. 이는 독립적인 검증이 아닙니다.
policy_ref를 증거로 사용할 수 있으려면 규칙 집합의 콘텐츠 해시를 사용하고 규칙 집합 아티팩트를 보관하십시오 — 해석할 수 없는 레이블은 해당 필드를 장식으로 만듭니다.
| 경계에서 캡처됨 | 기존 텔레메트리에서 수집됨 |
|---|---|
네이티브 레코더 (from halo_record import trace) | OpenTelemetry GenAI 스팬 |
| MCP 인터셉터 | LiteLLM 콜백 |
| LangChain / LangGraph 콜백 | Langfuse 내보내기 |
| OpenAI Agents SDK 훅 | 모든 게이트웨이 / 리버스 프록시 로그 |
| Claude Agent SDK 훅 | Claude Code 및 Codex CLI PostToolUse 훅 (도구 실행 후 발생) |
halo door가 구매자 측에서 읽는 플랫폼 로그 내보내기 (GitHub 보안 로그, Salesforce Event Monitoring) |