swarm-audit

Auditoría en enjambre (Swarm Audit)

Inventario → dividir en secciones → un árbol de trabajo y un agente de auditoría por sección → cada agente reporta hallazgos validados al orquestador → auditoría de encadenamiento sobre todos los hallazgos → un informe combinado. El orquestador es el árbol de trabajo desde el que comienzas. Muestra al usuario cada artefacto antes de continuar; ellos deciden el alcance y la agrupación.

0. Verificación previa (Preflight)

Antes de hacer cualquier otra cosa, resuelve tres aspectos. Pregunta cada uno de los aspectos abiertos en una sola llamada AskUserQuestion (directamente si no hay herramienta de pregunta), luego detente hasta que el usuario responda.

Modelo de amenazas. Busca **/THREAT_MODEL.md, omitiendo los directorios de dependencias instaladas y proveídas. Si existe uno sin marcadores de posición <…> de plantilla, úsalo. De lo contrario, pregunta, a menos que el usuario ya haya solicitado una ejecución rápida:

• Construir un modelo de amenazas primero (Recomendado): cada auditor de sección y crítico usará sus controles y la lista de fuera de alcance, lo que reduce los falsos positivos en todo el enjambre y revela errores de lógica de negocio. Cuesta algunas rondas de preguntas al principio; las auditorías posteriores lo reutilizan.
• Ejecución rápida sin uno: sin preguntas y sin modelo de amenazas; los auditores de sección trabajan a partir del inventario y del código únicamente. Es la forma más rápida de ver qué encuentra el enjambre; espera más ruido.

En Construir, ejecuta la habilidad security-audit incluida en este plugin a través de la herramienta Skill en el orquestador, solicitando solo un modelo de amenazas, y espera el archivo THREAT_MODEL.md antes del paso 1.

Estrategia de división. Si los argumentos contienen --by-group [N] o --by-theme, úsala. De lo contrario, pregunta:

• Por tema (Recomendado): las secciones siguen lo que hace el código (autenticación, cuenta, pagos, pedidos, administración, uno por cada integración de terceros). Cada auditor ve un flujo completo, por lo que se encuentran errores que abarcan varios puntos de entrada. Los tamaños varían.
• Por grupo: grupos de tamaño fijo de aproximadamente N puntos de entrada (pregunta N, por defecto 25) en orden de origen. Carga de trabajo uniforme por auditor, sin decisiones subjetivas, pero un flujo puede dividirse entre dos secciones; la auditoría de encadenamiento (paso 6) recupera parte de eso.

Alcance. Si el usuario no ha nombrado ninguno, pregunta qué servicios, directorios o tipos de puntos de entrada cubrir, y qué excluir.

1. Inventariar los puntos de entrada

Un punto de entrada es cualquier lugar donde la entrada externa llega al código: rutas HTTP, manejadores GraphQL/RPC, webhooks, consumidores de colas y eventos, trabajos programados que leen datos externos, comandos CLI, procesadores de archivos o subidas, manejadores de mensajes del lado del cliente, enlaces profundos o IPC.

• Encuéntralos con un analizador para el lenguaje del repositorio (su compilador o API de servidor de lenguaje, o tree-sitter), no con expresiones regulares: los registros abarcan líneas y usan arrays. Mantén el script en el bloc de notas (scratchpad) para que pueda re-ejecutarse.
• Por punto de entrada registra: tipo, nombre o método + ruta, quién puede alcanzarlo (público, usuario registrado, administrador, interno, webhook firmado), guardas (autenticación, MFA, captcha, límite de velocidad, esquema de entrada, verificación de firma), manejador, toda la cadena de middleware, decorador, filtro o interceptor, archivo:línea.
• Fáciles de pasar por alto:
  • Enrutadores anidados, controladores o grupos de manejadores registrados bajo un prefijo, y funciones auxiliares que se registran en un objeto pasado
  • Manejadores registrados globalmente dentro de una función auxiliar: sin prefijo
  • Middleware, filtros o guardas heredados de un registro anterior a nivel de prefijo o de captura general
  • Un grupo de manejadores registrado dos veces: listar una vez, anotar el alias
  • Puntos de entrada solo para ciertos entornos (staging, depuración, características bajo bandera): márcalos
  • Puntos de entrada que registra una dependencia (servidores de autenticación, paneles de administración, comprobaciones de salud, tableros de trabajos): lee el código fuente del paquete, agrégalos manualmente
• Encuentra lo que falta: examina el código cliente (aplicación web, aplicación móvil, proxy, otros servicios) en busca de cada ruta o mensaje que envía, y lista todo lo registrado en el nivel superior. Pregunta al usuario cuáles agregar; di cuáles omitiste y por qué.
• Escribe el inventario en entry-points.md (o el nombre que el usuario dé) en el árbol de trabajo del orquestador.

2. Dividir en secciones

• Por tema: agrupa por lo que hace el código, no por tamaño, y nunca mezcles dos límites de confianza (público, socio, interno, trabajador) en una misma sección. Divide un tema que sea demasiado grande para un solo auditor.
• Por grupo: corta el inventario en orden en grupos de aproximadamente N; mantén los puntos de entrada de un mismo archivo juntos cuando eso cambie un grupo solo por unos pocos.
• Muestra la división propuesta (nombre, recuento, una línea de contenido, decisiones subjetivas) y espera la aprobación antes de escribirla en el archivo de inventario.

3. Un árbol de trabajo por sección

Crea el árbol de trabajo de cada sección a partir del commit actual del orquestador, para que cada sección audite el código en el que está el usuario. Usa mori cuando command -v mori lo encuentre, de lo contrario, usa git simple:

	mori	git
Crear	mori new sec-audit-NN-<nombre> --from <rama actual>; imprime la ruta del árbol de trabajo (bajo ~/.mori/worktrees/<repo>/) — regístrala	git worktree add ../<repo>-sec-audit-NN-<nombre> -b sec-audit-NN-<nombre>
Dependencias	instaladas por los pasos post_create del archivo .mori.json del repositorio si los tiene; de lo contrario, instálalas tú mismo	instálalas tú mismo
Eliminar	verifica dirty en mori list --json, luego mori remove <rama> -f; elimina la rama si permanece	verifica git status en él, luego git worktree remove <dir> y git branch -D <rama>

En un HEAD separado, usa git (git worktree add <dir> -b <rama> HEAD). Crea los árboles de trabajo en segundo plano.

• Copia en cada uno: AUDIT_SCOPE.md (la tabla de la sección, las notas de columna, "auditar solo estos puntos de entrada"), el inventario completo y, si el modelo de amenazas se ha construido pero aún no está confirmado, una copia del mismo en la misma ruta.
• Crea la bandeja de entrada en el orquestador: <orquestador>/.security-audit/swarm/<seccion>/.
• Para rehacer la división: elimina los árboles de trabajo antiguos y sus ramas como se indicó anteriormente (nunca fuerces la eliminación de uno con cambios que no hayas revisado), luego vuelve a crearlos.

4. Ejecutar las auditorías de sección en paralelo

Escribe un resumen en el bloc de notas y lanza un agente en segundo plano por sección apuntando a él. El resumen debe decir:

• Trabaja solo en WORKTREE; lee las instrucciones de su agente (CLAUDE.md, AGENTS.md). Las únicas escrituras fuera de WORKTREE van a INBOX (ruta absoluta a la bandeja de entrada de la sección en el orquestador).
• Usa la habilidad security-audit incluida en este plugin (u otra que el usuario nombre), a través de la herramienta Skill, con ámbito en @AUDIT_SCOPE.md; en una ejecución rápida, indícale que es una ejecución rápida para que nunca se detenga a preguntar. Sin una: traza cada entrada desde el punto de entrada hasta el sumidero con archivo:línea, demuestra que es alcanzable más allá de cada control, descarta cualquier cosa que no sea alcanzable.
• Con un modelo de amenazas: léelo completo antes de trazar; usa sus puntos de entrada, controles y lista de fuera de alcance; nunca lo reescribas. Ejecución rápida: sin modelo de amenazas, no crees uno. Nunca hagas preguntas.
• Cada candidato va a un subagente crítico nuevo que asume que es un falso positivo; si no se puede lanzar uno, haz una autocrítica y dilo por hallazgo.
• Crítico/Alto: una prueba fallida a través del punto de entrada real, ejecutada con el ejecutor de pruebas del repositorio, dejada en el árbol.
• Reporta cada hallazgo a INBOX tan pronto como su crítico regrese, un archivo por hallazgo (NN-slug.md), para que no se pierda nada si la salida del agente se corta. Formato a continuación.
• También reporta candidatos bloqueados: un flujo que alcanza un sumidero pero necesita algo que la sección no puede proporcionar (un id, un token, una acción de la víctima, un valor filtrado, una condición de carrera). Usa status: blocked y nombra exactamente qué falta; otra sección puede proporcionarlo.
• También escribe el informe de la sección en WORKTREE/.security-audit/<seccion>-<fecha>.md.
• Reglas estrictas: sigue las reglas de seguridad del repositorio; sin migraciones ni scripts de base de datos, sin escrituras en git, sin llamadas a servicios externos.
• Mensaje final: línea de veredicto, una línea por hallazgo, cuántos archivos fueron a INBOX, elementos no verificados y cómo se invocó la habilidad de auditoría.

Formato del archivo de hallazgo:

---
id: <seccion>-NN
status: validated | blocked
severity: critical | high | medium | low | info
critic: independent | self
entry_point: <método + ruta o nombre del manejador>
needs: <lo que el atacante debe tener antes: tipo de cuenta, id, token, clic de la víctima, sincronización>
gives: <lo que el atacante tiene después: valor filtrado, acceso de escritura, sesión, dinero, ejecución de código>
test: <ruta o none>
---
Afirmación en una línea.

Traza: fuente `archivo:línea` → … → sumidero `archivo:línea`.
Repro: entrada exacta (solicitud, mensaje, archivo) en un bloque de código.
Controles verificados: qué se revisó y por qué no detiene esto.

needs y gives son lo que la auditoría de encadenamiento une: escríbelos de forma concreta ("un id de pedido de la víctima", no "algunos datos").

Puedes auditar una sección tú mismo directamente. Espera que el límite de subagentes concurrentes bloquee algunos críticos.

5. Revisar antes de encadenar

Cuando cada agente de sección haya terminado, lee la bandeja de entrada y compara los recuentos de archivos con el mensaje final de cada agente. Luego ejecuta un nuevo crítico tú mismo sobre:

• cualquier Alto o Crítico con critic: self
• cualquier hallazgo marcado como provisional, condicional o "depende de ": lee el código de ese servicio si lo tienes y resuelve la cuestión. Los errores en el límite entre dos servicios son los que cada sección pasa por alto por separado.

Actualiza el archivo de hallazgo con la severidad del crítico y conserva el original en una línea was:.

6. Auditoría de encadenamiento

Una última auditoría en el orquestador sobre toda la bandeja de entrada, con el inventario y el modelo de amenazas (si lo hay) a mano. Ejecútala directamente o como un agente con la bandeja de entrada completa en su resumen.

1. Deduplicar. Fusiona hallazgos con la misma causa raíz (mismo sumidero y mismo control faltante) en uno solo, listando cada sección y punto de entrada que lo alcanza. Dos puntos de entrada en un solo error son un hallazgo con un radio de explosión más amplio, no dos hallazgos.
2. Unir. Para cada par, verifica si los gives de un hallazgo satisfacen los needs de otro, incluidos los candidatos blocked. También busca las escaladas habituales:
   • fuga de información (id, email, token, URL interna) → IDOR, toma de cuenta o SSRF que lo necesitaba
   • enumeración de usuarios + límite de velocidad faltante → relleno de credenciales o fuerza bruta de OTP
   • self-XSS o inyección HTML + CSRF o CSRF de inicio de sesión → XSS almacenado en una víctima
   • redirección abierta + flujo de OAuth o enlace mágico → robo de token
   • asignación masiva o validación débil + un consumidor privilegiado aguas abajo (trabajador, vista de administración, webhook)
   • condición de carrera + saldo, cupón, límite o acción única → ganancia repetida
   • dos brechas de lógica de negocio de bajo impacto que juntas mueven dinero o evitan un límite
3. Probar cada cadena. Trazarla de extremo a extremo con archivo:línea en cada enlace y la entrada exacta en cada paso. Un enlace que no está en el código no es una cadena: no inventes uno y no cuentes un enlace que necesite una condición previa que ningún hallazgo o acción pública proporcione.
4. Criticar cada cadena con un nuevo subagente, en paralelo. Asume que los pasos no se conectan en la práctica (diferentes usuarios, diferentes sesiones, tokens caducados, orden, un paso ya corregido por otro control) y devuelve la severidad de la cadena: impacto de la ganancia final × probabilidad de todos los pasos juntos, o "descartada".
5. Probar cada cadena Crítica o Alta con una prueba fallida que impulse cada paso a través de los puntos de entrada reales, en el árbol de trabajo del orquestador.
6. Escribir cada cadena en <orquestador>/.security-audit/swarm/cadenas/NN-slug.md en el formato de hallazgo, con links: listando los ids de los hallazgos. Conserva también los hallazgos componentes.

7. Informe combinado

Escribe .security-audit/<alcance>-combinado-<fecha>.md en el orquestador:

1. Línea de veredicto con recuentos después de la deduplicación, las cadenas contadas por separado ("3 cadenas, 2 elevan la severidad"). En una ejecución rápida, comienza con la línea de ejecución rápida del archivo references/REPORT_FORMAT.md de la habilidad security-audit.
2. Cadenas primero: los pasos como lista numerada con entrada y archivo:línea, ganancia final, severidad antes y después del encadenamiento, crítico, ruta de prueba. Di qué arreglo único rompe cada cadena.
3. Informes de Crítico/Alto: reproducción con la entrada exacta, traza con archivo:línea, ganancia y requisitos previos, arreglo, crítico, ruta de prueba y qué no demuestra la prueba.
4. Tabla de Medio, lista de Bajo (colapsada), candidatos bloqueados que nada desbloqueó (colapsados: son pistas, no hallazgos).
5. Patrones entre secciones.
6. Brechas de cobertura y elementos no verificados (agentes cortados, discrepancias en el recuento de bandeja de entrada, configuración de producción, comportamiento de terceros, críticos auto-revisados).
7. Tabla de secciones con la ruta del informe en cada árbol de trabajo.

No se confirma nada. Encabeza el resumen del chat con las cadenas y la tabla de Crítico/Alto, y di qué arreglo enviar primero: prefiere el que rompe la mayor cantidad de cadenas.