Developer documentation¶

В рамках проекта FuzzRV основными директориями для работы являются:

• infra – в этой директории расположены скрипты и логика для сборки Docker-образов и запуска фаззинга. Здесь же находятся вспомогательные инструменты и настройки, необходимые для автоматизации.
• build – директория, которая формируется после компиляции фаззера. Содержит:
  • тесты, давшие новое покрытие (new coverage);
  • исходные сиды (seed corpus), с которых начинается фаззинг;
  • скомпилированный и исполняемый файл фаззера;
  • дополнительную директорию, куда помещаются тесты, завершившиеся ошибкой соответствующего санитайзера.
• projects – основная директория с проектами, готовыми к фаззингу. В каждом проекте находятся все необходимые файлы конфигурации (Dockerfile, build.sh и т.д.). По мере развития проекта эта директория пополняется новыми проектами.

Описание проекта¶

В каждом проекте, как минимум, должны присутствовать следующие файлы:

• build.sh – скрипт сборки и компиляции фаззера. Содержит информацию о процессе подготовки среды тестирования (этапы компиляции, генерация фаззинг-ядра, настройка параметров для тестовой среды).

• Dockerfile – файл, описывающий все зависимости и инструменты, необходимые для работы проекта в Docker-окружении (установка системных пакетов, тулчейна RISC-V, необходимых библиотек и т.д.). Обеспечивает воспроизводимость и независимость процесса фаззинга от внешней среды.

• project.yaml – конфигурационный файл, в котором указывается, какой движок фаззера (например, libFuzzer или AFL) используется, а также какие санитайзеры (AddressSanitizer, UndefinedBehaviorSanitizer) нужно задействовать. Определяет ключевые параметры тестирования.

• projectName_fuzzer.cpp – исходный код фаззера, содержащий функцию `LLVMFuzzerTestOneInput` (для libFuzzer) или аналогичную точку входа для выбранного движка, а также необязательные дополнительные мутаторы, инициализацию, вызовы тестируемой модели и т.п.

Изменения в файлах и создание собственных проектов¶

Все перечисленные файлы (build.sh, Dockerfile, project.yaml, projectName_fuzzer.cpp) могут подвергаться модификациям по мере необходимости:
- обновление версий пакетов и библиотек в Dockerfile;
- корректировка процесса сборки или фаззинга в build.sh;
- дополнение или изменение настроек фаззера (движок, санитайзеры) в project.yaml;
- доработка кода фаззера (новые мутаторы, иной порядок запуска тестируемой модели) в projectName_fuzzer.cpp.

Если требуется создать собственный проект для фаззинга, его необходимо разместить в директории projects и включить туда все необходимые конфигурационные файлы, аналогично уже существующим проектам. Такой подход обеспечивает гибкость и позволяет легко расширять FuzzRV новыми сценариями тестирования или менять окружение под конкретные цели и требования.

Список мутаторов¶

1. InsertLabelJumpsMutator
Добавляет новые метки и условные/безусловные переходы, изменяя логику исполнения кода.

2. StructuralArithmeticMutator
Меняет арифметические операции и значения (например, переключение `add` на `sub`, сдвиги меток и переходов), что даёт значительные изменения в логике.

3. ReplaceRandomInstructionsMutator
Заменяет найденные инструкции на случайные варианты (например, `add`, `sub`, `mul`, `div`, `and`), повышая разнообразие кода.

4. InsertRandomCSRMutator
Внедряет операции с системными регистрами (CSR), изменяя их и потенциально влияя на счётчики инструкций.

5. InsertRandomMemoryAccessMutator
Вставляет случайные операции работы с памятью (загрузку и запись), меняя поведение программы за счёт манипуляций с адресами и регистрами.