If any of the steps fail: check Notes section at the end for common problems and fixes.

Important Note: most of the configurations files in fuzz/configs are not up to date. All tested and up to date configurations are listed in benchmarks/eval/target_drvs. To use one of the remaining configurations, please update it according to the configuration options described below.

All benchmarks along with documentation and helper scripts can be found under benchmarks.

Overview

VIA is an in-process userspace Linux-kernel fuzzer, that targets the hardware-OS interface of device drivers.

VIA contains and is based on the following projects:

llvm: https://github.com/llvm/llvm-project
lkl: https://github.com/lkl/linux

Docker

Build the docker image

cd via/docker
docker build . -t via --build-arg NT=<number of build threads (make -j $NT)>

Start fuzzing with the docker image

mkdir <tmp_indir>
docker run -v <tmp_indir>:/tmp_indir --env FUZZ_TARGET="rocker" via /via/fuzz/bin/fuzzl__X.elf -detect_leaks=0 /tmp_indir

Installation

Dependencies

libconfig-dev
python3.8
libllvm10
llvm-10
cmake

Clone Repo

git clone https://github.com/file-citas/via.git via

Build clang

cd via
cd via/llvm
mkdir build
cd build
cmake -DLLVM_ENABLE_PROJECTS="clang;compiler-rt" -DCMAKE_BUILD_TYPE="Release" -G "Unix Makefiles" ../llvm
make -j<N>

make sure this clang instance is used for all builds from now on...

Setup Environment

cd via
export VIA_PATH=$PWD
source setup_env
mkdir fuzz/targets_fuzz

Build the LKL Library

Make sure that $CC is set correclty (source via/fuzz/setup_env should do this)

(defconfig is applied automatically)

cd via/lkl
make -C tools/lkl CC=$CC HOSTCC=$CC FUZZ=1 LLVM_IAS=1 PYTHON=python3.8 -j<N>
make drivers modules ARCH=lkl CC=$CC HOSTCC=$CC FUZZ=1 LLVM_IAS=1 PYTHON=python3.8 -j<N>
find . -name '*ko' -exec cp {} $VIA_PG_PATH/targets_fuzz \;

Build the Harness

cd via/fuzz
mkdir bin
mkdir bin/harness
make -j<N>

Start Fuzzing

Note: you can redirect stdout to clean up the output VIA also supports all the default libfuzzer options: https://llvm.org/docs/LibFuzzer.html#options

cd via/fuzz
mkdir tmp_indir
FUZZ_TARGET="virtio_net" ./bin/fuzzl__X.elf -detect_leaks=0 ./tmp_indir

Re-Execute on one particular IO-stream

FUZZ_TARGET="virtio_net" ./bin/runl__X.elf <io.bin>

Configuration

(Also: check the comments in via/fuzz/src/util.c)

Configuration options are applied via a combination of values read from the environment and the module configuration file (via/fuzz/configs/<target>.config)

IMPORTANT: Always set FUZZ_TARGET=<target> to select the configuration file.

Global Configuration

These should be set by source via/fuzz/setup_env ...

env: VIA_HARNESS directory containing the harness libraries; e.g. via/fuzz/bin/harness
env: VIA_CONFIGS directory containing the modules configuration files; e.g. via/fuzz/configs
env: VIA_MODULES directory containing the modules; e.g. via/fuzz/<targets_fuzz>
env: VIA_FW directory containing the firmware files; e.g. via/fuzz/fw

Target Specific Configuration

Each target is configured via a via/fuzz/configs/<target>.config This file must minimally contain:

module: Name of the module in <targets_fuzz>; e.g. module="virtio_net.ko"
module_deps: if the target module depends on other modules, this information can be found in modules.dep; to generate modules.dep run make ARCH=lkl CC=$CC HOSTCC=$CC LLVM_IAS=1 FUZZ=1 drivers/ modules_install INSTALL_MOD_PATH=../<moddir>; e.g. virtio_net.ko depends on moddeps=["virtio.ko", "virtio_ring.ko", "virtio_mmio.ko"]
harness: Name of the harness library, for a list of available harness libraries check via/fuzz/bin/harness/; e.g. harness="fuzz_net_icmp.so"
devtype: Device Type (0=PCI, 1=VIRTIO, 2=PLATFORM)
fws: Array of firmware file name (must be present in via/fuzz/fws, if the module requires external firmware
barsizes and barflags: size and flags of MMIO or PIO regions; e.g. barsizes=[0xfffff, 0xfffff] and barflags=[0x40200, 0x40200] (note, virtio resources will be configured automatically)

Device Specific Configuration

plt_name (PLATFORM): compatible name of device
vid (PCI, VIRTIO): vendor id
did (PCI, VIRTIO): device id
svid (PCI): sub-vendor id
sdid (PCI): sub-device id
pci_class (PCI)
revision (PCI)
vio_nofuzz (VIRTIO): mmio offsets to exclude from fuzzing
features_set_mask_high/low (VIRTIO): features to be always set
features_unset_mask_high/low (VIRTIO): features to be always cleared
drain_irqs (VIRTIO): continue issuing IRQs after end of io-stream
extra_io (VIRTIO): extend io-stream with PRNG data
fuzz_dma (VIRTIO): 0: Simulation Mode, 1: Passthrough Mode
nqueues (VIRTIO): number of virtio queues

Debug Configuration

env: FUZZ_TRACE_MOD (default 0): trace module (un)init
env: FUZZ_TRACE_IO (default 0): trace io-stream passed on to module
env: FUZZ_TRACE_IRQ (default 0): trace requested IRQ lines
env: FUZZ_TRACE_MSIIRQ (default 0): trace requested MSI-IRQ lines
env: FUZZ_TRACE_DMA (default 0): trace dma allocations, syncs and maps
env: FUZZ_TRACE_DMAINJ (default 0): trace asan based coherent dma injection
env: FUZZ_TRACE_CONF (default 0): trace pci device configuration
env: FUZZ_TRACE_WAITERS (default 0): trace addition and removal of blocked workloads
env: FUZZ_TRACE_BST (default 0): trace management and verification of mapped dma addresses
env: FUZZ_TRACE_DONECB (default 0): trace io-stream end callback invocation
env: FUZZ_TRACE_DEVNODES (default 0): trace allocation of device nodes

Patch Configuration

apply_patch (default 0), overwritten by env:PATCH: apply patches to avoid assertions, deadlocks and unbounded allocations
apply_patch_2 (default 0), overwritten by env:PATCH2: apply patches for remaining bugs (if available)
apply_hacks (default 0), overwritten by env:HACKS: apply fuzzing optimizations

Delay Configuration

env: MIN_ALL_DELAY: sets all options below to one
minimize_delay (default 0): reduce delay and sleep
minimize_wq_delay (default 0): reduce delay in queue_delayed_work
minimize_timeout (default 0): reduce timeout in schedule_timeout_*
minimize_timebefore/after (default 0): reduce delay through in time_before/_after*

Runtime Configuration

loglevel (default: 0), overwritten by env:LOGLEVEL: kernel log level (0=no log, 8=verbose)
target_irqs (default: 0), overwritten by env:TARGET_IRQS: use targeted IRQ injection
fast_irqs (default: 0), overwritten by env:FAST_IRQS: trigger IRQ immediatly after request_irq
do_update_hwm (default: 1), overwritten by env:UPDATEHWM: update io-stream size after each iteration
use_bst (default: 0), overwritten by env: USEBST: keep track of mapped dma addresses and valiadate them on sync and unmap

Network Configuration

interface (default: NULL): name of network interface
ifindex (default: 0): network interface index
mtu (default: -1): minimum transfer unit size

Adding a new Harness

The fuzzing harness is device specific, therefore such functionality has been separated into different libs. The harness libs must implement the function mod_fuzz (will be called from LLVMFuzzerTestOneInput) and can optionally provide mod_init (will be called at the end of LLVMFuzzerInitialize). See src/harness/ for examples. The harness library to be used is selected in the config file via the harness parameter. To create a new harness, implement the functionality in src/harness/<new_target_harness>.c and add bin/harness/<new_target_harness>.so to the the TARGET_HARNESS list in Makefile

Concurrent IRQ Triggering

Most of the default fuzzing harnesses start an IRQ thread. If the target blocks on resources which have to be generated asynchronously on the IRQ path, configure an IRQ callback in mod_init via start_irqthread_cb(irq_cb) and call request_irqs(<max_irqs>) before invoking the blocking function from the mod_fuzz function in the harness lib. If <max_irqs>==-1 an unlimited amount of IRQs will be generated. Call cancel_irqs() to stall IRQ generation.

If targeted IRQ injection is enabled, the harness can call lkl_fuzz_wait_for_wait to block until a workload of the target module enters a blocked state. Call lkl_fuzz_has_waiters to check the current number of blocked threads. This should also be called before lkl_fuzz_wait_for_wait to avoid deadlocks. Coverage stability will probably suffer if using this, but targeted IRQ injection should help a bit.

IO-Stream End Callback

If the io-stream generated by the fuzzer is used up a callback function will be invoked. This callback function can be configured in mod_init via lkl_fuzz_set_done_callback(done_cb). By invoking start_thread_done_default() a default callback will be configured, that unloads the module when the IO stream is used up. Using this functionality correctly can be a bit tricky, since it can lead to deadlocks, so take care when adjusting the default functionality.

Add new Fuzzing Target

To add a new PCI, PLATFORM or VIRTIO target module:

Get the device config from the lkl linux source code (see Configuration for required parameters).
Configure the module in the lkl linux config (update defconfig, since the lkl build process overwrites .config)
Create a new config file in via/fuzz/configs/.
If the module has dependencies on other module add those to the config file as well (modules_dep). Otherwise the harness will crash due to undefined symbols.
Specify the device specific harness lib (see src/harness for already available harnesses or create a new one).

Notes

If you get an error like

lib/hijack/xlate.c:558:7: error: use of undeclared identifier 'SIOCGSTAMP

add the header

#include <linux/sockios.h>

To avoid leak detection notifications set this asan option (the leaks are an artefact of the harness)

export ASAN_OPTIONS=detect_leaks=0

If the drivers's probe function is not invoked, make sure that all the pci dev config options match the values set in struct pci_device_id. This include sub ids pci class etc. If you get iomem errors like error reading iomem 0x9 check the config options barsizes and barflags. You can add up to 6 iomem regions, adding more than requested by the driver is ok.

If the hwasan build fails, you can disable it; e.g. by removing X86_64 from ALL_HWASAN_SUPPORTED_ARCH

You can use gdb for debugging. Note that symbols are only resolved after the dynamic libraries have been loaded, so run the harness once to get all the symbols and then restart or continue.

FUZZ_TARGET=virtio_balloon gdb --args ./bin/runl__X.elf ./crash-2a7cf9bf19656b33acd7873f5ea251ad9d351b74
FUZZ_TARGET=virtio_balloon gdb --args ./bin/fuzzl__X.elf -detect_leaks=0 ./tmp_indir

file-citas / via Goto Github PK

via's Introduction