Un audit trail para agentes de IA es un registro local y cronológico de cada acción que ejecuta un agente de código: qué archivos leyó, qué modificó, qué comandos corrió y cuándo. El proyecto Gryph, lanzado en 2026 bajo licencia Apache 2.0, es la primera herramienta open source que implementa rastreo de agentes IA para Claude Code, Cursor, Gemini CLI y otros, almacenando todo localmente sin enviar datos a la nube.
En 30 segundos
- Gryph es un proyecto open source (Apache 2.0) que registra cada acción de agentes como Claude Code, Cursor y Gemini CLI en una base SQLite local, sin telemetría externa.
- Ninguno de los agentes de código populares tiene audit trail nativo: si Claude Code leyó tu
.envo tu.git/config, no hay registro oficial de eso salvo que lo instrumentes vos. - La EU AI Act, efectiva agosto 2026, va a requerir auditabilidad de cambios de código generados por IA, lo que convierte esto en un tema de compliance, no solo de curiosidad técnica.
- Gryph registra archivos leídos, archivos escritos (con hash de contenido), comandos ejecutados (con exit code y stderr), y tool calls MCP con sus parámetros.
- Existe al menos una vulnerabilidad documentada en Claude Code (CVE-2025-59536) que permite bypass de seguridad; sin audit trail, detectarla en producción es difícil.
Claude Code es una interfaz desarrollada por Anthropic que proporciona acceso al modelo de lenguaje Claude para asistencia en programación, disponible como aplicación web, CLI, desktop y extensiones IDE.
Qué es un Audit Trail para agentes de IA (y por qué es crítico)
Un audit trail es un log estructurado que registra quién hizo qué, cuándo y dónde. En el contexto de agentes de IA que escriben y ejecutan código, “quién” es el agente, “qué” puede ser leer un secreto de tu .env o modificar una función de autenticación, y “cuándo” puede ser en medio de una sesión que terminó con errores y no sabés exactamente en qué estado quedaron tus archivos.
Ponele que le pedís a Claude Code que refactorice un módulo de pagos. El agente puede leer perfectamente tu config/secrets.py, tu .env.production y tu historial de git para entender el contexto. Todo legítimo. Pero si ese contexto incluye credenciales de Stripe o tokens de API, y el agente está conectado a herramientas MCP que pueden hacer requests externos, querés saber exactamente qué leyó y qué mandó a dónde.
El rastreo de agentes IA no es paranoia. Es el mismo principio que usás cuando revisás el acceso a una base de datos de producción.
El problema: agentes de código sin visibilidad
Claude Code, Cursor y Gemini CLI son herramientas con acceso amplio al sistema de archivos. Por diseño, necesitan leer contexto para ser útiles. El problema es que no generan registros de auditoría que vos puedas consultar después.
¿Alguien verificó de forma independiente qué archivos exactos lee Cursor cuando analizás un proyecto? Hay telemetría que se va a los servidores del proveedor, pero no hay un log local estructurado que vos puedas abrir y decir “esta sesión del martes pasado tocó estos archivos”.
El CVE-2025-59536, documentado este año, es un bypass de seguridad en Claude Code que permite que instrucciones maliciosas en archivos del proyecto modifiquen el comportamiento del agente. Sin audit trail, si un repositorio comprometido con el que trabajaste ejecutó acciones no autorizadas, enterarte requiere revisar manualmente el historial de git y los logs del sistema operativo, que no tienen la granularidad necesaria. Cubrimos ese tema en detalle en los modelos más recientes de Claude.
Los riesgos concretos en un flujo de desarrollo cotidiano son tres: exfiltración de API keys que están en archivos de configuración que el agente lee para contexto, modificación de código de seguridad sin que el desarrollador lo note en el diff, y ejecución de comandos con permisos del usuario actual (que en muchos setups de desarrollo es bastante amplio).
Introducción a Gryph: cómo funciona técnicamente
Gryph es un proyecto de SafeDep, lanzado en 2026, con licencia Apache 2.0. La arquitectura es deliberadamente local-first: los hooks se configuran en el archivo de configuración del agente, los eventos se registran en una base SQLite en tu máquina, y no hay ningún proceso de sincronización externa.
La instalación se hace vía hooks en el archivo de configuración de cada agente. Para Claude Code, por ejemplo, se agrega un hook pre y post tool-call que intercepta cada acción antes y después de ejecutarla. Gryph soporta actualmente Claude Code, Cursor, Windsurf, Gemini CLI, OpenCode y Pi Agent.
La diferencia clave con soluciones de monitoreo empresarial (Datadog, SigNoz, OpenTelemetry) es que esas herramientas están diseñadas para observabilidad de sistemas distribuidos, no para auditar acciones granulares de un agente en tu sistema de archivos local. Son herramientas distintas para problemas distintos.
Existe también Snitch, un plugin de auditoría de seguridad con un enfoque más especializado en detección de amenazas. Gryph apunta más al registro comprehensivo para compliance y debugging.
Qué registra Gryph: granularidad del rastreo
El log de Gryph captura cuatro tipos de eventos:
- Archivo leído: path absoluto, timestamp, hash del contenido al momento de la lectura.
- Archivo escrito: path, hash antes y después, diff de los cambios detectados.
- Comando ejecutado: el comando completo, exit code, stdout y stderr capturados.
- Tool call MCP: nombre de la herramienta, parámetros pasados, respuesta recibida.
Esa granularidad permite hacer session replay: reconstruir exactamente qué pasó en una sesión. Si terminaste una sesión con Claude Code y tu suite de tests pasó a fallar, podés ver en orden cronológico qué archivos se modificaron y en qué secuencia, sin depender de que el agente te lo explique (spoiler: los agentes no siempre recuerdan con precisión qué hicieron dos sesiones atrás).
Para los que tienen secretos en .env, el log de lecturas es especialmente relevante. Sabés exactamente si en la sesión del viernes a las 22:00 el agente leyó tu .env.production y con qué tool call lo hizo. Lo explicamos a fondo en diferencias entre Claude Code y otros agents.
Consulta y análisis de logs: ejemplos prácticos
Los datos quedan en SQLite, lo que significa que cualquier herramienta que entienda SQL puede consultarlos. Sin dependencias adicionales, sin dashboards propietarios.
Algunos queries útiles para empezar:
- Todos los archivos
.envleídos en las últimas 24 horas:SELECT path, timestamp FROM file_reads WHERE path LIKE '%.env%' AND timestamp > datetime('now', '-1 day') - Archivos modificados en una sesión específica:
SELECT path, diff FROM file_writes WHERE session_id = 'X' ORDER BY timestamp - Comandos que terminaron con error:
SELECT command, exit_code, stderr FROM command_executions WHERE exit_code != 0
Para compliance, los logs se pueden exportar a JSON o CSV para adjuntarlos a reportes de auditoría. El formato SQLite también es compatible con herramientas de análisis forense estándar.
Una cosa que no queda del todo clara todavía es qué tan bien funciona la captura de comandos cuando el agente encadena múltiples subprocesos. Los casos simples están documentados, los flujos complejos de CI/CD automatizados merecen pruebas propias antes de confiar en el registro como fuente de verdad para auditorías formales.
Comparación: Gryph vs otras soluciones de auditoría
| Solución | Tipo | Almacenamiento | Granularidad | Agentes soportados | Costo |
|---|---|---|---|---|---|
| Gryph | Open source | Local SQLite | Alta (file/cmd/MCP) | Claude Code, Cursor, Gemini CLI, Windsurf | Gratis |
| Snitch | Plugin seguridad | Local | Media (foco en amenazas) | Específico por agente | Gratis/pago |
| OpenTelemetry + Datadog | Observabilidad | Nube | Baja para file ops | Via SDK manual | USD 15-30/host/mes |
| Logs del SO | Nativo | Local | Muy baja | Todos | Gratis |
Para un desarrollador individual que quiere saber qué hicieron sus agentes, Gryph es la opción más completa disponible hoy. Para un equipo que ya tiene infraestructura de observabilidad, puede complementarse: los logs de sistema distribuido no reemplazan el registro granular de acciones de agente.
La opción de los logs del sistema operativo (auditd en Linux, el Event Log en Windows) registra operaciones de archivo a nivel de proceso, pero no tiene contexto de qué agente tomó qué decisión ni qué tool call generó el acceso. Registra el “qué” sin el “por qué”.
Cumplimiento regulatorio: EU AI Act y auditoría de agentes
La EU AI Act entra en plena vigencia en agosto de 2026. Para sistemas de IA de alto riesgo (y los agentes que modifican código de producción van a entrar en esa categoría para muchas empresas), el reglamento exige trazabilidad: quién generó qué cambio, cuándo, con qué herramienta. En cómo optimizar el comportamiento del agent profundizamos sobre esto.
Un audit trail como el de Gryph cubre exactamente eso: el agente (quién), los archivos modificados con timestamps (qué y cuándo), y el contexto de la sesión (dónde). Para empresas en la Unión Europea o que venden a clientes europeos, implementar este tipo de registro deja de ser una buena práctica y pasa a ser un requisito de procurement.
Según análisis recientes sobre el EU AI Act, los equipos de desarrollo que usan agentes de IA para modificar código de sistemas críticos van a necesitar demostrar auditabilidad como condición para obtener certificaciones de conformidad. Empresas latinoamericanas que exportan software a Europa ya deberían estar evaluando qué herramientas usar.
Eso sí: la regulación es nueva y la interpretación exacta de qué constituye “auditabilidad suficiente” para agentes de código todavía está en desarrollo. Tomalo con pinzas en lo que respecta a cuánto de Gryph cubre el checklist regulatorio completo.
Qué está confirmado / Qué no está claro
- Confirmado: Gryph está disponible en GitHub bajo Apache 2.0 y soporta Claude Code, Cursor, Gemini CLI, Windsurf, OpenCode y Pi Agent.
- Confirmado: La arquitectura es local-first, sin telemetría a servidores externos.
- Confirmado: El CVE-2025-59536 en Claude Code existe y está documentado.
- Confirmado: La EU AI Act entra en vigor agosto 2026.
- No está claro: Qué tan completo es el soporte para cada agente; la documentación de casos edge (subprocesos, sesiones largas) es limitada.
- No está claro: Si el nivel de logging de Gryph cubre todos los requisitos específicos de auditabilidad bajo la EU AI Act, que todavía está siendo interpretada por organismos reguladores.
- No está claro: El roadmap del proyecto y si SafeDep va a mantener actualizaciones cuando los agentes lancen nuevas versiones.
Errores comunes al implementar auditoría de agentes
Confiar en el historial de git como audit trail. Git registra qué cambió en archivos trackeados, no qué archivos leyó el agente, qué comandos ejecutó ni qué acciones tomó con herramientas MCP. Si el agente leyó tu secrets.json sin modificarlo, git no lo registra.
Asumir que los logs del agente son completos. Claude Code tiene logs de sesión, pero están orientados a debugging del agente, no a auditoría de seguridad. Cubrís el caso de “qué dijo el agente que iba a hacer”, no necesariamente “qué hizo realmente a nivel de sistema”.
Implementar auditoría solo en producción. Los entornos de desarrollo son donde los agentes tienen acceso más amplio: repositorios completos, credenciales de múltiples servicios, configuraciones locales. El riesgo no está solo en el servidor de producción.
Preguntas Frecuentes
¿Qué es un audit trail para agentes de IA y por qué es importante?
Un audit trail es un registro estructurado de cada acción que ejecuta un agente: archivos leídos, archivos modificados, comandos ejecutados y tool calls realizadas, con timestamps y contexto. Es importante porque los agentes de código tienen acceso amplio al sistema de archivos y pueden leer credenciales, ejecutar comandos y modificar código crítico; sin registro, no hay forma de verificar qué hicieron en una sesión determinada. Esto se conecta con lo que analizamos en problemas de rendimiento detectados antes.
¿Cómo sé qué archivo leyó o modificó Claude Code en mi sesión?
Sin una herramienta de auditoría como Gryph, no hay forma directa. Claude Code genera logs de sesión en ~/.claude/logs/, pero esos logs están orientados a debugging de la conversación, no registran accesos al sistema de archivos de forma estructurada. Con Gryph instalado, podés consultar la base SQLite local y filtrar por tipo de operación, path y timestamp.
¿Existe forma de auditar Cursor, Gemini CLI y otros agentes de código?
Gryph es la solución open source más completa disponible en 2026 para auditar múltiples agentes. Soporta Claude Code, Cursor, Windsurf, Gemini CLI, OpenCode y Pi Agent mediante hooks en los archivos de configuración de cada agente. Para auditoría de seguridad más específica, Snitch es una alternativa con foco en detección de amenazas.
¿Cómo proteger archivos sensibles de agentes que pueden leer y ejecutar código?
El primer paso es restringir qué directorios puede leer el agente usando las configuraciones de permissions disponibles en cada herramienta (Claude Code tiene allowedDirectories en su configuración). El segundo paso es implementar un audit trail para detectar accesos no esperados. Para proyectos con credenciales sensibles, separar los secretos en archivos fuera del árbol del proyecto es la medida más efectiva.
¿Qué requiere la EU AI Act para auditar agentes de código?
La EU AI Act, vigente desde agosto 2026, exige para sistemas de IA de alto riesgo trazabilidad de las decisiones: quién (el agente), qué cambios realizó, cuándo y en qué sistema. Para equipos que desarrollan software para el mercado europeo, esto implica mantener registros de qué agentes modificaron qué código y en qué contexto. Los detalles específicos de implementación aún están siendo definidos por los organismos reguladores.
Conclusión
Gryph resuelve un problema que nadie estaba resolviendo: registrar qué hacen los agentes de IA en tu máquina, de forma local, sin depender del proveedor del agente y con suficiente granularidad para ser útil en debugging y compliance. El rastreo de agentes IA dejó de ser un tema teórico en 2026, con la EU AI Act generando presión regulatoria real y vulnerabilidades como el CVE-2025-59536 en producción.
Si usás Claude Code, Cursor o Gemini CLI en proyectos con información sensible, implementar alguna forma de audit trail es una práctica razonable ahora, no cuando lo exija el regulador. Gryph es la opción más accesible disponible hoy para hacerlo.