diff --git a/docs/config/index.md b/docs/config/index.md index 020d21e..29adcdc 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -1,4 +1,4 @@ -# Конфигурационный файл Sydf-fuzz +# Конфигурационный файл Sydr-fuzz * TOC {:toc} @@ -338,6 +338,8 @@ path = "/target_fuzzer" args = "-dict=/json.dict -jobs=6 /corpus" cmin = true set_cover_merge = true +proto_packer_path = "/packer" +use_ft_coverage = false [libfuzzer.env] ASAN_OPTIONS = "allocator_may_return_null=0" ``` @@ -371,6 +373,16 @@ M - число аварийных завершений, зависаний и oo позволяет использовать для минимизации опцию libFuzzer `set_cover_merge`. Если параметр выключен, для минимизации используется опция `merge`. +**proto_packer_path** - путь до packer-утилиты для гибридного фаззинга структурированных данных при +помощи libFuzzer с [LPM](https://github.com/google/libprotobuf-mutator) в паре с Sydr. +Утилита выполняет двустороннюю конвертацию между целевым форматом входных данных и protobuf-сообщениями. +При наличии данного параметра в конфигурационном файле обязательно присутствие таблицы `[sydr]`. + +**use_ft_coverage** - булевый параметр (по умолчанию выключен), который позволяет +учитывать метрику features (ft:) libFuzzer'а для отслеживания прироста покрытия. По +умолчанию на факт прироста покрытия влияет только метрика coverage (cov:). При фаззинге +Go-приложений (go-fuzz) метрика coverage отсутсвует, поэтому feature используется всегда. + **[libfuzzer.env]** - таблица, содержащая значения переменных окружения, которые будут выставлены для каждого запускаемого процесса libFuzzer. Каждая строка таблицы задаёт строковую переменную, имя которой совпадает с именем соответствующей переменной окружения. @@ -391,6 +403,7 @@ path = "/target_fuzzer" args = "-dict=/json.dict -jobs=6 /corpus" cmin = true set_cover_merge = true +use_ft_coverage = false ld_preload = false [atheris.env] ASAN_OPTIONS = "allocator_may_return_null=0" @@ -426,8 +439,10 @@ args = "--cp=/path/to/java/classes/ --asan -jobs=6 /corpus" target_class = "TargetClass" cmin = true set_cover_merge = true +use_ft_coverage = false java = "/path/to/jvm/launcher/java" jacocolib = "/path/to/jacoco/lib" +jacoco_args = "excludes=com.code_intelligence.jazzer.*\\:com.sun.tools.attach.VirtualMachine" [jazzer.env] LD_LIBRARY_PATH = "/path/to/native/libraries/" ``` @@ -447,6 +462,12 @@ jacocolib = "/path/to/jacoco/lib" **jacocolib** - путь до jar файлов библиотеки jacoco (необходимо для сбора покрытия, по умолчанию: `/usr/local/lib/jacoco/lib`). +**jacoco_args** - дополнительные аргументы для библиотеки JaCoCo, которые передаются через опцию +`--additional_jvm_args`. Параметр ожидает строку формата "arg1=value1,arg2=value2". С помощью данного +параметра можно указать аргумент `excludes`, который позволяет избежать ошибок с одинаковыми именами +разных классов при сборе покрытия. Аргумент `destfile` всегда задается автоматически, поэтому он +не может быть указан в данном параметре. + Jazzer поддерживает фаззинг C/C++ библиотек, загруженных JVM, например, через `System.load()`. Иногда требуется добавить пути, в которых будет производится поиск разделяемых библиотек. Сделать это можно с помощью таблицы `[jazzer.env]`, указав значение @@ -471,6 +492,7 @@ path = "/target_fuzzer" args = "-i=target_lib /corpus -- -dict=/json.dict -jobs=6" cmin = true set_cover_merge = true +use_ft_coverage = false ld_preload = false [jazzer_js.env] ASAN_OPTIONS = "allocator_may_return_null=0" @@ -591,6 +613,8 @@ use_minicover = false как глобальный .NET инструмент, то он будет по умолчанию находиться в `$HOME/.dotnet/tools`. Параметр не обязателен, если путь добавлен в `$PATH` (в докере `sydr/ubuntu20.04-sydr-fuzz` уже добавлен). +**proto_to_native_cov** - булевый параметр (по умолчанию `false`), который указывает, нужно ли конвертировать во время сбора покрытия результирующий корпус. Используется только при указанном в таблице `libfuzzer` параметре `proto_packer_path`. + Таблица **[cov.env]** в случае C#-кода не используется, так как переменные окружения для сбора покрытия не используются в `minicover` и `AltCover`. diff --git a/docs/misc/index.md b/docs/misc/index.md index 332fd46..388888e 100644 --- a/docs/misc/index.md +++ b/docs/misc/index.md @@ -88,6 +88,11 @@ int main(int argc, char** argv) Таким же образом, из libFuzzer обертки можно получить обертки для AFL++. +При использовании libFuzzer с [LPM](https://github.com/google/libprotobuf-mutator?tab=readme-ov-file#integrating-with-libfuzzer) в обертке с помощью +макроса `DEFINE_PROTO_FUZZER` предлагается реализовать функцию `TestOneProtoInput`, которая +получает в качестве входных данных protobuf-сообщение. Поэтому перед вызовом целевой функции +обертка дополнительно должна осуществлять его [преобразование к соответствующему формату](https://chromium.googlesource.com/chromium/src/+/main/testing/libfuzzer/libprotobuf-mutator.md#Write-the-Fuzz-Target-and-Conversion-Code). + ### Обертка AFL++ Для AFL++ написание отдельной обертки не требуется, можно полностью использовать diff --git a/docs/sydr-fuzz/index.md b/docs/sydr-fuzz/index.md index ebdf04f..68d1f6f 100644 --- a/docs/sydr-fuzz/index.md +++ b/docs/sydr-fuzz/index.md @@ -1,5 +1,5 @@ # Гибридный фаззер Sydr-fuzz - + * TOC {:toc} @@ -508,6 +508,12 @@ CASR отчетов в DefectDojo. Использование данной оп анализа в рамках продукта (по умолчанию складывается из имени конфигурационного файла и даты). +Для аккумуляции отчетов с найденными ранее ошибками можно использовать +переменную среды `CASR_PREV_CLUSTERS_DIR`, указав путь к предыдущей кластерной +структуре (например `CASR_PREV_CLUSTERS_DIR=/casr`). +Указанная директория будет скопирована в выходную директорию проекта, а новые +аварийные завершения и их отчёты будут в ней накапливаться. + ### Опции удаления аварийных завершений из корпуса $ sydr-fuzz rm-crashes -h @@ -730,17 +736,6 @@ Sydr в режиме проверки предикатов безопаснос $ ls name-out/aflplusplus/afl_main-worker/queue | grep "sync:sydr-worker" -Поддерживается возможность одновременного запуска libFuzzer, AFL++ и Sydr (опционален). -Для этого в конфигурационном файле должны пристутствовать таблицы для всех -вышеперечисленных инструментов. Никаких дополнительных опций/настроек задавать -не нужно. При указании всех трех таблиц будет произведен запуск фаззеров и -символьного исполнителя. AFL++ синхонизирован с инструментом Sydr по обычной стратегии, -однако рабочая директория libFuzzer'a будет задана для AFL++ как директория -внешненго фаззера (через опцию `-F`). Sydr попеременно выбирает входные данные от фаззеров -и подкладывает сгенерированные в рабочую директорию libFuzzer'а, -из которой впоследствии только уникальные (с точки зрения `afl-showmap`) -попадают в выходную директорию AFL++ в корпус Sydr (`aflplusplus/sydr-worker/queue`). - По завершении фаззинга результаты работы будут сохранены в `name-out/crashes`. Рекомендуется воспользоваться комнандой `cmin` (см. следующий раздел) для агрегации фаззинг-корпуса в `name-out/corpus`. В противном случае @@ -749,6 +744,33 @@ Sydr в режиме проверки предикатов безопаснос либо разбит по директориям AFL++ (`name-out/aflplusplus/*-worker/queue`) и libFuzzer (`name-out/libfuzzer/queue`). +### Ensemble-фаззинг + +Поддерживается возможность одновременного запуска libFuzzer, AFL++ и +Sydr (ensemble фаззинг). Для этого в конфигурационном файле должны присутствовать +таблицы для всех вышеперечисленных инструментов. Никаких дополнительных +опций/настроек задавать не нужно. При указании всех трех таблиц будет +произведен запуск фаззеров и символьного исполнителя. Следующий инпут для запуска +Sydr выбирается в соответствии с выбранной стратегией (по умолчанию - прирост +покрытия) поочередно из каждого фаззера. + +Синхронизация между инструментами во время ensemble-фаззинга устроена +следующим образом: + +- AFL++/Sydr: в общей для AFL директории `name-out/aflplusplus` +создается директория `sydr-worker/queue`, куда сохраняются сгенерированные +Sydr инпуты. Поскольку число таких инпутов может быть очень велико, +производится дополнительная минимизация с помощью afl-showmap. +- libFuzzer/Sydr: Sydr генерирует новые инпуты напрямую в директорию +корпуса libFuzzer'а `name-out/corpus` (в случае ensemble фаззинга -- +`name-out/libfuzzer/queue`). Все непригодившиеся инпуты Sydr'а (которые +не были импортированы фаззером) удаляются из корпуса через 1 минуту. +- AFL++/libFuzzer: директория корпуса libFuzzer передается в AFL++ +через опцию -F (внешний фаззер). +- libFuzzer/AFL++: новые инпуты из корпуса основного инстанса AFL++ +периодически копируются в корпус libFuzzer'а. Через 1 минуту после этого, +все скопированные файлы из корпуса удаляются. + ## Минимизация корпуса Чтобы минимизировать корпус, надо запустить команду `cmin`: