gitlab-org/security-products/protocol-fuzzer-ceEsta é a edição comunitária do framework de fuzzing de protocolos do GitLab. Este framework é baseado no Peach Fuzzer Professional com alguns recursos removidos.
:toc:
= GitLab Protocol Fuzzer Community Edition
Este projeto é baseado no Peach Fuzzer Professional v4, que foi https://about.gitlab.com/press/releases/2020-06-11-gitlab-acquires-peach-tech-and-fuzzit-to-expand-devsecops-offering.html[adquirido pela GitLab] em 2020. Algumas funcionalidades do Peach Fuzzer Professional foram removidas e serão disponibilizadas como parte do GitLab no futuro. Este projeto substitui os projetos Peach Fuzzer Community hospedados no GitLab e também no Source Forge.
Como este código foi originalmente desenvolvido pela Peach Tech, pode haver referências em todo o repositório a pessoal, endereços de e-mail, sites ou capacidades específicas da Peach Tech. Elas serão atualizadas ao longo do tempo para se referirem ao GitLab. Se encontrar alguma, sinta-se à vontade para abrir um MR para pedir esclarecimentos e/ou atualizá-la.
Por favor, siga as instruções de compilação local até que os binários estejam disponíveis.
== Estrutura do Repositório
build::
Scripts de compilação para compilar o repositório.
Isso inclui o waf (sistema de compilação usado pelo Peach),
templates asciidoctor e vários scripts usados pelo Jenkins
para compilações de integração.
core::
Classes e interfaces comuns entre o Peach OSS e o Peach fechado.
docs::
Toda a documentação para o guia do usuário, guia do desenvolvedor e guias de teste.
packer::
O template e os scripts usados pelo packer (https://packer.io) para gerar
a AMI de teste hospedada e a OVA de teste on-premise.
pro::
O código-fonte do Peach Professional e dos aplicativos e testes associados.
tools::
Scripts necessários para a compilação (lançador nunit e gerador de *.exe.config).
== Fluxo de Trabalho Git
Os scripts de compilação esperam que todas as mensagens de commit sigam um conjunto de regras.
As mensagens DEVEM começar com um dos seguintes prefixos:
new: chg: .
Nenhum commit de merge é permitido, e é recomendado que todos os PRs
sejam squashados em um único commit.
fix:dev:A primeira linha da mensagem de commit é usada para gerar automaticamente o changelog voltado para o cliente.
As linhas subsequentes da mensagem de commit podem conter qualquer coisa e são ignoradas durante a geração do changelog.
Se a mensagem de commit começar com dev:, o commit será omitido do changelog.
Os outros commits são categorizados como novo, alterado ou corrigido.
== Instruções de Compilação Local
O Peach suporta compilação em computadores Windows, Linux e OSX. O Peach usa o waf (https://waf.io/) como seu sistema de compilação. O Waf suporta a ideia de 'variantes de compilação', que é usada para compilar o Peach para várias plataformas e arquiteturas.
O Peach usa 11 variantes de compilação diferentes:
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
Documentação::
doc
O Waf compila fora da árvore, ou seja, os arquivos intermediários e binários de saída
são colocados em um diretório diferente do código-fonte.
Para a compilação do Peach, os arquivos intermediários são colocados no diretório slag/{variant}
e são instalados no diretório output/{variant}.
O Waf procura por arquivos wscript_build em todos os subdiretórios da raiz
e executa o que estiver neles. Para a maioria dos arquivos wscript_build de nível superior,
eles normalmente contêm apenas a próxima lista de subdiretórios nos quais recorrer.
=== Pré-requisitos de compilação no Windows:
Adicione as seguintes duas entradas de registro via PowerShell:
=== Pré-requisitos de compilação no Linux:
=== Comandos de Compilação
Os comandos mínimos necessários para compilar o Peach são mostrados abaixo:
waf configure::
Este é o primeiro passo que deve ser executado para compilar o Peach.
Este passo é análogo à fase autoconf da compilação de bibliotecas Linux. +
+
O Waf tentará localizar todas as dependências de compilação e salvará seus caminhos.
Se uma dependência de compilação não puder ser localizada para uma variante específica,
a variante de compilação será marcada como não suportada.
Isso pode ser útil se você quiser compilar apenas para linux_x86_64, mas não quiser compilar a documentação. +
+
A fase de configuração executará o programa Paket (https://fsprojects.github.io/Paket/) e buscará
todas as dependências de terceiros do nuget usando os requisitos listados em paket/paket.dependencies. +
+
NOTA: waf configure só precisa ser executado uma vez.
Para o fluxo de trabalho normal do desenvolvedor de modificar as fontes do Peach, você não
precisará executar este comando. No entanto, se você fizer alterações nos scripts de compilação
(localizados no diretório build, ou se alterar o conjunto instalado de ferramentas de compilação,
precisará executar novamente este comando para que o caminho atualizado da ferramenta seja resolvido. +
+
DICA: Se ocorrer um erro porque uma ferramenta necessária não pode ser localizada, tente
executar novamente com verbosidade aumentada. waf configure -v exibirá
cada dependência que está sendo localizada, bem como o caminho completo onde é detectada. +
+
A fase de configuração também é como a compilação de integração define o número da versão.
Executando waf configure --buildtag=4.3.100, todos os artefatos compilados serão
carimbados com o buildtag especificado. Se nenhuma opção for especificada, o buildtag
padrão é 0.0.0.
waf build::
Este é o comando que compilará todos os bits no repositório.
A compilação inclui gerar arquivos com versão,
executar qualquer transpilação de código-fonte,
compilar o código-fonte e vincular os resultados. +
+
Este comando é análogo a executar make no Linux. +
+
Todos os artefatos da fase de compilação terminarão no diretório slag/{variant}.
waf install::
Este comando instala as saídas do programa, bem como todas as dependências de biblioteca, no diretório output/{variant}. +
+
Este comando é análogo a executar make install no Linux. +
+
O fluxo de trabalho usual do desenvolvedor para Linux é executar waf install --variant=linux_x86_64_debug
e então executar ./output/linux_x86_64_debug/bin/peach.
=== Comandos de Compilação Opcionais
waf pkg::
Isso gera os zips do instalador.
Para o Peach, há dois zips, um para uso interno (execução de testes unitários/testes de integração)
e um para uso externo (upload para o site de download).
Os dois zips vão para a pasta output/{variant}/pkg.
Por fim, este comando waf criará o zip do servidor de licenças local.
waf test::
Executa todos os testes unitários. Para executar testes unitários para a variante debug x64 do Windows, você pode executar
waf test --variant=win_x64_debug.
waf msvs2017::
Cria todos os arquivos .csproj e o arquivo Peach.sln para uso com o Visual Studio 2017.
waf zip:: Compacta todas as saídas da fase de instalação em um único artefato.
=== Notas sobre o Waf
O uso do Waf segue a sintaxe: waf [comando] [opções]
Para todos os comandos, a verbosidade pode ser aumentada adicionando um ou mais argumentos -v.
Para todos os comandos, exceto configure, as seguintes opções são suportadas:
--variant=xxx filtrará o comando para variantes que contenham 'xxx' em seu nome.
Isso significa que --variant=4_d corresponderá às variantes linux_x86_64_debug e win_x64_debug.-j1 controlará a paralelização de tarefas do waf para que apenas 1 tarefa possa ser executada por vez.
Por padrão, o waf executará N tarefas simultaneamente, onde N corresponde ao número de núcleos de CPU no host.
Executar apenas uma tarefa por vez pode ajudar na solução de problemas de erros de compilação.waf --help exibirá a lista completa de comandos e opções suportados.== Submissão de Merge Requests
Diretrizes
. Testes unitários devem ser fornecidos com o pull request . Uso correto de logging . Todos os merge requests passarão por uma revisão de código-fonte
Certifique-se de que o Time Peach e especificamente @mikeeddington esteja ciente de quaisquer prazos para que os merge requests sejam aceitos. Não é incomum que merge requests levem vários meses para serem aceitos caso contrário.
=== Logging
O Peach usa NLog para logging de mensagens de debug/trace.
Debug:: Mensagens de debug devem ser usadas com moderação. Os clientes usam --debug para identificar problemas em seus pits. É fundamental manter esta saída concisa, apenas com as informações necessárias para o usuário final exibir.
Trace:: Este é o nível de log que deve ser usado para saída desejada principalmente por desenvolvedores Peach ou ao diagnosticar um possível problema, mas não algo que o cliente queira ver sempre.
=== Testes Unitários
Todos os pull requests são obrigados a ter testes unitários que forneçam cobertura razoável de todos os recursos. NUnit é nosso framework de teste unitário. Antes de submeter um pull request, verifique se todos os testes unitários do Peach estão passando.
=== Documentação
Todos os recursos de código enviado exigem documentação do produto. Isso pode ser uma nova documentação para uma correção ou similar sendo adicionada, ou uma atualização da documentação existente.