gitlab-org/security-products/protocol-fuzzer-ceCeci est l'édition communautaire du framework de fuzzing de protocole de GitLab. Ce framework est basé sur Peach Fuzzer Professional avec certaines fonctionnalités supprimées.
:toc:
= Édition Communautaire du Fuzzer de Protocole GitLab
Ce projet est basé sur Peach Fuzzer Professional v4, qui a été https://about.gitlab.com/press/releases/2020-06-11-gitlab-acquires-peach-tech-and-fuzzit-to-expand-devsecops-offering.html[acquis par GitLab] en 2020. Certaines fonctionnalités de Peach Fuzzer Professional ont été supprimées et seront mises à disposition dans le cadre de GitLab à l’avenir. Ce projet remplace les projets Peach Fuzzer Community hébergés sur GitLab et aussi sur Source Forge.
Comme ce code a été initialement développé par Peach Tech, il peut y avoir des références tout au long du dépôt à du personnel, des adresses e-mail, des sites Web ou des capacités spécifiques à Peach Tech. Celles-ci seront mises à jour au fil du temps pour faire référence à GitLab. Si vous en trouvez une, n’hésitez pas à ouvrir une MR pour demander une clarification et/ou la mettre à jour.
Veuillez suivre les instructions de construction locales jusqu’à ce que les binaires soient disponibles.
== Structure du dépôt
build::
Scripts de construction pour compiler le dépôt.
Cela inclut waf (le système de construction utilisé par Peach),
les modèles asciidoctor, et divers scripts utilisés par Jenkins
pour les builds d’intégration.
core::
Classes et interfaces communes entre Peach OSS et la version fermée.
docs::
Toute la documentation pour le guide de l’utilisateur, le guide du développeur et les guides d’essai.
packer::
Le modèle et les scripts utilisés par packer (https://packer.io) pour générer
l’AMI d’essai hébergé et l’OVA d’essai sur site.
pro::
Le code source de Peach Professional et les applications et tests associés.
tools::
Scripts nécessaires à la construction (lanceur nunit et générateur de *.exe.config).
== Workflow Git
Les scripts de construction attendent que tous les messages de commit suivent un ensemble de règles.
Les messages DOIVENT commencer par l’un des préfixes suivants :
new: chg: fix: dev:.
Aucun commit de fusion n’est autorisé, et il est recommandé que toutes les PR
soient regroupées en un seul commit.
La première ligne du message de commit est utilisée pour générer automatiquement le journal des modifications destiné aux clients.
Les lignes suivantes du message de commit peuvent contenir n’importe quoi et sont ignorées lors de la génération du journal.
Si le message de commit commence par dev:, le commit sera omis du journal.
Les autres commits sont catégorisés comme nouveaux, modifiés ou corrigés.
== Instructions de construction locale
Peach prend en charge la compilation sur Windows, Linux et OS X. Peach utilise waf (https://waf.io/) comme système de construction. Waf prend en charge l’idée de « variantes de construction » utilisée pour compiler Peach pour diverses plateformes et architectures.
Peach utilise 11 variantes de construction différentes :
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
OS X::
osx_debug osx_release
Documentation::
doc
Waf construit hors arborescence, ce qui signifie que les fichiers intermédiaires et les binaires de sortie
sont placés dans un répertoire différent du code source.
Pour la construction Peach, les fichiers intermédiaires sont placés dans le répertoire slag/{variant}
et sont installés dans le répertoire output/{variant}.
Waf recherche les fichiers wscript_build dans tous les sous-répertoires de la racine
et exécute ce qu’ils contiennent. Pour la plupart des fichiers wscript_build de haut niveau,
ils contiennent généralement simplement la liste des sous-répertoires dans lesquels descendre.
=== Prérequis pour la construction sur Windows :
Ajoutez les deux entrées de registre suivantes via PowerShell :
=== Prérequis pour la construction sur Linux :
=== Commandes de construction
Les commandes minimales nécessaires pour compiler Peach sont indiquées ci-dessous :
waf configure::
C’est la première étape à exécuter pour compiler Peach.
Cette étape est analogue à la phase autoconf de la compilation de bibliothèques Linux. +
+
Waf essaiera de localiser toutes les dépendances de construction et enregistrera leurs chemins.
Si une dépendance de construction ne peut pas être localisée pour une variante spécifique,
la variante de construction sera marquée comme non prise en charge.
Cela peut être utile si vous souhaitez uniquement construire pour linux_x86_64 mais ne voulez pas construire la documentation. +
+
La phase de configuration exécutera le programme Paket (https://fsprojects.github.io/Paket/) et récupérera
toutes les dépendances tierces de NuGet en utilisant les exigences listées dans paket/paket.dependencies. +
+
REMARQUE : waf configure ne doit être exécuté qu’une seule fois.
Pour le flux de travail normal du développeur consistant à modifier les sources de Peach, vous n’aurez pas
besoin d’exécuter cette commande. Cependant, si vous apportez des modifications aux scripts de construction
(situés dans le répertoire build), ou si vous modifiez l’ensemble des outils de construction installés,
vous devrez réexécuter cette commande pour que les chemins d’outils mis à jour soient résolus. +
+
CONSEIL : Si une erreur se produit parce qu’un outil requis ne peut pas être localisé, essayez de
réexécuter avec une verbosité accrue. waf configure -v affichera
chaque dépendance en cours de localisation ainsi que le chemin complet où elle est détectée. +
+
La phase de configuration est également la façon dont la construction d’intégration définit le numéro de version.
En exécutant waf configure --buildtag=4.3.100, tous les artefacts construits seront
estampillés avec le buildtag spécifié. Si aucune option n’est spécifiée, le buildtag
par défaut est 0.0.0.
waf build::
C’est la commande qui compilera tous les bits du dépôt.
La compilation inclut la génération de fichiers estampillés avec la version,
l’exécution de toute transpilation de code source,
la compilation de la source et l’édition des liens des résultats. +
+
Cette commande est analogue à l’exécution de make sur Linux. +
+
Tous les artefacts de la phase de construction se retrouveront dans le répertoire slag/{variant}.
waf install::
Cette commande installe les sorties du programme, ainsi que toutes les dépendances de bibliothèque, dans le répertoire output/{variant}. +
+
Cette commande est analogue à l’exécution de make install sur Linux. +
+
Le flux de travail habituel du développeur sous Linux est d’exécuter waf install --variant=linux_x86_64_debug
puis d’exécuter ./output/linux_x86_64_debug/bin/peach.
=== Commandes de construction optionnelles
waf pkg::
Cela génère les archives d’installation.
Pour Peach, il y a deux archives, une pour usage interne (exécution de tests unitaires/tests d’intégration)
et une pour usage externe (téléchargement sur le site de téléchargement).
Les deux archives atterrissent dans le dossier output/{variant}/pkg.
Enfin, cette commande waf créera l’archive zip du serveur de licence local.
waf test::
Exécute tous les tests unitaires. Pour exécuter les tests unitaires pour la variante de débogage Windows x64, vous pouvez exécuter
waf test --variant=win_x64_debug.
waf msvs2017::
Crée tous les fichiers .csproj et le fichier Peach.sln pour une utilisation avec Visual Studio 2017.
waf zip:: Compresse toutes les sorties de la phase d’installation en un seul artefact.
=== Remarques sur Waf
L’utilisation de Waf suit la syntaxe : waf [command] [options]
Pour toutes les commandes, la verbosité peut être augmentée en ajoutant un ou plusieurs arguments -v.
Pour toutes les commandes sauf configure, les options suivantes sont prises en charge :
--variant=xxx filtrera la commande pour les variantes contenant 'xxx' dans leur nom.
Cela signifie que --variant=4_d correspondra aux variantes linux_x86_64_debug et win_x64_debug.-j1 contrôlera la parallélisation des tâches de waf afin qu’une seule tâche puisse s’exécuter à la fois.
Par défaut, waf exécute N tâches simultanément, où N correspond au nombre de cœurs CPU sur l’hôte.
Exécuter une seule tâche à la fois peut parfois aider à résoudre les erreurs de construction.waf --help affichera la liste complète des commandes et options prises en charge.== Soumission de demandes de fusion
Directives
. Des tests unitaires doivent être fournis avec la pull request . Utilisation correcte de la journalisation . Toutes les demandes de fusion passeront par une revue de code source
Assurez-vous que l’équipe Peach et en particulier @mikeeddington sont informés des échéances pour obtenir l’acceptation des demandes de fusion. Il n’est pas rare que les demandes de fusion prennent plusieurs mois pour être acceptées autrement.
=== Journalisation
Peach utilise NLog pour la journalisation des messages de débogage/trace.
Débogage:: Les messages de débogage doivent être utilisés avec parcimonie. Les clients utilisent --debug pour identifier les problèmes dans leurs pits. Il est essentiel de garder cette sortie concise, avec seulement les informations nécessaires à l’affichage pour l’utilisateur final.
Trace:: C’est le niveau de journalisation à utiliser pour les sorties principalement souhaitées par les développeurs Peach ou lors du diagnostic d’un problème éventuel, mais pas quelque chose que le client voudrait toujours voir.
=== Tests unitaires
Toutes les pull requests doivent inclure des tests unitaires qui fournissent une couverture raisonnable de toutes les fonctionnalités. NUnit est notre framework de test unitaire. Avant de soumettre une pull request, vérifiez que tous les tests unitaires de Peach réussissent.
=== Documentation
Toutes les fonctionnalités du code livré nécessitent une documentation produit. Cela peut être une nouvelle documentation pour une correction ou similaire ajoutée, ou une mise à jour de la documentation existante.