{"id":31747661,"url":"https://github.com/aflplusplus/linux-qemu-image-builder","last_synced_at":"2025-10-09T13:44:10.755Z","repository":{"id":318658542,"uuid":"846010860","full_name":"AFLplusplus/linux-qemu-image-builder","owner":"AFLplusplus","description":"Linux kernel VM builder to create customizable \u0026 ready-to-fuzz QEMU images","archived":false,"fork":false,"pushed_at":"2025-10-08T12:09:19.000Z","size":72,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-08T14:23:19.691Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AFLplusplus.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-22T11:15:56.000Z","updated_at":"2025-10-08T12:09:23.000Z","dependencies_parsed_at":"2025-10-08T14:23:34.324Z","dependency_job_id":"21af2d34-3fa5-498b-9d42-0bf1dbb273c2","html_url":"https://github.com/AFLplusplus/linux-qemu-image-builder","commit_stats":null,"previous_names":["aflplusplus/linux-qemu-image-builder"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AFLplusplus/linux-qemu-image-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Flinux-qemu-image-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Flinux-qemu-image-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Flinux-qemu-image-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Flinux-qemu-image-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AFLplusplus","download_url":"https://codeload.github.com/AFLplusplus/linux-qemu-image-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Flinux-qemu-image-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001461,"owners_count":26083102,"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-10-09T02:00:07.460Z","response_time":59,"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":[],"created_at":"2025-10-09T13:44:09.394Z","updated_at":"2025-10-09T13:44:10.749Z","avatar_url":"https://github.com/AFLplusplus.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linux kernel fuzzer template\n\nThis repository offers an easy way to set a QEMU-compatible, full-fledged and ready to fuzz Linux disk.\nUEFI is automatically configured to boot the Linux disk without any use interaction.\nWe use UKI for faster boot.\nIt has been tested successfully in both KVM and TCG mode on the x86\\_64 architecture.\n\nThe scripts have been kept as short and readable as possible, to make script hacking reasonably painless.\n\nThis repository has been designed with [LibAFL QEMU](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_qemu) in mind, although it is completely separated.\nThus, it should be quite easy to reuse this as a basis in other projects.\n\nPlease refer to the [LibAFL QEMU Linux fuzzer example]() for an example of usecase in a fuzzing context.\n\nFor more information about the technical details, you can have a look to [the design section](#design).\n\n## Prerequisites\n\nAt the moment, these scripts are only compatible with Linux.\n**Your kernel should have the NBD kernel module (it is the case in most cases) and docker available.**\n\nInstall docker if it's not already installed.\nAdapt this to your distribution if it's not debian-based.\n\n```bash\nsudo apt install -y docker.io qemu-utils qemu-system-x86 docker-buildx\n```\n\nTest if the NBD kernel module is installed on your host machine.\nThe following command should run successfully.\nOtherwise, your kernel is most likely not shipped with NBD.\nPlease install the NBD kernel module to proceed in case of error.\n\n```bash\nsudo modprobe nbd max_part=8\n```\n\n## Basic usage\n\nFor a quick test, first build the QCOW2 image.\n\n```bash\n./build.sh\n```\n\nIf everything goes well, there should be 3 files in `output`:\n- `linux.qcow2`: the image containing the Linux kernel and the root directory.\n- `OVMF_CODE.fd`: the OVMF UEFI code section.\n- `OVMF_VARS.fd`: the OVMF UEFI variable store.\n\nFrom there, it should be straightforward to run Linux in QEMU:\n\n```bash\n./run.sh\n```\n\nIf the login prompt appears after a few seconds, it means everything works as expected.\nWe configured user `root` and password `toor` as default credentials. This can be changed in `setup/setup.sh`.\nCheckout [the basic modification section](#basic-modifications) for more details.\n\nIt is also possible to run a headless (without a GUI) version of this.\nIt is a more common way to configure qemu for fuzzing.\n\n```bash\n./run_headless.sh\n```\n\n## Basic modifications\n\nFor the simplest modifications, we expect things to happen mostly in `hooks`. It contains 3 directories, running hooks at different moments of the installation process:\n- `setup` content will be copied under `/setup` in the VM and `/setup/setup.sh` will be run **during disk creation**, chrooted into the disk root directory. Edit `setup/setup.sh` with anything that should be done during the creation of the disk. It is requried to fully recreate the disk (with `build.sh`) if an update should be applied.\n- `runtime` content will be copied under `/runtime` in the VM and `/runtime/entrypoint.sh` will be run **each time the VM starts**. A service has been setup to handle everything automatically. Edit `runtime/entrypoint.sh` with anything that should be run at VM start. It is possible to run `update.sh` to automatically update the QEMU image without recreating the full disk. Beware, the old content of the `/runtime` directory (in the VM) will be lost forever.\n- `runtime_firstboot` content will be copied under `/runtime` in the VM and `/runtime/entrypoint.sh` will be run **each time the VM starts**. A service has been setup to handle everything automatically. Edit `runtime/entrypoint.sh` with anything that should be run at VM start. It is possible to run `update.sh` to automatically update the QEMU image without recreating the full disk. Beware, the old content of the `/runtime` directory (in the VM) will be lost forever.\n\n## Details\n\nMain scripts, expected to be run by most users:\n- `build.sh`: Build the QEMU image.\n- `parameters.sh`: Set of editable parameters and common functions used to create and run the VM.\n- `run.sh`: Run the QEMU VM (with GUI).\n- `run_headless.sh`: Run the QEMU VM (without GUI).\n- `update.sh`: Update `/runtime` (old VM `setup` and `runtime` will be erased).\n\nInternal scripts, for more advanced uses:\n- `scripts/create_image.sh`: Create the QEMU image without wrapping the execution in a docker container (main creation script is run there). It highly relies on `sudo`, run it on your host machine at your own risk.\n- `scripts/mount.sh`: Mount the QEMU disk under `mnt`. Can be run on the host machine.\n- `scripts/umount.sh`: Unmount the QEMU disk under `mnt`. Can be run on the host machine. It is supposed to be resilient and can be used to cleanup things in most cases.\n- `scripts/update.sh`: Update the QEMU image `setup` and `runtime` directory, without wrapping the execution in a docker container.\n\nOther stuff:\n- `templates`: various files and placeholders used during the creationg of the VM image.\n- `mnt`: Mount directory, folder where the disk get mounted when calling `scripts/mount.sh`\n\n## Design\n\nWe chose [ArchLinux](https://archlinux.org/) as the underlying kernel for multiple reasons:\n- It is  lightweight. It makes it a good candidate to get high performance during fuzzing, by minimizing the amount of programs being run in background with a low memory consumption.\n- It proposes a kernel very close to the vanilla Linux kernel. Thus, it should be easy to adapt these scripts to run with highly customized kernels.\n- It is easy to setup with scripts from the host. At least compared to most alternatives.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faflplusplus%2Flinux-qemu-image-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faflplusplus%2Flinux-qemu-image-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faflplusplus%2Flinux-qemu-image-builder/lists"}