frelatage

pip3 install frelatage


Il Fuzzer Python che il mondo merita

Installazione    |    Come funziona    |    Caratteristiche    |    Usare Frelatage    |    Configurazione

Frelatage è una libreria di fuzzing Python basata sulla copertura del codice che può essere utilizzata per fare fuzzing di codice Python. Lo sviluppo di Frelatage è stato ispirato da vari altri fuzzer, tra cui AFL/AFL++, Atheris e PythonFuzz. Lo scopo principale del progetto è sfruttare le migliori caratteristiche di questi fuzzer e riunirle in un nuovo strumento per fare fuzzing di applicazioni Python in modo efficiente.

DICHIARAZIONE DI NON RESPONSABILITÀ: Questo progetto è in fase alpha e può ancora causare molti comportamenti imprevisti. Frelatage non dovrebbe essere utilizzato in un ambiente di produzione al momento.

Requisiti

Python 3

Installazione

Installazione con pip (consigliata)

pip3 install frelatage

Oppure compilare dal sorgente

Consigliato per sviluppatori. Clona automaticamente il branch principale dal repository di Frelatage e installa dal sorgente.

# Automatically clone the Frelatage repository and install Frelatage from source
bash <(wget -q https://raw.githubusercontent.com/Rog3rSm1th/Frelatage/main/scripts/autoinstall.sh -O -)

Come funziona

L'idea alla base del progetto di Frelatage è l'uso di un algoritmo genetico per generare mutazioni che coprano quanto più codice possibile. Il funzionamento di un ciclo di fuzzing può essere riassunto approssimativamente con questo diagramma:

graph TB

    m1(Mutation 1) --> |input| function(Fuzzed function)
    m2(Mutation 2) --> |input| function(Fuzzed function)
    mplus(Mutation ...) --> |input| function(Fuzzed function)
    mn(Mutation n) --> |input| function(Fuzzed function)
    
    function --> generate_reports(Generate reports)
    generate_reports --> rank_reports(Rank reports)  
    rank_reports --> select(Select n best reports)
    
    select --> |mutate| nm1(Mutation 1) & nm2(Mutation 2) & nmplus(Mutation ...) & nmn(Mutation n)
    
    subgraph Cycle mutations
    direction LR
    m1
    m2
    mplus
    mn
    end
    
    subgraph Next cycle mutations
    direction LR
    nm1
    nm2
    nmplus
    nmn
    end
     
    style function fill:#5388e8,stroke:white,stroke-width:4px

Caratteristiche

Fuzzing di diversi tipi di argomenti:

• Stringa
• Intero
• Numero a virgola mobile
• Lista
• Tupla
• Dizionario

Fuzzing di file

Frelatage permette di fare fuzzing di una funzione passando un file come input.

Efficienza del fuzzer

• Corpus
• Dizionario

Usare Frelatage

Fuzz di un parametro classico

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()

Fuzz di un parametro file

Frelatage ti dà la possibilità di fare fuzzing di parametri di input di tipo file. Per inizializzare il valore di questi file, devi creare file nella cartella di input (./in di default).

Se vogliamo inizializzare il valore di un file usato per il fuzzing, possiamo farlo così:

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

E poi eseguire il 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()

Fuzz di più metodi usando decoratori (sperimentale)

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)
# And so on

# It will fuzz the instrumented methods one after the other
frelatage.Fuzzer.fuzz_all()

E così via. Farà il fuzzing dei metodi instrumentati uno dopo l'altro.

Caricare più file in un corpus contemporaneamente

Se hai bisogno di caricare più file in un corpus contemporaneamente (utile se usi un corpus grande) puoi usare la funzione integrata di Frelatage load_corpus. Questa funzione restituisce una lista di Input.

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

• directory: Sottodirectory della directory di input (percorso relativo), es. ./, ./images
• file_extensions: Lista di estensioni di file da includere nelle voci del corpus, es. ["jpeg", "gif"], ["pdf"]

import frelatage
import my_vulnerable_library

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

# Load every every file in the ./in directory
corpus_1 = frelatage.load_corpus(directory="./")
# Load every .gif/.jpeg file in the ./in/images subdirectory
corpus_2 = frelatage.load_corpus(directory="./images", file_extension=["gif", "jpeg"])

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

Fuzz con un dizionario

Puoi copiare uno o più dizionari situati qui nella directory dedicata ai dizionari (./dict di default).

Fuzzing differenziale

Il fuzzing differenziale è una popolare tecnica di testing del software che tenta di rilevare bug fornendo lo stesso input a più librerie/programmi e osservando le differenze nei loro comportamenti. Troverai un esempio qui di un uso del fuzzing differenziale con Frelatage con le librerie json e ujson.

Esempi

Puoi trovare più esempi di fuzzer e corpus nella directory degli esempi.

• Fuzzing di Pillow con Frelatage per trovare bug e vulnerabilità

Report di crash

Ogni report di crash viene salvato nella cartella di output (./out di default), in una cartella denominata: id:<crash ID>,err:<error type>,err_pos:<error>,err_file:<error file>.