mxmssh/manulManul es un fuzzer paralelo guiado por cobertura para binarios de código abierto y de caja negra en Windows, Linux y MacOS
# Manul
Manul es un fuzzer paralelo guiado por cobertura para binarios de código abierto y caja negra en Windows, Linux y macOS (beta) escrito en Python puro.
# Inicio rápido
```
pip3 install psutil
git clone https://github.com/mxmssh/manul
cd manul
mkdir in
mkdir out
echo "AAAAAA" > in/test
python3 manul.py -i in -o out -n 4 "linux/test/test_afl @@"
```
### Instalación de Radamsa
```
sudo apt-get install gcc make git wget
git clone https://gitlab.com/akihe/radamsa.git && cd radamsa && make && sudo make install
```
No es necesario instalar radamsa en Windows, Manul se distribuye con la biblioteca nativa de radamsa en esta plataforma.
# Lista de CVEs públicos
| CVE IDs | Producto | Descubridor |
|----------------------------------------------|-----------|-------------|
| CVE-2019-9631 CVE-2019-7310 CVE-2019-9959 | Poppler | Maksim Shudrak |
| CVE-2018-17019 CVE-2018-16807 CVE-2019-12175 | Bro/Zeek | Maksim Shudrak |
Si encontraste un nuevo error usando Manul, por favor contáctame y te agregaré a la lista.
# Demostración
# Dependencias
0. Python3 (Python2 está obsoleto desde el 1 de enero de 2020, pero Manul aún debería funcionar bien con Python2)
1. [psutil](https://pypi.org/project/psutil/)
2. pywin32 (```pip install pywin32```) en la plataforma Windows (requerido solo para el modo de persistencia DBI).
# Fuzzing guiado por cobertura
Actualmente, Manul soporta dos tipos de instrumentación: basada en AFL (afl-gcc, afl-clang y [afl-clang-fast](https://github.com/mirrorer/afl/tree/master/llvm_mode)) y DBI.
## Fuzzing guiado por cobertura (modo de instrumentación AFL)
Instrumenta tu objetivo con ```afl-gcc``` o ```afl-clang-fast``` y ```Address Sanitizer``` (recomendado para mejores resultados). Por ejemplo:
```
CC=afl-gcc CXX=afl-g++ CFLAGS=-fsanitize=address CXXFLAGS=-fsanitize=address cmake <path_to_your_target>
make -j 8
```
```
USE_ASAN=1 CC=afl-clang-fast CXX=afl-clang-fast++ cmake <path_to_your_target>
make -j 8
```
Consulta [estas instrucciones](http://lcamtuf.coredump.cx/afl/QuickStartGuide.txt) para más detalles.
## Fuzzing guiado por cobertura en modo DBI
No necesitas instrumentar tu objetivo en este modo, pero necesitas descargar la última versión del framework DynamoRIO para Windows o Linux.
Manul se distribuye con clientes precompilados x86/x64 para Linux y Windows. Puedes encontrarlos en las siguientes carpetas:
```
linux/dbi_32|dbi_64/libbinafl.so (DynamoRIO client)
win/dbi_32|dbi_64/binafl.dll
```
Desafortunadamente, DynamoRIO no es compatible oficialmente en macOS.
### Usando DynamoRIO para fuzzear binarios de caja negra
Puedes encontrar los paquetes de la última versión de DynamoRIO en la [página de descarga de DynamoRIO](https://github.com/DynamoRIO/dynamorio/wiki/Downloads).
Tienes que descomentar las siguientes líneas en el archivo ```manul.config``` y proporcionar la ruta correcta al lanzador y cliente de DynamoRIO.
```
# Choose DBI framework to provide coverage back to Manul ("dynamorio" or "pin"). Example dbi = dynamorio
dbi = dynamorio
# If dbi parameter is not None the path to dbi engine launcher and dbi client should be specified.
dbi_root = /home/max/DynamoRIO/bin64/drrun
dbi_client_root = /home/max/manul/linux/dbi_64/libbinafl.so
dbi_client_libs = None
```
Además, puedes aumentar el rendimiento de tu campaña de fuzzing de caja negra usando fuzzing persistente en memoria. En este modo, debes indicarle a Manul que instrumente una función particular (sí, necesitas encontrarla desensamblando tu binario) y la ejecutará en un bucle descomentando las siguientes líneas:
```
dbi_persistence_mode = 1
dbi_target_module = afl_test
dbi_target_method = open_file
#dbi_target_offset = 0x3198 # optionally you can provide offset of this function instead of name
dbi_fuzz_iterations = 1000
```
Los autores de winAFL proporcionan una muy buena explicación de cómo funciona realmente [aquí](https://github.com/googleprojectzero/winafl/blob/master/readme_dr.md#in-app-persistence-mode). Manul usa una gran parte del código de la biblioteca de instrumentación de winAFL para comunicarse e instrumentar un objetivo.
NOTA IMPORTANTE: ¡Debes usar un lanzador de 32 bits y un cliente de 32 bits para fuzzear binarios de 32 bits, y un lanzador de 64 bits y un cliente de 64 bits para binarios de 64 bits!
#### Compilación de la biblioteca cliente de DynamoRIO
Para compilar la biblioteca de instrumentación, necesitas usar la última versión de [DynamoRIO](https://github.com/DynamoRIO/dynamorio/releases/download/). El código fuente de la biblioteca de instrumentación se puede encontrar en ```dbi_clients_src``` ubicado en la carpeta principal de Manul.
```
64-bit Linux
cd dbi_clients_src
wget <DynamoRIO-x86_64-Linux-X.XX.XXXX-X.tar.gz> - download the latest DynamoRIO
tar xvf DynamoRIO-x86_64-X.XX.XXXX-X.tar.gz
mkdir client_64
cd client_64
cmake ../dr_cov/ -DDynamoRIO_DIR=/home/max/manul/dbi_clients_src/DynamoRIO-x86_64-Linux-X.XX.XXXX-X.tar.gz/cmake
make
```
```
32-bit Linux
cd dbi_clients_src
wget <DynamoRIO-i386-Linux-X.XX.XXXX-X.tar.gz> - download the latest DynamoRIO
tar xvf DynamoRIO-x86_64-X.XX.XXXX-X.tar.gz
mkdir client_64
cd client_64
CFLAGS=-m32 CXXFLAGS=-m32 cmake ../dr_cov/ -DDynamoRIO_DIR=/home/max/manul/dbi_clients_src/DynamoRIO-i386-Linux-X.XX.XXXX-X.tar.gz/cmake
make
```
On Windows, the easiest way to compile the library would be to install Visual Studio (tested on 2017 & 2013 versions), launch ```VS20XX Cross Tools Command Prompt``` and run the following commands:
```
64-bit Windows
cd dbi_clients_src
<Download and extract the latest version of DynamoRIO>
mkdir client_64
cd client_64
cmake -G"Visual Studio 15 Win64" ..\dr_cov\ -DDynamoRIO_DIR=C:\Users\max\manul\dbi_clients_src\DynamoRIO-Windows-XXXX.XX.X.X\cmake
cmake --build . --config RelWithDebInfo (or just Debug if needed)
```
```
32-bit Windows
cd dbi_clients_src
<Download and extract the latest version of DynamoRIO>
mkdir client_32
cd client_32
cmake -G"Visual Studio 15" ..\dr_cov\ -DDynamoRIO_DIR=C:\Users\max\manul\dbi_clients_src\DynamoRIO-Windows-XXXX.XX.X.X\cmake
cmake --build . --config RelWithDebInfo (or just Debug if needed)
```
### Usando Intel PIN para fuzzear binarios de caja negra en Linux
Manul inicialmente soportaba fuzzing guiado por cobertura con Intel PIN, pero debido al bajo rendimiento y la alta sobrecarga de mantenimiento, ya no es compatible.
# Argumentos de línea de comandos
```
Example: python3 manul.py -i corpus -o out_dir -n 40 "target @@"
positional arguments:
target_binary The target binary and options to be executed (don't forget to include quotes e.g. "target e @@").
optional arguments:
-h, --help show this help message and exit
-n NFUZZERS Number of parallel fuzzers
-s Run dumb fuzzing (no code instrumentation)
-c CONFIG Path to config file with additional options (see Configuration File Options section below)
-r Restore previous session
Required parameters:
-i INPUT Path to directory with initial corpus
-o OUTPUT Path to output directory
```
# Opciones del archivo de configuración
Manul se distribuye con el archivo ```manul.config``` predeterminado donde el usuario puede encontrar todas las opciones compatibles y ejemplos de uso. Las opciones deben especificarse en el siguiente formato ```Formato: <nombre_opción> = <valor>```. El símbolo ```#``` se puede usar para ignorar una línea.
#### Diccionario
```dict = /home/max/dictionaries/test.dict```. La estrategia de mutación de AFL permite al usuario especificar una lista de tokens personalizados que se pueden insertar en lugares aleatorios del archivo fuzzeado. Manul soporta esta funcionalidad mediante esta opción (se prefieren rutas absolutas).
#### Pesos de mutadores
```mutator_weights=afl:7,radamsa:2,my_mutator:1```. Los pesos de mutadores permiten al usuario indicarle a Manul cuántas mutaciones por cada 10 ejecuciones debe realizar un determinado fuzzer. En este ejemplo, el mutador AFL se ejecutará en 7/10 mutaciones, Radamsa 2/10 y algún mutador personalizado ```my_mutator``` obtendrá 1/10. Si deseas deshabilitar un mutador, se le debe asignar un peso de 0 (por ejemplo, ```mutator_weights=afl:0,radamsa:1,my_mutator:9```).
#### Semilla determinista (Opción de Radamsa)
```deterministic_seed = False|True```. Al proporcionar ```True```, las mutaciones de Radamsa se volverán deterministas, por lo tanto, cada ejecución de Manul producirá las mismas salidas.
#### Mostrar resumen por hilo
```print_per_thread = False|True```. Al habilitar esta opción, Manul imprimirá un resumen para cada hilo que se ejecute en lugar del resumen total.
#### Deshabilitar rutas volátiles
```disable_volatile_bytes = False|True```. Al habilitar esta opción, Manul no incluirá en la lista negra las rutas volátiles.
#### Forkserver de AFL (solo UNIX)
```forkserver_on = False|True```. Habilita o deshabilita el [forkserver](https://lcamtuf.blogspot.com/2014/10/fuzzing-binary-without-execve.html) de AFL.
#### Opciones de DBI
```dbi = dynamorio|pin```. Esta opción le indica a Manul qué framework DBI se usará para instrumentar el objetivo.
```dbi_root = <path>```. Esta opción le indica a Manul dónde encontrar el lanzador principal del framework DBI.
```dbi_client_root = <path>```. Esta opción le indica a Manul dónde encontrar el cliente DBI para realizar la instrumentación.
```dbi_client_libs = name_#1,name_#2|None```. Esta opción se puede usar para especificar una lista de bibliotecas que necesitan ser instrumentadas junto con el objetivo principal (por ejemplo, tienes un ejecutable que carga la biblioteca objetivo y varias otras donde deseas buscar errores).
```dbi_persistence_mode = 0|1|2```. Esta opción se usa para elegir entre los modos persistentes de DBI. 0 - sin persistencia, 1 - persistencia estándar (envoltura de funciones), 2 - aún no soportado.
Si ```dbi-persistence_mode = 1|2```, se deben especificar las siguientes opciones:
```dbi_target_module = <module name>```. Manul intentará buscar la función objetivo en el módulo especificado aquí.
```dbi_target_method = <function name>```. Nombre de la función a envolver para persistencia.
```dbi_target_offset = <offset of function e.g. 0x3198>```. Desplazamiento de la función a envolver para persistencia. Esta opción se puede usar en lugar de ```dbi_target_method``` si los símbolos de depuración no están disponibles.
```dbi_fuzz_iterations = 500```. El número de iteraciones de fuzzing a ejecutar en memoria antes de que todo el programa se reinicie. Puedes ajustar este argumento para encontrar el valor que funcione mejor con tu objetivo.
```dbi_thread_coverage = False```. Instrumentar cobertura solo desde un hilo que ejecutó la función objetivo (aún no soportado).
#### Tiempo de espera (timeout)
```timeout = 10```. Tiempo de espera antes de matar el objetivo y enviar el siguiente caso de prueba.
#### init_wait
```init_wait = 1```. Esta opción se puede usar para configurar un tiempo de espera requerido para que el objetivo se inicialice.
#### Opciones de Netslave y Netmaster
Las opciones ```net_config_master``` y ```net_config_slave``` se usan para distribuir instancias de Manul a través de la red. Debes realizar los siguientes 3 pasos para ejecutar fuzzing distribuido.
1. Crea un archivo con una lista de hosts en el siguiente formato: ```IP:port``` donde se ejecutarán tus esclavos.
2. Inicia todas las instancias esclavas de Manul en máquinas remotas (con todas las opciones requeridas y la ruta al binario objetivo) y habilita la siguiente opción:
```net_config_slave = 0.0.0.0:1337```. Manul lanzará la instancia y esperará una conexión entrante de la instancia maestra en el puerto 1337.
3. Inicia la instancia maestra y proporciona el archivo con la lista de instancias esclavas creada en el Paso 1 usando ```net_config_master = file_name```.
#### Modo de depuración
```debug = False|True``` - imprime información de depuración.
```logging_enable = False|True``` - guarda información de depuración en el registro.
#### Logotipo
```manul_logo = False|True``` - imprime el logotipo de Manul al inicio.
#### Deshabilitar estadísticas
```no_stats = False|True``` - guardar estadísticas.
#### Frecuencia de sincronización de bitmap (5000 recomendado para modo DBI)
```sync_freq = 10000```. Permite al usuario cambiar la frecuencia de sincronización del bitmap de cobertura. Esta opción le indica a Manul con qué frecuencia debe sincronizar la cobertura entre instancias de fuzzing paralelas. Un valor más bajo disminuye el rendimiento pero aumenta la coordinación entre instancias.
#### Ruta personalizada para guardar salida
```#custom_path = test_path``` - esta opción permite guardar el caso de prueba en la carpeta personalizada (si el objetivo desea cargarlo desde algún lugar predefinido).
#### Fuzzing por línea de comandos (experimental)
```cmd_fuzzing = True|False```. Si esta opción está habilitada, Manul proporcionará la entrada al objetivo a través de la línea de comandos en lugar de guardarla en el archivo.
#### Ignorar señales
```user_signals = 6,2,1|None```. El usuario puede indicarle a Manul qué señales del objetivo deben ignorarse (no considerar como fallo).
#### Fuzzing por red (experimental)
```target_ip_port = 127.0.0.1:7715|None``` - utilizado para especificar la IP y el PUERTO del objetivo.
```target_protocol = tcp|tcp``` - utilizado para especificar el protocolo para enviar la entrada al objetivo a través de la red.
```net_sleep_between_cases = 0.0```. Esta opción se puede usar para definir un retraso entre los casos de prueba enviados al objetivo.
Actualmente, el fuzzing por red es una característica experimental (consulta los issues para más detalles).
# Agregar mutador personalizado
Se puede agregar un mutador personalizado en los siguientes tres pasos:
Paso 1. Crea un archivo Python (.py) y asígnale un nombre (por ejemplo, example_mutator.py)
Paso 2. Crea dos funciones ```def init(fuzzer_id)``` y ```def mutate(data)```. Consulta [example_mutator](https://github.com/mxmssh/manul/blob/master/example_mutator.py) para más detalles. Manul llamará a la función ```init``` durante la inicialización del fuzzing y a ```mutate``` para cada archivo que se proporcione al objetivo.
Paso 3. Habilita el mutador especificando su nombre usando ```mutator_weights``` en ```manul.config```. Por ejemplo, ```mutator_weights=afl:2,radamsa:0,example_mutator:8```.
NOTA: Los mutadores AFL y Radamsa siempre deben especificarse. Si deseas deshabilitar AFL o Radamsa, solo asigna un peso de 0.
## Detalles técnicos
Por determinar
## Pantalla de estado
