{"id":31030941,"url":"https://github.com/0xccf4/ufuzz","last_synced_at":"2025-09-13T23:53:02.490Z","repository":{"id":313611407,"uuid":"1017831872","full_name":"0xCCF4/ufuzz","owner":"0xCCF4","description":"A microcode-feedback-enhaced post-silicon x86 CPU fuzzer","archived":false,"fork":false,"pushed_at":"2025-09-07T08:38:51.000Z","size":2655,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T10:17:51.647Z","etag":null,"topics":["cpu","fuzzer","fuzzing","hardware-fuzzing","microcode","microcode-speculation","microcode-update","x86"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xCCF4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-11T07:01:41.000Z","updated_at":"2025-09-07T08:38:53.000Z","dependencies_parsed_at":"2025-09-07T10:18:03.471Z","dependency_job_id":"2ff1da25-95df-4df3-a232-bfd82155f757","html_url":"https://github.com/0xCCF4/ufuzz","commit_stats":null,"previous_names":["0xccf4/ufuzz"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/0xCCF4/ufuzz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xCCF4%2Fufuzz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xCCF4%2Fufuzz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xCCF4%2Fufuzz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xCCF4%2Fufuzz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xCCF4","download_url":"https://codeload.github.com/0xCCF4/ufuzz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xCCF4%2Fufuzz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275043662,"owners_count":25395591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpu","fuzzer","fuzzing","hardware-fuzzing","microcode","microcode-speculation","microcode-update","x86"],"created_at":"2025-09-13T23:53:00.867Z","updated_at":"2025-09-13T23:53:02.469Z","avatar_url":"https://github.com/0xCCF4.png","language":"Rust","readme":"# Fuzzilicon\nA x86 CPU fuzzer utilizing microcode coverage\n\nInternal synonym: uFuzz\n\n## Overview\nuFuzz is the first x86 CPU fuzzer that leverages microcode coverage information as feedback to guide the fuzzing campaign. For more details see the [paper](xxx).\n\n## Structure\nuFuzz consists of three different systems:\n1. The fuzzer agent: This is the target device that runs the device under test. We used the [Gigabyte Brix (GB-BPCE-3350C-BWUP)](https://www.gigabyte.com/de/Mini-PcBarebone/GB-BPCE-3350C-rev-10) with an Intel Apollo Lake (Celeron, Goldmont) N3350 processor (`CPUID[1].EAX=0x506ca`) ; vulnerable to the Red-unlock vulnerability.\n2. A fuzzer instrumentor: This is a device that emulates a USB storage (for serving the UEFI app) and USB keyboard for skipping the BIOS screen automatically, further controls the power supply of the fuzzer device. (Raspberry Pi 4)\n3. The fuzzer controller: The main fuzzing loop runs here, tasks are scheduled on the fuzzer device for execution. (Raspberry Pi 4)\n\n## Project structure\nThe uFuzz project is structured as follows:\n\nComponent       | Description\n--------------- | -----------\n[`corpus-gen`](corpus-gen/) | Generates the corpus for initial fuzzing inputs. See the evaluation section of the paper. \n[`coverage`](coverage/) | Collects microcode coverage from the CPU by deploying microcode updates\n[`custom_processing_unit`](custom_processing_unit/) | Contains utility function derived from [CustomProcessingUnit*](https://github.com/pietroborrello/CustomProcessingUnit).\n[`data_types`](data_types/) | Contains shared data types for writing custom microcode updates.\n[`fuzzer_data`](fuzzer_data/) | Contains shared data between the fuzzer instance and fuzzer master controller.\n[`fuzzer_device`](fuzzer_device/) | Contains the implementation of the fuzzing agent, which runs on the target device/CPU.\n[`fuzzer_master`](fuzzer_master/) | Contains the implementation of the fuzzer controler that controls a fuzzer agent.\n[`fuzzer_node`](fuzzer_node/) | Contains the implementation of the fuzzer device instrumentor - emulating USB devices for the fuzzer device.\n[`hypervisor`](hypervisor/) | Contains the implementation of the hypervisor environment.\n[`literature_search`](literature_search/) | Contains a tool to search connected/related works by paper connections.\n[`nix`](nix/) | Contains the definition of system of the fuzzer master and fuzzer instrumentor.\n[`performance_timing`](performance_timing/) | Contains the tools to collect timing information from the fuzzer device,\n[`performance_timing_macros`](performance_timing_macros/) | Contains utility macros to automate timing collection from target functions.\n[`spec_fuzz`](spec_fuzz/) | Contains the implementation of the speculative micrcode fuzzer.\n[`speculation_x86`](speculation_x86/) | Contains some test scenarios to check speculative execution behavior.\n[`speculation_ucode`](speculation_ucode/) | Contains some test scenarios to check speculative execution behavior.\n[`ucode_compiler_bridge`](ucode_compiler_bridge/) | Contains a bridge implementation to interface with the microcode compiler from [CustomProcessingUnit*](https://github.com/pietroborrello/CustomProcessingUnit) and preprocessor macros for deriving multi file microcode updates.\n[`ucode_compiler_derive`](ucode_compiler_derive/)| Contains utility macros to automate the generation of microcode updates.\n[`ucode_compiler_dynamic`](ucode_compiler_dynamic/) | Contains runtime mircocode update compilation.\n[`ucode_dump`](ucode_dump/) | Contains microcode dumps of the CPU.\n[`uefi_udp4`](uefi_udp4/) | Contains a basic UEFI driver implementation of UDP.\n[`x86_perf_counter`](x86_perf_counter/) | Contains the implementation to use x86 performance counters. \n[`xtask`](xtask/) | Contains build automation for this project.\n\n\\* CustomProcessingUnit: Licensed under the Apache License, Version 2.0\n\n## Install dependencies\nTo build and run the uFuzz project, you will need the Rust compiler with the nightly toolchain and UEFI target support.\n```bash\n# Install python (ubuntu/debian); required for the CustomProcessingUnit microcode compiler\nsudo apt install python3 python3-click\n\n# Install compiler\nsudo apt install gcc-aarch64-linux-gnu build-essential git\n\n# Install rust\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain none -y # installs rustup\nrustup install nightly-2025-05-30 # verified to work with the project\nrustup target add x86_64-unknown-uefi # to compile UEFI applications\nrustup target add aarch64-unknown-linux-gnu # to compile the fuzzer instrumentor\nrustup target add x86_64-unknown-linux-gnu # to compile documentation\nrustup default nightly-2025-05-30 # set the default toolchain to nightly\n```\n\n## Getting started\nDownload [CustomProcessingUnit](https://github.com/pietroborrello/CustomProcessingUnit) and 1. place it into the parent directory of this folder or 2. set the env var `UASM` to the\n`uasm.py` file from CustomProcessingUnit. The uFuzz project uses the `uasm.py` script to compile microcode updates.\n\nThen apply the following git-patch to `uasm.py`: [uasm.py.patch](ucode_compiler_bridge/uasm.py.patch).\n\nTo deploy the fuzzer instrumentor and fuzzer master, you will need `nix` installed (follow \u003chttps://nixos.org/download/\u003e to install the package manager).\nGo into the [`nix`](nix/) directory, change the public ssh keys, IPs etc., to your likings,\nand run the following commands to build the SD card images for the PIs (`|\u0026 nom` is optional):\n```bash\nnix build .#images.master |\u0026 nom\nnix build .#images.node |\u0026 nom\n```\nThis builds SD card images for the fuzzer master and fuzzer instrumentor. After initial setup,\nfurther changes may be deployed using (deploy-rs) by running in the `nix` directory (`|\u0026 nom` is optional):\n```bash\nnix run |\u0026 nom\n```\n\nTo built and deploy the fuzzer device UEFI app:\n```bash\nHOST_NODE=\"put IP of the instrumentor here\" cargo xtask put-remote\n  --remote-ip {address of fuzzer controller}\n  --source-ip {address of agent}\n  --netmask {network mask}\n  --port {udp port}\n  --startup {app name here}\n```\nDepending on the target fuzzing scenario, use `spec_fuzz` (speculative microcode fuzzing) or `fuzzer_device` (x86 instruction fuzzing)\ninstead of `{app name here}`.\n\nThen boot the fuzzer master. Start the `fuzzer_master` app. Settings can be displayed by using `--help` in the CLI.\n          \n```bash\nfuzzer_master --help\n\n# Main fuzzing application. This app governs and controls the entire fuzzing process, issuing commands to a fuzzer agent (which e.g. executes fuzzing inputs on its CPU)\n# \n# Usage: fuzz_master [OPTIONS] \u003cCOMMAND\u003e\n# \n# Commands:\n#   genetic               Perform coverage fuzzing using (bad) genetic mutation algorithm, probably you would like to execute the `afl` command. == Requires the `fuzzer_device` app running on the agent ==\n#   instruction-mutation  Under-construction\n#   init                  Bring up the fuzzer agent to a usable state\n#   reboot                Reboot the fuzzer agent\n#   cap                   Report the capabilities of the fuzzer agent\n#   performance           Extract performance values from the fuzzer agent\n#   spec                  Do speculative microcode fuzzing == Requires the `spec_fuzz` app running on the agent ==\n#   spec-manual           Executes a given speculative fuzzing payload manually == Requires the `spec_fuzz` app running on the agent ==\n#   manual                Executes a single fuzzing input manually == Requires the `fuzzer_device` app running on the agent ==\n#   bulk-manual           Executes a corpus of fuzzing inputs; essentially runs the manual command using all files within the given directory == Requires the `fuzzer_device` app running on the agent ==\n#   afl                   Executes the main fuzzing loop with AFL mutations == Requires the `fuzzer_device` app running on the agent ==\n#   help                  Print this message or the help of the given subcommand(s)\n# \n# Options:\n#   -d, --database \u003cDATABASE\u003e          The database file to save fuzzing progress and results to; a .gz extension enables gzip compression\n#       --compression \u003cCOMPRESSION\u003e    Compression level of database when using gzip compression (1-9) [default: 6]\n#       --dont-reset                   Dont reset address blacklist\n#       --instrumentor \u003cINSTRUMENTOR\u003e  Address of the fuzzer instrumentor [default: http://10.83.3.198:8000]\n#       --agent \u003cAGENT\u003e                Address of the fuzzer agent [default: 10.83.3.6:4444]\n#   -h, --help                         Print help\n#   -V, --version                      Print version\n```\n\nEach mentioned `fuzz_master` commands (experiments) includes built-in help documentation that allows you to specify parameters. For example:\n\n- For running the fuzzing campaign with AFL mutations:\n```bash\nfuzz_master afl --help\n\n# Executes the main fuzzing loop with AFL mutations == Requires the `fuzzer_device` app running on the agent ==\n# \n# Usage: fuzz_master afl [OPTIONS]\n# \n# Options:\n#   -s, --solutions \u003cSOLUTIONS\u003e          Store findings to this path\n#   -c, --corpus \u003cCORPUS\u003e                Use the provided corpus file to generate initial fuzzing inputs from\n#   -a, --afl-corpus \u003cAFL_CORPUS\u003e        Store the fuzzing corpus to that path\n#   -t, --timeout-hours \u003cTIMEOUT_HOURS\u003e  End fuzzing after that many hours automatically, if not set fuzzing does not terminate\n#   -d, --disable-feedback               Disabled coverage fuzzing feedback; instead fuzzing feedback is randomized\n#   -p, --printable-input-generation     When not using the `corpus` argument; initial fuzzing inputs are random byte sequences; enabling this flag these byte sequences are selected among printable ASCII characters\n#   -h, --help                           Print help\n```\n\n- For running the fuzzing campaign with pure genetic mutations:\n```bash\nfuzz_master genetic --help\n\n# Perform coverage fuzzing using (bad) genetic mutation algorithm, probably you would like to execute the `afl` command. == Requires the `fuzzer_device` app running on the agent ==\n# \n# Usage: fuzz_master genetic [OPTIONS]\n# \n# Options:\n#   -c, --corpus \u003cCORPUS\u003e                A corpus file to generate the initial fuzzing inputs from\n#   -t, --timeout-hours \u003cTIMEOUT_HOURS\u003e  After how many hours the fuzzing should be terminated. If not given fuzzing must be interrupted by CTRL+C\n#   -d, --disable-feedback               Disable the feedback loop, fuzzing input ratings will become randomized\n#   -h, --help                           Print help\n```\n\n- For running the fuzzing campaign with speculative microcode fuzzing:\n```bash\nfuzz_master spec --help\n\n# Do speculative microcode fuzzing == Requires the `spec_fuzz` app running on the agent ==\n# \n# Usage: fuzz_master spec [OPTIONS] \u003cREPORT\u003e\n# \n# Arguments:\n#   \u003cREPORT\u003e  Path to database; save the results to this file\n# \n# Options:\n#   -a, --all                Execute fuzzing for all instructions extracted from MSROM\n#   -s, --skip               Skip instruction that were already run; continue a stopped fuzzing execution\n#   -n, --no-crbus           Skip all CRBUS related instructions\n#   -e, --exclude \u003cEXCLUDE\u003e  Exclude a list of instructions from running through the fuzzer\n#   -f, --fuzzy-pmc          Run all PMC variants through the fuzzer; takes a long time\n#   -h, --help               Print help\n```\n---\n\nThe fuzzing results will be stored to a database file (specifiable via the `--database` argument) (fuzzer master) \nand can be viewed by running (fuzzer master):\n```bash\nfuzz_viewer database.json.gz\n```\n\n---\n\nThe following binaries are provided for the fuzzing master:\n\n| Binary              | Description                                                                                    |\n|---------------------|------------------------------------------------------------------------------------------------|\n| `fuzzer_master`     | Main fuzzing controller, main fuzzing loop + manual execution, list all options using `--help` |\n| `fuzz_viewer`       | Tool for viewing and analyzing fuzzing results from the database                               |\n| `fuzz_compare`      | Compares execution results from different manual fuzzing input executions                      |\n| `spec_compare`      | Analyzes and compares results from speculative execution fuzzing campaigns                     |\n| `spec_new_database` | Creates new speculative execution databases from templates (copies exclusions)                 |\n| `fuzz_combine`      | Combines multiple fuzzing databases into a single output database                              |\n| `afl_convert`       | Converts AFL fuzzing findings to inputs usable with the manual execution fuzzing tool          |\n\n## Documentation\nGenerate the rust doc documentation using the following command:\n```bash\ncargo xtask doc\n```\nThe results will be placed inside the build directory `target/doc`\n\n## Utilities\nThe `cargo xtask` command contains utilities to, for example, test the hypervisor environment on a simulated\nCPU using the bochs emulator; allowing easier debugging.\n```bash\ncargo xtask emulate hypervisor bochs-intel\n```\n\nList all available xtask commands using:\n```bash\ncargo xtask --help\n\n# A build and test assist program\n# \n# Usage: xtask \u003cCOMMAND\u003e\n# \n# Commands:\n#   emulate         Emulate a UEFI application using BOCHS CPU emulator\n#   put-remote      Push an UEFI app onto the remote machine\n#   control-remote  Control a remote machine\n#   update-node     Update the node's software, systemd service, etc\n#   doc             Generate documentation\n#   check           Compile all examples and subprojects\n#   help            Print this message or the help of the given subcommand(s)\n# \n# Options:\n#   -h, --help  Print help\n```\n\n### Cite Us\n\nA up-to-date version of the source-code can be found at: \u003chttps://github.com/0xCCF4/ufuzz\u003e\n\nOur work has been published as a [paper](xxx) at Network and Distributed System Security Symposium 2026 ([NDSS'26](https://www.ndss-symposium.org/ndss2026/)): \n```\n@inproceedings{TBD}\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xccf4%2Fufuzz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xccf4%2Fufuzz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xccf4%2Fufuzz/lists"}