halo-record

Защищённые от подделки журналы выполнения для ИИ-агентов: аудиторский след, который вендор ведёт, но не может редактировать.

Каждое действие вашего агента (вызовы инструментов, вызовы моделей, доступ к данным, согласования) становится одной записью в журнале с append-only структурой и хэш-цепочкой. Любая сторона, у которой есть контрольная точка цепочки, может проверить, что записи за ней никогда не изменялись, не доверяя тому, кто их создал. Когда служба безопасности заказчика спрашивает: «что ваш агент делал с нашими данными?», вы даёте им ссылку вместо абзаца. Проверки безопасности уже задают вопросы об ИИ наряду с чек-листом SOC 2, и сегодня письменного заверения всё ещё достаточно. Ставка этого проекта в том, что так будет недолго.

Формат записей открыт, и его можно свободно реализовать. Этот пакет — эталонная реализация: рекордер, верификатор, клиент свидетеля и сервер отчётов.

Почему этому коду можно доверять

Вас просят встроить рекордер внутрь вашего агента. Не стоит принимать это на веру:

• Ноль зависимостей времени выполнения. Только стандартная библиотека. pip install halo-record устанавливает ровно один пакет.
• Никаких сетевых вызовов, кроме свидетеля, который подключается опционально и получает только количество записей и отпечаток цепочки. Содержимое записей никогда не покидает вашу инфраструктуру.
• Сырые входные данные никогда не попадают в запись. Аргументы хэшируются и сохраняются только в виде сводки, из которой удалены чувствительные данные, — никогда в виде исходного значения. Удаление чувствительных данных выполняется по принципу 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

Любой из вариантов разворачивает каркас вымышленного вендора агента поддержки с двумя клиентами, заверяет цепочки, раздаёт их Runtime-отчёты с разграничением доступа и открывает консоль оператора в вашем браузере. Затем попробуйте тест на вмешательство: удалите строку из одного из .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-отчёт своего агента в браузере. Если вы получили JSONL-файл, но не отчёт, что-то не так: откройте issue.

Подключение к тому, что вы уже запускаете

Каждая запись несёт тег source, поэтому отчёт показывает, как было собрано каждое доказательство. Захваченные и импортированные записи находятся в одной цепочке.

Всё, что испускает OpenTelemetry GenAI-спаны (CrewAI, LlamaIndex и большинство агентных фреймворков с OTel-инструментацией), попадает в цепочку через OTel-адаптер, а TypeScript-пакет поставляет нативные адаптеры для Vercel AI SDK и экосистемы JS-агентов. Не хватает адаптера для вашего стека? Откройте issue. Большинство адаптеров — около сотни строк.

Запись действий вашего кодинг-агента

Claude Code запускает хук PostToolUse после каждого вызова инструмента. Пропишите в нём halo hook, и каждое действие — запись файлов, команды оболочки, вызовы MCP-коннекторов — станет записью в локальной цепочке. Без изменений кода; одна запись в настройках:

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

Добавьте это в ~/.claude/settings.json, и записи будут попадать в ~/.halo/audit.jsonl (переопределяется через $HALO_LOG). Инструменты чистой оркестрации, не затрагивающие данные, сеть или внешнее состояние, пропускаются — цепочка записывает действия, пересекающие границу доверия, а не мышление. Установите HALO_HASH_ONLY=1, чтобы записывать хэши содержимого без сводок. Установите HALO_AGENT_VERSION (и опционально HALO_AGENT_MODEL), чтобы привязать каждую запись к сборке агента, которая её создала, — когда аудитор спрашивает о версии, работавшей в определённом окне, экспорт отвечает колонкой, а не по памяти.

Если вам нужно, чтобы отчёт отвечал на вопрос «по каким правилам выполнялся этот запуск?», установите HALO_AUTHORITY_FILE в JSON-снимок действующих полномочий (effective authority) для сессии. Сохраняйте его приватным: хэши и ссылки, а не исходные промпты, тексты внутренних политик, секреты или полные схемы инструментов.

{
  "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

Любая среда выполнения агента, поддерживающая хук после действия, может передавать данные той же команде: хук читает одно событие в формате JSON из stdin и добавляет одну запись.

Целостность против полноты (прочтите эту часть)

Будьте точны в том, что доказывает каждый уровень, — потому что это разные утверждения, и именно различия здесь важны:

Самостоятельно хранимая цепочка доказывает целостность относительно установленной головы: если у кого-то уже есть голова цепочки, любое изменение, перестановка или удаление записей за ней становится обнаружимым. Сама по себе — пока никто, кроме оператора, не видел головы — цепочка доказывает внутреннюю согласованность, а не историю: оператор мог бы удалить запись и перезапечатать цепочку, и новый файл прошёл бы проверку. Цепочка становится исторически зафиксированной в тот момент, когда её голова покидает контроль оператора.

Вот для чего нужен свидетель: сторона за пределами оператора, которая периодически получает отпечатки цепочки (количество записей и хэш головы — и ничего больше). Контрольные точки делают обнаружимым переписывание зафиксированной истории, а пропущенная контрольная точка сама по себе является видимым событием:

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-отчётом вместо скриншотов и текста.
• AIUC-1: обеспечивает защищённое от подделки журналирование (E015.4) и записи полной цепочки выполнения с событиями авторизации (E015.2), которых требуют контроли подотчётности (Accountability) стандарта, — непрерывные доказательства времени выполнения, а не восстановленные в момент аудита.
• OWASP (GenAI Security Project): доказательства времени выполнения, стоящие за рисками поведения агентов в OWASP Top 10 for Agentic Applications 2026 и LLM Top 10, — перехват цели, неправомерное использование инструментов, злоупотребление идентификацией и привилегиями, — зафиксированные как то, что агент фактически делал, с какими инструментами и данными.
• AARM (CSA): создаёт защищённую от подделки квитанцию о действии (action receipt), которую определяет AARM (R5/R6), — с хэш-цепочкой и независимым освидетельствованием. halo-record — это уровень квитанций; объедините его со шлюзом принудительного контроля (enforcement gateway) для получения полной системы AARM. См. AARM.md.
• Agentic Trust Controls: записи времени выполнения, стоящие за контролами доказательств ATC, — защищённое от подделки журналирование действий (RBM-03) и аттестация полномочий (AID-05) в одной записи с хэш-цепочкой, а поверх обоих — уровень свидетеля. См. ATC.md.
• EU AI Act (Закон ЕС об ИИ): обязательства по журналированию и ведению записей для высокорисковых систем ИИ.
• 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 нуля. Проверка пересчитывает каждый хэш и проверяет каждую связь. Секрет не требуется; в этом суть.

Думаете, что сможете изменить цепочку так, что верификатор не заметит? Попытки и результаты — здесь.

Полный справочник полей: halo-record.schema.json.

TypeScript

Тот же рекордер поставляется для Node: halo-record-ts. Тот же формат цепочки, тот же протокол свидетеля. Записи, созданные на любом из языков, проверяются любым из верификаторов.

Участие

Приветствуются issues, обсуждения и пул-реквесты — основные правила см. в CONTRIBUTING.md (кратко: обязательны тесты, небольшие PR, изменения схемы сначала обсуждаются).

Лицензия

Apache-2.0