Это подтягивает `seclab-taskflow-agent` и `seclab-taskflows` (родительский)
транзитивно, поэтому каждая точечная ссылка вида
`seclab_taskflows.taskflows.audit.*`,
`seclab_taskflows.toolboxes.local_file_viewer`,
`seclab_taskflows.toolboxes.gh_file_viewer` и
`seclab_taskflows.configs.model_config` разрешается из родительского
дистрибутива во время выполнения.

---

## Содержание

1. [Что это такое](#what-this-is)
2. [Быстрый старт](#quick-start)
3. [Архитектура](#architecture)
4. [Пайплайн, этап за этапом](#the-pipeline-stage-by-stage)
5. [Цикл обратной связи по покрытию](#the-coverage-feedback-loop)
6. [Структурно-осведомлённый фаззинг](#structure-aware-fuzzing)
7. [Постоянный корпус между итерациями и кампаниями](#persistent-corpus-across-iterations-and-campaigns)
8. [Триаж и отчёты об уязвимостях](#triage-and-vulnerability-reports)
9. [Живая панель мониторинга](#live-dashboard)
10. [Выходные файлы](#output-files)
11. [Схема базы данных](#database-schema)
12. [Инструменты MCP (словарь агента)](#mcp-tools-the-agents-vocabulary)
13. [Настраиваемые параметры (переменные окружения)](#tunable-knobs-environment-variables)
14. [Расширение пайплайна](#extending-the-pipeline)
15. [Бенчмарк-проекты и результаты](#benchmark-projects-and-results)
16. [Ограничения и подводные камни](#limitations-and-gotchas)
17. [Предупреждение о безопасности](#security-warning)
18. [Разработка: тестирование, линтинг, участие](#development-testing-linting-contributing)
19. [Глоссарий](#glossary)

---

## Что это такое

Этот taskflow представляет собой полностью автономный пайплайн фаззинга. Получив GitHub-репозиторий
нативного проекта на C/C++, он:

1. установит AFL++ + clang/llvm/lcov + ctags/cscope/graphviz, если их нет,
2. получит исходный код,
3. определит кандидатов в цели фаззинга (парсеры, декодеры, валидаторы, …),
4. проанализирует систему сборки,
5. напишет одного или нескольких кандидатов в harness'ы на каждую цель, соберёт каждого как
   AFL-инструментированный `.afl` бинарник и как coverage-инструментированный `.cov` бинарник,
6. (опционально) отберёт кандидатов по 60-секундному покрытию и оставит лучших,
7. запустит цикл фаззинг/покрытие/улучшение с удвоением временных бюджетов,
8. проведёт триаж каждого краша, подтвердит, что ранее известные краши всё ещё воспроизводятся, и
   напишет по каждому крашу markdown-отчёт об уязвимости с вердиктами, эксплуатируемостью,
   предлагаемыми патчами и набросками регрессионных тестов,
9. построит граф вызовов в стиле Fuzz-Introspector + отчёт о нетронутых API для
   следующей кампании,
10. опубликует всё на живой HTML-панели мониторинга.

Пайплайн **в духе OSS-Fuzz**: он использует многие из тех же
техник (мутаторы и словари для каждого формата, структурно-осведомлённое сращивание токенов, улучшения harness'ов на основе покрытия, машиночитаемые отчёты,
дедуплицированные краши с хешированием стеков), но он гораздо меньше и самодостаточен.

---

## Быстрый старт```bash
# Inside the codespace (or a host with python + git available):
./scripts/fuzzing/run_fuzzing.sh tukaani-project/xz

## Архитектура

Три слоя, сверху вниз:```
┌────────────────────────────────────────────────────────────────────┐
│  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                           │
└────────────────────────────────────────────────────────────────────┘

На каждой итерации, для каждого харнесса агент:

1. Запрашивает `get_persistent_corpus_dir(harness_id)` для получения стабильного
   каталога корпуса этого харнесса.
2. Вызывает `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>,
   output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)`.
3. Вызывает `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue,
   output_dir=<run>/coverage)` для создания LCOV-трейсфайла и HTML-отчёта.
4. Вызывает `store_coverage_from_lcov(run_id, lcov_path, html_path)` для сохранения
   строки `coverage_report` + строк `coverage_gap` для каждого непокрытого элемента.
5. Вызывает `fold_queue_into_persistent_corpus(...)` для слияния очереди итерации
   AFL в постоянный корпус и запускает `cmin` для ограничения размера.
6. Читает `get_coverage_summary` + `get_coverage_gaps`, затем либо:
   - добавляет новое зерно (с тегом `coverage_feedback`) для достижения непокрытой
     ветви,
   - редактирует исходный код харнесса для вызова дополнительного API,
   - вызывает `enrich_dictionary_from_uncovered(...)` для автоматического добавления
     словарных записей для магических констант, необходимых AFL для прохождения
     проверки, либо
   - пропускает пробел (холодный путь ошибки / код вендора).
7. Вызывает `store_iteration_note(repo, iteration_number, harness_id, note=<одна
   строка с итогом>)`, чтобы временная шкала итераций на дашборде отслеживала, что
   изменилось.

**Обнаружение плато.** Цикл завершается досрочно, как только две последовательные
итерации обе дали прирост < `FUZZ_PLATEAU_THRESHOLD_PCT` (по умолчанию `1.0`)
абсолютных процентных пунктов покрытия строк.

---

## Структурно-осведомлённый фаззинг

Три взаимодополняющих механизма позволяют получать более сильные входные данные,
чем чистая побайтовая мутация.

### 1. Словари для каждого формата + пользовательские мутаторы

Для целей, чей `input_kind` соответствует известному формату, taskflow поставляет
готовые словари и исходные файлы `LLVMFuzzerCustomMutator` на C:

| Формат | Словарь | Мутатор | Примечания |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | Сплайсинг токенов, дублирование/удаление сбалансированных скобок, смена типа |
| `xml` | `xml.dict` | `xml_mutator.c` | Теги, сущности, DTD, токены billion-laughs |
| `regex` | `regex.dict` | `regex_mutator.c` | Якоря, классы, квантификаторы, реальные ReDoS-паттерны |
| `binary_tlv` | _(нет)_ | `binary_tlv_mutator.c` | Записи с префиксом длины: переполнение длины / дублирование / удаление |
| `png` | `png.dict` | _(переиспользует binary_tlv)_ | Словарь PNG + мутатор binary_tlv |

Они подхватываются автоматически функциями `write_initial_harnesses` (словарь
копируется рядом с зёрнами) и `build_harnesses` (мутатор линкуется в бинарник AFL).
Каждый мутатор делегирует 50% мутаций стандартному побайтовому мутатору AFL, чтобы
не потерять рандомизацию движка.

Чтобы добавить новый формат: поместите `<name>.dict` и/или `<name>_mutator.c` в
`src/seclab_taskflows/dictionaries/`, затем зарегистрируйте его в карте
`_FORMAT_ASSETS` в конце `fuzz_runner.py`.

### 2. Осведомлённый об исходниках (проектно-специфичный) умный мутатор

Для незнакомых форматов или когда нужны более сильные проектно-специфичные токены,
`generate_smart_mutator` сканирует собственные файлы `.c`/`.h` целевого репозитория
и генерирует C-файл `LLVMFuzzerCustomMutator`, чьи словари сплайсинга извлекаются из:

- строковых литералов с ≥3 буквенными символами (после фильтрации шума
  компилятора/лицензий, путей, заголовков, asm-ограничений, спецификаторов формата),
- 32-битных числовых констант из `#define`, `case` и `enum` (после фильтрации
  общего шума малых целых, такого как 0, 1, 256, 0xff…).

Доступны три фокуса:

| Фокус | Что сплайсится | Когда использовать |
|-------|-----------------|-------------|
| `strings` | Только строковые литералы проекта | Текстовые форматы (JSON, XML, YAML, CSV) |
| `constants` | Только 32-битные числовые магические значения | Бинарные протоколы, заголовки с магическими числами |
| `combined` | Оба | По умолчанию; обычно лучший |

Сочетайте `generate_smart_mutators(...)` (во множественном числе) с
`HARNESS_CANDIDATES >= 3`, чтобы каждый фокус стал кандидатом-харнессом в
квалификационном раунде.

### 3. Проектно-осведомлённый словарь AFL + обогащение на основе покрытия

Два взаимодополняющих инструмента создают и развивают словарь AFL `-x` по мере
продвижения кампании:

- **`generate_project_dictionary(source_root, output_path)`** — запускается один раз
  перед итерацией 1, статически извлекает тот же набор исходных токенов, что
  используется умным мутатором, и записывает его как словарь AFL. Числовые константы
  выводятся в ОБОИХ порядках байтов, чтобы фаззер мог удовлетворить
  `memcmp(x, &magic, 4)` независимо от порядка байтов хоста.

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path,
  uncovered_locations)`** — запускается после шага покрытия каждой итерации,
  сканирует окружающий исходный код на предмет условных проверок
  (`strncmp/memcmp/strstr`, `case 0xN:`, `== 0xN`, `== 'X'`) рядом с
  непокрытыми строками и ДОБАВЛЯЕТ любые новые токены в словарь. Идемпотентен:
  никогда не добавляет повторно уже присутствующую запись.

### 4. Операция сплайсинга корпуса

Когда в `generate_smart_mutator` передаётся `corpus_dir`, сгенерированный C также
получает оператор сплайсинга корпуса: при первом вызове он загружает до 64 файлов
из этого каталога (с ограничением 4 КиБ каждый), и с этого момента может
сплайсить случайные подобласти этих файлов в мутируемый вход. Это даёт мутатору
оператор в стиле рекомбинации, который стандартный havoc AFL выполняет плохо.
Сочетайте с `get_persistent_corpus_dir(...)`, чтобы библиотека сплайсинга
представляла собой «ремикс того, что AFL уже обнаружил».

---

## Постоянный корпус между итерациями и кампаниями

У каждого харнесса есть стабильный каталог корпуса по пути:```
<workspace>/corpus/harness_<id>/

---

## Выходные файлы

Все находятся в `~/.local/share/seclab-taskflow-agent/seclab-taskflows/`.

| Путь | Содержимое |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — цели, харнессы, запуски, покрытие, краши, вердикты, графы вызовов, предложения по харнессам, заметки об итерациях |
| `fuzz_runner/builds/` | Собранные бинарники `.afl` и `.cov` |
| `fuzz_runner/runs/` | Выходные каталоги AFL + файлы LCOV + HTML-отчёты о покрытии |
| `fuzz_runner/corpus/harness_<id>/` | Постоянный корпус для каждого харнесса (переносится между итерациями и кампаниями) |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Markdown-сводка кампании, краши сгруппированы по вердикту |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | Markdown-отчёт об уязвимости для каждого краша |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | Статический граф вызовов + наложение достигнутых/недостигнутых |

---

## Схема базы данных

Таблицы в `fuzz_context.db` (SQLite через SQLAlchemy):

| Таблица | Интересующие столбцы |
|-------|--------------------|
| `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` |

Миграции схемы находятся в `_migrate()` в `fuzz_context.py`. Новые ТАБЛИЦЫ
автоматически создаются через `Base.metadata.create_all()`; только для новых
СТОЛБЦОВ требуется `ALTER TABLE` на основе PRAGMA.

---

## Инструменты MCP (словарь агента)

Агент никогда не вызывает AFL или clang напрямую — он собирает конвейер,
вызывая инструменты MCP. Полный набор, сгруппированный по назначению:

### Персистентность (`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`

### Сборка / фаззинг / покрытие (`fuzz_runner.py`)

- `check_tooling`, `workspace_paths`
- `compile_harness` — собирает бинарники `.afl` и `.cov`
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — воспроизводит очередь AFL против бинарника `.cov`, экспортирует LCOV
- `extract_dictionary` — извлекает печатаемые строки из бинарника
- `package_reproducer` — упаковывает `.tgz` для одного краша

### Постоянный корпус (v8)

- `get_persistent_corpus_dir`, `fold_queue_into_persistent_corpus`

### Ресурсы форматов (C5)

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

### Умный мутатор + словарь с учётом проекта

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

Функции инструментов декорированы `@mcp.tool()` (FastMCP). В тестах
вызывайте их через атрибут `.fn`, например
`fr.run_afl_for.fn(afl_binary_path=..., ...)`.

---

## Настраиваемые параметры (переменные окружения)

| Переменная | По умолчанию | Назначение |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | Количество кандидатных харнессов, создаваемых для каждой цели. Установите 2 или 3 для конкуренции в стиле OSS-Fuzz-Gen. Этап квалификации запускает каждый в течение `QUALIFIER_SECONDS` и оставляет лучший по проценту строк. |
| `QUALIFIER_SECONDS` | `60` | Бюджет реального времени на каждого кандидата на этапе квалификации. |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | Прирост покрытия строк (в абсолютных п.п.), ниже которого две последовательные итерации считаются плато и цикл останавливается досрочно. |
| `FUZZ_DASHBOARD_PORT` | `8765` | Порт для живого дашборда. |
| `FUZZ_NO_DASHBOARD` | (не задано) | Установите `1`, чтобы пропустить запуск дашборда. |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | Таймаут подпроцесса на инструмент в `fuzz_runner` (секунды). |
| `LOCAL_SHELL_TIMEOUT` | `180` | Таймаут на команду в `local_shell` (секунды). |

Плюс стандартные переменные агента (`COPILOT_TOKEN`, `LOG_DIR`,
`FUZZ_CONTEXT_DIR`, …). Полный список см. в README в корне проекта.

---

## Расширение конвейера

### Добавление нового формата (мутатор + словарь)

1. Поместите `dictionaries/<name>.dict` (формат AFL `-x`) и/или
   `dictionaries/<name>_mutator.c` (пользовательский мутатор libFuzzer).
2. Зарегистрируйте в `_FORMAT_ASSETS` в конце `fuzz_runner.py`:   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

Соглашения кодовой базы (см. также `benchmark/improvements.md` для
версии этих соглашений в контексте истории кампаний):

- Используйте `os.environ.get(NAME) or "default"` вместо
  `os.environ.get(NAME, "default")`. Иначе пустые строки из подстановки
  шаблона YAML будут возвращены.
- Используйте `X | None` (PEP 604) в новых аннотациях, а не `Optional[X]`.
- Тесты вызывают MCP-инструменты через `.fn(...)`, а не через
  декорированное имя напрямую.
- Избегайте литералов `/tmp/...` в тестах — используйте pytest-фикстуру
  `tmp_path` (правило линтера `S108`).
- Все inline-импорты внутри методов тестов нуждаются в `# noqa: PLC0415`,
  если вы не можете переместить их в начало файла (например, при
  условном импорте после `pytest.skip`).
- Одно утверждение на строку для составных проверок истинности (правило
  линтера `PT018`).

Трекер улучшений (`benchmark/improvements.md`) — это постоянный
журнал того, что было добавлено в пайплайн across версий. Когда вы
добавляете существенную функцию, добавьте туда раздел с описанием того,
что изменилось, где это находится и какие тесты это защищают.

---

## Глоссарий

- **AFL++** — Грейбокс-фаззер с покрытием; здесь — движок исполнения.
- **libAFLDriver** — Статическая библиотека, позволяющая харнессам AFL++
  использовать соглашение о точке входа libFuzzer
  (`LLVMFuzzerTestOneInput`).
- **LCOV** — Отраслевой стандартный формат файла трассировки покрытия.
  Мы экспортируем в него через `llvm-cov export -format=lcov` и
  разбираем его сами.
- **`stack_top_hash`** — 16-символьный хеш верхних N нормализованных
  кадров трассировки стека ASan/UBSan. Используется для дедупликации
  крашей.
- **Постоянный корпус** — Директория для каждого харнесса по пути
  `<workspace>/corpus/harness_<id>/`, которая переносит интересные
  входные данные AFL между итерациями и повторными запусками одной и
  той же кампании.
- **Умный мутатор** — `LLVMFuzzerCustomMutator`, чьи токены для
  сплайсинга извлекаются из исходного кода самой цели
  (`generate_smart_mutator`).
- **Пользовательский мутатор (libFuzzer)** — Предоставляемая
  пользователем C-функция, вызываемая движком с полной свободой в
  отношении того, как мутировать буфер; AFL++ поддерживает тот же ABI.
- **MCP-инструмент** — Функция, декорированная FastMCP, которую может
  вызывать LLM-агент.
- **OSS-Fuzz / Fuzz-Introspector** — Инфраструктура Google для
  открытого фаззинга и сопутствующий инструмент анализа графа вызовов
  и покрытия. Некоторые функции этого taskflow (мутаторы для каждого
  формата, дедупликация по стеку, отчёт по графу вызовов и
  нетронутым API, многокандидатные харнессы) вдохновлены ими.

---

## Лицензия

Этот проект лицензирован на условиях открытой лицензии MIT. Полные
условия см. в файле [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt).

## Сопровождающие

См. [CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS) или свяжитесь с командой GitHub
Security Lab.

## Поддержка

См. [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md) для получения подробной информации о
том, как получить помощь по этому проекту.

## Благодарности

Этот проект построен на основе концепций и техник
[AFL++](https://github.com/AFLplusplus/AFLplusplus),
[OSS-Fuzz](https://github.com/google/oss-fuzz) и
[Fuzz-Introspector](https://github.com/ossf/fuzz-introspector).