{"id":22381842,"url":"https://github.com/googleinterns/hw-fuzzing","last_synced_at":"2025-07-31T02:32:59.230Z","repository":{"id":50309004,"uuid":"275233005","full_name":"googleinterns/hw-fuzzing","owner":"googleinterns","description":null,"archived":false,"fork":false,"pushed_at":"2023-01-20T06:08:48.000Z","size":2275,"stargazers_count":78,"open_issues_count":4,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-01T06:16:35.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googleinterns.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-26T19:32:49.000Z","updated_at":"2024-11-13T21:27:47.000Z","dependencies_parsed_at":"2023-02-12T00:05:13.357Z","dependency_job_id":null,"html_url":"https://github.com/googleinterns/hw-fuzzing","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fhw-fuzzing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fhw-fuzzing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fhw-fuzzing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleinterns%2Fhw-fuzzing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googleinterns","download_url":"https://codeload.github.com/googleinterns/hw-fuzzing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228209947,"owners_count":17885595,"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","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":[],"created_at":"2024-12-05T00:10:38.688Z","updated_at":"2024-12-05T00:10:39.387Z","avatar_url":"https://github.com/googleinterns.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fuzzing Hardware Like Software\n\n**Maintainer**: Timothy Trippel\n\u003cbr\u003e\n**Personal Website**: https://timothytrippel.com\n\u003cbr\u003e\n\n\u003cfigure\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/figures/hwf_process.png\" \n    data-canonical-src=\"docs/figures/hwf_process.png\" width=\"75%\"/\u003e\n    \u003cbr\u003e\n    \u003cb\u003eFigure 1: Fuzzing Hardware Like Software.\u003c/b\u003e\n  \u003c/p\u003e\n\u003c/figure\u003e\n\nDue to the economic and reputational incentives to design and fabricate flawless\nhardware, design verification research has been an active arena. Unfortunately\nthe fruits of this labor mainly consist of strategies concentrated at two\nextremes: 1) broad coverage through constrained random verification, or 2)\n(bounded) formal verification. Moreover, both of these techniques require\nextensive implementation knowledge of the Design Under Test (DUT) to be\neffective.\n\nTo close this gap, we propose _fuzzing hardware like software_ to automate test\nvector generation in an intelligent manner---that boosts coverage---_without_\nrequiring expensive Design Verification (DV) engineers and tools. A technical\npaper describing this project can be found\n[here](https://arxiv.org/pdf/2102.02308.pdf).\n\nIn this project, we demonstrate how to translate RTL hardware to a software\nmodel, and leverage coverage-guided software fuzzers---like\n[AFL](https://github.com/google/AFL)---to automate test vector generation for\nhardware verification (Figure 1). Specifically we demonstrate this technique on\nhardware from the [OpenTitan](https://opentitan.org/) IP ecosystem. While we do\nnot suggest this as a replacement to traditional DV methods for sign-off, we\nargue this technique serves a low-cost preventative mechanism to identify\ncomplex hardware vulnerabilities _before_ they are exploited for malice.\n\nTo understand the layout of this project and how to get started, read below.\n\n## Directory Structure\n\n### docs\n\nThis directory currently only contains a document that describes how to\ncontribute to this project and some figures that are displayed in this README.\nHowever, it will be the location of any future documentation that is added.\n\n### experiment_scripts\n\nThis directory contains some python scripts to automate launching large batches\nof fuzzing experiments on GCP VMs. Additionally there are some scripts that can\nbe used to plot fuzzing data using Seaborn/Matplotlib.\n\n### hw\n\nThis directory contains several supporting files to fuzz various various\nOpenTitan hardware IP blocks. Currently, the following OpenTitan IP blocks are\nsupported: AES, HMAC, KMAC, and the RV Timer. Additionally, a subdirectory\ncalled _ot_template_ can be copied, and the files within edited, to bring-up \nanother OpenTitan IP block for fuzzing. Lastly, a custom digital _lock_ hardware\nblock is included to stress test our fuzzing infrastructure. This block is\nactually autogenerated by a tool written in Rust (using the\n[kaze](https://docs.rs/kaze/0.1.18/kaze/) crate). For more details checkout the\ntechnical paper linked above.\n\n### infra\n\nThis directory contains several subdirectories that contain Dockerfiles and\nShell/Python scripts that makeup a containerized infrastructure for fuzzing\nhardware designs at scale. This infrastructure is modeled after Google's\n[OSS-Fuzz](https://github.com/google/oss-fuzz) project. This infrastructure can\nbe used to jumpstart fuzzing hardware locally or on GCP (provided you have an\nactive account). See _Getting Started_ below for how to build this\ninfrastructure. Read the technical paper above for exactly what is included in\nthe fuzzing infrastructure.\n\n### tests\n\nThis directory contains some HJSON fuzzing configuration files along with a\nPython script to test the overall fuzzing infrastructure is successfully\nsimulating OpenTitan hardware.\n\n## Getting Started\n\n### I. Clone/Fork Repository\n\n1. `git clone https://github.com/googleinterns/hw-fuzzing.git`\n2. `cd hw-fuzzing`\n\n### II. Set Environment Variables\n\nTo use any of the fuzzing infrastructure, which consists of: 1) building several\nDocker images to isolate fuzzing each target hardware IP block, and 2) using two\n(included) Python packages, some environment variables must be set. You can set\nthem system wide, however, I recommend using the\n[direnv](https://github.com/direnv/direnv) tool to set/unset them when you\nenter/leave your _hw-fuzzing_ project directory.\n\n##### Using direnv (assuming it is installed):\n\n1. Create a `.envrc` file in the hw-fuzzing root directory with the following:\n\n```\nexport HW_FUZZING=$(pwd)\nexport PYTHONPATH=\"./:../:$(pwd)/infra/hwfp:$(pwd)/infra/base-sim/hwfutils\"\n```\n\n2. `direnv allow`\n\n##### Setting system-wide:\n\nAdd the above two lines to your _.bashrc_ or _.zshrc_ (depending on the shell\nyou use), except replace the _\\$(pwd)_ within each statement with the global\npath to your _hw-fuzzing_ directory.\n\n### III. Install Python Dependencies\n\nThe automated Hardware Fuzzing Pipeline (HWFP) Python tooling is tested using\nPython 3.8, and requires the following dependencies.\n\n1. Create Python virtual environment (not required, but recommended).\n2. Activate virtual environment (if you made one).\n3. `pip install -r infra/hwfp/requirements.txt`\n4. `pip install -r infra/base-sim/hwfutils/requirements.txt`\n\n### IV. [Install Docker](https://docs.docker.com/get-docker/)\n\n### V. Build Docker Infrastructure\n\n1. `make build-infra`\n2. Grab a cup of coffee ☕... this will take a while since we are building LLVM\n   here.\n\n### VI. Fuzz a Design\n\n##### a. Fuzzing Locally\n\n1. `make fuzz-\u003ccore\u003e` where `\u003ccore\u003e` is [aes, hmac, kmac, rv_timer] to launch\n   interactive container.\n2. `run` to begin RTL translation, intrustmentation, and fuzzing (if in manual\n    mode, which is default, otherwise this step can be skipped).\n2. Press `Ctrl+c` to terminate fuzzing and begin final coverage tracing.\n\n##### b. Fuzzing on GCP\n\n1. Create GCP account.\n2. Create a GCS bucket to store all fuzzing data.\n3. Edit the _gcp_config.hjson_ file with your GCP project details.\n4. Edit the value for the _run_on_gcp_ key in the _cpp_afl.hjson_\n   configuration file for the core you want to fuzz in _hw/`\u003ccore\u003e`/_.\n5. Run `make fuzz-\u003ccore\u003e`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleinterns%2Fhw-fuzzing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogleinterns%2Fhw-fuzzing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleinterns%2Fhw-fuzzing/lists"}