The Python Fuzzer that the world deserves ๐Ÿ

Overview


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

Python 3

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) --&gt; |input| function(Fuzzed function)
    m2(Mutation 2) --&gt; |input| function(Fuzzed function)
    mplus(Mutation ...) --&gt; |input| function(Fuzzed function)
    mn(Mutation n) --&gt; |input| function(Fuzzed function)
    
    function --&gt; generate_reports(Generate reports)
    generate_reports --&gt; rank_reports(Rank reports)  
    rank_reports --&gt; select(Select n best reports)
    
    select --&gt; |mutate| nm1(Mutation 1) &amp; nm2(Mutation 2) &amp; nmplus(Mutation ...) &amp; 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

Comments
  • Use all of corpus in frelatage input

    Use all of corpus in frelatage input

    If we have thousands or more corpus, can we use all of corpus in the input directory instead of define filenames manually in frelatage.Input(file=True, value="filename") ?

    enhancement 
    opened by CityOfLight77 1
  • Numpy used but not included in poetry.lock file

    Numpy used but not included in poetry.lock file

    Just started this up and getting the following error:

    Traceback (most recent call last):
      File "/Users/test2.py", line 11, in <module>
        import frelatage
      File "/Users/username/.pyenv/versions/3.10.1/lib/python3.10/site-packages/frelatage/__init__.py", line 6, in <module>
        from frelatage.queue.queue import Queue
      File "/Users/username/.pyenv/versions/3.10.1/lib/python3.10/site-packages/frelatage/queue/queue.py", line 2, in <module>
        import numpy as np
    ModuleNotFoundError: No module named 'numpy'
    

    and I looked in the poetry.lock file and did not see numpy listed.

    opened by MSAdministrator 0
  • Error when loading input files from a subdirectory

    Error when loading input files from a subdirectory

    When loading an input file from a subdirectory of the input directory, we have a bug.

    For example:

    my_file = frelatage.Input("./subdir/myfile")
    

    Tries reates a temporary file in /tmp/frelatage/0/0/subdir/myfile when it should copy the file to /tmp/frelatage/0/0/myfile.

    bug 
    opened by Rog3rSm1th 0
  • Dev/rog3rsm1th

    Dev/rog3rsm1th

    • Implement the load_corpus function to load several files at once into a corpus, fixes #13
    • Make the input folder parameter an environment variable (FRELATAGE_INPUT_DIR).
    • Load the version number from the package informations.
    opened by Rog3rSm1th 0
  • Bug when passing the same file to two arguments

    Bug when passing the same file to two arguments

    When passing the same file to two arguments, there is a collision in the reports folder.

    For example:

    import frelatage 
    from PIL import Image
    
    def fuzz_gif(input_file1, input_file2):
        Image.open(input_file)
        Image.open(input_file)
    
    gif_file = frelatage.Input(file=True, value="image.gif")
    
    f = frelatage.Fuzzer(fuzz_gif, [[gif_file], [gif_file]])
    f.fuzz()
    

    In the reports, both image.gif will be written in the same file, making it impossible to reproduce the bug. The structure of the report folders should therefore be modified in this way:

    โ”œโ”€โ”€ out
        โ”‚   โ”œโ”€โ”€ id:<crash ID>,err:<error type>,err_pos:<error>,err_file:<error file>,err_pos:<err_pos>
        โ”‚       โ”œโ”€โ”€ input
        โ”‚       โ”œโ”€โ”€ 0
        โ”‚           โ”œโ”€โ”€ image.gif
        โ”‚       โ”œโ”€โ”€ 1
        โ”‚           โ”œโ”€โ”€ image.gif
    
    bug 
    opened by Rog3rSm1th 0
  • Use more specifics report's names to simplify the bug reproduction

    Use more specifics report's names to simplify the bug reproduction

    Currently the reports name only contain the type of the triggered error. It would be interesting to add the instruction where the bug was triggered, as well as the file where the bug crash occured in order to facilitate its reproduction.

    enhancement 
    opened by Rog3rSm1th 0
  • More minimalistic interface

    More minimalistic interface

    Currently the interface is quite large and does not fit well on small terminals. It needs to be reworked in order to obtain a more minimalist and slim interface. It would be possible to take inspiration from the interfaces of other fuzzers such as AFL/AFL++ or WinAFL.

    enhancement 
    opened by Rog3rSm1th 0
  • Allow the use of several values in the corpus

    Allow the use of several values in the corpus

    For now it is only possible to use one value for the corpus. It should be possible to pass several values in the corpus.

    For example for the classical arguments:

    inp = frelatage.Input(value=["value1", "value2", "value3"])
    

    For the argument of type "file":

      โ”œโ”€โ”€ in
      โ”‚    โ”œโ”€โ”€ 0
      โ”‚        โ”œโ”€โ”€ file1
      โ”‚        โ”œโ”€โ”€ file2
      โ”‚        โ””โ”€โ”€ ...
      โ”‚    โ”œโ”€โ”€ 1
      โ”‚    โ”œโ”€โ”€ ...
    
    enhancement 
    opened by Rog3rSm1th 0
  • Dev/rog3rsm1th

    Dev/rog3rsm1th

    New features:

    • Adds the possibility to enable or disable dictionnary mutations.
    • Implements silent mode.
    • Checks ENV variables values before launching the fuzzer.
    • Fixes #2
    opened by Rog3rSm1th 0
  • Improve interface

    Improve interface

    Different aspects of the interface need to be improved:

    • The name of the fuzzed function must be displayed.
    • the use of curses "breaks" the terminal display when exiting the program, this must be corrected.
    • A message should be displayed at the end of the fuzzing, with the reason why the program stopped (user-induced or not) as well as general statistics about the fuzzing.
    enhancement 
    opened by Rog3rSm1th 0
  • Use dictionary in Fuzzer

    Use dictionary in Fuzzer

    Although we can use dictionary, I didn't see option in frelatage.Fuzzer() to load specific dictionary for a fuzzing campaign.

    What security and non-security issues we can found during fuzzing with Frelatage?

    And if I have N cores, how many threads should I use?

    opened by CityOfLight77 0
  • Fix curses error when the window is too small

    Fix curses error when the window is too small

    when you run Frelatage with a terminal that is too small, or when you resize the terminal during execution, you get an error related to curses: _curses.error: addwstr() returned ERR

    bug 
    opened by Rog3rSm1th 0
  • Implement multithreading

    Implement multithreading

    Currently threads are launched one after the other, it is therefore necessary to implement multithreading to increase the performance and speed of fuzzing.

    enhancement 
    opened by Rog3rSm1th 0
Releases(v0.1.0)
  • v0.1.0(May 31, 2022)

    What's changed?

    • ๐ŸŽ‰ Frelatage goes from Alpha to Beta with version 0.1.0 ๐ŸŽ‰
    • The interface has been reworked
    • Many bugs have been fixed
    • The source code is now formatted to meet PEP8 standards and typing and verified using MyPy
    • Infinite fuzzing is now possible, #23
    Source code(tar.gz)
    Source code(zip)
  • v0.0.6(Mar 22, 2022)

    What's changed?

    • Ignores warnings during fuzzing process
    • Improves integer fuzzing by adding new magic values.
    • Adds timeout delay in the interface.
    • Implements load_corpus to load several files at once into a corpus. #13
    • Allows to load input files from subdirectories. #16
    • Make the input folder parameter an environment variable.
    • Minor interface fixes and version standardization (__version__)
    Source code(tar.gz)
    Source code(zip)
  • v0.0.4(Mar 14, 2022)

  • v0.0.3(Mar 10, 2022)

    What's changed?

    • The interface has been reworked to fit more easily into smaller terminals.
    • Possibility to use a corpus to fuzz more efficiently.
    • Implementation of a queue system to test the elements of the corpus one after the other.
    Source code(tar.gz)
    Source code(zip)
  • v0.0.2(Mar 8, 2022)

    What's changed?

    • The interface now displays the name of the fuzzed function, and the cursor is now hidden.
    • A detailed report is displayed at the end of the fuzzing.
    • The value of the environment variables is checked before the fuzzer is launched.
    • Implementation of a silent mode.
    Source code(tar.gz)
    Source code(zip)
Owner
Rog3r
Fuzzing / OSINT / Low level stuffs
Rog3r
My attempt at this years Advent of Code!

Advent-of-code-2021 My attempt at this years Advent of Code! day 1: ** day 2: ** day 3: ** day 4: ** day 5: ** day 6: ** day 7: ** day 8: * day 9: day

1 Jul 06, 2022
Streamlit apps done following data professor's course on YouTube

streamlit-twelve-apps Streamlit apps done following data professor's course on YouTube Espaรฑol Curso de apps de data science hecho por Data Professor

Federico Bravin 1 Jan 10, 2022
A command line interface tool converting starknet warp transpiled outputs into readable cairo contracts.

warp-to-cairo warp-to-cairo is a simple tool converting starknet warp outputs (NethermindEth/warp) outputs into readable cairo contracts. The warp out

Michael K 5 Jun 10, 2022
Advanced Keylogger in Python

Advanced Keylogger in Python Important Disclaimer: The author will not be held r

Suvanth Erranki 1 Feb 07, 2022
Run Python code right in your Telegram messages

Run Python code right in your Telegram messages Made with Telethon library, TGPy is a tool for evaluating expressions and Telegram API scripts. Instal

29 Nov 22, 2022
A guy with a lot of useful things to do when doing AtCoder in Python

atcoder_python_env Python ใง AtCoder ใ‚’ใ‚„ใ‚‹ใจใใซไพฟๅˆฉใช่ซธใ€…ใ‚’็”จๆ„ใ—ใŸใ‚„ใค ใ‚ณใƒณใƒ†ใ‚นใƒˆ็”จใƒ•ใ‚ฉใƒซใƒ€ใฎไฝœๆˆ ใ‚ปใƒƒใƒˆใ‚ขใƒƒใƒ— ่‡ชๅ‹•ใƒ†ใ‚น

2 Dec 28, 2021
Doom oโ€™clock is a website/project that features a countdown of โ€œwhen will the earth endโ€ and a greenhouse gas effect emission prediction thatโ€™s predicted

Doom oโ€™clock is a website/project that features a countdown of โ€œwhen will the earth endโ€ and a greenhouse gas effect emission prediction thatโ€™s predicted

shironeko(Hazel) 4 Jan 01, 2022
Advent of Code 2021 challenges

Data analysis Document here the project: AoC21 Description: Project Description Data Source: Type of analysis: Please document the project the better

Daniel Wendel 1 Jan 07, 2022
Procedural 3D data generation pipeline for architecture

Synthetic Dataset Generator Authors: Stanislava Fedorova Alberto Tono Meher Shashwat Nigam Jiayao Zhang Amirhossein Ahmadnia Cecilia bolognesi Dominik

Computational Design Institute 49 Nov 25, 2022
decorator

Decorators for Humans The goal of the decorator module is to make it easy to define signature-preserving function decorators and decorator factories.

Michele Simionato 734 Dec 30, 2022
Notifies server owners of mod updates, also notifies of player deaths and player joins through Discord.

ProjectZomboid-ServerAssistant Notifies server owners of mod updates, also notifies of player deaths and player joins through Discord. A Python based

3 Sep 30, 2022
A free and powerful system for awareness and research of the American judicial system.

CourtListener Started in 2009, CourtListener.com is the main initiative of Free Law Project. The goal of CourtListener.com is to provide high quality

Free Law Project 332 Dec 25, 2022
Writeup and scripts for the 2021 malwarebytes crackme

Malwarebytes Crackme 2021 Tools and environment setup We will be doing this analysis in a Windows 10 VM with the flare-vm tools installed. Most of the

Jerome Leow 9 Dec 02, 2022
Python API for HotBits random data generator

HotBits Python API Python API for HotBits random data generator. Description This project is random data generator. It uses is HotBits API web service

Filip ล  2 Sep 11, 2020
Jannik Ramrath 1 Feb 05, 2022
Djangoblog - A blogging site where people can make their accout and write blogs and read other author's blogs

This a blogging site where people can make their accout and write blogs and read other author's blogs.

1 Jan 26, 2022
Movie recommend community

README 0. ์ดˆ๋ก 1) ๋ชฉ์  ์‚ฌ์šฉ์ž์˜ Needs๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ์˜ํ™”๋ฅผ ์ถ”์ฒœํ•ด์ฃผ๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ ์„œ๋น„์Šค ๊ตฌํ˜„ 2) p!ck ์„œ๋น„์Šค๋ž€? "pick your taste!" ์ทจํ–ฅ๋Œ€๋กœ ์˜ํ™” ํ”Œ๋ ˆ์ด๋ฆฌ์ŠคํŠธ(์ดํ•˜ ์„œ๋น„์Šค ๋‚ด์—์„œ์˜ ๋ช…์นญ์ธ '๋ฐ”์Šค์ผ“'์ด๋ผ ํ•จ)๋ฅผ ๋งŒ๋“ค๊ณ , ๋น„์Šทํ•œ ์ทจํ–ฅ์„ ๊ฐ€์ง„

2 Dec 08, 2021
Example code for the book Fluent Python, 1st Edition (O'Reilly, 2015)

Fluent Python, First Edition: example code This repository is archived and will not be updated.

Fluent Python 5.4k Jan 09, 2023
A basic layout of atm working of my local database

Software for working Banking service ๐Ÿ˜„ This project was developed for Banking service. mysql server is required To have mysql server on your system u

satya 1 Oct 21, 2021
Create beautiful diagrams just by typing mathematical notation in plain text.

Penrose Penrose is an early-stage system that is still in development. Our system is not ready for contributions or public use yet, but hopefully will

Penrose 5.6k Jan 08, 2023