Deployment

kAFL’s deployment system (or installation) is built around Ansible, an IT automation framework useful for deploying Cloud services and provisioning virtual machines.

Note

As a user, you are only expected to update the Ansible 🗋 deploy/inventory if you want to perform a remote deployment. See Ansible’s inventory documentation.

System modifications

This is the list system level modifications made by the Ansible playbook when installing kAFL:

• checking for KVM’s compatibility with kAFL. If necessary, setup a new kernel:

  • download

  • install (5.10.73)

  • update GRUB

  • reboot

Local setup

• ensure current user is in kvm group

• ensure /dev/kvm device has permissions for the kvm group

Docker image

Nothing else !

Makefile targets

Target	Description	EXTRA_ARGS
deploy	Deploys kAFL components according to the playbook and the deploy/inventory file. Will be deployed on localhost by default.	☑️
env	Enters a new sub-shell with the kAFL environment variables set.
clean	Removes the virtualenv deploy/venv
update	Forces to git pull on every repository managed by the playbook. Developer oriented target. Uses the clone Ansible tag.	☑️
build	Rebuilds every component that can be built. Developer oriented target. Uses the build Ansible tag.	☑️

EXTRA_ARGS

Some Makefile targets can accept additional command line arguments (EXTRA_ARGS) by specifying them after the end of command options symbol (a double dash --).

These arguments will be passed to the underlying Ansible command line.

Example:

# toggle Ansible 3rd level verbosity
make deploy -- -vvv
# toggle the 'kernel' Ansible tag
make deploy -- --tags kernel
# skip the hardware_check Ansible tag
make deploy -- --skip-tags hardare_check

Warning

Since we use a Makefile hack to convert additional targets as EXTRA_ARGS, it’s not possible to use keyword arguments, or pass a quoted string:

Example:

# doesn't work
make deploy -- --extra-vars ansible_connection=local
make deploy -- --extra-vars '{"ansible_connection": "local"}'

Ansible tags

A set of Ansible tags are available to have fine grained control on the playbook’s execution.

They can be toggled or skipped with the --tags and --skip-tags Ansible command line parameters, and directly added from the makefile target via EXTRA_ARGS feature (described previously).

Tag	Description
kernel	Selects the kernel tasks
radamsa	Selects the radamsa tasks
capstone	Selects the capstone tasks
libxdc	Selects the libxdc tasks
qemu	Selects the QEMU tasks
fuzzer	Selects the fuzzer tasks
hardware_check	Selects the hardware/kernel requirements checking tasks. Introduced to be skipped on the CI runs.
kvm_device	Selects the tasks related to fixing permissions on the KVM node device. Introduced to be skipped on the CI runs.
reboot_kernel	Selects the task responsible for rebooting the remote node after kernel installation. Introduced to be skipped on the CI runs.
update_grub	Selects the tasks related to GRUB entry update after kernel installation. Introduced to be skipped on the CI runs.
build	Selects all tasks where a component can be rebuild (QEMU, libxdc, etc …). Developer oriented tag.
clone	Selects all tasks where a repository is cloned. Developer oriented tag.
examples-template-windows	Installs the required tooling to build the Windows template and run the examples. (Packer, Vagrant, agrant-plugins, qemu-bridge-helper, …)
examples-dvkm	Installs the required packages and submodules to use the Damn Vulnerable Kernel Module linux example

Note

You can list available tags with

make deploy -- --list-tags

Ansible Galaxy and composability

One of the reasons to rewrite kAFL’s deployment from scratching for the v0.5 release was to achieve a better composability.

In fact, other projects at Intel are based on kAFL, like the ccc-linux-guest-hardening repo. And we expect the community to develop their own tooling and use cases based on kAFL.

We wanted to make it as easy as possible to reuse the current kAFL deployment and cherry-pick the desired components. With this goal in mind, we leveraged a powerful feature of Ansible: Ansible Galaxy to breakdown kAFL’s setup into modular roles, and distribute them into a reusable collection.

intellabs.kafl Ansible collection

The intellabs.kafl collection is available in the 📁deploy directory.

It regroups all the essential components required to setup kAFL (kernel package, QEMU, libxdc, capstone, fuzzer frontend …).

The roles are depending on each other, in such a way that including the fuzzer role will pull out the others:

  roles:
    - role: intellabs.kafl.fuzzer

flowchart LR fuzzer --> kernel fuzzer --> qemu fuzzer --> radamsa qemu --> capstone qemu --> libxdc

Reusing the collection

kAFL and ccc-linux-guest-hardening are sharing the same deployment for kAFL.

Note

Since the collection is hosted in the top-level kAFL repository, it is included locally by specifying the source directory path.

ccc-linux-guest-hardening on the other hand, needs to specify the git repository and the subfolder.

flowchart LR kAFL==>|source: ./intellabs/kafl|intellabs.kafl ccc-linux-guest-hardening==>|source: git+https://github.com/IntelLabs/kAFL#/deploy/intellabs/|intellabs.kafl

Note

The intellabs.kafl Ansible collection is not yet publicly distributed on the Ansible Galaxy website.

It can be referenced in your requirements.yml via the git repository:

collections:
  - name: intellabs.kafl
    source: git+https://github.com/IntelLabs/kAFL#/deploy/intellabs/
    type: git
    version: master