pip3 install frelatage
Current release : 0.0.2
The Python Fuzzer that the world deserves
Installation | How it works | Features | Use Frelatage | Configuration
Frelatage is a coverage-based Python fuzzing library which can be used to fuzz python code. The development of Frelatage was inspired by various other fuzzers, including AFL/AFL++, Atheris and PyFuzzer.The main purpose of the project is to take advantage of the best features of these fuzzers and gather them together into a new tool in order to efficiently fuzz python applications.
DISCLAIMER : This project is at the alpha stage and can still cause many unexpected behaviors. Frelatage should not be used in a production environment at this time.
Requirements
Installation
Install with pip (recommended)
pip3 install frelatage
Or build from source
Recommended for developers. It automatically clones the main branch from the frelatage repo, and installs from source.
# Automatically clone the Frelatage repository and install Frelatage from source
bash <(wget -q https://raw.githubusercontent.com/Rog3rSm1th/Frelatage/main/scripts/autoinstall.sh -O -)
How it works
The idea behind the design of Frelatage is the usage of a genetic algorithm to generate mutations that will cover as much code as possible. The functioning of a fuzzing cycle can be roughly summarized with this diagram :
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
Features
Fuzzing different argument types:
- String
- Int
- Float
- List
- Tuple
- Dictionary
File fuzzing
Frelatage allows to fuzz a function by passing a file as input.
Use Frelatage
Fuzz a classical parameter
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 a file parameter
Frelatage gives you the possibility to fuzz file type input parameters. To initialize the value of these files, you must create as many files in the input folder as there are arguments of type file. These files must be named as follows: the first file argument must be named 0, the second 1, and so on.
In case we have only one input file, we can initialize it like this:
echo "initial value" > ./in/0
And then run the fuzzer:
import frelatage
import my_vulnerable_library
def MyFunctionFuzz(data):
my_vulnerable_library.load_file(data)
input = frelatage.Input(file=True)
f = frelatage.Fuzzer(MyFunctionFuzz, [input])
f.fuzz()
Fuzz with a dictionary
You can copy one or more dictionaries located here in the directory dedicated to dictionaries (./dict by default).
Reports
Each crash is saved in the output folder (./out by default), in a folder named : id<crash ID>,err<error type>.
The report directory is in the following form:
βββ out
β βββ id<crash ID>,err<error type>
β βββ input
β βββ 0
β βββ ...
β βββ ...
Read a crash report
Inputs passed to a function are serialized using the pickle module before being saved in the <report_folder>/input file. It is therefore necessary to deserialize it to be able to read the contents of the file. This action can be performed with this script.
./read_report.py input
Configuration
There are two ways to set up Frelatage:
Using the environment variables
| ENV Variable | Description | Possible Values | Default Value |
|---|---|---|---|
| FRELATAGE_DICTIONARY_ENABLE | Enable the use of mutations based on dictionary elements | 1 to enable, 0 otherwise |
1 |
| FRELATAGE_TIMEOUT_DELAY | Delay in seconds after which a function will return a TimeoutError | 1 - 20 |
2 |
| FRELATAGE_INPUT_FILE_TMP_DIR | Temporary folder where input files are stored | absolute path to a folder, e.g. /tmp/custom_dir |
/tmp/frelatage |
| FRELATAGE_INPUT_MAX_LEN | Maximum size of an input variable in bytes | 4 - 1000000 |
4094 |
| FRELATAGE_MAX_THREADS | Maximum number of simultaneous threads | 8 - 50 |
8 |
| FRELATAGE_DICTIONARY_DIR | Default directory for dictionaries. It needs to be a relative path (to the path of the fuzzing file) | relative path to a folder, e.g. ./dict |
./dict |
A configuration example :
export FRELATAGE_DICTIONARY_ENABLE=1 &&
export FRELATAGE_TIMEOUT_DELAY=2 &&
export FRELATAGE_INPUT_FILE_TMP_DIR="/tmp/frelatage" &&
export FRELATAGE_INPUT_MAX_LEN=4096 &&
export FRELATAGE_MAX_THREADS=8 &&
export FRELATAGE_DICTIONARY_DIR="./dict" &&
python3 fuzzer.py
Passing arguments to the fuzzer
import frelatage
def myfunction(input1_string, input2_int):
pass
input1 = frelatage.Input(value="initial_value")
input2 = frelatage.Input(value=2)
f = frelatage.Fuzzer(
# The method you want to fuzz
method=myfunction,
# The initial arguments
arguments=[input1, input2],
# Number of threads
threads_count=8,
# Exceptions that will be taken into account
exceptions_whitelist=(OSError),
# Exceptions that will not be taken into account
exceptions_blacklist=(),
# Directory where the error reports will be stored
output_directory="./out",
# Directory containing the initial input files
input_directory="./in",
# Enable or disable silent mode
silent=False
)
f.fuzz()
Risks
Please keep in mind that, similarly to many other computationally-intensive tasks, fuzzing may put strain on your hardware and on the OS. In particular:
-
Your CPU will run hot and will need adequate cooling. In most cases, if cooling is insufficient or stops working properly, CPU speeds will be automatically throttled. That said, especially when fuzzing on less suitable hardware (laptops, smartphones, etc), it's not entirely impossible for something to blow up.
-
Targeted programs may end up erratically grabbing gigabytes of memory or filling up disk space with junk files. Frelatage tries to enforce basic memory limits, but can't prevent each and every possible mishap. The bottom line is that you shouldn't be fuzzing on systems where the prospect of data loss is not an acceptable risk.
-
Fuzzing involves billions of reads and writes to the filesystem. On modern systems, this will be usually heavily cached, resulting in fairly modest "physical" I/O - but there are many factors that may alter this equation. It is your responsibility to monitor for potential trouble; with very heavy I/O, the lifespan of many HDDs and SSDs may be reduced.
A good way to monitor disk I/O on Linux is the 'iostat' command:
$ iostat -d 3 -x -k [...optional disk ID...]
Contact
for any remark, suggestion, bug report, or if you found a bug using Frelatage, you can contact me at [email protected] or on twitter @Rog3rSm1th
1 Nov 06, 2021
154 Jan 06, 2023
67 Dec 31, 2022
12.5k Jan 07, 2023
10 Aug 18, 2022
2 Jun 14, 2022
6 May 21, 2022
5 Apr 26, 2022
1 Oct 24, 2021
248 Dec 28, 2022
2 Jan 11, 2022
20 Mar 10, 2021
5 Oct 29, 2021
0 Jun 22, 2022
9 Nov 27, 2022
31 Nov 10, 2022
2 Sep 28, 2022
0 May 03, 2022
29 Nov 22, 2022
7 Sep 18, 2022