Seclab Taskflows Fuzzing

Una pipeline di fuzzing in stile OSS-Fuzz guidata da LLM per progetti nativi C/C++. AFL++ per l'esecuzione, clang+lcov per la copertura, un agente LLM per la scrittura degli harness, le decisioni basate sul feedback di copertura, il triage e il reporting.

• Completamente autonomo: fornisci un repository GitHub e gestisce tutto, dall'identificazione del target ai report sulle vulnerabilità.
• Tecniche in stile OSS-Fuzz: mutatori/dizionari per formato, splicing di token consapevole della struttura, miglioramenti degli harness guidati dalla copertura.
• Produce report di crash leggibili dalla macchina con verdetti di sfruttabilità e patch suggerite.
• Dashboard HTML live per il monitoraggio delle campagne in tempo reale.
• Scritto in Python (taskflows/toolboxes/configs) con generazione di harness C per AFL++.
• Stato: Sviluppo attivo.

Contesto

Questo repository contiene il taskflow di fuzzing per il GitHub Security Lab Taskflow Agent. Dipende dal repository complementare seclab-taskflows per alcuni blocchi di costruzione condivisi (taskflow fetch_source_code, toolbox local_file_viewer / gh_file_viewer, e il model_config predefinito) — questi vengono installati automaticamente come dipendenza Python.

I contributi sono benvenuti! Consulta CONTRIBUTING.md per le linee guida.

Requisiti

• Python 3.11+
• Un ambiente Linux (o Codespace) con accesso ad apt
• AFL++, clang, lcov, ctags, cscope, graphviz (installati automaticamente dalla pipeline se mancanti)
• Git e GitHub CLI (gh)

Installazione

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

Questo include transitivamente seclab-taskflow-agent e seclab-taskflows (parent), quindi ogni riferimento puntato nella forma seclab_taskflows.taskflows.audit.*, seclab_taskflows.toolboxes.local_file_viewer, seclab_taskflows.toolboxes.gh_file_viewer, e seclab_taskflows.configs.model_config viene risolto dalla distribuzione parent a runtime.

---

Indice

1. Cos'è questo
2. Avvio rapido
3. Architettura
4. La pipeline, fase per fase
5. Il ciclo di feedback sulla copertura
6. Fuzzing structure-aware
7. Corpus persistente tra iterazioni e campagne
8. Triage e report di vulnerabilità
9. Dashboard live
10. File di output
11. Schema del database
12. Strumenti MCP (il vocabolario dell'agente)
13. Parametri regolabili (variabili d'ambiente)
14. Estendere la pipeline
15. Progetti di benchmark e risultati
16. Limitazioni e insidie
17. Avviso di sicurezza
18. Sviluppo: testing, linting, contribuire
19. Glossario

---

Cos'è questo

Questo taskflow è una pipeline di fuzzing completamente autonoma. Dato un repository GitHub di un progetto nativo C/C++, esso:

1. installa AFL++ + clang/llvm/lcov + ctags/cscope/graphviz se mancanti,
2. recupera il codice sorgente,
3. identifica i potenziali target di fuzzing (parser, decoder, validatori, …),
4. analizza il sistema di build e compila la libreria target tre volte: con strumentazione di copertura edge di AFL++ più sanitizer, con strumentazione CMPLOG di AFL++, e con strumentazione di copertura basata su sorgente di clang,
5. scrive uno o più candidati harness per target, compilando ciascuno come binario .afl instrumentato con AFL++, un binario .cmplog instrumentato con CMPLOG di AFL++ e un binario .cov instrumentato con copertura di clang,
6. (opzionalmente) qualifica i candidati tramite copertura di 60 secondi e mantiene il migliore,
7. esegue un ciclo fuzz/copertura/miglioramento con budget temporali raddoppiati,
8. effettua il triage di ogni crash, conferma che i crash precedentemente noti si riproducono ancora, e scrive report di vulnerabilità markdown per ogni crash con verdetti, sfruttabilità, patch suggerite e bozze di test di regressione,
9. costruisce un call graph in stile Fuzz-Introspector + report delle API non toccate per la campagna successiva,
10. pubblica tutto su una dashboard HTML live.

La pipeline è in stile OSS-Fuzz: utilizza molte delle stesse tecniche (mutatori e dizionari per formato, splicing di token structure-aware, miglioramenti dell'harness guidati dalla copertura, report leggibili da macchina, crash deduplicati con hash dello stack) ma è molto più piccola e autosufficiente.

---

Avvio rapido

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

È tutta l'interfaccia. Lo script è autonomo; installerà AFL++ alla prima esecuzione, poi guiderà il resto del taskflow. I file di output vengono scritti in ~/.local/share/seclab-taskflow-agent/seclab-taskflows/.

La dashboard si avvia automaticamente in background; in un Codespace, la porta 8765 viene inoltrata automaticamente — aprila in qualsiasi browser per seguire i progressi in tempo reale.

Per un rapido smoke-test, usa un target di piccole dimensioni:

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

Architettura

Tre livelli, dall'alto verso il basso:

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

Regole di progettazione chiave: