Seclab Taskflows Fuzzing

Un pipeline de fuzzing estilo OSS-Fuzz impulsado por LLM para proyectos nativos en C/C++. AFL++ para la ejecución, clang+lcov para la cobertura, un agente LLM para la escritura de harnesses, decisiones basadas en retroalimentación de cobertura, triaje y reportes.

• Totalmente autónomo: dale un repositorio de GitHub y se encarga de todo, desde la identificación del objetivo hasta los reportes de vulnerabilidades.
• Técnicas estilo OSS-Fuzz: mutadores/diccionarios por formato, empalme de tokens consciente de la estructura, mejoras de harness guiadas por cobertura.
• Genera reportes de fallos legibles por máquina con veredictos de explotabilidad y parches sugeridos.
• Panel HTML en vivo para el monitoreo de campañas en tiempo real.
• Escrito en Python (taskflows/toolboxes/configs) con generación de harness en C para AFL++.
• Estado: Desarrollo activo.

Antecedentes

Este repositorio contiene el taskflow de fuzzing para el GitHub Security Lab Taskflow Agent. Depende del repositorio complementario seclab-taskflows para algunos bloques de construcción compartidos (taskflow fetch_source_code, toolboxes local_file_viewer / gh_file_viewer, y el model_config predeterminado) — esos se instalan automáticamente como una dependencia de Python.

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para obtener las pautas.

Requisitos

• Python 3.11+
• Un entorno Linux (o Codespace) con acceso a apt
• AFL++, clang, lcov, ctags, cscope, graphviz (instalados automáticamente por el pipeline si faltan)
• Git y GitHub CLI (gh)

Instalación

pip install git+https://github.com/GitHubSecurityLab/seclab-taskflows-fuzzing

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
2. Inicio rápido
3. Arquitectura
4. El pipeline, etapa por etapa
5. El bucle de retroalimentación de cobertura
6. Fuzzing consciente de la estructura
7. Corpus persistente entre iteraciones y campañas
8. Triaje e informes de vulnerabilidades
9. Panel en vivo
10. Archivos de salida
11. Esquema de la base de datos
12. Herramientas MCP (el vocabulario del agente)
13. Parámetros ajustables (variables de entorno)
14. Extender el pipeline
15. Proyectos de referencia y resultados
16. Limitaciones y advertencias
17. Advertencia de seguridad
18. Desarrollo: pruebas, linting, contribución
19. Glosario

---

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 y compilar la biblioteca objetivo tres veces: con instrumentación de cobertura de aristas de AFL++ más sanitizers, con instrumentación CMPLOG de AFL++, y con instrumentación de cobertura basada en código fuente de clang,
5. escribir uno o más candidatos de harness por objetivo, compilar cada uno como un binario .afl instrumentado con AFL++, un binario .cmplog instrumentado con CMPLOG de AFL++ y un binario .cov instrumentado con cobertura de clang,
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. hacer triaje de cada crash, confirmar que los crashes previamente conocidos aún se reproducen, y escribir informes de vulnerabilidad en markdown por crash con veredictos, explotabilidad, parches sugeridos y bocetos de pruebas de regresión,
9. construir un grafo de llamadas 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 estilo OSS-Fuzz en espíritu: usa 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, crashes deduplicados con hash de pila) pero es mucho más pequeño y autocontenido.

---

Inicio rápido

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

Esa es toda la interfaz. El script es autónomo; instalará AFL++ en la primera ejecución y luego dirigirá el resto del flujo de tareas. Los archivos de salida se escriben en ~/.local/share/seclab-taskflow-agent/seclab-taskflows/.

El panel de control se inicia automáticamente en segundo plano; en un Codespace, el puerto 8765 se redirige automáticamente — ábrelo en cualquier navegador para ver el progreso en vivo.

Para una prueba rápida, usa un objetivo pequeño:

./scripts/fuzzing/run_fuzzing.sh DaveGamble/cJSON

---

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                           │
└────────────────────────────────────────────────────────────────────┘

Reglas de diseño clave: