DOCSEARCHbyAlgolia
Submit Docs

Phuzzer

repository·master·Indexed 41 days ago

https://github.com/angr/phuzzer

A Python wrapper for interacting with fuzzers like AFL (American Fuzzy Lop). It provides a high-level interface to manage AFL instances, add slave workers, inject and retrieve testcases, and monitor performance metrics. It supports symbolic-assisted fuzzing (drilling) and includes a CLI tool, analyze_result.py, for processing coverage metrics and crash statistics.

Tokens
1.1K
Snippets
4
Records
4
Agent score
1%

What's inside Phuzzer

  1. Install Phuzzer

    master

    Phuzzer requires several Debian system packages and specific Python modules to function. It is highly recommended to perform the installation within a Python virtual environment.

    1. Install Debian dependencies

    Install the necessary build tools and QEMU dependencies:

    sudo apt-get install build-essential gcc-multilib libtool automake autoconf bison debootstrap debian-archive-keyring libtool-bin
sudo apt-get build-dep qemu

    2. Install Python dependencies

    Install the required Shellphish and angr modules. Note that this process may take a significant amount of time as it compiles QEMU multiple times:

    pip install git+https://github.com/shellphish/shellphish-afl
pip install git+https://github.com/shellphish/driller
pip install git+https://github.com/angr/tracer

    3. Install Phuzzer

    Finally, install the phuzzer wrapper:

    pip install git+https://github.com/angr/phuzzer
    sudo apt-get install build-essential gcc-multilib libtool automake autoconf bison debootstrap debian-archive-keyring libtool-bin
sudo apt-get build-dep qemu
pip install git+https://github.com/shellphish/shellphish-afl
pip install git+https://github.com/shellphish/driller
pip install git+https://github.com/angr/tracer
pip install git+https://github.com/angr/phuzzer

  2. Use Phuzzer programmatically

    master

    Phuzzer can be used as a Python module. While official API documentation is currently unavailable, you can begin by importing the fuzzer module. For implementation details, refer to the source code of the shellphuzz script.

    import fuzzer

  3. Use the phuzzer CLI

    master

    The easiest way to use Phuzzer is via the python -m phuzzer command (or the shellphuzz script). This allows you to run AFL instances and optionally enable symbolic-assisted fuzzing (drilling).

    Common CLI Flags

    • -i: (Implicit in examples) Likely enables an interactive or specific mode.
    • -c <number>: Specifies the number of AFL cores to use.
    • -d <number>: Specifies the number of symbolic tracing (drilling) cores to use.

    To see all available options, run the command with --help.

    # fuzz with 4 AFL cores
python -m phuzzer -i -c 4 /path/to/binary

# perform symbolic-assisted fuzzing with 4 AFL cores and 2 symbolic tracing (drilling) cores
python -m phuzzer -i -c 4 -d 2 /path/to/binary

  4. Analyze Phuzzer results with analyze_result.py

    master

    The analyze_result.py script is a CLI tool used to process and summarize the results of a Phuzzer execution run. It parses the input directory to identify the target binary and job metadata, then calculates coverage metrics and crash statistics.

    Usage

    Run the script by providing the path to the Phuzzer results directory as the first positional argument.

    python analyze_result.py <results_directory_path>

    Output

    The tool provides two types of output:

    1. Human-readable logs: Lines prefixed with RESULT containing the tag, binary name, metric key, and value.
    2. JSON summary: A single JSON object containing all calculated metrics, which is useful for automated post-processing.

    JSON Result Schema

    The JSON output includes the following keys:

    • bin: The name of the target binary (extracted from the directory name).
    • tag: A tag derived from the directory structure.
    • testcase_count: Total number of valid test cases found.
    • crash_count: Total number of crashes found.
    • crashed: Boolean indicating if any crashes were detected.
    • crash_time: Time elapsed until the first crash (in seconds).
    • crash_techniques: A tuple of techniques that contributed to the first crash.
    • grease_assisted_crash: Boolean; true if 'grease' was in the first crash's techniques.
    • driller_assisted_crash: Boolean; true if 'driller' was in the first crash's techniques.
    • fuzzer_assisted_crash: Boolean; true if 'fuzzer' was in the first crash's techniques.
    • fuzzer_only_testcases: Count of test cases where the only contributing technique was 'fuzzer'.
    • greese_derived_testcases: Count of test cases derived via 'grease'.
    • driller_derived_testcases: Count of test cases derived via 'driller'.
    • hybrid_derived_testcases: Count of test cases derived via both 'grease' and 'driller'.
    • blocks_triggered: Total unique code blocks triggered across all inputs.
    • transitions_triggered: Total unique code transitions triggered across all inputs.
    python analyze_result.py <results_directory_path>