gitlab-org/security-products/protocol-fuzzer-ceEsta es la edición comunitaria del framework de fuzzing de protocolos de GitLab. Este framework está basado en Peach Fuzzer Professional con algunas características eliminadas.
:toc:
= Edición Comunitaria del Fuzzer de Protocolos de GitLab
Este proyecto se basa en Peach Fuzzer Professional v4 que fue https://about.gitlab.com/press/releases/2020-06-11-gitlab-acquires-peach-tech-and-fuzzit-to-expand-devsecops-offering.html[adquirido por GitLab] en 2020. Algunas características de Peach Fuzzer Professional fueron eliminadas y estarán disponibles como parte de GitLab en el futuro. Este proyecto reemplaza los proyectos Peach Fuzzer Community alojados en GitLab y también en Source Forge.
Como este código fue desarrollado originalmente por Peach Tech, puede haber referencias en todo el repositorio a personal, direcciones de correo electrónico, sitios web o capacidades específicas de Peach Tech. Estas se actualizarán con el tiempo para referirse a GitLab. Si encuentra alguna, no dude en abrir un MR para solicitar aclaración y/o actualizarla.
Siga las instrucciones de compilación local hasta que los binarios estén disponibles.
== Estructura del Repositorio
build::
Scripts de compilación para compilar el repositorio.
Esto incluye waf (el sistema de compilación utilizado por peach),
plantillas de asciidoctor y varios scripts utilizados por jenkins
para compilaciones de integración.
core::
Clases e interfaces comunes entre Peach de código abierto y cerrado.
docs::
Toda la documentación para la guía del usuario, la guía del desarrollador y las guías de prueba.
packer::
La plantilla y los scripts utilizados por packer (https://packer.io) para generar
la AMI de prueba alojada y la OVA de prueba local.
pro::
El código fuente de Peach Professional y las aplicaciones y pruebas asociadas.
tools::
Scripts necesarios para la compilación (lanzador nunit y generador de archivos *.exe.config).
== Flujo de Trabajo Git
Los scripts de compilación esperan que todos los mensajes de commit sigan un conjunto de reglas.
Los mensajes DEBEN comenzar con uno de los siguientes prefijos:
new: chg: .
No se permiten commits de fusión, y se recomienda que todos los PR
se aplasten en un solo commit.
fix:dev:La primera línea del mensaje de commit se utiliza para generar automáticamente el changelog orientado al cliente.
Las líneas siguientes del mensaje de commit pueden contener cualquier cosa y se ignoran durante la generación del changelog.
Si el mensaje de commit comienza con dev:, el commit se omitirá del changelog.
Los otros commits se clasifican como nuevo, cambiado o corregido.
== Instrucciones de Compilación Local
Peach admite la compilación en computadoras con Windows, Linux y OSX. Peach utiliza waf (https://waf.io/) como su sistema de compilación. Waf admite la idea de 'variantes de compilación' que se utiliza para compilar Peach para varias plataformas y arquitecturas.
Peach utiliza 11 variantes de compilación 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
Documentación::
doc
Waf compila fuera del árbol, lo que significa que los archivos intermedios y los binarios
de salida se colocan en un directorio diferente al del código fuente.
Para la compilación de peach, los archivos intermedios se colocan en el directorio slag/{variant}
y se instalan en el directorio output/{variant}.
Waf busca archivos wscript_build en todos los subdirectorios de la raíz
y ejecuta lo que contengan. Para la mayoría de los archivos wscript_build de nivel superior,
normalmente solo contienen la siguiente lista de subdirectorios en los que recurrir.
=== Prerrequisitos de compilación en Windows:
Add the following two registry entries via PowerShell:
=== Prerrequisitos de compilación en Linux:
=== Comandos de Compilación
Los comandos mínimos necesarios para compilar peach se muestran a continuación:
waf configure::
Este es el primer paso que debe ejecutarse para compilar peach.
Este paso es análogo a la fase autoconf de la compilación de bibliotecas linux. +
+
Waf intentará localizar todas las dependencias de compilación y guardará sus rutas.
Si no se puede localizar una dependencia de compilación para una variante específica,
la variante de compilación se marcará como no soportada.
Esto puede ser útil si solo desea compilar para linux_x86_64 pero no desea compilar documentación. +
+
La fase de configuración ejecutará el programa paket (https://fsprojects.github.io/Paket/) y obtendrá
todas las dependencias de terceros de nuget utilizando los requisitos enumerados en paket/paket.depenencies. +
+
NOTA: waf configure solo necesita ejecutarse una vez.
Para el flujo de trabajo normal del desarrollador que modifica fuentes de Peach, no
necesitará ejecutar este comando. Sin embargo, si realiza cambios en los scripts de compilación
(ubicados en el directorio build, o cambió el conjunto de herramientas de compilación instalado,
deberá volver a ejecutar este comando para que se pueda resolver la ruta de la herramienta actualizada. +
+
CONSEJO: Si ocurre un error porque no se puede localizar una herramienta requerida, intente
volver a ejecutar con mayor verbosidad. waf configure -v mostrará
cada dependencia que se está localizando, así como la ruta completa donde se detecta. +
+
La fase de configuración también es cómo la compilación de integración establece el número de versión.
Al ejecutar waf configure --buildtag=4.3.100, todos los artefactos compilados se
marcarán con el buildtag especificado. Si no se especifica ninguna opción, el buildtag
por defecto será 0.0.0.
waf build::
Este es el comando que compilará todos los componentes en el repositorio.
La compilación incluye la generación de archivos con marca de versión,
la ejecución de cualquier transpilación de código fuente,
la compilación del código fuente y el enlace de los resultados. +
+
Este comando es análogo a ejecutar make en linux. +
+
Todos los artefactos de la fase de compilación terminarán en el directorio slag/{variant}.
waf install::
Este comando instala las salidas del programa, así como todas las dependencias de bibliotecas,
en el directorio output/{variant}. +
+
Este comando es análogo a ejecutar make install en linux. +
+
El flujo de trabajo habitual del desarrollador en linux es ejecutar waf install --variant=linux_x86_64_debug
y luego ejecutar ./output/linux_x86_64_debug/bin/peach.
=== Comandos de Compilación Opcionales
waf pkg::
Esto genera los zips del instalador.
Para peach, hay dos zips, uno para uso interno (ejecución de pruebas unitarias/pruebas de integración)
y otro para uso externo (carga al sitio de descarga).
Los dos zips se almacenan en la carpeta output/{variant}/pkg.
Por último, este comando waf creará el zip del servidor de licencias local.
waf test::
Ejecuta todas las pruebas unitarias. Para ejecutar pruebas unitarias para la variante debug de windows x64,
puede ejecutar waf test --variant=win_x64_debug.
waf msvs2017::
Crea todos los archivos .csproj y el archivo Peach.sln para su uso con Visual Studio 2017.
waf zip:: Comprime todas las salidas de la fase de instalación en un solo artefacto.
=== Notas sobre Waf
El uso de Waf sigue la sintaxis: waf [comando] [opciones]
Para todos los comandos, la verbosidad se puede aumentar agregando uno o más argumentos -v.
Para todos los comandos excepto configure, se admiten las siguientes opciones:
--variant=xxx filtrará el comando a las variantes que contengan 'xxx' en su nombre.
Esto significa que --variant=4_d coincidirá con las variantes linux_x86_64_debug y win_x64_debug.-j1 controlará la paralelización de tareas de waf para que solo se ejecute 1 tarea a la vez.
Por defecto, waf ejecutará N tareas simultáneamente donde N corresponde al número de núcleos de CPU en el host.
Ejecutar solo una tarea a la vez a veces puede ayudar a solucionar errores de compilación.waf --help mostrará la lista completa de comandos y opciones admitidos.== Envío de Merge Requests
Guías
. Se deben proporcionar pruebas unitarias con la solicitud de extracción. . Uso correcto del registro. . Todas las merge requests pasarán por una revisión de código fuente.
Asegúrese de que el equipo de Peach y específicamente @mikeeddington estén al tanto de los plazos para que se acepten las merge requests. No es raro que las merge requests tarden varios meses en ser aceptadas de otra manera.
=== Registro
Peach utiliza NLog para el registro de mensajes de depuración/trazado.
Depuración:: Los mensajes de depuración deben usarse con moderación. Los clientes usan --debug para identificar problemas en sus pits. Es fundamental mantener esta salida concisa, mostrando solo la información necesaria para el usuario final.
Trazado:: Este es el nivel de registro que debe usarse para la salida que principalmente desean los desarrolladores de Peach o al diagnosticar un posible problema, pero no algo que el cliente quiera ver siempre.
=== Pruebas Unitarias
Se requiere que todas las solicitudes de extracción tengan pruebas unitarias que proporcionen una cobertura razonable de todas las funciones. NUnit es nuestro marco de pruebas unitarias. Antes de enviar una solicitud de extracción, verifique que todas las pruebas unitarias de Peach estén pasando.
=== Documentación
Todas las funciones de código en envío requieren documentación del producto. Esto podría ser documentación nueva para una corrección o similar que se está agregando, o una actualización de la documentación existente.