Auditorías — detección de mejoras mediante agentes

Las auditorías son trabajos recurrentes que analizan tus registros de agente entre sesiones para encontrar aspectos susceptibles de mejora. Mientras que una alerta vigila una métrica concreta que ya conoces en tiempo casi real, una auditoría investiga: según el calendario que establezcas, ejecuta un pase de políticas determinístico sobre la ventana temporal y luego pone en marcha un agente de fiabilidad de IA sobre tus sesiones — el agente consulta los datos directamente, lee transcripciones sospechosas y (cuando resulta útil) ejecuta pequeños scripts de análisis, para después redactar recomendaciones de mejora respaldadas por evidencias concretas. Usa las auditorías para responder a la pregunta “¿qué debería corregir o mejorar en mis agentes?” — y las alertas para recibir una notificación en el momento en que se supere un umbral específico. Cada mejora enlaza a las sesiones y consultas exactas que la respaldan, y con un solo clic puedes crear una alerta preconfigurada para detectar recurrencias. La vista del panel es /<org-slug>/audits (barra lateral → analyze → audits), protegida por los permisos audits:read / audits:write.

---

​

Cómo funciona una ejecución

Cada ejecución tiene dos capas: una base determinística y una investigación mediante agentes.

​

1. El pase de políticas (determinístico)

Antes de que se ejecute ningún modelo, la auditoría realiza un pequeño catálogo de comprobaciones de políticas SQL sobre la ventana temporal: consultas de agregados acotados que marcan patrones problemáticos conocidos y reportan cuántos eventos / qué sesiones coincidieron — nunca el texto en sí que coincidió. El catálogo incluye:

• Filtración de secretos y credenciales en las cargas útiles de eventos — claves de acceso de AWS, claves API con prefijo sk-…, claves privadas PEM, tokens JWT / bearer, y asignaciones de credenciales con la forma KEY=….
• Marcadores de inyección de prompts — “ignore las instrucciones anteriores”, “revela tu prompt de sistema”, y similares.
• PII — números con formato de SSN (heurístico).
• Denegaciones de permisos de herramientas y bucles desbocados de llamadas a herramientas.

Los resultados de políticas se persisten como hallazgos (tipo policy) que siempre aparecen (nunca se eliminan por el límite por ejecución), y se entregan al agente de IA como pistas de partida. Como esta capa no necesita ningún modelo, una auditoría sigue produciendo sus señales de seguridad más importantes aunque el agente de IA no esté disponible.

​

2. La investigación mediante agentes (IA)

La auditoría ejecuta a continuación un agente de fiabilidad autónomo (el mismo servicio del Claude Agent SDK que impulsa el asistente del panel, con un prompt específico para auditorías). Dado el alcance de la auditoría (agentes × entornos seleccionados) y la ventana temporal, el agente:

• ejecuta consultas SQL de solo lectura contra tus tablas de análisis,
• lee un conjunto representativo de transcripciones de sesiones,
• opcionalmente escribe y ejecuta breves scripts de Python en un sandbox aislado dentro del pod (sin red, sin acceso al sistema de archivos, con secretos eliminados) para análisis que SQL no puede expresar — clustering de errores, cálculo de distribuciones, análisis de cargas útiles ya obtenidas,
• y registra cada mejora bien fundamentada que encuentra.

El agente trabaja a través de varias líneas de investigación — clustering de errores, deriva respecto a una línea base, fallos de objetivo en transcripciones, uso indebido de herramientas, compromisos calidad/coste y brechas de cobertura — según la sensibilidad de la auditoría (baja / media / alta). Cada mejora debe citar evidencias: los IDs de sesión que el agente inspeccionó realmente y/o el SQL que ejecutó. El servidor valida que las sesiones citadas existen y descarta cualquier mejora sin evidencias, por lo que el agente investiga pero nunca inventa. Cada mejora incluye:

• una recomendación (el cambio concreto que realizar — un ajuste de prompt, una corrección del esquema de una herramienta, una política de reintentos, una salvaguarda, mayor cobertura de evaluación),
• un impacto esperado y una estimación de esfuerzo (bajo / medio / alto),
• una magnitud — big (hay que avisar al operador), medium (pertenece al informe de la ejecución) o small (contexto del panel),
• una huella digital estable (derivada de la categoría del problema + su alcance, no de las sesiones de esta ejecución) para que el mismo problema se rastree ejecución tras ejecución aunque las evidencias cambien,
• y, cuando un vigilante determinístico sencillo podría detectar recurrencias, una alerta sugerida que puedes crear con un solo clic.

La capa de IA es opcional pero recomendada. Si no hay ningún agente de IA configurado para el pipeline de auditoría, las ejecuciones se llevan a cabo igualmente, persisten los hallazgos de políticas, e informan honestamente de que “el análisis no está disponible” para la capa de agentes en lugar de pasar silenciosamente.

​

Modos de fallo

Las mejoras se clasifican en el catálogo de modos de fallo duraderos de tu organización (o proponen un nuevo modo). Los modos dan a los patrones una identidad estable entre ejecuciones y permiten el seguimiento de recurrencias a largo plazo.

​

Ciclo de vida de triaje

En la página de un hallazgo (/audits/<id>/findings/<finding-id>): El ruido de baja señal se controla por auditoría con un límite de hallazgos por ejecución (top_k) sobre las mejoras del agente. Los hallazgos de políticas no están sujetos al límite (son relevantes para la seguridad y siempre se muestran). Todo lo que quede fuera del límite se contabiliza en las estadísticas de la ejecución — nada se descarta silenciosamente.

​

Programación

• Cadencia (schedule_interval_secs): de cada hora a semanal; la frecuencia predeterminada es diaria. Las auditorías son deliberadamente menos frecuentes que las alertas — una investigación mediante agentes analiza ventanas completas y se ejecuta durante minutos.
• Ventana: ya sea una retrospectiva fija (por ejemplo, “cada ejecución analiza los últimos 7 días”) o desde la última ejecución (el valor predeterminado) — cada ejecución continúa donde terminó la anterior exitosa, con una pequeña superposición para que nunca se pierdan eventos en los límites.
• La siguiente ejecución se programa un intervalo completo después de que la anterior se complete, de modo que una ejecución lenta nunca apila una segunda ejecución concurrente de la misma auditoría.
• Run now en la página de la auditoría la hace ejecutarse de inmediato.

​

Selección del modelo

Al crear una auditoría puedes elegir qué modelo usa la investigación, entre la lista de modelos que tu operador ha configurado para el servicio de agentes. Con un único modelo configurado, el selector lo muestra como subtítulo; con varios, puedes elegir. Si lo dejas sin configurar, se usa el predeterminado configurado.

​

Notificaciones

Cuando una ejecución detecta hallazgos nuevos, la auditoría notifica a los canales configurados de tu organización — los mismos canales y configuración de alerts.enabled_channels que usa el pipeline de alertas:

• Slack — un resumen de los nuevos elementos significativos (big) con un enlace directo.
• Email — un informe de auditoría diseñado con las nuevas mejoras (mayor severidad, recomendaciones por elemento, enlace directo), enviado cuando la auditoría tiene un canal de email asociado y hay al menos un nuevo hallazgo.

Los hallazgos recurrentes pero ya conocidos no generan nuevas notificaciones.

​

Referencia de configuración

Las definiciones de auditoría se gestionan en el panel (/audits/new) o a través de la API. Los ajustes por auditoría incluyen la cadencia y ventana de programación, el alcance ({"environments": [...], "agent_ids": [...]}), la sensibilidad (low / medium / high), los canales de notificación, el límite de hallazgos por ejecución (top_k) y el modelo (mediante llm_budget.model). La configuración del servidor a nivel de operador (tiempos de espera, sandbox, la URL del servicio de agentes) está documentada en deployment.md.

​

API

Todos los endpoints tienen ámbito de organización y siguen la autenticación estándar por clave bearer (consulta api-keys.md). Para los casos “la auditoría se ejecutó pero no encontró nada”, “el sandbox de código está deshabilitado” y “el email de auditoría no se entregó”, consulta troubleshooting.md.