Seclab Taskflows Fuzzing

Um pipeline de fuzzing no estilo OSS-Fuzz, orientado por LLM, para projetos nativos em C/C++. AFL++ para execução, clang+lcov para cobertura, um agente LLM para escrita de harness, decisões baseadas em feedback de cobertura, triagem e relatórios.

• Totalmente autônomo: basta fornecer um repositório do GitHub e ele cuida de tudo, desde a identificação do alvo até os relatórios de vulnerabilidade.
• Técnicas no estilo OSS-Fuzz: mutadores/dicionários por formato, splicing de tokens ciente da estrutura, melhorias de harness orientadas por cobertura.
• Produz relatórios de crash legíveis por máquina com veredictos de explorabilidade e patches sugeridos.
• Painel HTML ao vivo para monitoramento de campanhas em tempo real.
• Escrito em Python (taskflows/toolboxes/configs) com geração de harness em C para AFL++.
• Status: Desenvolvimento ativo.

Contexto

Este repositório contém o taskflow de fuzzing para o GitHub Security Lab Taskflow Agent. Ele depende do repositório complementar seclab-taskflows para alguns blocos de construção compartilhados (taskflow fetch_source_code, toolboxes local_file_viewer / gh_file_viewer e o model_config padrão) — esses são instalados automaticamente como uma dependência Python.

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Requisitos

• Python 3.11+
• Um ambiente Linux (ou Codespace) com acesso ao apt
• AFL++, clang, lcov, ctags, cscope, graphviz (instalados automaticamente pelo pipeline se ausentes)
• Git e GitHub CLI (gh)

Instalação

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

Isso traz seclab-taskflow-agent e seclab-taskflows (pai) transitivamente, então toda referência pontuada da forma seclab_taskflows.taskflows.audit.*, seclab_taskflows.toolboxes.local_file_viewer, seclab_taskflows.toolboxes.gh_file_viewer, e seclab_taskflows.configs.model_config é resolvida a partir da distribuição pai em tempo de execução.

---

Índice

1. O que é isto
2. Início rápido
3. Arquitetura
4. O pipeline, estágio por estágio
5. O ciclo de feedback de cobertura
6. Fuzzing ciente da estrutura
7. Corpus persistente entre iterações e campanhas
8. Triagem e relatórios de vulnerabilidade
9. Painel ao vivo
10. Arquivos de saída
11. Esquema do banco de dados
12. Ferramentas MCP (o vocabulário do agente)
13. Ajustes configuráveis (variáveis de ambiente)
14. Estendendo o pipeline
15. Projetos de benchmark e resultados
16. Limitações e armadilhas
17. Aviso de segurança
18. Desenvolvimento: testes, linting, contribuição
19. Glossário

---

O que é isto

Este taskflow é um pipeline de fuzzing totalmente autônomo. Dado um repositório GitHub de um projeto nativo em C/C++, ele irá:

1. instalar AFL++ + clang/llvm/lcov + ctags/cscope/graphviz se estiverem ausentes,
2. buscar o código-fonte,
3. identificar alvos de fuzzing candidatos (parsers, decodificadores, validadores, …),
4. analisar o sistema de build e compilar a biblioteca alvo três vezes: com instrumentação de cobertura de arestas do AFL++ mais sanitizers, com instrumentação CMPLOG do AFL++, e com instrumentação de cobertura baseada em código-fonte do clang,
5. escrever um ou mais candidatos a harness por alvo, compilar cada um como um binário .afl instrumentado com AFL++, um binário .cmplog instrumentado com CMPLOG do AFL++ e um binário .cov instrumentado com cobertura do clang,
6. (opcionalmente) qualificar candidatos por cobertura de 60 segundos e manter o melhor,
7. executar um ciclo de fuzz/cobertura/melhoria com orçamentos de tempo duplicados,
8. fazer a triagem de cada crash, confirmar que crashes previamente conhecidos ainda se reproduzem, e escrever relatórios markdown de vulnerabilidade por crash com veredictos, explorabilidade, patches sugeridos e esboços de testes de regressão,
9. construir um grafo de chamadas no estilo Fuzz-Introspector + relatório de APIs não tocadas para a próxima campanha,
10. publicar tudo em um painel HTML ao vivo.

O pipeline é no estilo OSS-Fuzz: usa muitas das mesmas técnicas (mutadores e dicionários por formato, splicing de tokens ciente da estrutura, melhorias de harness guiadas por cobertura, relatórios legíveis por máquina, crashes deduplicados por hash de pilha), mas é muito menor e autocontido.

---

Início rápido

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

Essa é toda a interface. O script é autónomo; irá instalar o AFL++ na primeira execução e, em seguida, conduzir o resto do fluxo de tarefas. Os ficheiros de saída são escritos em ~/.local/share/seclab-taskflow-agent/seclab-taskflows/.

O dashboard inicia automaticamente em segundo plano; num Codespace, a porta 8765 é reencaminhada automaticamente — abra-a em qualquer navegador para acompanhar o progresso em direto.

Para um teste rápido de verificação, use um alvo pequeno:

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

Arquitetura

Três camadas, de cima para baixo:

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

Regras de design principais: