¿Prefieres HTTP sin procesar? Usa la API directamente con curl:```bash
curl -X POST http://localhost:8080/api/v1/execute/async/sec-af.audit \
  -H "Content-Type: application/json" \
  -d '{"input": {"repo_url": "https://github.com/dolevf/Damn-Vulnerable-GraphQL-Application"}}'

Cada hallazgo incluye un **veredicto** (`confirmed` / `likely` / `inconclusive` / `not_exploitable`), un **objeto de prueba** con el rastro de taint completo y la ubicación exacta del código. No es «esto podría ser un problema». SEC-AF rastrea los datos desde la fuente hasta el sumidero y demuestra si realmente es explotable.

> Salida completa del benchmark (30 hallazgos): [`exampl/dvga-benchmark-result.json`](https://github.com/agent-field/sec-af/blob/HEAD/exampl/dvga-benchmark-result.json) | Análisis de rendimiento: [`exampl/benchmark-analysis.json`](https://github.com/agent-field/sec-af/blob/HEAD/exampl/benchmark-analysis.json)

## Benchmark: DVGA

Ejecutamos SEC-AF contra [Damn Vulnerable GraphQL Application](https://github.com/dolevf/Damn-Vulnerable-GraphQL-Application), una aplicación deliberadamente vulnerable con 21 escenarios de seguridad documentados.

| Métrica | Valor |
|---|---|
| Hallazgos brutos descubiertos | 106 |
| Tras la deduplicación con IA | 61 |
| **Tras la verificación adversarial** | **28 confirmados** |
| No concluyente (requiere revisión manual) | 1 |
| No explotable (rechazado correctamente) | 1 |
| Reducción de ruido | 94% |
| Aristas del DAG (llamadas de reasoners) | 82 |
| Llamadas de agentes | ~166–255 |
| Estrategias ejecutadas | 11 |
| Tiempo real | ~78 min |
| Costo estimado (Kimi K2.5) | ~$0.18–$0.90 |

<details>
<summary><strong>Desglose: 30 hallazgos verificados por categoría</strong></summary>

| Categoría | Número | Ejemplos |
|---|---|---|
| Falta de autenticación | 8 | ImportPaste, delete_all_pastes, system_debug, CreateUser, subida de archivos |
| Inyección de comandos | 4 | `os.popen(cmd)` a través de ImportPaste, system_debug, system_diagnostics |
| Inyección SQL | 3 | `filter` sin sanitizar en `resolve_pastes`, inyección de patrón LIKE, login |
| Omisión de autenticación | 3 | Firma JWT deshabilitada, omisión de autorización JWT, autenticación de contraseña insegura |
| Credenciales en texto plano | 3 | Almacenamiento de contraseña en texto claro, comparación en texto plano, contraseña en diagnósticos |
| SSRF | 2 | La mutación ImportPaste sigue URLs proporcionadas por el usuario en el servidor |
| Lógica de negocio / Sanitización de URL | 2 | Sanitización de URL inadecuada, eliminación masiva no autenticada |
| DoS / Agotamiento de recursos | 3 | Falta de paginación en consultas de users/audits, simulate_load sin control |
| Configuración / Secretos | 2 | Secretos JWT/Flask codificados, modo debug habilitado en producción |

</details>

<details>
<summary><strong>Patrones de diseño: cómo funciona el análisis de seguridad nativo de IA</strong></summary>

SEC-AF aplica varios patrones arquitectónicos que se habilitan de manera única al componer muchos agentes de IA especializados en lugar de ejecutar un escaneo monolítico. Estos patrones abordan desafíos fundamentales en el análisis de seguridad impulsado por IA.

**1. Tensión adversarial entre agentes (HUNT vs. PROVE)**

La mayoría de las herramientas de seguridad con IA le piden a un solo modelo «¿es esto vulnerable?» y aceptan la respuesta. SEC-AF separa estructuralmente los agentes de _hallazgo_ de los agentes de _refutación_. Los cazadores tienen incentivos para encontrar vulnerabilidades; los verificadores tienen incentivos para refutarlas. Cada hallazgo pasa por una cadena de verificación de 4 agentes: un rastreador reconstruye el flujo de datos, un analizador de sanitización busca mitigaciones que el cazador podría haber pasado por alto, un hipotetizador de exploits construye un escenario de ataque concreto y un agente de veredicto sopesa toda la evidencia contradictoria. Esta tensión adversarial entre agentes es lo que impulsa la reducción de ruido del 94%: la arquitectura misma codifica el escepticismo.

**2. Cascada de señales con estrechamiento progresivo**

En lugar de arrojar todos los hallazgos al usuario, el pipeline comprime la señal en cada etapa: 106 hallazgos brutos → 61 tras la deduplicación con IA → 30 tras la verificación adversarial. Cada fase es un filtro. Esto refleja cómo los equipos de seguridad humanos clasifican — primero un descubrimiento amplio, luego un escrutinio progresivamente más estricto. La idea clave es que cada filtro es un _tipo diferente_ de razonamiento de IA: similitud semántica para la deduplicación, análisis de taint para la verificación, construcción de exploits para la confirmación.

**3. Economía de la información mediante poda de contexto**

Los LLM alucinan más cuando reciben contexto irrelevante. SEC-AF enruta solo la información que cada agente necesita: un cazador de inyecciones recibe el contexto de reconocimiento podado para incluir mapas de flujo de datos y puntos de entrada, mientras que un cazador de criptografía recibe árboles de dependencias y patrones de gestión de claves. Los verificadores reciben vistas proyectadas de los hallazgos con solo los campos necesarios para su método de verificación específico. Esta poda de contexto por estrategia reduce tanto la alucinación como el costo: los agentes no pueden confundirse con información que nunca ven.

**4. Superposición de fases mediante streaming**

Los pipelines tradicionales se ejecutan de forma secuencial: terminan el reconocimiento, luego comienzan a cazar y luego comienzan a verificar. SEC-AF superpone las fases mediante `asyncio.Queue`: los cazadores comienzan a consumir la salida del reconocimiento a medida que llega, y la deduplicación procesa los hallazgos a medida que cada cazador completa. Los verificadores comienzan a verificar los primeros hallazgos deduplicados mientras los cazadores posteriores aún están en ejecución. Esta arquitectura de streaming reduce el tiempo real sin sacrificar la cascada de señales: cada hallazgo sigue pasando por todos los filtros, solo que antes.

**5. Enrutamiento dinámico mediante puertas de IA**

El pipeline se adapta en tiempo de ejecución según lo que descubre. Una puerta de IA examina la salida del reconocimiento y selecciona qué estrategias de caza activar: una aplicación Flask con autenticación JWT activa cazadores distintos a los de un microservicio Go con gRPC. Una puerta de expansión CWE separada amplía dinámicamente la lista de vulnerabilidades objetivo según la pila tecnológica detectada. Una puerta de alcanzabilidad evalúa si las vulnerabilidades de dependencias tienen rutas de llamada explotables antes de desperdiciar recursos de verificación en código inalcanzable.

**6. Autonomía guiada para agentes de codificación**

SEC-AF se ejecuta sobre agentes de codificación (Claude Code, OpenCode, Codex) mediante el harness de AgentField. En lugar de darle al agente un único prompt masivo, cada reasoner proporciona autonomía guiada por fases: el agente recibe una definición de tarea estrecha, un esquema de salida plano (2-4 campos) y contexto específico de la estrategia. El agente tiene autonomía total dentro de estos límites — puede leer archivos, rastrear código y razonar libremente — pero el harness restringe la _forma_ de su salida. Esto evita el modo de fallo común en el que los agentes autónomos se desvían de la tarea o producen resultados no estructurados.

**7. DAG de reasoners componible con observabilidad completa**

Cada llamada de agente fluye a través del plano de control de AgentField, creando un grafo acíclico dirigido completo de la auditoría. Puedes ver qué cazador encontró qué hallazgo, cuánto tardó cada verificación, qué evidencia generó el verificador y dónde invirtió su tiempo el pipeline. Añadir una nueva clase de vulnerabilidad es un archivo — un nuevo cazador. El orquestador lo descubre, le enruta contexto e integra sus hallazgos en el pipeline existente de dedup → prove → remediación. El DAG es la arquitectura.

</details>

<details>
<summary><strong>Lo que no detectó (y por qué)</strong></summary>

Los 9 escenarios no detectados son principalmente **ataques a nivel de protocolo GraphQL**: consultas por lotes, recursión profunda, abuso de alias, duplicación de campos, exposición de introspección. Estos requieren análisis en tiempo de ejecución/DAST. SEC-AF se centra actualmente en SAST. La detección a nivel de protocolo está en la hoja de ruta.

</details>

## Cómo Funciona

SEC-AF se basa en la filosofía de [Composite Intelligence](https://github.com/Agent-Field/agentfield): en lugar de depender de una sola llamada monolítica al LLM, compone muchas llamadas guiadas y enfocadas al LLM en un **DAG de reasoners** donde la arquitectura misma codifica la inteligencia (para una inmersión más profunda en este patrón, consulta [The Atomic Unit of Intelligence](https://www.santoshkumarradha.com/writing/atomic-unit-of-intelligence)). Cada llamada al LLM maneja una tarea pequeña y bien definida con un esquema Pydantic plano (2-4 atributos). El orquestador gestiona el flujo de contexto, el paralelismo y el enrutamiento dinámico.

### Arquitectura: Grafo de llamadas de reasoners (DAG)

Cada fase es un `@reasoner` que invoca sub-reasoners a través del plano de control de AgentField, sumando alrededor de ~200-300 agentes trabajando sincrónicamente para una consulta determinada:

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7491/d3e99c5c9b7067b17005f71ecb0f7c7abeb9d7fc8843d33938de9f755f416b7b.png" alt="SEC-AF Signal Cascade Pipeline — RECON → HUNT → DEDUP → PROVE → OUTPUT" width="100%" />
</p>

### Pipeline de cascada de señales

Cada fase estrecha la señal. Los hallazgos brutos se filtran a través de puertas progresivamente más estrictas:

| Fase | Propósito | Paralelismo |
|---|---|---|
| **RECON** | Mapear la arquitectura, dependencias, flujos de datos y contexto de seguridad | Paralelismo de 3 vías (arquitectura + dependencias + configuración), luego de 2 vías (flujo de datos + seguridad) |
| **HUNT** | Ejecutar 10+ cazadores de estrategia especializados | Paralelismo limitado por semáforo (4 concurrentes por defecto) con dedup incremental |
| **PROVE** | Verificación adversarial: intentar **refutar** cada hallazgo | Paralelismo limitado por semáforo (3 concurrentes por defecto) |
| **REMEDIATION** | Generar sugerencias de corrección para hallazgos confirmados/probables | Paralelismo limitado por semáforo (3 concurrentes por defecto) |

### Por qué la arquitectura multi-reasoner

La mayoría de las herramientas de seguridad con IA ejecutan un único prompt grande y esperan que el LLM lo haga bien. SEC-AF descompone el problema en ~258 llamadas de agentes enfocadas, cada una con un esquema plano (2-4 campos) y una tarea estrecha. La arquitectura codifica la estrategia de razonamiento, no el prompt (consulta [The Atomic Unit of Intelligence](https://www.santoshkumarradha.com/writing/atomic-unit-of-intelligence) para saber por qué esto importa).

- **Muchos agentes enfocados > un agente poderoso.** Una sola llamada al LLM no puede mapear simultáneamente la arquitectura, rastrear flujos de datos, cazar inyecciones, verificar la explotabilidad y sugerir correcciones. SEC-AF asigna cada una de esas tareas a un reasoner separado que hace bien una sola cosa. El orquestador maneja la composición, el paralelismo y el enrutamiento de contexto.
- **Verificación adversarial, no sesgo de confirmación.** La fase PROVE ejecuta 4 subagentes por hallazgo con objetivos opuestos: el rastreador reconstruye el flujo de datos, el analizador de sanitización busca bloqueos, el hipotetizador de exploits construye un ataque y el agente de veredicto sopesa toda la evidencia. Esta tensión entre agentes produce mayor confianza que preguntarle a un solo modelo «¿es esto explotable?»
- **Enrutamiento dinámico mediante puertas de IA.** El sistema se adapta en tiempo de ejecución. Una puerta de IA examina la salida del reconocimiento y selecciona qué estrategias de caza activar. Una puerta separada expande la lista de objetivos CWE según la pila detectada. Una aplicación Flask con autenticación JWT recibe cazadores distintos a los de un microservicio Go con gRPC.
- **Estrechamiento progresivo de la señal.** 106 hallazgos brutos se convierten en 61 tras la dedup, y luego en 30 tras la verificación adversarial — una reducción de ruido del 94%. Cada fase es un filtro. El pipeline comprime el ruido; no se limita a detectar vulnerabilidades y volcarlas.
- **Economía de la información.** Cada agente ve solo lo que necesita. Los cazadores reciben contexto de reconocimiento podado para su estrategia. Los verificadores reciben vistas proyectadas de hallazgos con campos mínimos. Esto reduce la alucinación, reduce el costo y mantiene cada llamada al LLM enfocada.
- **Streaming incremental.** La dedup se ejecuta como consumidor mientras los cazadores aún están produciendo. Los hallazgos se deduplican por huella digital a medida que cada cazador completa, y luego una pasada semántica final detecta duplicados entre estrategias. El pipeline transmite en streaming; no procesa por lotes.

## Comparación

> Afirmaciones tomadas de documentación oficial y páginas de precios. Si algo está mal, [abre un issue](https://github.com/Agent-Field/sec-af/issues).

| | SEC-AF | Nullify | Snyk Code | Semgrep | CodeQL |
|---|---|---|---|---|---|
| **Enfoque** | **Nativo de IA** | **Nativo de IA** | **Asistido por IA** | **Basado en reglas** | **Basado en reglas** |
| | DAG multi-reasoner · el LLM razona sobre el código | Fuerza de trabajo de seguridad autónoma | Motor de IA DeepCode | Coincidencia de patrones + taint | Análisis semántico + flujo de datos |
| **Código abierto** | ✅ Apache 2.0 | ❌ Propietario | ❌ Propietario | Motor: LGPL-2.1 · Reglas Pro: propietarias | Consultas: MIT · Motor: propietario |
| **Hallazgos verificados** | ✅ Fase PROVE adversarial · veredicto + prueba por hallazgo | ✅ Generación de prueba de exploit | ❌ Priority Score (opaco) · sin prueba de exploit | ❌ Solo coincidencias de patrones | ❌ Alertas de análisis estático |
| **Evidencia por hallazgo** | Rastro de flujo de datos con propagación de taint | Ruta de exploit + pasos de reproducción | Flujo de origen a sumidero mostrado | - | Las consultas de ruta muestran el flujo de datos |
| **Arquitectura** | DAG de reasoners componible con observabilidad completa | Agente monolítico | Motor de una sola pasada | Motor de reglas | Motor de consultas |
| **Paralelismo** | ✅ Cazadores, verificadores y remediadores en paralelo con dedup incremental | No documentado | No documentado | ✅ Paralelismo de reglas | ✅ Paralelismo de consultas |
| **Puntuación** | ✅ Fórmula compuesta publicada | Interna | Priority Score opaca | Interna | - |
| **SARIF** | ✅ Nativo 2.1.0 | No documentado | ✅ | ✅ | ✅ Nativo |
| **Mapeo de cumplimiento** | PCI-DSS, SOC2, OWASP, HIPAA, ISO27001 | No documentado | Solo cumplimiento de plataforma | Reglas OWASP disponibles | - |
| **Lenguajes** | Cualquier lenguaje compatible con LLM | No documentado | 14+ | 35+ (basado en analizadores sintácticos) | 10 |
| **Precios** | **Gratis · código abierto** (~$0.18–$0.90/auditoría en costos de LLM) | **$6,000/mes** | $25-105/mes/desarrollador | Motor OSS: uso gratuito · Pro: $30/mes por contribuidor | Gratis para repos públicos · $49/mes por committer (GHAS) |

**Donde SEC-AF es más fuerte**: Hallazgos verificados con objetos de prueba, puntuación transparente, mapeo de cumplimiento, arquitectura multiagente componible con observabilidad completa del DAG y totalmente código abierto.

**Dónde otros son más fuertes**: Semgrep y CodeQL tienen años de cobertura de reglas probadas en batalla en más de 35 lenguajes. Snyk tiene una integración profunda IDE/SCA. Nullify añade contexto de nube en tiempo de ejecución y campañas de remediación automática. SEC-AF es más nuevo y actualmente es más fuerte en el análisis de código a nivel de código impulsado por IA.

> **La misma arquitectura, diferente dominio:** [Contract-AF](https://github.com/Agent-Field/contract-af) aplica el HUNT→PROVE adversarial a contratos legales — los agentes crean agentes para encontrar interacciones entre cláusulas que los LLM solos pasan por alto.

### Por qué importa la arquitectura multiagente

Los escáneres de seguridad tradicionales son monolíticos: un motor, una pasada, un conjunto de reglas. La arquitectura multi-reasoner de SEC-AF ofrece ventajas estructurales:

- **Especialización**: Cada cazador es un especialista LLM guiado — un cazador de inyecciones razona de manera diferente a un cazador de criptografía. La arquitectura codifica el conocimiento del dominio en el enrutamiento, no solo en los prompts.
- **Componibilidad**: Añade una nueva clase de vulnerabilidad añadiendo un archivo de cazador. El orquestador lo descubre y lo ejecuta automáticamente. Sin cambios en el pipeline.
- **Verificación adversarial**: La fase PROVE está estructuralmente separada de HUNT. Los cazadores intentan encontrar vulnerabilidades; los verificadores intentan refutarlas. Esta tensión adversarial reduce los falsos positivos.
- **Observabilidad**: Cada llamada de reasoner fluye a través del plano de control, creando un DAG completo. Puedes ver exactamente qué cazador encontró qué hallazgo, cuánto tardó cada fase y qué razonó el LLM en cada paso.
- **Eficiencia de costos**: La poda de contexto y las vistas de esquema hacen que cada llamada al LLM reciba solo el contexto que necesita. Una auditoría completa de profundidad estándar con 30 hallazgos verificados cuesta un estimado de ~$0.18–$0.90 en llamadas al LLM (Kimi K2.5 a través de OpenRouter).

## Inicio Rápido

### Instalar en AgentField (`af install`)

¿Ya tienes un plano de control de [AgentField](https://github.com/Agent-Field/agentfield) en funcionamiento? Instala SEC-AF directamente desde GitHub — sin clonar, sin configuración local:```bash
af install https://github.com/Agent-Field/sec-af
af run sec-af

¿Nuevo en AgentField? Instala primero el plano de control con `curl -fsSL https://agentfield.ai/install.sh | bash`, o usa las opciones de Docker / Railway a continuación.

### Despliegue en un clic (Railway)

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/sec-af)

Despliega el plano de control de AgentField + el agente SEC-AF. Necesitarás una `OPENROUTER_API_KEY`.

### Local (Docker Compose)```bash
git clone https://github.com/Agent-Field/sec-af.git && cd sec-af
cp .env.example .env          # Add OPENROUTER_API_KEY
docker compose up --build

Consultar resultados:```bash
curl http://localhost:8080/api/v1/executions/<execution_id>

**Paso 2 — Crear y activar un entorno virtual**```bash
python3 -m venv .venv
source .venv/bin/activate

**Paso 4 — Configura las variables de entorno**```bash
cp .env.example .env

Opcional — establece un directorio de workspace personalizado para evitar problemas de permisos:```
SEC_AF_WORKSPACES_DIR=~/.sec-af/workspaces

Esto se ejecuta en `http://localhost:8080` por defecto.

**Paso 6 — Inicia el agente SEC-AF** (en otra terminal, con el venv activo)```bash
python3 main.py

## API

<details>
<summary><strong>Opciones completas de solicitud</strong></summary>```bash
curl -X POST http://localhost:8080/api/v1/execute/async/sec-af.audit \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "repo_url": "https://github.com/org/repo",
      "branch": "main",
      "depth": "thorough",
      "severity_threshold": "high",
      "scan_types": ["sast", "sca", "secrets", "config"],
      "output_formats": ["sarif", "json", "markdown"],
      "compliance_frameworks": ["pci-dss", "soc2", "owasp", "hipaa"],
      "max_cost_usd": 15.0,
      "max_provers": 30,
      "max_duration_seconds": 1800,
      "include_paths": ["src/"],
      "exclude_paths": ["tests/", "vendor/"]
    }
  }'