{"id":20275643,"url":"https://github.com/softsec-kaist/ntfuzz","last_synced_at":"2025-04-11T05:25:08.210Z","repository":{"id":42227284,"uuid":"361899815","full_name":"SoftSec-KAIST/NTFuzz","owner":"SoftSec-KAIST","description":"NTFUZZ: Enabling Type-Aware Kernel Fuzzing on Windows with Static Binary Analysis (IEEE S\u0026P '21)","archived":false,"fork":false,"pushed_at":"2021-10-21T09:35:10.000Z","size":8306,"stargazers_count":102,"open_issues_count":6,"forks_count":23,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-25T03:34:05.651Z","etag":null,"topics":["b2r2","binary-analysis","fsharp","fuzzer","fuzzing","kernel-fuzzer","windows-kernel"],"latest_commit_sha":null,"homepage":"","language":"F#","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/SoftSec-KAIST.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-26T21:34:10.000Z","updated_at":"2025-03-22T23:15:17.000Z","dependencies_parsed_at":"2022-09-05T13:20:44.739Z","dependency_job_id":null,"html_url":"https://github.com/SoftSec-KAIST/NTFuzz","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FNTFuzz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FNTFuzz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FNTFuzz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FNTFuzz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftSec-KAIST","download_url":"https://codeload.github.com/SoftSec-KAIST/NTFuzz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248346823,"owners_count":21088535,"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":["b2r2","binary-analysis","fsharp","fuzzer","fuzzing","kernel-fuzzer","windows-kernel"],"created_at":"2024-11-14T13:10:24.204Z","updated_at":"2025-04-11T05:25:08.189Z","avatar_url":"https://github.com/SoftSec-KAIST.png","language":"F#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NTFUZZ\n\nNTFUZZ is a type-aware kernel fuzzing framework for Windows. For the details of\nNTFUZZ, please see our paper \"NTFUZZ: Enabling Type-Aware Kernel Fuzzing on\nWindows with Static Binary Analysis\", published in *IEEE Symposium on Security\nand Privacy 2021*.\n\n# Overview\n\nYou can clone the repository and initialize it as follow.\n\n```\n$ git clone https://github.com/SoftSec-KAIST/NTFuzz\n$ cd NTFuzz\nNTFuzz$ git submodule update --init\n```\n\nThe repository contains three components.\n\n[DLLAnalysis](./DLLAnalysis) statically analyzes Windows system binaries and\ninfers the types of system calls.\n\n[Hooker](./Hooker) is a hooking driver which is installed in kernel. It\nintercepts system calls generated by a seed application, and performs type-aware\nfuzzing on their arguments.\n\n[Launcher](./Launcher) is responsible for launching a seed application used for\nhooking-based fuzzing.\n\n# Step 1 - Static Analysis on Windows DLLs\n\nFirst, we use [DLLAnalysis](./DLLAnalysis) module to statically analyze Windows\nsystem binaries and infer system call types. In addition, DLLAnalysis module\nalso generates system call wrapper code needed by [Hooker](./Hooker) module.\n\nWe used Windows Subsystem for Linux (WSL) to run the static analyzer, but you\ncan run the analyzer on a pure Linux, too. Other platforms are also supported if\nyou slightly modify the commands and scripts below.\n\n1. Install .NET 5.0 SDK and .NET 3.1 Runtime.\n\nInstallation process depends on the Linux distributions and versions, so please\nrefer to this [link](https://docs.microsoft.com/en-us/dotnet/core/install/).\nFor instance, if you are using Ubuntu 18.04, you would have run the following\ncommands.\n\n```\n$ wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb\n$ sudo dpkg -i packages-microsoft-prod.deb\n$ rm packages-microsoft-prod.deb\n$ sudo apt-get update\n$ sudo apt-get install -y apt-transport-https\n$ sudo apt-get update\n$ sudo apt-get install -y dotnet-sdk-5.0 dotnet-runtime-3.1\n```\n\n2. Build the static analyzer.\n\n```\nNTFuzz$ cd DLLAnalysis\nNTFuzz/DLLAnalysis$ make\n```\n\n3. Run the analysis on DLL files.\n\nFor fuzzing on Windows 17134.1 build (released in April 2018), run the following\nscript. It statically analyze Windows DLL files under `binaries/17134.1`\ndirectory, and generates outputs at `output/` directory.\n```\nNTFuzz/DLLAnalysis$ ./scripts/run_on_18_Apr.sh\n```\n\nSimilarly, you can use the following command to analyze the system binaries of\nWindows 18362.592 build (released in January 2020).\n```\nNTFuzz/DLLAnalysis$ ./scripts/run_on_20_Jan.sh\n```\n\nTo run the analyzer on other builds of Windows 10, you can put the relevant DLL\nfiles under `./binaries/\u003cbuild number\u003e` directory and create your own script\nsimilar to `run_on_18_Apr.sh` or `run_on_20_Jan.sh`.\n\n## Note on B2R2 Front-end\n\nFor now, we release B2R2 front-end for static analysis in binary form. This is\nbecause the B2R2 version we used in NTFUZZ is not yet released in the [upstream\nrepository](https://github.com/B2R2-org/B2R2).\n\n# Step 2 - Preparing Kernel Driver for System Call Hooking\n\n1. Install Visual Studio, Windows SDK and Windows Driver Kit.\n\nIn particular, we used Visual Studio 2019, Windows SDK 10.0.18362.1, and Windows\nDriver Kit 10.0.18362.1.\n\n2. Copy system call wrapper code generated by the DLL analyzer.\n\nFor instance, if you are targeting Windows 17134.1 build, you can copy the files\ngenerated from the previous step as follow.\n```\nNTFuzz$ cp DLLAnalysis/output/VersionConst_18_Apr.h Hooker/Driver/inc/VersionConst.h\nNTFuzz$ cp DLLAnalysis/output/GeneralHooker_18_Apr.cpp Hooker/Driver/src/GeneralHooker.cpp\n```\n\n3. Build the hooking driver and its controller.\n\nOpen [Hooker.sln](Hooker/Hooker.sln) with Visual Studio and build the\nsolution. You may have to manually set the target platform into 'x86' before the\nbuild. The solution will output a hooking driver (Hooker.sys) and a program to\ninteract with that driver (Controller.exe).\n\n4. Pack up the hooker directory.\n\nNow, pack up the hooker directory by copying the system call type specification\nfile. This hooker directory will be used in the next step. Please make sure to\nuse the exact file names specified below.\n```\nNTFuzz$ cp DLLAnalysis/output/Types_18_Apr.json ./Hooker/Debug/Types.json\nNTFuzz$ ls Hooker/Debug\nController.exe  Hooker.sys  Types.json  ...\n```\n\n# Step 3 - Running Hooking-based Fuzzing\n\n1. Prepare a Windows VM image.\n\nWe used a VM image to run hooking-based fuzzing, and do NOT recommend to run the\nfuzzing on your real machine.\n\nBe careful to prepare the exact same Windows build that you statically analyzed\nin the first step. If the build versions do not match, the hooking driver will\nraise a kernel panic (blue screen of death) before the fuzzing actually starts.\n\n2. Install python packages and seed applications.\n\nFirst, install python-2.7, and install PyWin32 and PyUserInput packages.\n\nNext, setup seed applications to use for hooking-based fuzzing. If you are not\nsure what a seed application means, please refer to our paper. We will use\n[Launcher](./Launcher) module to run the seed applications. This module contains\nscripts to run the 8 seed application that we used in the experiment. You can\nadd your own seed application and its running script, too.\n\nLauncher module assumes that seed applications are properly prepared. For\ninstance, the script for [SumatraPDF](./Launcher/apps/sumatra.py) assumes that\nthe target executable is stored in `C:\\Apps\\SumatraPDF.exe`, and a sample PDF\nfile is stored in `C:\\Files\\paper.pdf`. Please check the script and satisfy the\nrequirement for the seed application that you wish to run.\n\n3. Copy hooker and launcher directories.\n\nFirst, copy the Hooker build directory (`Debug`) created in the previous step\nand put it as `C:\\Hooker` in the VM.\n\nAlso, copy the [Launcher](./Launcher) directory and put it as `C:\\Launcher` in\nthe VM.\n\n4. Setup the hooker and start fuzzing.\n\nFirst, launch a command prompt with an administrator privilege, and run the\nfollowing commands. These commands register our hooking driver to the kernel.\n\n```\n\u003e bcdedit /set testsigning on\n\u003e sc create Hooker type=kernel binpath=C:\\Hooker\\Hooker.sys\n```\n\nNext, initialize the hooker and start fuzzing. This does not have to be run with\nan administrator privilege.\n\n```\n\u003e python C:\\Launcher\\hooker32.py\n\u003e python C:\\Launcher\\run32.py \u003cheartbeat path\u003e \u003ctarget app\u003e \u003cmutate ratio\u003e \u003cPRNG seed\u003e\n```\n- \"heartbeat path\": `run32.py` will periodically create an empty file at this\n  path. This can be used as a signal to indicate that the fuzzing process is\n  properly running. You can simply provide a dummy (but valid) path if this\n  feature is not needed.\n- \"target app\": The ID of seed application to run. Currently we support\n`awatch`, `chess`, `dxdiag`, `ppt`, `sniffer`, `sumatra`, `unity`, and\n`wordpad`. See [Launcher/apps](./Launcher/apps) directory for more details.\n- \"mutate ratio\": The mutation ratio for fuzzing. Note that our parameter unit\n  considers 1000000 as 100%. Thus, you should provide 10000 to specify 1%\n  mutation ratio, for example. If you provide 1 as a mutation ratio, it will be\n  interpreted as a *variable* mutation ratio we used in the experiment (Section\n  VII.C of the paper).\n- \"PRNG seed\": A pseudo random number generator seed to use in the fuzzing loop.\n  You may want to provide different seeds if you run multiple instances of VM.\n\n## Scaling up fuzzing\n\nOne may be interested in automating the whole fuzzing process, to scale up\nfuzzing. This includes launching VMs, detecting kernel crashes, rebooting the\nVMs, and so on. If you are interested, please take a look at this\n[repository](https://github.com/jchoi2022/NtFuzz-Framework), although we do not\nprovide detailed documentation as of now.\n\n# Citation\n\nYou can cite our paper with the following bibtex entry.\n```bibtex\n@INPROCEEDINGS{choi:oakland:2021,\n  author = {Jaeseung Choi and Kangsu Kim and Daejin Lee and Sang Kil Cha},\n  title = {{NTFUZZ}: Enabling Type-Aware Kernel Fuzzing on Windows with Static Binary Analysis},\n  booktitle = {Proceedings of the {IEEE} Symposium on Security and Privacy},\n  pages = {1973--1989},\n  year = 2021\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Fntfuzz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftsec-kaist%2Fntfuzz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Fntfuzz/lists"}