Esto incorpora `seclab-taskflow-agent` y `seclab-taskflows` (padre)
de forma transitiva, por lo que cada referencia con puntos de la forma
`seclab_taskflows.taskflows.audit.*`,
`seclab_taskflows.toolboxes.local_file_viewer`,
`seclab_taskflows.toolboxes.gh_file_viewer`, y
`seclab_taskflows.configs.model_config` se resuelve desde la distribución
padre en tiempo de ejecución.

---

## Tabla de contenidos

1. [Qué es esto](#what-this-is)
2. [Inicio rápido](#quick-start)
3. [Arquitectura](#architecture)
4. [El pipeline, etapa por etapa](#the-pipeline-stage-by-stage)
5. [El bucle de retroalimentación de cobertura](#the-coverage-feedback-loop)
6. [Fuzzing consciente de la estructura](#structure-aware-fuzzing)
7. [Corpus persistente entre iteraciones y campañas](#persistent-corpus-across-iterations-and-campaigns)
8. [Triaje e informes de vulnerabilidades](#triage-and-vulnerability-reports)
9. [Panel en vivo](#live-dashboard)
10. [Archivos de salida](#output-files)
11. [Esquema de la base de datos](#database-schema)
12. [Herramientas MCP (el vocabulario del agente)](#mcp-tools-the-agents-vocabulary)
13. [Parámetros ajustables (variables de entorno)](#tunable-knobs-environment-variables)
14. [Extender el pipeline](#extending-the-pipeline)
15. [Proyectos de referencia y resultados](#benchmark-projects-and-results)
16. [Limitaciones y trampas](#limitations-and-gotchas)
17. [Advertencia de seguridad](#security-warning)
18. [Desarrollo: pruebas, linting, contribución](#development-testing-linting-contributing)
19. [Glosario](#glossary)

---

## Qué es esto

Este taskflow es un pipeline de fuzzing totalmente autónomo. Dado un repositorio de GitHub
de un proyecto nativo en C/C++, hará lo siguiente:

1. instalar AFL++ + clang/llvm/lcov + ctags/cscope/graphviz si faltan,
2. obtener el código fuente,
3. identificar objetivos de fuzzing candidatos (parsers, decodificadores, validadores, …),
4. analizar el sistema de compilación,
5. escribir uno o más candidatos de harness por objetivo, compilar cada uno tanto como un
   binario `.afl` instrumentado con AFL como un binario `.cov` instrumentado para cobertura,
6. (opcionalmente) calificar candidatos mediante cobertura de 60 segundos y conservar el mejor,
7. ejecutar un bucle de fuzzing/cobertura/mejora con presupuestos de tiempo que se duplican,
8. triar cada fallo, confirmar que los fallos previamente conocidos aún se reproducen, y
   escribir informes de vulnerabilidad en markdown por cada fallo con veredictos, explotabilidad,
   parches sugeridos y bocetos de pruebas de regresión,
9. construir un grafo de llamadas al estilo Fuzz-Introspector + informe de API no tocada para la
   siguiente campaña,
10. publicar todo en un panel HTML en vivo.

El pipeline es **al estilo OSS-Fuzz** en esencia: utiliza muchas de las mismas
técnicas (mutadores y diccionarios por formato, empalme de tokens consciente de la estructura, mejoras de harness guiadas por cobertura, informes legibles por máquina,
fallos deduplicados con hash de pila) pero es mucho más pequeño y autocontenido.

---

## Inicio rápido```bash
# Inside the codespace (or a host with python + git available):
./scripts/fuzzing/run_fuzzing.sh tukaani-project/xz

---

## Arquitectura

Tres capas, de arriba a abajo:```
┌────────────────────────────────────────────────────────────────────┐
│  scripts/fuzzing/run_fuzzing.sh                                    │
│      shell driver; chains the taskflow stages with `set +e`        │
└────────────────────┬───────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/taskflows/fuzzing/*.yaml                     │
│      LLM agent prompts; one YAML per pipeline stage                │
└────────────────────┬───────────────────────────────────────────────┘
                     │  (calls MCP tools)
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/mcp_servers/                                 │
│   ├ fuzz_context.py    persistence (SQLite via SQLAlchemy)         │
│   └ fuzz_runner.py     subprocess wrappers (AFL, clang, lcov, ...) │
│                                                                    │
│  scripts/fuzzing/dashboard.py                                      │
│   read-only HTML view of fuzz_context.db                           │
└────────────────────────────────────────────────────────────────────┘

En cada iteración, para cada harness, el agente:

1. Solicita `get_persistent_corpus_dir(harness_id)` para obtener el
   directorio de corpus estable de este harness.
2. Llama a `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>,
   output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)`.
3. Llama a `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue,
   output_dir=<run>/coverage)` para producir un tracefile LCOV y un informe HTML.
4. Llama a `store_coverage_from_lcov(run_id, lcov_path, html_path)` para persistir
   una fila `coverage_report` + filas `coverage_gap` por cada elemento no cubierto.
5. Llama a `fold_queue_into_persistent_corpus(...)` para fusionar la cola de iteración
   de AFL en el corpus persistente y ejecutar `cmin` para mantener el tamaño acotado.
6. Lee `get_coverage_summary` + `get_coverage_gaps`, y luego:
   - añade una nueva semilla (etiquetada `coverage_feedback`) para alcanzar una
     rama no cubierta,
   - edita el código fuente del harness para llamar a una API adicional,
   - llama a `enrich_dictionary_from_uncovered(...)` para añadir automáticamente
     entradas al diccionario para las constantes mágicas que AFL necesita para
     satisfacer un guard, o
   - omite la brecha (ruta de error en frío / código de proveedor).
7. Llama a `store_iteration_note(repo, iteration_number, harness_id, note=<resumen
   de una línea>)` para que la línea temporal de iteraciones del panel de control
   registre lo que cambió.

**Detección de estancamiento.** El bucle termina anticipadamente una vez que dos iteraciones consecutivas
han ganado ambas < `FUZZ_PLATEAU_THRESHOLD_PCT` (por defecto `1.0`) puntos porcentuales absolutos
de cobertura de líneas.

---

## Fuzzing consciente de la estructura

Tres mecanismos complementarios producen entradas más sólidas que la mutación de bytes en bruto.

### 1. Diccionarios por formato + mutadores personalizados

Para objetivos cuyo `input_kind` coincide con un formato conocido, el taskflow incluye
diccionarios preconstruidos y archivos fuente C de `LLVMFuzzerCustomMutator`:

| Formato | Diccionario | Mutador | Notas |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | Empalme de tokens, dup/drop de corchetes balanceados, cambio de tipo |
| `xml` | `xml.dict` | `xml_mutator.c` | Etiquetas, entidades, DTDs, tokens billion-laughs |
| `regex` | `regex.dict` | `regex_mutator.c` | Anclas, clases, cuantificadores, patrones ReDoS reales |
| `binary_tlv` | _(ninguno)_ | `binary_tlv_mutator.c` | Registros con prefijo de longitud: desbordamiento de longitud / dup / drop |
| `png` | `png.dict` | _(reutiliza binary_tlv)_ | Diccionario PNG + mutador binary_tlv |

Estos son recogidos automáticamente por `write_initial_harnesses` (diccionario
copiado junto a las semillas) y `build_harnesses` (mutador enlazado en el binario
de AFL). Cada mutador delega el 50% de las mutaciones al mutador de bytes por defecto
de AFL para no perder la aleatorización del motor.

Para añadir un nuevo formato: coloca un `<name>.dict` y/o un `<name>_mutator.c` en
`src/seclab_taskflows/dictionaries/`, luego regístralo en el
mapa `_FORMAT_ASSETS` al final de `fuzz_runner.py`.

### 2. Mutador inteligente consciente del código fuente (específico del proyecto)

Para formatos desconocidos, o cuando quieras tokens más sólidos específicos del proyecto,
`generate_smart_mutator` escanea los propios archivos `.c`/`.h` del repositorio objetivo
y emite un archivo C `LLVMFuzzerCustomMutator` cuyos diccionarios de empalme
se extraen de:

- literales de cadena con ≥3 caracteres alfabéticos (tras filtrar ruido de
  compilador/licencia, rutas, cabeceras, restricciones asm, especificadores de formato),
- constantes numéricas de 32 bits de `#define`, `case` y `enum` (tras
  filtrar ruido genérico de enteros pequeños como 0, 1, 256, 0xff…).

Hay tres enfoques disponibles:

| Enfoque | Qué empalma | Cuándo usarlo |
|-------|-----------------|-------------|
| `strings` | Solo literales de cadena del proyecto | Formatos de texto (JSON, XML, YAML, CSV) |
| `constants` | Solo valores mágicos numéricos de 32 bits | Protocolos binarios, cabeceras con números mágicos |
| `combined` | Ambos | Por defecto; normalmente el mejor |

Combina `generate_smart_mutators(...)` (plural) con `HARNESS_CANDIDATES >= 3`
para que cada enfoque se convierta en un harness candidato en la ronda de clasificación.

### 3. Diccionario AFL consciente del proyecto + enriquecimiento guiado por cobertura

Dos herramientas complementarias construyen y hacen crecer un diccionario `-x` de AFL
a medida que avanza la campaña:

- **`generate_project_dictionary(source_root, output_path)`** — se ejecuta una vez
  antes de la iteración 1, extrae estáticamente el mismo conjunto de tokens de código fuente
  usado por el mutador inteligente y lo escribe como un diccionario AFL. Las constantes
  numéricas se emiten en AMBAS endiannesses para que el fuzzer pueda satisfacer
  `memcmp(x, &magic, 4)` independientemente del orden de bytes del host.

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path,
  uncovered_locations)`** — se ejecuta después del paso de cobertura de cada iteración,
  escanea el código fuente circundante en busca de guards condicionales
  (`strncmp/memcmp/strstr`, `case 0xN:`, `== 0xN`, `== 'X'`) cerca de las
  líneas no cubiertas, y AÑADE cualquier token nuevo al diccionario. Idempotente:
  nunca vuelve a añadir una entrada que ya está presente.

### 4. Operación de empalme de corpus

Cuando se pasa `corpus_dir` a `generate_smart_mutator`, el C generado
también obtiene un operador de empalme de corpus: en la primera llamada carga hasta 64 archivos
de ese directorio (limitados a 4 KiB cada uno), y a partir de entonces puede empalmar
subregiones aleatorias de esos archivos en la entrada mutada. Esto le da
al mutador un operador de estilo recombinación que el havoc estándar de AFL no hace
bien. Combínalo con `get_persistent_corpus_dir(...)` para que la biblioteca de empalme
sea "remezclar lo que AFL ya ha descubierto".

---

## Corpus persistente entre iteraciones y campañas

Cada harness tiene un directorio de corpus estable en:```
<workspace>/corpus/harness_<id>/

---

## Archivos de salida

Todos bajo `~/.local/share/seclab-taskflow-agent/seclab-taskflows/`.

| Ruta | Contenido |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — objetivos, harnesses, ejecuciones, cobertura, crashes, veredictos, grafos de llamadas, sugerencias de harness, notas de iteración |
| `fuzz_runner/builds/` | Binarios `.afl` y `.cov` compilados |
| `fuzz_runner/runs/` | Directorios de salida de AFL + archivos LCOV + informes de cobertura HTML |
| `fuzz_runner/corpus/harness_<id>/` | Corpus persistente por harness (se mantiene entre iteraciones y campañas) |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Resumen de campaña en Markdown, crashes agrupados por veredicto |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | Informe de vulnerabilidad en Markdown por crash |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | Grafo de llamadas estático + superposición de alcanzadas/no alcanzadas |

---

## Esquema de la base de datos

Tablas en `fuzz_context.db` (SQLite vía SQLAlchemy):

| Tabla | Columnas de interés |
|-------|--------------------|
| `fuzz_target` | `repo, file, function, signature, input_kind` |
| `harness` | `target_id, repo, harness_path, afl_binary_path, cov_binary_path, build_status, version, sanitizers` |
| `seed_corpus` | `target_id, source, path, bytes_count, added_in_iteration` |
| `fuzz_run` | `harness_id, iteration_number, exec_per_sec, paths_total, crashes_count, status, output_dir, started_at, ended_at` |
| `coverage_report` | `run_id, lines_total, lines_hit, line_pct, fns_*, branches_*, lcov_path, html_path` |
| `coverage_gap` | `report_id, file, function, line, kind, reason_hint` |
| `crash` | `run_id, input_blob_path, minimized_path, stack_top_hash, sanitizer_output, verdict, bug_class, cwe, severity, vuln_report_path, reproducer_path, classification, notes` |
| `call_graph` | `repo, target_id, dot_path, svg_path, functions_total, functions_in_graph, functions_reached, functions_unreached, untouched_surface_json` |
| `harness_suggestion` | `repo, function_name, file, rationale, input_kind, priority` |
| `iteration_note` | `repo, harness_id, iteration_number, note, created_at` |

Las migraciones del esquema residen en `_migrate()` en `fuzz_context.py`. Las nuevas TABLAS se crean automáticamente mediante `Base.metadata.create_all()`; solo las nuevas COLUMNAS necesitan `ALTER TABLE` basado en PRAGMA.

---

## Herramientas MCP (el vocabulario del agente)

El agente nunca llama directamente a AFL o clang — compone el pipeline llamando a herramientas MCP. El conjunto completo, agrupado por propósito:

### Persistencia (`fuzz_context.py`)

- `store_fuzz_target`, `get_fuzz_targets`
- `store_harness`, `update_harness_build`, `get_harnesses`
- `store_seed`, `start_fuzz_run`, `finish_fuzz_run`, `get_fuzz_runs`
- `store_coverage_from_lcov`, `get_coverage_summary`, `get_coverage_gaps`,
  `coverage_plateau_reached`
- `store_crash`, `update_crash_verdict`, `get_crashes`,
  `get_crashes_grouped`, `suggest_severity`
- `store_call_graph`, `get_call_graphs`, `get_repo_reached_functions`
- `store_harness_suggestion`, `get_harness_suggestions`
- `store_iteration_note`, `get_iteration_notes`

### Compilación / fuzzing / cobertura (`fuzz_runner.py`)

- `check_tooling`, `workspace_paths`
- `compile_harness` — compila los binarios `.afl` y `.cov`
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — reproduce la cola de AFL contra el binario `.cov`, exporta LCOV
- `extract_dictionary` — extrae cadenas imprimibles de un binario
- `package_reproducer` — empaqueta un `.tgz` de un solo crash

### Corpus persistente (v8)

- `get_persistent_corpus_dir`, `fold_queue_into_persistent_corpus`

### Recursos de formato (C5)

- `list_format_assets`, `get_format_dictionary`, `write_format_mutator`

### Mutador inteligente + diccionario consciente del proyecto

- `generate_smart_mutator`, `generate_smart_mutators`
- `generate_project_dictionary`, `enrich_dictionary_from_uncovered`

Las funciones de las herramientas están decoradas con `@mcp.tool()` (FastMCP). Dentro de las pruebas, invócalas mediante el atributo `.fn`, p. ej.
`fr.run_afl_for.fn(afl_binary_path=..., ...)`.

---

## Parámetros ajustables (variables de entorno)

| Variable | Valor predeterminado | Propósito |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | Número de harnesses candidatos escritos por objetivo. Establécelo en 2 o 3 para una competencia al estilo OSS-Fuzz-Gen. La etapa de calificación ejecuta cada uno durante `QUALIFIER_SECONDS` y conserva el mejor por % de líneas. |
| `QUALIFIER_SECONDS` | `60` | Presupuesto de tiempo real por candidato en la etapa de calificación. |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | Ganancia de cobertura de líneas (en pp absolutos) por debajo de la cual dos iteraciones consecutivas se consideran una meseta y el bucle se detiene anticipadamente. |
| `FUZZ_DASHBOARD_PORT` | `8765` | Puerto para el panel en vivo. |
| `FUZZ_NO_DASHBOARD` | (sin establecer) | Establécelo en `1` para omitir el inicio del panel. |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | Tiempo de espera del subproceso por herramienta en `fuzz_runner` (segundos). |
| `LOCAL_SHELL_TIMEOUT` | `180` | Tiempo de espera por comando en `local_shell` (segundos). |

Además de las variables estándar del agente (`COPILOT_TOKEN`, `LOG_DIR`,
`FUZZ_CONTEXT_DIR`, …). Consulta el README raíz del proyecto para la lista completa.

---

## Extender el pipeline

### Añadir un nuevo formato (mutador + diccionario)

1. Coloca `dictionaries/<name>.dict` (formato `-x` de AFL) y/o
   `dictionaries/<name>_mutator.c` (mutador personalizado de libFuzzer).
2. Regístralo en `_FORMAT_ASSETS` al final de `fuzz_runner.py`:   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

Convenciones del código base (véase también `benchmark/improvements.md` para la versión de estas según el historial de la campaña):

- Use `os.environ.get(NAME) or "default"` en lugar de
  `os.environ.get(NAME, "default")`. De lo contrario, se devolverían cadenas vacías
  procedentes de la sustitución de plantillas YAML.
- Use `X | None` (PEP 604) en las nuevas anotaciones, no `Optional[X]`.
- Las pruebas invocan las herramientas MCP mediante `.fn(...)`, no directamente el nombre decorado.
- Evite los literales `/tmp/...` en las pruebas — use el fixture `tmp_path` de pytest
  (regla de lint `S108`).
- Todas las importaciones en línea dentro de los métodos de prueba necesitan `# noqa: PLC0415` si
  no puede moverlas al principio del archivo (por ejemplo, cuando se importan condicionalmente
  después de un `pytest.skip`).
- Una sola aserción por línea para pruebas de verdad compuestas (regla de lint `PT018`).

El registro de mejoras (`benchmark/improvements.md`) es el log persistente
de lo que se ha añadido al pipeline a lo largo de las versiones. Cuando añada una
característica sustancial, agregue una sección allí describiendo qué cambió, dónde
reside y qué pruebas la protegen.

---

## Glosario

- **AFL++** — Fuzzer greybox guiado por cobertura; el motor de ejecución aquí.
- **libAFLDriver** — Biblioteca estática que permite a los arneses de AFL++ usar
  la convención de punto de entrada de libFuzzer (`LLVMFuzzerTestOneInput`).
- **LCOV** — Formato estándar de la industria para archivos de traza de cobertura. Exportamos a él
  mediante `llvm-cov export -format=lcov` y lo analizamos nosotros mismos.
- **`stack_top_hash`** — Un hash de 16 caracteres de los N marcos superiores normalizados de
  una traza de pila de ASan/UBSan. Se usa para la deduplicación de fallos.
- **Corpus persistente** — Directorio por arnés en
  `<workspace>/corpus/harness_<id>/` que conserva las entradas interesantes de AFL
  a través de iteraciones y re-ejecuciones de la misma campaña.
- **Mutador inteligente** — Un `LLVMFuzzerCustomMutator` cuyos tokens de empalme se
  extraen del propio código fuente del objetivo (`generate_smart_mutator`).
- **Mutador personalizado (libFuzzer)** — Una función C proporcionada por el usuario invocada por
  el motor con total libertad sobre cómo mutar un búfer; AFL++ admite
  la misma ABI.
- **Herramienta MCP** — Una función decorada con FastMCP que el agente LLM puede invocar.
- **OSS-Fuzz / Fuzz-Introspector** — La infraestructura de fuzzing de código abierto de Google
  y su herramienta complementaria de análisis de grafo de llamadas/cobertura.
  Varias de las características de este taskflow (mutadores por formato, deduplicación por pila,
  informe de grafo de llamadas + API no tocada, arneses multi-candidato) están
  inspiradas en ellas.

---

## Licencia

Este proyecto está licenciado bajo los términos de la licencia de código abierto MIT. Consulte el archivo [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt) para conocer los términos completos.

## Mantenedores

Consulte [CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS) o póngase en contacto con el equipo de GitHub Security Lab.

## Soporte

Consulte [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md) para obtener detalles sobre cómo obtener ayuda con este proyecto.

## Agradecimientos

Este proyecto se basa en los conceptos y técnicas de [AFL++](https://github.com/AFLplusplus/AFLplusplus), [OSS-Fuzz](https://github.com/google/oss-fuzz) y [Fuzz-Introspector](https://github.com/ossf/fuzz-introspector).