gitlab-org/security-products/protocol-fuzzer-ceЭто общедоступная версия фреймворка для фаззинга протоколов от GitLab. Этот фреймворк основан на Peach Fuzzer Professional с удалением некоторых функций.
:toc:
= GitLab Protocol Fuzzer Community Edition
Этот проект основан на Peach Fuzzer Professional v4, который был https://about.gitlab.com/press/releases/2020-06-11-gitlab-acquires-peach-tech-and-fuzzit-to-expand-devsecops-offering.html[приобретён GitLab] в 2020 году. Некоторые функции Peach Fuzzer Professional были удалены и будут доступны в составе GitLab в будущем. Этот проект заменяет проекты Peach Fuzzer Community, размещённые на GitLab, а также на Source Forge.
Поскольку этот код изначально был разработан Peach Tech, в репозитории могут встречаться ссылки на сотрудников, адреса электронной почты, веб-сайты или возможности, специфичные для Peach Tech. Со временем они будут обновлены для ссылки на GitLab. Если вы найдёте такой фрагмент, не стесняйтесь открыть MR, чтобы запросить разъяснение и/или обновить его.
Пожалуйста, следуйте инструкциям по локальной сборке, пока не станут доступны бинарные сборки.
== Структура репозитория
build::
Скрипты сборки для компиляции репозитория.
Сюда входят waf (система сборки, используемая Peach),
шаблоны Asciidoctor и различные скрипты, используемые Jenkins
для интеграционных сборок.
core::
Общие классы и интерфейсы между открытой и закрытой версиями Peach.
docs::
Вся документация для руководства пользователя, руководства разработчика и руководств по пробной версии.
packer::
Шаблон и скрипты, используемые packer (https://packer.io) для создания
пробного AMI и пробного OVA для локального развёртывания.
pro::
Исходный код Peach Professional и связанных приложений и тестов.
tools::
Скрипты, необходимые для сборки (запускатор nunit и генератор *.exe.config).
== Git-рабочий процесс
Скрипты сборки ожидают, что все сообщения коммитов соответствуют определённым правилам.
Сообщения ДОЛЖНЫ начинаться с одного из следующих префиксов:
new: chg: .
Слияния коммитов (merge commits) не допускаются, и рекомендуется, чтобы все PR
были сжаты в один коммит.
fix:dev:Первая строка сообщения коммита используется для автоматической генерации списка изменений для клиентов.
Последующие строки сообщения коммита могут содержать что угодно и игнорируются при генерации списка изменений.
Если сообщение коммита начинается с dev:, коммит будет опущен из списка изменений.
Остальные коммиты классифицируются как новые, изменённые или исправленные.
== Инструкции по локальной сборке
Peach поддерживает компиляцию на компьютерах с Windows, Linux и OSX. Peach использует waf (https://waf.io/) в качестве системы сборки. Waf поддерживает концепцию «вариантов сборки», которая используется для компиляции Peach для различных платформ и архитектур.
Peach использует 11 различных вариантов сборки:
Windows::
win_x86_debug win_x86_release win_x64_debug win_x64_release
Linux::
linux_x86_debug linux_x86_release linux_x86_64_debug linux_x86_64_release
OSX::
osx_debug osx_release
Документация::
doc
Waf выполняет сборку вне дерева исходников, то есть промежуточные файлы и выходные
бинарные файлы помещаются в каталог, отличный от исходного кода.
Для сборки Peach промежуточные файлы помещаются в каталог slag/{variant}
и устанавливаются в каталог output/{variant}.
Waf ищет файлы wscript_build во всех подкаталогах корня
и выполняет то, что в них написано. Для большинства файлов wscript_build верхнего уровня
они обычно содержат только следующий список подкаталогов для рекурсивного обхода.
=== Предварительные требования для сборки в Windows:
Добавьте следующие две записи реестра через PowerShell:
=== Предварительные требования для сборки в Linux:
=== Команды сборки
Минимальные команды, необходимые для компиляции Peach, показаны ниже:
waf configure::
Это первый шаг, который необходимо выполнить для компиляции Peach.
Этот шаг аналогичен фазе autoconf при компиляции библиотек Linux. +
+
Waf попытается найти все зависимости сборки и сохранит их пути.
Если зависимость сборки не может быть найдена для конкретного варианта,
вариант сборки будет помечен как неподдерживаемый.
Это может быть полезно, если вы хотите собрать только для linux_x86_64, но не хотите собирать документацию. +
+
Фаза конфигурации запустит программу Paket (https://fsprojects.github.io/Paket/) и загрузит
все сторонние зависимости из nuget, используя требования, перечисленные в paket/paket.dependencies. +
+
ПРИМЕЧАНИЕ: waf configure нужно запустить только один раз.
Для обычного рабочего процесса разработчика с изменением исходных кодов Peach вам не
нужно будет запускать эту команду. Однако, если вы вносите изменения в скрипты сборки
(находящиеся в каталоге build) или меняете установленный набор инструментов сборки,
вам потребуется перезапустить эту команду, чтобы обновлённые пути к инструментам были разрешены. +
+
СОВЕТ: Если возникает ошибка из-за того, что необходимый инструмент не найден, попробуйте
перезапустить с повышенной детализацией. waf configure -v покажет
каждую зависимость, которая обнаруживается, а также полный путь, по которому она найдена. +
+
Фаза конфигурации также используется для установки номера версии при интеграционной сборке.
При выполнении waf configure --buildtag=4.3.100 все собранные артефакты будут
помечены указанным buildtag. Если опция не указана, buildtag
по умолчанию равен 0.0.0.
waf build::
Это команда, которая скомпилирует все компоненты в репозитории.
Компиляция включает генерацию файлов с отметками версии,
выполнение любой транспиляции исходного кода,
компиляцию исходников и связывание результатов. +
+
Эта команда аналогична выполнению make в Linux. +
+
Все артефакты фазы сборки будут помещены в каталог slag/{variant}.
waf install::
Эта команда устанавливает выходные файлы программы, а также все зависимости библиотек, в каталог output/{variant}. +
+
Эта команда аналогична выполнению make install в Linux. +
+
Обычный рабочий процесс разработчика в Linux — выполнить waf install --variant=linux_x86_64_debug
и затем запустить ./output/linux_x86_64_debug/bin/peach.
=== Дополнительные команды сборки
waf pkg::
Создаёт установочные архивы zip.
Для Peach существует два zip-архива: один для внутреннего использования (запуск модульных/интеграционных тестов)
и один для внешнего использования (загрузка на сайт загрузок).
Оба zip-архива попадают в папку output/{variant}/pkg.
Наконец, эта команда waf создаёт локальный zip-архив сервера лицензий.
waf test::
Запускает все модульные тесты. Чтобы запустить модульные тесты для варианта windows x64 debug, выполните
waf test --variant=win_x64_debug.
waf msvs2017::
Создаёт все файлы .csproj и файл Peach.sln для использования с Visual Studio 2017.
waf zip:: Упаковывает все выходные данные фазы установки в единый артефакт.
=== Примечания к Waf
Использование waf следует синтаксису: waf [команда] [опции]
Для всех команд детализацию можно увеличить, добавив один или несколько аргументов -v.
Для всех команд, кроме configure, поддерживаются следующие опции:
--variant=xxx отфильтрует команду для вариантов, содержащих 'xxx' в имени.
Это означает, что --variant=4_d будет соответствовать вариантам linux_x86_64_debug и win_x64_debug.-j1 управляет распараллеливанием задач waf, так что одновременно может выполняться только одна задача.
По умолчанию waf запускает N задач одновременно, где N соответствует количеству ядер ЦП на хосте.
Запуск только одной задачи за раз может иногда помочь в устранении ошибок сборки.waf --help отобразит полный список поддерживаемых команд и опций.== Отправка запросов на слияние
Рекомендации
. К запросу на слияние должны прилагаться модульные тесты . Корректное использование журналирования . Все запросы на слияние пройдут проверку исходного кода
Убедитесь, что команда Peach и особенно @mikeeddington осведомлены о любых сроках, необходимых для принятия запросов на слияние. В противном случае нередки случаи, когда запросы на слияние принимаются в течение нескольких месяцев.
=== Журналирование
Peach использует NLog для журналирования отладочных/трассировочных сообщений.
Debug:: Отладочные сообщения должны использоваться экономно. Клиенты используют --debug для выявления проблем в своих тестовых стендах. Крайне важно, чтобы этот вывод был кратким и содержал только информацию, необходимую конечному пользователю.
Trace:: Это уровень журнала, который следует использовать для вывода, в основном необходимого разработчикам Peach или при диагностике возможной проблемы, но не того, что клиент хотел бы видеть постоянно.
=== Модульные тесты
Все запросы на слияние должны содержать модульные тесты, обеспечивающие разумное покрытие всех функций. NUnit — это наша среда модульного тестирования. Перед отправкой запроса на слияние убедитесь, что все модульные тесты Peach проходят успешно.
=== Документация
Все поставляемые функции кода требуют документации продукта. Это может быть новая документация для исправления или аналогичного дополнения, либо обновление существующей документации.