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#

kAFL userspace stack can be setup via 2 ways:

Note

This Ansible playbook methods is recommended as it will give you a better understanding what gets installed, configured, and how.

Furthermore, you will be able to modify these components and update them, should it be necessary for your target.

Additionally, the docker command line is more complex since it requires mounting volumes into the container, and isn’t recommended unless you are very familiar with the tool.

The requirements for either of these setups:

  • Python 3 interpreter (>= 3.9)

  • Git

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

The following command will install the required software on Ubuntu

sudo apt-get install -y python3-dev python3-venv git build-essential

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 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.

make deploy

If you follow the Docker image based setup for kAFL, you only need to install the kAFL kernel.

This can be done with make deploy, by specifying an Ansible tag.

make deploy -- --tags kernel

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.

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

Nothing to be done here. You are good to go !

5. Verify the installation#

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

$ kafl fuzz

Let’s pull the intellabs/kafl image

docker pull intellabs/kafl

And execute the fuzz subcommand !

docker run \
        -ti --rm \
        --device /dev/kvm \
        --user $(id -u):$(id -g) \
        --group-add $(getent group kvm | cut -d: -f3) \
        intellabs/kafl \
        fuzz

You should see the kAFL ACSII art logo:


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

<< kAFL Fuzzer >>

Warning: Launching without --seed-dir?
No PT trace region defined.
00:00:00:     0 exec/s,    0 edges,  0% favs pending, findings: <0, 0, 0>
Worker-00 Launching virtual machine...
/home/mtarral/kafl/kafl/qemu/x86_64-softmmu/qemu-system-x86_64
        -enable-kvm
        -machine kAFL64-v1
        -cpu kAFL64-Hypervisor-v1,+vmx
        -no-reboot
        -net none
        -display none
        -chardev socket,server,id=nyx_socket,path=/dev/shm/kafl_mtarral/interface_0
        -device nyx,chardev=nyx_socket,workdir=/dev/shm/kafl_mtarral,worker_id=0,bitmap_size=65536,input_buffer_size=131072
        -device isa-serial,chardev=kafl_serial
        -chardev file,id=kafl_serial,mux=on,path=/dev/shm/kafl_mtarral/serial_00.log
        -m 256
        -fast_vm_reload path=/dev/shm/kafl_mtarral/snapshot/,load=off
[QEMU-NYX] Max Dirty Ring Size -> 1048576 (Entries: 65536)
qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.01H:ECX.pcid [bit 17]
qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.07H:EBX.hle [bit 4]
qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.07H:EBX.rtm [bit 11]
[QEMU-NYX] Dirty ring mmap region located at 0x767b25d00000
[QEMU-NYX] Warning: Invalid sharedir...
[QEMU-NYX] Booting VM to start fuzzing...
...

If that’s the case, kAFL is correctly configured !

You can now send a CTRL-C to stop kAFL:

^CReceived Ctrl-C, killing workers...
Waiting for Workers to shutdown...
Worker-00 Shutting down Qemu after 0 execs..
qemu-system-x86_64: terminating on signal 15 from pid 115166 (/home/mtarral/kafl/kafl/.venv/bin/python3)

Note

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

6. On to the next steps !#

Now you are ready to configure one of our pre-baked kAFL targets, and start the fuzzer !