This directory provides the statically compiled fuzzer which produces reproducers (yaml files). The code resides in client. The remaining code is supporting code for re-running and expanding these reproducers.

The framework largely depends on Nix for package retrieval. If not done already run direnv allow. This should expand FRAMEWORK_ROOT and load the needed packages.

The fuzzer is implemented largely in client/src/architectural-sc-fuzzer.c and client/src/lib/sc_fuzzing_lib.h. It can be build by calling:

build-client --check-mem --vector --seq-len 76 --target exfilstate --out exfilstate

This produces a binary exfilstate in the CWD.

The fuzzer can just be copied to a machine and run. It also supports Android (e.g., via Termux). The fuzzer first finds which instructions it should use and then starts a campaign. The results are saved in outdir relative to the CWD.

A typical outdir looks like this:

outdir
|-- 4108d034
|   `-- 04_04
|       `-- 073_097_1_2_00315_00020.yaml
|-- 4108d092
|   |-- 00_00
|   |   |-- 100_100_1_2_00007_00001.yaml
|   |   `-- 100_100_1_2_00333_00016.yaml
|   `-- 11_11
|       |-- 077_099_1_2_00419_00024.yaml
|       |-- 078_088_1_3_00091_00007.yaml
|       |-- 082_096_1_4_00256_00015.yaml
|       |-- 082_098_1_2_00006_00002.yaml
|       |-- 082_099_1_2_00251_00012.yaml
|       |-- 082_099_1_2_00338_00019.yaml
|       |-- 088_094_1_2_00250_00014.yaml
|       |-- 089_100_1_2_00007_00003.yaml
|-- cpuinfo
|-- instruction_list_0
|-- instruction_list_1
|-- instruction_list_2
|-- instruction_list_3
|-- instruction_list_4
|-- instruction_list_5
|-- possible
|-- progress_worker_0
|-- progress_worker_1
|-- progress_worker_2
|-- progress_worker_3
|-- progress_worker_4
`-- progress_worker_5

The instruction lists and progress logs for each worker (core) and the reproducers stored in the directories named after the MIDR (the microarchiteture's identifier). The name of the reproducer can be read as follows:

11_11/077_099_1_2_00419_00024.yaml

• 11_11/ → Signal number of architectural outcomes. Here SEGV vs. SEGV.
• 077 → Correct rate (%) of best result.
• 099 → F-score.
• 1 → Number of differences (n_diffs).
• 2 → Sequence length (seq_len).
• 00419 → Seconds since start.
• 00024 → Counter (unique reproducer index).

The results can be copied off the machine after a fuzzing run. To expand the metadata of these reproducers, run expand-repro <path-to-dir-or-single-reproducer>. This is needed before the clustering stage for example and is just much nicer to inspect.

To quickly skim over expanded reproducers run:

for dir in outdir/*/*/; do find "$dir" -maxdepth 1 -type f | head -n 1; done | xargs bat --style=header --line-range :100

Reproducer files (yaml) can be compiled to static binaries for quick reproduction. The framework provides multiple commands for that.

init-repro-template produces a C program that can be compiled and run:

init-repro-template outdir/4108d034/04_04/073_097_1_2_00315_00020.yaml

Creates a file outdir/4108d034/04_04/073_097_1_2_00315_00020.c.

This file can then be compiled with:

build-repro outdir/4108d034/04_04/073_097_1_2_00315_00020.c

This produces a static binary outdir,4108d034,04_04,073_097_1_2_00315_00020.

build-repro-run-on allows for quickly building and running on a machine using ssh:

build-repro-run-on outdir/4108d034/04_04/073_097_1_2_00315_00020.c -- <ssh/hostname>

init-build-run-on allows for quickly initializing, building and running on a machine using ssh:

init-build-run-on outdir/4108d034/04_04/073_097_1_2_00315_00020.yaml -- -- <ssh/hostname>

The reproducer binaries automatically pin to the correct microarchitecture.

For all these scripts the following flags can be used:

• --orig-seq: Use the original bytes as sequence and not assemble the recovered assembly instructions.
• --no-sig: Build the reproducer without signal handling, i.e., plain. This is not that useful for the reproducers generated by exfilstate.