{"id":15115278,"url":"https://github.com/GJDuck/EnvFuzz","last_synced_at":"2025-09-27T20:32:18.659Z","repository":{"id":237126970,"uuid":"793857689","full_name":"GJDuck/EnvFuzz","owner":"GJDuck","description":"Fuzz anything with Program Environment Fuzzing","archived":false,"fork":false,"pushed_at":"2024-12-19T02:12:04.000Z","size":1537,"stargazers_count":357,"open_issues_count":1,"forks_count":24,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-19T03:21:49.320Z","etag":null,"topics":["binary","e9patch","fuzz-testing","fuzzing","gui-testing","network-fuzzer","reverse-execution","testing","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GJDuck.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-30T02:11:48.000Z","updated_at":"2024-12-19T02:12:08.000Z","dependencies_parsed_at":"2024-07-09T10:04:39.645Z","dependency_job_id":"15dbbadc-3c05-4706-9d3c-72ad3ea1c250","html_url":"https://github.com/GJDuck/EnvFuzz","commit_stats":null,"previous_names":["gjduck/rrfuzz","gjduck/envfuzz"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GJDuck%2FEnvFuzz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GJDuck%2FEnvFuzz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GJDuck%2FEnvFuzz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GJDuck%2FEnvFuzz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GJDuck","download_url":"https://codeload.github.com/GJDuck/EnvFuzz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234460505,"owners_count":18836837,"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":["binary","e9patch","fuzz-testing","fuzzing","gui-testing","network-fuzzer","reverse-execution","testing","testing-tools"],"created_at":"2024-09-26T01:43:44.739Z","updated_at":"2025-09-27T20:32:13.263Z","avatar_url":"https://github.com/GJDuck.png","language":"C++","readme":"Program Environment Fuzzing (EnvFuzz)\n=====================================\n\nEnvFuzz (\u0026#x3B5;Fuzz) is a new type of fuzzer that can **fuzz just about\nanything**, including:\n\n* Network servers/clients\n* *Graphical User Interface* (GUI) applications\n* Editors\n* Compilers\n* Databases\n* *any other Linux user-mode software*, etc.\n\nFor example, the following demo shows how to fuzz a *GUI application*\nusing EnvFuzz:\n\n---\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"img/demo.gif\"\n     alt=\"EnvFuzz demo\"\n     style=\"width: 85%;\"\u003e\n\u003c/p\u003e\n\n[*Demo of EnvFuzz fuzzing a GUI application binary (`gnome-calculator`).\nFirst, the app is run normally, and all environmental interactions (including\nuser inputs) are recorded to a file.\nNext, the app is fuzzed, this time by repeatedly replaying the original\nrecording but with one or mutations applied.\nEnvFuzz quickly finds several crashes, as highlighted in red.*]\n\n---\n\nUnlike existing fuzzers, which only fuzz a specific input source (like AFL),\nEnvFuzz fuzzes the **entire interaction** between the subject and its\nenvironment (\u0026#x3B5;)---including all files (configuration, cache, resource,\nfonts, etc.), sockets (session manager, accessibility service, name service,\netc.), user interactions via the windowing system, special files, devices, and\nstandard streams, as illustrated below:\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"img/calc-full.png\"\n     alt=\"Full calculator app environment\"\n     style=\"width: 60%;\"\u003e\n\u003c/p\u003e\n\nIn other words, EnvFuzz considers the entire environment (\u0026#x3B5;) itself is\nthe fuzz target---a.k.a.  *program environment fuzzing*.\nThis even includes user interactions via the windowing system (e.g., mouse\nmovements, button clicks, etc.), which are treated as just another input\nsource, no different than any other socket or file.\nThis makes EnvFuzz a very comprehensive fuzzer, as it will automatically fuzz\nall inputs (and input combinations), even obscure inputs that are normally\noverlooked in a typical fuzz campaign.\n\nEnvFuzz is also very general, and is designed to fuzz off-the-shelf user-mode\nLinux binaries with **zero configuration or set-up**.\nSee the demo above.\n\nHow EnvFuzz Works?\n------------------\n\nEnvFuzz is based on an underlying full environmental *Record and Replay* (rr)\nand fuzzing infrastructure.\nThe infrastructure is based on the insight that, for typical user-mode\nprograms, all environmental interactions pass through the kernel-user mode\ninterface.\nThus, by recording this interface, we also implicitly record the program's\ninteraction with the environment, which then can be subject to fuzzing.\nBasically, EnvFuzz works in two phases:\n\n1. A *Recording* phase that executes the program normally, and records all\n   interactions (e.g., system calls, signals, thread switches, etc.) between\n   the subject and its environment into a file.\n2. Next, a *Replay-with-Fuzzing* phase that repeatedly re-executes the program\n   in a fuzzing loop.\n   However, this time the original environmental interactions are replayed\n   from the recording, but with one or more possible mutations applied.\n   These mutations can induce new program behaviours and possible crashes.\n\nSince EnvFuzz works at the abstraction of environmental interactions, it can\nfuzz a very diverse range of subjects without any special-case handling.\nThis makes EnvFuzz powerful and easy-to-use.\n\nAn example of EnvFuzz usage is shown in the simple demo above:\n\n1. The first phase **records** the `gnome-calculator` app using the command:\n\n        $ ./env-fuzz record gnome-calculator\n\n    This creates an `out/` sub-directory, and the recording is stored in a\n    `out/RECORD.pcap.gz` file.\n\n2. The second phase **fuzzes** the `gnome-calculator` app using the command:\n\n        $ ./env-fuzz fuzz\n\n   The fuzzer uses the original recording from step (1.) as the initial seed,\n   and repeatedly re-executes the program.\n   Rather than replaying the original recording exactly, the fuzzer will\n   apply one (or more) mutations, inducing new program behaviours and\n   possible crashes.\n\nDiscovered crashes are stored in the `out/crash/` sub-directory, and can be\nreplayed using the command:\n\n        $ ./env-fuzz replay out/crash/SIGSEGV_XXXX_m0YYYY.patch\n\nWe applied EnvFuzz to a diverse range of programs and discovered several new\nbugs, including those that are difficult or impossible to find with\ntraditional fuzzers.\nFor more information, please see the preprint listed below.\n\nBuilding\n--------\n\nTo build EnvFuzz, simply run the `build.sh` script.\n\n        $ ./build.sh\n\nThis has only been tested on Ubuntu-based systems.\n\nEnvFuzz Usage\n-------------\n\nRecord:\n\n        $ ./env-fuzz record -- vim hello.txt\n\nReplay:\n\n        $ ./env-fuzz replay\n\nFuzz:\n\n        $ ./env-fuzz fuzz\n\nReplay crash:\n\n        $ ./env-fuzz replay out/crash/SIGSEGV_XXXX_mYYYYY.patch\n\nDebug crash:\n\n        $ ./env-fuzz replay out/crash/SIGSEGV_XXXX_mYYYYY.patch -d\n\nEnvFuzz also supports (optional) AFL-style coverage instrumentation:\n\nInstrument program binary:\n\n        $ ./env-fuzz instrument program\n\nThis will generate an instrumented `program.rr` binary, that can be\nsubstituted for the original.\n\nIt is also possible to instrument library code:\n\n        $ ./env-fuzz instrument /path/to/library.so\n\nThis will place an instrumented version of the library into the `lib/`\nsub-directory, which is included in the library search path.\n\nEnvFuzz Files\n-----------\n\nDuring fuzzing, several files will be generated:\n\n- `out/COMMAND.cmd`: The command-line\n- `out/RECORD.pcap.gz`: The recording\n- `out/crash/*.patch`: Crashing patches\n- `out/hang/*.patch`: Hanging patches\n- `out/abort/*.patch`: Aborting patches\n- `out/queue/m*/*.patch`: Interesting patches\n- `lib/`: Location where the patched `libc` and instrumented libraries are stored.\n\nNote that interactions stored in the `out/RECORD.pcap.gz` file can be viewed\nusing Wireshark.\n\nEnvFuzz Technical Information\n---------------------------\n\nEnvFuzz uses [E9Patch](https://github.com/GJDuck/e9patch) to statically rewrite\nall `syscall` instructions in `libc`.\n\n* https://github.com/GJDuck/e9patch\n\nThus, whenever the program invokes a system call (e.g., `open`, `read`,\n`write`, etc.), the call will be diverted to our record-and-replay\ninfrastructure.\nFor recording, the infrastructure acts as a *man-in-the-middle* between user\nand kernel-mode, and all interactions are saved to a file.\nFor replay (with fuzzing), the program is (repeatedly) executed again, but\nthis time each system call is *replayed* from the original recording, possibly\nwith one or more mutations applied.\nDuring replay, system calls are almost entirely serviced from the recording,\nand there is no interaction with the kernel and the real environment.\nIn addition to `libc` system calls, EnvFuzz also special methods for handling\nthe vDSO, signals, thread switches, and syscall instructions outside of\n`libc`.\nEnvFuzz does not use ptrace.\n\nOne problem is that program behaviour can (and will) diverge after a mutation\nis applied.\nIndeed, the main point of fuzzing is to induce new behaviours in the hope of\nfinding new bugs.\nTo handle this case, EnvFuzz resorts to \"system call emulation\" after\nmutation, in a \"relaxed\" replay-mode.\nThis allows for diverse program behaviours to be explored using only the\noriginal recording.\nPlease see the preprint below for more information.\n\nEnvFuzz Status\n--------------\n\nImplementing a full environmental record and replay infrastructure is\nnotoriously challenging.\nFor example, the related `rr-debug` project estimates a total of *five\nperson-years total* ([source](https://arxiv.org/pdf/1705.05937)) was spent on\ndevelopment (as of 2017), and even then it cannot perfectly record and replay\nall programs.\nOur underlying record and eplay framework has not nearly had as much\ndevelopment time, and the current implementation should be viewed as a\n\"research prototype\" that will not necessarily work for all programs.\nNevertheless, we provide the system \"as-is\", *since EnvFuzz has been proven\neffective at finding bugs that other fuzzers cannot detect*, even if the\nimplementation is not fully polished.\n\nWe will continue to develop and improve EnvFuzz depending on the level of\ninterest from the community.\n\nEnvFuzz Issues\n--------------\n\nPlease keep in mind that EnvFuzz is alpha-quality software and a research prototype.\n\nPlease report obvious bugs here:\n\n* https://github.com/GJDuck/EnvFuzz/issues\n\nIssues relating to unexpected divergence during replay should generally not be\nreported.\nThat said, pull requests that fix divergence issues are very welcome.\n\nSimilarly, issues relating to missing ioctls, fcntls, and prctls should not be\nreported.\nInstead, you should update the corresponding `.tab` file if possible, and\nconsider making a pull request.\n\nAcknowledgement\n---------------\n\nThis research is supported by the National Research Foundation, Singapore,\nand Cyber Security Agency of Singapore under its National Cybersecurity R\u0026D\nProgramme (Fuzz Testing NRF-NCR25-Fuzz-0001).  Any opinions, findings and\nconclusions, or recommendations expressed in this material are those of the\nauthor(s) and do not reflect the views of National Research Foundation,\nSingapore, and Cyber Security Agency of Singapore.\n\nLicense\n-------\n\nThis software has been released under the GNU Public License (GPL) Version 3.\nSee the `LICENSE` file for more information.\n\nCiting EnvFuzz\n--------\n\nFor more information, please see our research paper:\n\n* Ruijie Meng, Gregory J. Duck, Abhik Roychoudhury, [*Program Environment Fuzzing*](https://arxiv.org/abs/2404.13951), ACM SIGSAC Conference on Computer and Communications Security (CCS), 2024.\n\nIf you use this code in your scientific work, please cite the paper as follows:\n\n    @inproceedings{envfuzz,\n        title={Program Environment Fuzzing},\n        author={Meng, Ruijie and Duck, Gregory J. and Roychoudhury, Abhik},\n        booktitle={Proceedings of the 31st ACM SIGSAC Conference on Computer and Communications Security (CCS)},\n        year={2024}\n    }\n\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGJDuck%2FEnvFuzz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGJDuck%2FEnvFuzz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGJDuck%2FEnvFuzz/lists"}