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](#what-this-is)
2. [Início rápido](#quick-start)
3. [Arquitetura](#architecture)
4. [O pipeline, estágio por estágio](#the-pipeline-stage-by-stage)
5. [O ciclo de feedback de cobertura](#the-coverage-feedback-loop)
6. [Fuzzing ciente de estrutura](#structure-aware-fuzzing)
7. [Corpus persistente entre iterações e campanhas](#persistent-corpus-across-iterations-and-campaigns)
8. [Triagem e relatórios de vulnerabilidade](#triage-and-vulnerability-reports)
9. [Dashboard ao vivo](#live-dashboard)
10. [Arquivos de saída](#output-files)
11. [Esquema do banco de dados](#database-schema)
12. [Ferramentas MCP (o vocabulário do agente)](#mcp-tools-the-agents-vocabulary)
13. [Ajustes configuráveis (variáveis de ambiente)](#tunable-knobs-environment-variables)
14. [Estendendo o pipeline](#extending-the-pipeline)
15. [Projetos de benchmark e resultados](#benchmark-projects-and-results)
16. [Limitações e armadilhas](#limitations-and-gotchas)
17. [Aviso de segurança](#security-warning)
18. [Desenvolvimento: testes, linting, contribuição](#development-testing-linting-contributing)
19. [Glossário](#glossary)

---

## 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,
5. escrever um ou mais candidatos a harness por alvo, compilar cada um tanto como
   um binário `.afl` instrumentado com AFL quanto como um binário `.cov`
   instrumentado para cobertura,
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 que dobram,
8. fazer 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 dashboard 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 de
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```bash
# Inside the codespace (or a host with python + git available):
./scripts/fuzzing/run_fuzzing.sh tukaani-project/xz

---

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

A cada iteração, a cada harness, o agente:

1. Solicita `get_persistent_corpus_dir(harness_id)` para obter o diretório
   de corpus estável deste harness.
2. Chama `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>,
   output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)`.
3. Chama `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue,
   output_dir=<run>/coverage)` para produzir um tracefile LCOV e um relatório HTML.
4. Chama `store_coverage_from_lcov(run_id, lcov_path, html_path)` para persistir
   uma linha `coverage_report` + linhas `coverage_gap` por item não coberto.
5. Chama `fold_queue_into_persistent_corpus(...)` para fundir a fila de iteração
   do AFL no corpus persistente e executar `cmin` para manter o tamanho limitado.
6. Lê `get_coverage_summary` + `get_coverage_gaps`, e então ou:
   - adiciona uma nova seed (marcada com `coverage_feedback`) para alcançar um
     branch não coberto,
   - edita o código-fonte do harness para chamar uma API adicional,
   - chama `enrich_dictionary_from_uncovered(...)` para adicionar automaticamente
     entradas de dicionário para as constantes mágicas que o AFL precisa para
     satisfazer um guard, ou
   - ignora a lacuna (caminho de erro frio / código do fornecedor).
7. Chama `store_iteration_note(repo, iteration_number, harness_id, note=<resumo
   de uma linha>)` para que a linha do tempo de iterações do dashboard acompanhe o que
   mudou.

**Detecção de platô.** O loop termina antecipadamente assim que duas iterações consecutivas
tiverem ambas ganhado < `FUZZ_PLATEAU_THRESHOLD_PCT` (padrão `1.0`) pontos percentuais
absolutos de cobertura de linhas.

---

## Fuzzing ciente da estrutura

Três mecanismos complementares produzem entradas mais fortes do que a mutação bruta de bytes.

### 1. Dicionários por formato + mutadores personalizados

Para alvos cujo `input_kind` corresponde a um formato conhecido, o taskflow inclui
dicionários pré-construídos e arquivos-fonte C `LLVMFuzzerCustomMutator`:

| Formato | Dicionário | Mutador | Notas |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | Emenda de tokens, dup/drop de colchetes balanceados, inversão de tipo |
| `xml` | `xml.dict` | `xml_mutator.c` | Tags, entidades, DTDs, tokens billion-laughs |
| `regex` | `regex.dict` | `regex_mutator.c` | Âncoras, classes, quantificadores, padrões ReDoS reais |
| `binary_tlv` | _(nenhum)_ | `binary_tlv_mutator.c` | Registros com prefixo de comprimento: estouro de comprimento / dup / drop |
| `png` | `png.dict` | _(reutiliza binary_tlv)_ | Dicionário PNG + mutador binary_tlv |

Estes são capturados automaticamente por `write_initial_harnesses` (dicionário
copiado ao lado das seeds) e `build_harnesses` (mutador vinculado ao binário
AFL). Cada mutador delega 50% das mutações ao mutador de bytes padrão do AFL
para não perdermos a randomização do motor.

Para adicionar um novo formato: coloque um `<name>.dict` e/ou um `<name>_mutator.c` em
`src/seclab_taskflows/dictionaries/`, depois registre-o no
mapa `_FORMAT_ASSETS` na parte inferior de `fuzz_runner.py`.

### 2. Mutador inteligente ciente do código-fonte (específico do projeto)

Para formatos desconhecidos, ou sempre que você quiser tokens mais fortes e específicos do projeto,
`generate_smart_mutator` escaneia os próprios arquivos `.c`/`.h` do repositório alvo
e emite um arquivo C `LLVMFuzzerCustomMutator` cujos dicionários de emenda
são extraídos de:

- literais de string com ≥3 caracteres alfabéticos (após filtrar ruído de compilador/licença,
  caminhos, cabeçalhos, restrições asm, especificadores de formato),
- constantes numéricas de 32 bits de `#define`, `case` e `enum` (após
  filtrar ruído genérico de inteiros pequenos como 0, 1, 256, 0xff…).

Três focos estão disponíveis:

| Foco | O que emenda | Quando usar |
|-------|-----------------|-------------|
| `strings` | Apenas literais de string do projeto | Formatos de texto (JSON, XML, YAML, CSV) |
| `constants` | Apenas valores mágicos numéricos de 32 bits | Protocolos binários, cabeçalhos com números mágicos |
| `combined` | Ambos | Padrão; geralmente o melhor |

Combine `generate_smart_mutators(...)` (plural) com `HARNESS_CANDIDATES >= 3`
para que cada foco se torne um harness candidato na rodada de qualificação.

### 3. Dicionário AFL ciente do projeto + enriquecimento orientado por cobertura

Duas ferramentas complementares constroem e expandem um dicionário AFL `-x` à medida que
a campanha avança:

- **`generate_project_dictionary(source_root, output_path)`** — executa uma vez
  antes da iteração 1, extrai estaticamente o mesmo conjunto de tokens de código-fonte usado pelo
  mutador inteligente e o escreve como um dicionário AFL. Constantes numéricas
  são emitidas em AMBAS as endiannesses para que o fuzzer possa satisfazer
  `memcmp(x, &magic, 4)` independentemente da ordem de bytes do host.

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path,
  uncovered_locations)`** — executa após a etapa de cobertura de cada iteração,
  escaneia o código-fonte ao redor em busca de guards condicionais
  (`strncmp/memcmp/strstr`, `case 0xN:`, `== 0xN`, `== 'X'`) próximos às
  linhas não cobertas, e ANEXA quaisquer novos tokens ao dicionário. Idempotente:
  nunca readiciona uma entrada que já está presente.

### 4. Operação de emenda de corpus

Quando `corpus_dir` é passado para `generate_smart_mutator`, o C gerado
também recebe um operador de emenda de corpus: na primeira chamada ele carrega até 64 arquivos
desse diretório (limitados a 4 KiB cada), e a partir daí pode emendar
sub-regiões aleatórias desses arquivos na entrada mutada. Isso dá ao
mutador um operador no estilo de recombinação que o havoc padrão do AFL não faz
bem. Combine com `get_persistent_corpus_dir(...)` para que a biblioteca de emenda
seja "remixar o que o AFL já descobriu".

---

## Corpus persistente entre iterações e campanhas

Cada harness tem um diretório de corpus estável em:```
<workspace>/corpus/harness_<id>/

---

## Arquivos de saída

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

| Caminho | Conteúdo |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — alvos, harnesses, execuções, cobertura, crashes, veredictos, grafos de chamadas, sugestões de harness, notas de iteração |
| `fuzz_runner/builds/` | Binários `.afl` e `.cov` compilados |
| `fuzz_runner/runs/` | Diretórios de saída do AFL + arquivos LCOV + relatórios de cobertura HTML |
| `fuzz_runner/corpus/harness_<id>/` | Corpus persistente por harness (mantém-se entre iterações e campanhas) |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Resumo da campanha em Markdown, crashes agrupados por veredicto |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | Relatório de vulnerabilidade em Markdown por crash |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | Grafo de chamadas estático + sobreposição de alcançadas/não alcançadas |

---

## Esquema da base de dados

Tabelas em `fuzz_context.db` (SQLite via SQLAlchemy):

| Tabela | Colunas de interesse |
|-------|--------------------|
| `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` |

As migrações de esquema residem em `_migrate()` em `fuzz_context.py`. Novas TABELAS são
criadas automaticamente por `Base.metadata.create_all()`; apenas novas COLUNAS precisam
de `ALTER TABLE` baseado em PRAGMA.

---

## Ferramentas MCP (o vocabulário do agente)

O agente nunca chama AFL ou clang diretamente — compõe o pipeline
chamando ferramentas MCP. O conjunto completo, agrupado por finalidade:

### Persistência (`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`

### Build / fuzz / cobertura (`fuzz_runner.py`)

- `check_tooling`, `workspace_paths`
- `compile_harness` — compila os binários `.afl` e `.cov`
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — reproduz a fila do AFL contra o binário `.cov`, exporta LCOV
- `extract_dictionary` — extrai strings imprimíveis de um binário
- `package_reproducer` — empacota um `.tgz` de crash único

### 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 + dicionário ciente do projeto

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

As funções de ferramenta são decoradas com `@mcp.tool()` (FastMCP). Dentro dos testes,
invocam-se através do atributo `.fn`, por exemplo
`fr.run_afl_for.fn(afl_binary_path=..., ...)`.

---

## Parâmetros ajustáveis (variáveis de ambiente)

| Variável | Padrão | Finalidade |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | Número de harnesses candidatos escritos por alvo. Defina como 2 ou 3 para competição ao estilo OSS-Fuzz-Gen. A fase de qualificação executa cada um durante `QUALIFIER_SECONDS` e mantém o melhor por % de linhas. |
| `QUALIFIER_SECONDS` | `60` | Orçamento de tempo real por candidato na fase de qualificação. |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | Ganho de cobertura de linhas (em pp absolutos) abaixo do qual duas iterações consecutivas são consideradas um plateau e o ciclo termina antecipadamente. |
| `FUZZ_DASHBOARD_PORT` | `8765` | Porta para o dashboard em tempo real. |
| `FUZZ_NO_DASHBOARD` | (não definido) | Defina como `1` para ignorar o arranque do dashboard. |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | Timeout do subprocesso por ferramenta em `fuzz_runner` (segundos). |
| `LOCAL_SHELL_TIMEOUT` | `180` | Timeout por comando em `local_shell` (segundos). |

Mais as variáveis padrão do agente (`COPILOT_TOKEN`, `LOG_DIR`,
`FUZZ_CONTEXT_DIR`, …). Consulte o README na raiz do projeto para a lista completa.

---

## Estender o pipeline

### Adicionar um novo formato (mutador + dicionário)

1. Coloque `dictionaries/<name>.dict` (formato `-x` do AFL) e/ou
   `dictionaries/<name>_mutator.c` (mutador personalizado libFuzzer).
2. Registe em `_FORMAT_ASSETS` no final de `fuzz_runner.py`:   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

Convenções do código (veja também `benchmark/improvements.md` para a
versão de histórico de campanha destas):

- Use `os.environ.get(NAME) or "default"` em vez de
  `os.environ.get(NAME, "default")`. Strings vazias provenientes da
  substituição de template YAML seriam retornadas de outra forma.
- Use `X | None` (PEP 604) em novas anotações, não `Optional[X]`.
- Os testes invocam ferramentas MCP via `.fn(...)`, não o nome decorado
  diretamente.
- Evite literais `/tmp/...` nos testes — use a fixture `tmp_path` do pytest
  (regra de lint `S108`).
- Todos os imports inline dentro de métodos de teste precisam de
  `# noqa: PLC0415` se você não puder movê-los para o topo do arquivo
  (por exemplo, quando importados condicionalmente após um `pytest.skip`).
- Uma asserção por linha para testes de verdade compostos (regra de lint
  `PT018`).

O rastreador de melhorias (`benchmark/improvements.md`) é o log
persistente do que foi adicionado ao pipeline ao longo das versões. Quando
você adicionar uma funcionalidade substancial, adicione uma seção lá
descrevendo o que mudou, onde ela vive e quais testes a protegem.

---

## Glossário

- **AFL++** — Fuzzer greybox guiado por cobertura; o motor de execução aqui.
- **libAFLDriver** — Biblioteca estática que permite que harnesses do
  AFL++ usem a convenção de ponto de entrada do libFuzzer
  (`LLVMFuzzerTestOneInput`).
- **LCOV** — Formato padrão da indústria para arquivos de rastreamento de
  cobertura. Exportamos para ele via `llvm-cov export -format=lcov` e o
  analisamos nós mesmos.
- **`stack_top_hash`** — Um hash de 16 caracteres dos N frames superiores
  normalizados de um stack trace do ASan/UBSan. Usado para deduplicação de
  crashes.
- **Corpus persistente** — Diretório por harness em
  `<workspace>/corpus/harness_<id>/` que carrega as entradas interessantes
  do AFL entre iterações e reexecuções da mesma campanha.
- **Mutador inteligente** — Um `LLVMFuzzerCustomMutator` cujos tokens de
  splice são extraídos do próprio código-fonte do alvo
  (`generate_smart_mutator`).
- **Mutador customizado (libFuzzer)** — Uma função C fornecida pelo
  usuário, chamada pelo motor com total liberdade sobre como mutar um
  buffer; o AFL++ suporta a mesma ABI.
- **Ferramenta MCP** — Uma função decorada com FastMCP que o agente LLM
  pode chamar.
- **OSS-Fuzz / Fuzz-Introspector** — A infraestrutura de fuzzing de
  código aberto do Google e sua ferramenta companheira de análise de
  call-graph/cobertura. Várias funcionalidades deste taskflow (mutadores
  por formato, dedup por stack, relatório de call-graph + APIs não
  tocadas, harnesses multi-candidatos) são inspiradas nelas.

---

## Licença

Este projeto está licenciado sob os termos da licença de código aberto
MIT. Consulte o arquivo [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt) para os termos completos.

## Mantenedores

Veja [CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS) ou entre em contato com a equipe do GitHub
Security Lab.

## Suporte

Veja [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md) para detalhes sobre como obter ajuda com
este projeto.

## Agradecimentos

Este projeto é construído sobre os conceitos e técnicas do
[AFL++](https://github.com/AFLplusplus/AFLplusplus),
[OSS-Fuzz](https://github.com/google/oss-fuzz) e
[Fuzz-Introspector](https://github.com/ossf/fuzz-introspector).