Installation

Before we dive into the installation process, let’s make sure that your local machine meets the necessary requirements to run the fuzzer.

1. Requirements

1.1 Hardware

Your processor must support Intel Processor Trace (Intel PT). This feature is available on Gen-6 (Skylake) or newer Intel processors.

Note

Although Intel Gen-5 (Broadwell) supports Intel PT, some addional Intel PT features have been introduced in Gen-6 that are required for kAFL to execute properly.

You can check your CPU’s compatibility with the following command:

echo -n "Intel PT support: "; if $(grep -q "intel_pt" /proc/cpuinfo); then echo "✅"; else echo "❌"; fi

Tip

kAFL’s installation process will start by checking your processor’s compatibility with Intel PT, and abort the installation if necessary.

1.2 Software

• Python 3 interpreter (>= 3.6)

• Git

• Essential toolchain to build software (make, gcc, …)

Note

The userspace installation and fuzzing workflow has been tested for recent Ubuntu (>=20.04) and Debian (>=Bullseye).

Important

The installation will require to download, install and reboot your system on a modifed Linux kernel.

Note

Setup inside VM or container is not supported at this point.

2. Cloning the sources

First clone the sources from the main kAFL repository on Github, and move into the directory

git clone https://github.com/IntelLabs/kAFL
cd kAFL

3. Deploying kAFL : make deploy

Run the deploy make target to start the installation.

The next step will trigger kAFL installation.

Important

Before continuing, you might want to check the system changes made by the installation.

Tip

If you want a glimpse of the installation execution, without actually touching anything on your system (dry-run), you can use the following command:

make deploy -- --check

Skip the prompt by pressing ENTER.

Once you are confortable with the changes that will be made to your system, execute the deploy make target:

make deploy

Important

You will be prompted for your root password by kAFL’s deployment tool (Ansible)

This is necessary to allow system modifications.

BECOME password:

Tip

The following message will be displayed before:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Ansible BECOME password: if you are using a passwordless SUDO, skip by pressing enter.┃
└━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┘

In fact, if your current user doesn’t require any password (user ALL=(ALL) NOPASSWD: ALL in sudoers), you can just press ENTER.

4. Setting kAFL environment : make env

Once the setup is complete, you can now run the env target. This command will start a new sub-shell, and source the newly created env.sh file to setup the kAFL environment variables.

make env

5. Verify the installation

To verify the installation, you should have the kafl_fuzz.py binary available in your PATH, and execute it from your new sub-shell:

$ kafl_fuzz.py

You should see the kAFL ACSII art logo:

    __                        __  ___    ________
   / /_____  _________  ___  / / /   |  / ____/ /
  / //_/ _ \/ ___/ __ \/ _ \/ / / /| | / /_  / /
 / ,< /  __/ /  / / / /  __/ / / ___ |/ __/ / /___
/_/|_|\___/_/  /_/ /_/\___/_/ /_/  |_/_/   /_____/
===================================================

<< kAFL Fuzzer >>

Note

The complete documentation regarding kAFL’s installation is available at reference/deployment