FuzzRV

h1. Developer documentation

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

* *infra* – в этой директории расположены скрипты и логика для сборки Docker-образов и запуска фаззинга. Здесь же находятся вспомогательные инструменты и настройки, необходимые для автоматизации.

* *build* – директория, которая формируется после компиляции фаззера. Содержит:

** тесты, давшие новое покрытие (new coverage);

** исходные сиды (seed corpus), с которых начинается фаззинг;

** скомпилированный и исполняемый файл фаззера;

** дополнительную директорию, куда помещаются тесты, завершившиеся ошибкой соответствующего санитайзера.

* *projects* – основная директория с проектами, готовыми к фаззингу. В каждом проекте находятся все необходимые файлы конфигурации (Dockerfile, build.sh и т.д.). По мере развития проекта эта директория пополняется новыми проектами.

h2. Описание проекта

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

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

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

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

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

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

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

- обновление версий пакетов и библиотек в *Dockerfile*;

- корректировка процесса сборки или фаззинга в *build.sh*;

- дополнение или изменение настроек фаззера (движок, санитайзеры) в *project.yaml*;

- доработка кода фаззера (новые мутаторы, иной порядок запуска тестируемой модели) в *projectName_fuzzer.cpp*.

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

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

1. **InsertLabelJumpsMutator**  

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

2. **StructuralArithmeticMutator**  

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

3. **ReplaceRandomInstructionsMutator**  

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

4. **InsertRandomCSRMutator**  

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

5. **InsertRandomMemoryAccessMutator**  

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