gitlab-org/security-products/protocol-fuzzer-ceQuesta è l'edizione community del framework di fuzzing dei protocolli di GitLab. Questo framework è basato su Peach Fuzzer Professional con alcune funzionalità rimosse.
:toc:
= GitLab Protocol Fuzzer Community Edition
Questo progetto è basato su Peach Fuzzer Professional v4 che è stato https://about.gitlab.com/press/releases/2020-06-11-gitlab-acquires-peach-tech-and-fuzzit-to-expand-devsecops-offering.html[acquisito da GitLab] nel 2020. Alcune funzionalità di Peach Fuzzer Profession sono state rimosse e saranno rese disponibili come parte di GitLab in futuro. Questo progetto sostituisce i progetti Peach Fuzzer Community ospitati su GitLab e anche su Source Forge.
Poiché questo codice è stato originariamente sviluppato da Peach Tech, potrebbero esserci riferimenti nel repository a personale, indirizzi email, siti web o capacità specifiche di Peach Tech. Questi verranno aggiornati nel tempo per fare riferimento a GitLab. Se ne trovi uno, sentiti libero di aprire un MR per chiedere chiarimenti e/o aggiornarlo.
Segui le istruzioni di build locale fino a quando non saranno disponibili i binari.
== Organizzazione del Repository
build::
Script di build per compilare il repository.
Include waf (il sistema di build utilizzato da peach),
template asciidoctor e vari script utilizzati da jenkins
per le build di integrazione.
core::
Classi e interfacce comuni tra Peach OSS e closed source.
docs::
Tutta la documentazione per la guida utente, la guida sviluppatore e le guide di prova.
packer::
Il template e gli script utilizzati da packer (https://packer.io) per generare
l'AMI di prova ospitata e l'OVA di prova on-prem.
pro::
Il codice sorgente per Peach Professional e le relative applicazioni e test.
tools::
Script necessari per la build (launcher nunit e generatore *.exe.config).
== Workflow Git
Gli script di build si aspettano che tutti i messaggi di commit seguano un insieme di regole.
I messaggi DEVONO iniziare con uno dei seguenti prefissi:
new: chg: fix: dev:.
Non sono consentiti merge commit e si raccomanda che tutte le PR
vengano compresse in un singolo commit.
La prima riga del messaggio di commit viene utilizzata per generare automaticamente il changelog visibile ai clienti.
Le righe successive del messaggio di commit possono contenere qualsiasi cosa e vengono ignorate durante la generazione del changelog.
Se il messaggio di commit inizia con dev:, il commit sarà omesso dal changelog.
Gli altri commit sono categorizzati come new, changed o fixed.
== Istruzioni per la Build Locale
Peach supporta la compilazione su computer Windows, Linux e OSX. Peach utilizza waf (https://waf.io/) come sistema di build. Waf supporta il concetto di 'varianti di build' che viene utilizzato per compilare Peach per varie piattaforme e architetture.
Peach utilizza 11 varianti di build diverse:
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
Documentazione::
doc
Waf build fuori dall'albero, il che significa che i file intermedi e i binari di output
vengono collocati in una directory diversa dal codice sorgente.
Per la build di peach, i file intermedi vengono inseriti nella directory slag/{variant}
e vengono installati nella directory output/{variant}.
Waf cerca i file wscript_build in tutte le sottodirectory della radice
ed esegue qualsiasi cosa essi contengano. Per la maggior parte dei file wscript_build di primo livello,
di solito contengono solo l'elenco delle sottodirectory da esplorare successivamente.
=== Prerequisiti per la Build su Windows:
Aggiungere le seguenti due voci di registro tramite PowerShell:
=== Prerequisiti per la Build su Linux:
=== Comandi di Build
I comandi minimi necessari per compilare peach sono mostrati di seguito:
waf configure::
Questo è il primo passo che deve essere eseguito per compilare peach.
Questo passo è analogo alla fase autoconf della compilazione di librerie linux. +
+
Waf cercherà di localizzare tutte le dipendenze di build e salverà i loro percorsi.
Se una dipendenza di build non può essere localizzata per una variante specifica,
la variante di build sarà contrassegnata come non supportata.
Questo può essere utile se si desidera compilare solo per linux_x86_64 ma non si vogliono compilare i documenti. +
+
La fase di configurazione eseguirà il programma paket (https://fsprojects.github.io/Paket/) e preleverà
tutte le dipendenze di terze parti da nuget utilizzando i requisiti elencati in paket/paket.depenencies. +
+
NOTA: waf configure deve essere eseguito solo una volta.
Per il normale flusso di lavoro dello sviluppatore di modifica dei sorgenti Peach, non sarà
necessario eseguire questo comando. Tuttavia, se si apportano modifiche agli script di build
(situati nella directory build, o se si cambia l'insieme di strumenti di build installati,
sarà necessario eseguire di nuovo questo comando per risolvere i percorsi aggiornati degli strumenti. +
+
SUGGERIMENTO: Se si verifica un errore perché uno strumento richiesto non può essere localizzato, provare a
eseguire di nuovo con maggiore verbosità. waf configure -v mostrerà
ogni dipendenza che viene localizzata e il percorso completo in cui viene rilevata. +
+
La fase di configurazione è anche il modo in cui la build di integrazione imposta il numero di versione.
Eseguendo waf configure --buildtag=4.3.100, tutti gli artefatti costruiti saranno
marcati con il buildtag specificato. Se non viene specificata alcuna opzione, il buildtag
predefinito è 0.0.0.
waf build::
Questo è il comando che compilerà tutti i bit nel repository.
La compilazione include la generazione di file con marche di versione,
l'esecuzione di eventuali trasposizioni di codice sorgente,
la compilazione del sorgente e il collegamento dei risultati. +
+
Questo comando è analogo all'esecuzione di make su linux. +
+
Tutti gli artefatti della fase di build finiranno nella directory slag/{variant}.
waf install::
Questo comando installa gli output del programma, nonché tutte le dipendenze delle librerie, nella directory output/{variant}. +
+
Questo comando è analogo all'esecuzione di make install su linux. +
+
Il flusso di lavoro tipico dello sviluppatore su linux è eseguire waf install --variant=linux_x86_64_debug
e quindi eseguire ./output/linux_x86_64_debug/bin/peach.
=== Comandi di Build Opzionali
waf pkg::
Genera gli zip del programma di installazione.
Per peach, ci sono due zip, uno per uso interno (esecuzione di test unitari/test di integrazione)
e uno per uso esterno (caricamento sul sito di download).
I due zip finiscono nella cartella output/{variant}/pkg.
Infine, questo comando waf creerà lo zip del server di licenza locale.
waf test::
Esegue tutti i test unitari. Per eseguire i test unitari per la variante debug Windows x64, si può eseguire
waf test --variant=win_x64_debug.
waf msvs2017::
Crea tutti i file .csproj e il file Peach.sln per l'uso con Visual Studio 2017.
waf zip:: Comprime tutti gli output della fase di installazione in un singolo artefatto.
=== Note su Waf
L'uso di Waf segue la sintassi: waf [comando] [opzioni]
Per tutti i comandi, la verbosità può essere aumentata aggiungendo uno o più argomenti -v.
Per tutti i comandi tranne configure, sono supportate le seguenti opzioni:
--variant=xxx filtra il comando alle varianti che contengono 'xxx' nel loro nome.
Ciò significa che --variant=4_d corrisponderà alle varianti linux_x86_64_debug e win_x64_debug.-j1 controlla la parallelizzazione delle attività di waf in modo che solo 1 attività possa essere eseguita alla volta.
Per impostazione predefinita, waf esegue N attività contemporaneamente, dove N corrisponde al numero di core della CPU dell'host.
Eseguire una sola attività alla volta può talvolta aiutare a risolvere gli errori di build.waf --help mostra l'elenco completo dei comandi e delle opzioni supportati.== Invio di Merge Request
Linee Guida
. Devono essere forniti test unitari con la pull request . Uso corretto della registrazione (logging) . Tutte le merge request passeranno attraverso una revisione del codice sorgente
Assicurati che il Team Peach e in particolare @mikeeddington sia a conoscenza di eventuali scadenze per l'accettazione delle merge request. Non è raro che le merge request richiedano diversi mesi per essere accettate altrimenti.
=== Registrazione (Logging)
Peach utilizza NLog per la registrazione di messaggi di debug/traccia.
Debug:: I messaggi di debug dovrebbero essere usati con parsimonia. I clienti usano --debug per identificare i problemi nei loro pit. È fondamentale mantenere questo output succinto, mostrando solo le informazioni necessarie per l'utente finale.
Traccia:: Questo è il livello di log che dovrebbe essere usato per l'output principalmente desiderato dagli sviluppatori Peach o durante la diagnosi di un possibile problema, ma non qualcosa che il cliente vorrebbe vedere sempre.
=== Test Unitari
Tutte le pull request devono includere test unitari che forniscano una copertura ragionevole di tutte le funzionalità. NUnit è il nostro framework di test unitari. Prima di inviare una pull request, verifica che tutti i test unitari di Peach siano superati.
=== Documentazione
Tutte le funzionalità del codice distribuito richiedono documentazione del prodotto. Potrebbe trattarsi di nuova documentazione per una correzione o simile, o di un aggiornamento alla documentazione esistente.