gitlab-org/security-products/protocol-fuzzer-ceDies ist die Community-Edition von GitLabs Protocol Fuzzing Framework. Dieses Framework basiert auf dem Peach Fuzzer Professional, bei dem einige Funktionen entfernt wurden.
:toc:
= GitLab Protocol Fuzzer Community Edition
Dieses Projekt basiert auf Peach Fuzzer Professional v4, das 2020 https://about.gitlab.com/press/releases/2020-06-11-gitlab-acquires-peach-tech-and-fuzzit-to-expand-devsecops-offering.html[von GitLab übernommen] wurde. Einige Funktionen von Peach Fuzzer Professional wurden entfernt und werden in Zukunft als Teil von GitLab verfügbar sein. Dieses Projekt ersetzt die Peach Fuzzer Community-Projekte, die auf GitLab und auch Source Forge gehostet wurden.
Da dieser Code ursprünglich von Peach Tech entwickelt wurde, gibt es möglicherweise Verweise im gesamten Repository auf Mitarbeiter, E-Mail-Adressen, Websites oder Funktionen, die für Peach Tech spezifisch sind. Diese werden im Laufe der Zeit aktualisiert, um auf GitLab zu verweisen. Wenn Sie einen finden, können Sie gerne einen MR eröffnen, um eine Klärung zu bitten und/oder ihn zu aktualisieren.
Bitte folgen Sie den lokalen Build-Anweisungen, bis Binärdateien verfügbar sind.
== Repository-Aufbau
build::
Build-Skripte zum Kompilieren des Repositorys. Dies umfasst waf (das von Peach verwendete Build-System), Asciidoctor-Vorlagen und verschiedene Skripte, die von Jenkins für Integrations-Builds verwendet werden.
core::
Gemeinsame Klassen und Schnittstellen zwischen OSS und Closed-Source-Peach.
docs::
Die gesamte Dokumentation für das Benutzerhandbuch, Entwicklerhandbuch und Testleitfäden.
packer::
Die Vorlage und Skripte, die von Packer (https://packer.io) verwendet werden, um das gehostete Test-AMI und die On-Prem-Test-OVA zu erstellen.
pro::
Der Quellcode für Peach Professional und die zugehörigen Anwendungen und Tests.
tools::
Skripte, die für den Build benötigt werden (nunit-Launcher und *.exe.config-Generator).
== Git-Workflow
Die Build-Skripte erwarten, dass alle Commit-Nachrichten einem Satz von Regeln folgen. Nachrichten MÜSSEN mit einem der folgenden Präfixe beginnen: new: chg: fix: dev:. Merge-Commits sind nicht erlaubt, und es wird empfohlen, dass alle PRs in einen einzelnen Commit zusammengefasst werden.
Die erste Zeile der Commit-Nachricht wird verwendet, um automatisch das kundenorientierte Changelog zu generieren. Die folgenden Zeilen der Commit-Nachricht können alles enthalten und werden bei der Changelog-Generierung ignoriert. Wenn die Commit-Nachricht mit dev: beginnt, wird der Commit aus dem Changelog ausgelassen. Die anderen Commits werden entweder als neu, geändert oder behoben kategorisiert.
== Lokale Build-Anweisungen
Peach unterstützt die Kompilierung auf Windows-, Linux- und OSX-Computern. Peach verwendet waf (https://waf.io/) als Build-System. Waf unterstützt das Konzept der 'Build-Varianten', das zum Kompilieren von Peach für verschiedene Plattformen und Architekturen verwendet wird.
Peach verwendet 11 verschiedene Build-Varianten:
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
Dokumentation::
doc
Waf baut 'out of tree', was bedeutet, dass die Zwischendateien und Ausgabebinärdateien in einem anderen Verzeichnis als der Quellcode abgelegt werden. Für den Peach-Build werden Zwischendateien im Verzeichnis slag/{variant} abgelegt und im Verzeichnis output/{variant} installiert.
Waf sucht in allen Unterverzeichnissen des Stammverzeichnisses nach wscript_build-Dateien und führt aus, was darin steht. Bei den meisten wscript_build-Dateien der obersten Ebene enthalten sie normalerweise nur die nächste Liste von Unterverzeichnissen, in die rekursiv vorgegangen werden soll.
=== Windows-Build-Voraussetzungen:
Fügen Sie die folgenden zwei Registrierungseinträge über PowerShell hinzu:
=== Linux-Build-Voraussetzungen:
=== Build-Befehle
Die minimalen Befehle, die zum Kompilieren von peach benötigt werden, sind unten aufgeführt:
waf configure::
Dies ist der erste Schritt, der ausgeführt werden muss, um peach zu kompilieren.
Dieser Schritt ist analog zur autoconf-Phase der Linux-Bibliothekskompilierung. +
+
Waf wird versuchen, alle Build-Abhängigkeiten zu lokalisieren und ihre Pfade zu speichern.
Wenn eine Build-Abhängigkeit für eine bestimmte Variante nicht gefunden werden kann,
wird die Build-Variante als nicht unterstützt markiert.
Dies kann nützlich sein, wenn Sie nur für linux_x86_64 bauen möchten, aber keine Dokumentation erstellen wollen. +
+
Die Konfigurationsphase wird das Programm Paket (https://fsprojects.github.io/Paket/) ausführen und
alle Abhängigkeiten von Drittanbietern von NuGet mithilfe der in paket/paket.dependencies aufgeführten Anforderungen abrufen. +
+
HINWEIS: waf configure muss nur einmal ausgeführt werden.
Für den normalen Entwickler-Workflow, bei dem Sie Peach-Quellen ändern, müssen Sie
diesen Befehl nicht erneut ausführen. Wenn Sie jedoch Änderungen an den Build-Skripten vornehmen
(die sich im Verzeichnis build befinden) oder wenn Sie den installierten Satz von Build-Tools ändern,
müssen Sie diesen Befehl erneut ausführen, damit die aktualisierten Tool-Pfade aufgelöst werden können. +
+
TIPP: Wenn ein Fehler auftritt, weil ein erforderliches Tool nicht gefunden werden kann, versuchen Sie,
es mit erhöhter Ausführlichkeit erneut auszuführen. waf configure -v zeigt jede Abhängigkeit,
die gefunden wird, sowie den vollständigen Pfad, an dem sie erkannt wird. +
+
Die Konfigurationsphase ist auch die Art und Weise, wie der Integrations-Build die Versionsnummer festlegt.
Durch Ausführen von waf configure --buildtag=4.3.100 werden alle erstellten Artefakte mit dem
angegebenen Buildtag versehen. Wenn keine Option angegeben wird, wird der Buildtag standardmäßig auf 0.0.0 gesetzt.
waf build::
Dies ist der Befehl, der alle Bits im Repository kompiliert.
Die Kompilierung umfasst das Generieren von versionierten Dateien,
das Ausführen von Quellcode-Transpilation,
das Kompilieren des Quellcodes und das Verknüpfen der Ergebnisse. +
+
Dieser Befehl ist analog zum Ausführen von make unter Linux. +
+
Alle Artefakte aus der Build-Phase landen im Verzeichnis slag/{variant}.
waf install::
Dieser Befehl installiert die Programmausgaben sowie alle Bibliotheksabhängigkeiten in das Verzeichnis output/{variant}. +
+
Dieser Befehl ist analog zum Ausführen von make install unter Linux. +
+
Der übliche Entwickler-Workflow für Linux ist es, waf install --variant=linux_x86_64_debug auszuführen
und dann ./output/linux_x86_64_debug/bin/peach zu starten.
=== Optionale Build-Befehle
waf pkg::
Dies erzeugt die Installer-ZIPs.
Für Peach gibt es zwei ZIPs, eine für die interne Verwendung (Ausführen von Unit-Tests/Integrationstests)
und eine für die externe Verwendung (Hochladen auf die Download-Seite).
Die beiden ZIPs landen im Ordner output/{variant}/pkg.
Schließlich erstellt dieser Waf-Befehl das lokale Lizenzserver-ZIP.
waf test::
Führt alle Unit-Tests aus. Um Unit-Tests für die Windows x64-Debug-Variante auszuführen, können Sie
waf test --variant=win_x64_debug ausführen.
waf msvs2017::
Erstellt alle .csproj-Dateien und die Peach.sln-Datei zur Verwendung mit Visual Studio 2017.
waf zip:: Packt alle Ausgaben aus der Installationsphase in ein einzelnes Artefakt.
=== Waf-Notizen
Die Waf-Nutzung folgt der Syntax: waf [Befehl] [Optionen]
Für alle Befehle kann die Ausführlichkeit durch Hinzufügen eines oder mehrerer -v-Argumente erhöht werden.
Für alle Befehle außer configure werden die folgenden Optionen unterstützt:
--variant=xxx filtert den Befehl auf Varianten, die 'xxx' in ihrem Namen enthalten.
Das bedeutet, dass --variant=4_d die Varianten linux_x86_64_debug und win_x64_debug matcht.-j1 steuert die Aufgabenparallelisierung von waf, sodass immer nur eine Aufgabe gleichzeitig ausgeführt werden kann.
Standardmäßig führt waf N Aufgaben gleichzeitig aus, wobei N der Anzahl der CPU-Kerne auf dem Host entspricht.
Das Ausführen nur einer einzelnen Aufgabe kann manchmal bei der Fehlersuche von Build-Fehlern helfen.waf --help zeigt die vollständige Liste der unterstützten Befehle und Optionen an.== Einreichen von Merge Requests
Richtlinien
. Unit-Tests müssen mit dem Pull-Request bereitgestellt werden . Korrekte Verwendung der Protokollierung . Alle Merge Requests durchlaufen eine Quellcode-Überprüfung
Stellen Sie sicher, dass das Peach-Team und insbesondere @mikeeddington über etwaige Fristen für die Annahme von Merge Requests informiert ist. Es ist nicht ungewöhnlich, dass Merge Requests sonst mehrere Monate bis zur Annahme benötigen.
=== Protokollierung
Peach verwendet NLog zur Protokollierung von Debug-/Trace-Nachrichten.
Debug:: Debug-Nachrichten sollten sparsam verwendet werden. Kunden verwenden --debug, um Probleme in ihren Pit-Dateien zu identifizieren. Es ist entscheidend, diese Ausgabe prägnant zu halten und nur die für den Endbenutzer erforderlichen Informationen anzuzeigen.
Trace:: Dies ist die Protokollierungsebene, die für Ausgaben verwendet werden sollte, die hauptsächlich von Peach-Entwicklern gewünscht werden oder bei der Diagnose eines möglichen Problems, aber nicht etwas, das der Kunde immer sehen möchte.
=== Unit-Tests
Alle Pull-Requests müssen Unit-Tests enthalten, die eine angemessene Abdeckung aller Funktionen bieten. NUnit ist unser Unit-Test-Framework. Überprüfen Sie vor dem Einreichen eines Pull-Requests, ob alle Peach-Unit-Tests bestanden werden.
=== Dokumentation
Alle ausgelieferten Codefunktionen erfordern Produktdokumentation. Dies kann eine neue Dokumentation für eine Korrektur oder ähnliches sein, die hinzugefügt wird, oder eine Aktualisierung der vorhandenen Dokumentation.