frelatage

pip3 install frelatage


O Fuzzer Python que o mundo merece

Instalação    |    Como funciona    |    Recursos    |    Usar o Frelatage    |    Configuração

Frelatage é uma biblioteca de fuzzing Python baseada em cobertura que pode ser usada para fuzzar código Python. O desenvolvimento do Frelatage foi inspirado por vários outros fuzzers, incluindo AFL/AFL++, Atheris e PythonFuzz. O principal objetivo do projeto é aproveitar as melhores características desses fuzzers e reuni-las em uma nova ferramenta para fuzzar aplicações Python de forma eficiente.

AVISO: Este projeto está em estágio alfa e ainda pode causar muitos comportamentos inesperados. O Frelatage não deve ser usado em ambiente de produção neste momento.

Requisitos

Python 3

Instalação

Instalar com pip (recomendado)

pip3 install frelatage

Ou compilar a partir do código-fonte

Recomendado para desenvolvedores. Ele clona automaticamente o branch principal do repositório frelatage e instala a partir do código-fonte.

# Clona automaticamente o repositório Frelatage e instala o Frelatage a partir do código-fonte
bash <(wget -q https://raw.githubusercontent.com/Rog3rSm1th/Frelatage/main/scripts/autoinstall.sh -O -)

Como funciona

A ideia por trás do design do Frelatage é o uso de um algoritmo genético para gerar mutações que cubram o máximo de código possível. O funcionamento de um ciclo de fuzzing pode ser resumido aproximadamente com este diagrama:

graph TB

    m1(Mutação 1) --> |input| function(Função fuzzada)
    m2(Mutação 2) --> |input| function(Função fuzzada)
    mplus(Mutação ...) --> |input| function(Função fuzzada)
    mn(Mutação n) --> |input| function(Função fuzzada)
    
    function --> generate_reports(Gerar relatórios)
    generate_reports --> rank_reports(Classificar relatórios)  
    rank_reports --> select(Selecionar n melhores relatórios)
    
    select --> |mutate| nm1(Mutação 1) & nm2(Mutação 2) & nmplus(Mutação ...) & nmn(Mutação n)
    
    subgraph Mutações do ciclo
    direction LR
    m1
    m2
    mplus
    mn
    end
    
    subgraph Mutações do próximo ciclo
    direction LR
    nm1
    nm2
    nmplus
    nmn
    end
     
    style function fill:#5388e8,stroke:white,stroke-width:4px

Recursos

Fuzzing de diferentes tipos de argumentos:

• String
• Int
• Float
• Lista
• Tupla
• Dicionário

Fuzzing de arquivos

O Frelatage permite fuzzar uma função passando um arquivo como entrada.

Eficiência do fuzzer

• Corpus
• Dicionário

Usar o Frelatage

Fuzzar um parâmetro clássico

import frelatage
import my_vulnerable_library

def MyFunctionFuzz(data):
  my_vulnerable_library.parse(data)

input = frelatage.Input(value="initial_value")
f = frelatage.Fuzzer(MyFunctionFuzz, [[input]])
f.fuzz()

Fuzzar um parâmetro de arquivo

O Frelatage oferece a possibilidade de fuzzar parâmetros de entrada do tipo arquivo. Para inicializar o valor desses arquivos, você deve criar arquivos na pasta de entrada (./in por padrão).

Se quisermos inicializar o valor de um arquivo usado para fuzzar, podemos fazer assim:

echo "initial value" > ./in/input.txt

E então executar o fuzzer:

import frelatage
import my_vulnerable_library

def MyFunctionFuzz(data):
  my_vulnerable_library.load_file(data)

input = frelatage.Input(file=True, value="input.txt")
f = frelatage.Fuzzer(MyFunctionFuzz, [[input]])
f.fuzz()

Fuzzar vários métodos usando decoradores (experimental)

import frelatage
import my_vulnerable_library

input = frelatage.Input(file=True, value="input.txt")

@frelatage.instrument([[input]])
def MyFunctionFuzz_1(data):
  my_vulnerable_library.load_file(data)

@frelatage.instrument([[input]])
def MyFunctionFuzz_1(data):
  my_vulnerable_library.load_file_but_different(data)
# E assim por diante

# Isso fuzzará os métodos instrumentados um após o outro
frelatage.Fuzzer.fuzz_all()

Carregar vários arquivos em um corpus de uma só vez

Se você precisar carregar vários arquivos em um corpus de uma só vez (útil se você usar um corpus grande), você pode usar a função embutida do Frelatage load_corpus. Esta função retorna uma lista de inputs.

load_corpus(directory: str, file_extensions: list) -> list[Input]

• directory: Subdiretório do diretório de entrada (caminho relativo), por exemplo ./, ./images
• file_extensions: Lista de extensões de arquivo a serem incluídas nas entradas do corpus, por exemplo ["jpeg", "gif"], ["pdf"]

import frelatage
import my_vulnerable_library

def MyFunctionFuzz(data):
  my_vulnerable_library.load_file(data)
  my_vulnerable_library.load_file(data2)

# Carrega todos os arquivos no diretório ./in
corpus_1 = frelatage.load_corpus(directory="./")
# Carrega todos os arquivos .gif/.jpeg no subdiretório ./in/images
corpus_2 = frelatage.load_corpus(directory="./images", file_extension=["gif", "jpeg"])

f = frelatage.Fuzzer(MyFunctionFuzz, [corpus_1, corpus_2])
f.fuzz()

Fuzzar com um dicionário

Você pode copiar um ou mais dicionários localizados aqui no diretório dedicado a dicionários (./dict por padrão).

Fuzzing diferencial

Fuzzing diferencial é uma técnica popular de teste de software que tenta detectar bugs fornecendo a mesma entrada para múltiplas bibliotecas/programas e observando diferenças em seus comportamentos. Você encontrará um exemplo aqui de uso de fuzzing diferencial com o Frelatage usando as bibliotecas json e ujson.

Exemplos

Você pode encontrar mais exemplos de fuzzers e corpus no diretório de exemplos.

• Fuzzando Pillow com Frelatage para encontrar bugs e vulnerabilidades

Relatórios de crash

Cada relatório de crash é salvo na pasta de saída (./out por padrão), em uma pasta chamada: id:<crash ID>,err:<tipo de erro>,err_pos:<erro>,err_file:<arquivo de erro>.