halo-record

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

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

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

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

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

• Ноль зависимостей времени выполнения. Только стандартная библиотека. pip install halo-record устанавливает ровно один пакет.
• Никаких сетевых вызовов, кроме свидетеля, который подключается по желанию и получает только количество записей и отпечаток цепочки. Содержимое записей никогда не покидает вашу инфраструктуру.
• Сырые входные данные никогда не попадают в запись. Аргументы хэшируются и сохраняются только в виде редактированного суммарного описания — никогда в виде raw-значения. Редактирование выполняется по принципу best-effort (regex по распространённым форматам секретов и PII): относитесь к нему как к защите в глубину, а не как к гарантии.
• Достаточно мал для аудита. ~4 300 строк Python. Можно прочитать всё за один день.
• Apache-2.0.

60-секундная демонстрация

Агент не требуется. С uv ничего устанавливать не нужно:

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

или классическим способом:

pip install halo-record
halo demo --serve

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

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

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

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

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

Claude Code запускает хук PostToolUse после каждого вызова инструмента. Укажите в нём halo hook — и каждое действие (запись в файл, shell-команда, вызов 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-снимок действующего набора полномочий для сессии. Соблюдайте приватность: хэши и ссылки, а не сырые промпты, тексты приватных политик, секреты или полные схемы инструментов.

{
  "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 и добавляет одну запись.

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

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

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

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

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

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

Любой может запустить свидетеля. Свидетель, которого вы запускаете сами, фиксирует историю для вас; фиксация для вашего клиента требует свидетеля, которому клиент имеет основания доверять. Протокол в любом случае открыт.

Хостируемый признанный свидетель — это то, как проект будет поддерживать себя. Ранний доступ: [email protected].

Место в стеке соответствия требованиям

halo-record — это слой доказательств, а не сертификация. Он производит артефакт, который оценочные фреймворки постоянно запрашивают другими словами:

• Опросники по безопасности и проверки SOC 2: отвечайте на разделы об ИИ с помощью проверяемого Runtime Report вместо скриншотов и прозы.
• AIUC-1: формирует защищённое от несанкционированных изменений журналирование (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 дополните его enforcement-шлюзом. См. 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, обсуждения и pull request'ы — основные правила см. в CONTRIBUTING.md (кратко: обязательны тесты, небольшие PR, изменения схемы сначала обсуждаются).

Лицензия

Apache-2.0