Modelo de auditoría
La capa de auditoría: qué se revisa, qué se registra, el modelo de severidad, los hallazgos típicos y la infraestructura de runtime.
Propósito
La capa de auditoría es la revisión sistemática del lab de su propio estado. Las auditorías responden cuatro preguntas:
- ¿Qué se revisó?
- ¿Qué funciona?
- ¿Qué falla?
- ¿Qué está degradado?
- ¿Qué acciones son prioritarias?
La salida de una auditoría es un report. Los reports se almacenan en {workspace-root}/security/audits/ y los referencian el Catálogo de fallos y el Roadmap.
La capa de auditoría también incluye infraestructura de auditoría en runtime — los mecanismos que registran cada evento relevante según ocurre, para que los audit reports se puedan construir a partir de datos reales en lugar de memoria. Los dos mecanismos de runtime son el request journal y el token pool state, ambos mantenidos por el research framework. Se documentan aquí porque son parte de la historia de auditoría del lab, no parte de los internals del research framework.
Cadencia de auditoría
| Cadencia | Scope | Ubicación del report |
|---|---|---|
| Semanal | Estado de gateways, sessions, misiones en curso | audits/YYYY-MM-DD-weekly.md |
| Mensual | Todos los componentes, security boundary, threat model | audits/YYYY-MM-DD-monthly.md |
| Trimestral | Revisión externa del modelo de seguridad | audits/YYYY-MM-DD-quarterly.md |
| Ad-hoc | Post-incident review | audits/YYYY-MM-DD-incident-{name}.md |
La auditoría semanal es el mínimo del operator. La auditoría mensual es la revisión comprehensiva. La auditoría trimestral la realiza un revisor externo (cuando está disponible). La auditoría ad-hoc se dispara por un incidente.
Estructura del audit report
Cada audit report tiene la siguiente estructura:
Modelo de severidad
| Severidad | Significado | Tiempo de respuesta |
|---|---|---|
| Critical | Bloquea funcionalidad o crea exposición insegura de datos. | Inmediato |
| High | Rompe un flow importante o impide la verificación. | Dentro de 24h |
| Medium | Degrada calidad, cobertura o reliability. | Dentro de 1 semana |
| Low | Mejora pendiente, cleanup o documentación. | Próximo sprint |
La severidad la asigna el auditor. El tiempo de respuesta es el tiempo máximo para empezar a trabajar en la resolución; el tiempo real hasta la resolución depende del trabajo requerido.
Hallazgos típicos
La auditoría surface regularmente los siguientes tipos de hallazgos:
- Dependencias externas no disponibles. Un servicio del que depende el lab está caído o rate-limited.
- Paquetes faltantes. Un paquete Python o módulo Node falta del entorno.
- Fuentes web inaccesibles. Una fuente web está detrás de un paywall o ha cambiado su estructura.
- Flujos parcialmente funcionales. Un flow que funcionaba en la última auditoría ahora funciona parcialmente.
- Permisos de ficheros que deberían endurecerse. Un fichero o directorio es legible o escribible por un grupo más amplio del necesario.
- Mocks aún presentes donde se esperan datos reales. Un test o integración está usando mock data en lugar de datos reales.
- Diferencias entre el estado documentado y el estado real. La documentación describe el sistema de forma distinta a como funciona realmente.
- Entradas de memoria obsoletas. Una entrada en
MEMORY.mdque ya no es precisa. - Entradas del tool registry obsoletas. Una entrada en
tools.jsonque apunta a una herramienta que ya no existe. - Documentación desactualizada. Una página que no se ha actualizado para reflejar un cambio reciente.
- Code paths no testeados. Un code path que no está cubierto por tests.
- Manejo de errores inconsistente. Distintas partes del código manejan el mismo error de forma distinta.
- Código no usado. Un módulo o función que ya no se usa.
- Naming inconsistente. Una convención de naming que no se sigue en todas partes.
Tracking de resolución
Los hallazgos se trackean desde la creación hasta la resolución. El status de un hallazgo transiciona como:
Un hallazgo es Resolved cuando la recomendación se ha implementado y verificado. Un hallazgo es Deferred cuando el trabajo se pospone a una fecha posterior; la razón se registra.
El status se actualiza en el audit report donde se creó el hallazgo por primera vez, y en el log consolidado de hallazgos en {workspace-root}/security/findings.jsonl.
Priorización de acciones
Al final de cada auditoría, el auditor produce una lista priorizada de acciones. La prioridad se basa en:
- Severidad (Critical primero).
- Esfuerzo (poco esfuerzo, alto impacto primero).
- Dependencias (desbloqueando otras acciones primero).
La lista de acciones es el input de la siguiente iteración del roadmap. El roadmap se actualiza para reflejar las acciones que se han priorizado para el siguiente periodo.
Auditor
El auditor es el operator. Las auditorías semanal y mensual las realiza el operator. La auditoría trimestral la realiza un revisor externo cuando está disponible; en ausencia de un revisor externo, el operator realiza una self-review con el reconocimiento explícito de que es una self-review.
El rol del auditor es hacer las preguntas que el operator podría no hacerse sobre su propio trabajo. La autoridad del auditor se limita a hacer recomendaciones; el operator decide qué recomendaciones implementar.
Runtime audit: request journal
El research framework escribe un journal append-only de cada llamada externa en {framework-root}/runtime/request_journal.jsonl. El journal es la base del audit trail de runtime del lab.
El journal está documentado en detalle en External Providers → Request Journal. El resumen, desde una perspectiva de auditoría:
- Un objeto JSON por línea.
- Una línea por request externa (search, transcript, Perplexity, etc.).
- Registra la mission, phase, adapter, action, request summary, response summary, result y cualquier error.
- El token usado se registra por name, nunca por value.
- El fichero se rota cuando excede el tamaño configurado (
SCOUTE_JOURNAL_MAX_BYTES, default50 MB).
El modelo de auditoría usa el journal para responder preguntas como:
- ¿Cuántas requests hizo la misión X al provider Y?
- ¿Qué tokens se agotaron durante la última semana?
- ¿Qué adaptador falló más en los últimos 30 días?
- ¿Cuál es el tiempo de respuesta medio por provider?
El journal se rota pero nunca se borra. Los ficheros rotados antiguos se conservan en {framework-root}/runtime/journal-archive/.
Runtime audit: token pool state
El token pool del research framework se configura en token_pool_config.json. El pool escribe su estado de runtime a {framework-root}/runtime/token_pool_state.json.
El estado de runtime registra por token:
- Total de requests.
- Total de errores.
- Último error (sanitizado).
- Timestamp de la última request exitosa.
- Status actual (
active,quota_exhausted,error).
El modelo de auditoría usa el estado del pool para responder:
- ¿Qué tokens están en uso actualmente?
- ¿Qué tokens están agotados y necesitan atención?
- ¿Hay tokens que llevan
errordemasiado tiempo?
El fichero de estado se regenera en cada request. No se rota. Es la vista live; el journal es la vista histórica.
Qué cubren los audit reports
Los audit reports combinan los datos de runtime (journal, pool state, mission states) con la revisión estática (ficheros de config, código, documentación) para producir los hallazgos.
Para cada auditoría:
- El auditor exporta los datos de runtime relevantes a un snapshot.
- El auditor revisa el snapshot, el código y la documentación.
- El auditor escribe el audit report.
- Los hallazgos se añaden al log consolidado.
- Las acciones se añaden a la siguiente iteración del roadmap.
Los datos de runtime son lo que hace las auditorías reproducibles: los mismos datos del journal + el mismo código = los mismos hallazgos (modulo la no-determinismo del provider del modelo).
Tooling de auditoría
El lab tiene un pequeño conjunto de herramientas de auditoría.
audit-collect.sh
Recolecta los datos de runtime a un snapshot.
La salida es un directorio bajo {workspace-root}/security/snapshots/YYYY-MM-DD/ con:
request_journal.jsonl(una copia del journal live).token_pool_state.json(una copia del estado live).mission_states.jsonl(un snapshot de los estados de misiones activas).config_snapshot.json(una copia de la configuración del framework).
audit-report.sh
Genera un audit report a partir de un snapshot.
La salida es un fichero markdown en {workspace-root}/security/audits/YYYY-MM-DD.md.
audit-review.sh
Revisa el audit report más reciente y lista los hallazgos abiertos.
La salida es una lista de hallazgos abiertos con su severidad, recomendación y status.
Ejemplos reales de auditorías
El lab ha realizado varias auditorías reales. Los reports están en:
security/audits/2026-05-11-full-hotel-cleanse.mdsecurity/audits/2026-05-11-scout-ecosystem.md
Estas son versiones sanitizadas de las auditorías reales. Los reports siguen la estructura de arriba y contienen hallazgos, resoluciones y acciones reales.
Los reports son los ejemplos más concretos del modelo de auditoría en acción. Merece la pena leerlos para entender cómo es una auditoría real.