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:
Our
Ansible playbook
(recommended)A prebuilt Docker image, which can be pulled from Dockerhub at
intellabs/kafl:latest
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 !
➡️ Continue by fuzzing on Linux
➡️ Continue by fuzzing Windows programs