Windows kernel fuzzing docs (#70)

.github/linters/.markdown-lint.yml

@@ -32,6 +32,7 @@ MD029: false # Ordered list item prefix
 MD033: false # Allow inline HTML
 MD036: false # Emphasis used instead of a heading
 MD041: false # HTML can be at the top of the file for the image and such
+MD045: false # Do not require alt text
 
 #################
 # Rules by tags #

.github/workflows/docs.yml

@@ -83,12 +83,12 @@ jobs:
       - name: Generate SIMICS Documentation
         run: |
           ispm projects "$(pwd)" --create --ignore-existing-files --non-interactive
-          ./documentation -o docs/book/simics --dont-open --project "$(pwd)"
+          ./documentation -o docs/book/html/simics --dont-open --project "$(pwd)"
 
       - name: Generate Crate Documentation
         run: |
           SIMICS_BASE="${HOME}/simics/simics-${{ env.PUBLIC_SIMICS_PACKAGE_VERSION_1000 }}" RUSTDOCFLAGS="--enable-index-page -Zunstable-options" TSFFS_TESTS_SKIP_BUILD=1 cargo doc --document-private-items --workspace --no-deps
-          cp -a target/doc/ docs/book/crates/
+          cp -a target/doc/ docs/book/html/crates/
 
       - name: Set Documentation Permissions
         run: |
@@ -104,7 +104,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
         with:
-          path: "./docs/book/"
+          path: "./docs/book/html/"
 
       - name: Deploy to GitHub Pages
         id: deployment

Cargo.toml

@@ -22,7 +22,7 @@ version = "0.2.1"
 [package.metadata.simics]
 package-number = 31337
 
-version = "6.0.6"
+version = "7.0.1"
 
 [lib]
 crate-type = ["cdylib", "rlib"]

README.md

@@ -1,5 +1,3 @@
-<p align="center"><img src="docs/images/logo.png" alt="TSFFS Logo"></p>
-
 # TSFFS: Target Software Fuzzer For SIMICS
 
 TSFFS is a snapshotting, coverage-guided fuzzer built on the
@@ -67,9 +65,10 @@ TSFFS is focused on several primary use cases:
 
 However, TSFFS is also capable of fuzzing:
 
-- Kernel & kernel drivers
-- User-space applications
+- Kernel & kernel drivers on Windows Linux, and more
+- User-space applications on Windows, Linux, and more
 - Network applications
+- Hypervisors and bare-metal systems
 
 ## Contact
 

docs/book.toml

@@ -7,3 +7,7 @@ language = "en"
 multilingual = false
 src = "src"
 title = "TSFFS: Target Software Fuzzer for SIMICS"
+
+[output.html]
+
+[output.linkcheck]

docs/src/SUMMARY.md

@@ -49,6 +49,27 @@
     - [Configuring the Fuzzer](tutorials/edk2-simics-platform-bios/configuring.md)
     - [Running the Fuzzer](tutorials/edk2-simics-platform-bios/running.md)
     - [Optimizing the Fuzzer](tutorials/edk2-simics-platform-bios/optimizing.md)
+  - [Fuzzing a Windows Kernel Mode Driver (KMD)](tutorials/windows-kernel/README.md)
+    - [Building a Windows Image](tutorials/windows-kernel/building-windows-image/README.md)
+      1. [Install VirtualBox](tutorials/windows-kernel/building-windows-image/install-virtualbox.md)
+      2. [Download Windows](tutorials/windows-kernel/building-windows-image/download-windows.md)
+      3. [Create a VM](tutorials/windows-kernel/building-windows-image/create-a-vm.md)
+      4. [Install Windows](tutorials/windows-kernel/building-windows-image/install-windows.md)
+      5. [Set Up SSH](tutorials/windows-kernel/building-windows-image/set-up-ssh.md)
+      6. [Enable SSH Port Forwarding in VirtualBox](tutorials/windows-kernel/building-windows-image/enable-ssh-port-forwarding-in-virtualbox.md)
+      7. [Change Default Shell to PowerShell](tutorials/windows-kernel/building-windows-image/change-default-shell-to-powershell.md)
+      8. [Installing the EWDK](tutorials/windows-kernel/building-windows-image/installing-the-ewdk.md)
+      9. [Installing Development Tools](tutorials/windows-kernel/building-windows-image/installing-development-tools.md)
+      10. [Install Simics Agent](tutorials/windows-kernel/building-windows-image/install-simics-agent.md)
+      11. [Clone and Build HEVD](tutorials/windows-kernel/building-windows-image/clone-and-build-hevd.md)
+      12. [Install the Code Signing Certificate](tutorials/windows-kernel/building-windows-image/install-the-code-signing-certificate.md)
+      13. [Install HEVD Driver](tutorials/windows-kernel/building-windows-image/install-hevd-driver.md)
+      14. [Create a Fuzz Harness](tutorials/windows-kernel/building-windows-image/create-a-fuzz-harness.md)
+      15. [Compile the Fuzz Harness](tutorials/windows-kernel/building-windows-image/compile-the-fuzz-harness.md)
+      16. [Convert the Image to CRAFF](tutorials/windows-kernel/building-windows-image/convert-image.md)
+    - [Create a Simics Project](tutorials/windows-kernel/create-a-project.md)
+    - [Run and Set Up the Simulation](tutorials/windows-kernel/run-the-simulation.md)
+    - [Run the Fuzzer](tutorials/windows-kernel/run-the-fuzzer.md)
 
 ## Reference Guide
 

docs/src/config/README.md

@@ -1,7 +1,25 @@
 # Configuration
 
 Before TSFFS can fuzz target software, it must be configured. The configuration API is
-kept as simple as possible, with sane defaults.
+kept as simple as possible, with sane defaults. TSFFS exposes all of its configuration
+options as Simics *attributes* which means that you can list its configuration options
+by running the following in a Simics CLI prompt in a project with TSFFS installed (see
+[Installing in Projects](installing-in-projects.md)).
+
+```simics
+load-module tsffs
+list-attributes tsffs
+```
+
+You'll see a list of attributes, each of which has help documentation available through
+the Simics CLI like:
+
+```simics
+help tsffs.exceptions
+```
+
+To read about all of the TSFFS options in detail, including methods for setup,
+installation, and configuration:
 
 - [Installing In Projects](installing-in-projects.md)
 - [Loading The TSFFS Module](loading-module.md)

docs/src/config/common-options.md

@@ -9,7 +9,6 @@ is desired.
     - [Setting Exception Solutions](#setting-exception-solutions)
     - [Setting Breakpoint Solutions](#setting-breakpoint-solutions)
   - [Fuzzer Settings](#fuzzer-settings)
-    - [Using Snapshots](#using-snapshots)
     - [Using CMPLog](#using-cmplog)
     - [Set Corpus and Solutions Directory](#set-corpus-and-solutions-directory)
     - [Enable and Set the Checkpoint Path](#enable-and-set-the-checkpoint-path)
@@ -122,23 +121,6 @@ heap.
 
 ## Fuzzer Settings
 
-### Using Snapshots
-
-SIMICS 6.0.175 introduced an experimental snapshots feature that is not dependent on
-reverse execution micro-checkpoints. In some cases, this snapshot method is faster and
-in some cases resolves issues with model incompatibility with micro-checkpoints. This
-feature is not enabled by default.
-
-To use reverse-execution micro-checkpoints instead, use:
-
-```python
-@tsffs.use_snapshots = False
-```
-
-Micro-checkpoints cannot be used by when compiling the module against versions of SIMICS
-which do not support them, and a runtime panic will occur when attempting to take a
-snapshot if enabled on an older version of SIMICS.
-
 ### Using CMPLog
 
 Comparison logging greatly improves the efficiency of the fuzzer by making each

docs/src/config/installing-in-projects.md

@@ -14,7 +14,7 @@ when creating projects.
 
 Projects are created using `ispm` (Intel Simics Package Manager). The command below
 would create a project with packages numbered 1000 (SIMICS Base), 2096 (Quick Start
-Platform [QSP] x86), 8112 (QSP CPU), and 31337 (TSFFS), each with the latest version
+Platform, or QSP, x86), 8112 (QSP CPU), and 31337 (TSFFS), each with the latest version
 except SIMICS base, which here is specified as 6.0.169. All that is required to create
 a new project with the TSFFS package included is to add it after the `--create` flag
 to `ispm`. Using the `-latest` version is recommended for simplicity, but if you are a

docs/src/fuzzing/compatibility.md

@@ -32,7 +32,7 @@ Supported Architectures:
 If your model's target architecture is one of these, it is supported by TSFFS. If not,
 file an issue or pull request. Adding new architectures is easy, and can be a good
 first contribution to the fuzzer. See the generic and specific architecture information
-[here](../../../modules/tsffs/src/tsffs/src/arch).
+[here](https://github.com/intel/tsffs/tree/main/src/arch).
 
 ## Micro Checkpoints
 
@@ -51,8 +51,10 @@ model with a simple test.
 ### Testing Micro Checkpoints
 
 As an example, let's consider the x86 QSP platform model that ships with SIMICS and the
-Hello World EFI [example](../../../examples/tests/x86_64-uefi/). The process for fuzzing
-this target software follows the basic flow:
+Hello World EFI [resource
+example](https://github.com/intel/tsffs/tree/main/tests/rsrc/x86_64-uefi) which you can
+build by running `./build.sh` in the resource directory. The process for fuzzing this
+target software follows the basic flow:
 
 1. Boot the x86 QSP BIOS with the QSP x86 hdd boot script, with a minimal boot disk
 2. Upload the test.efi EFI app using the SIMICS agent (for most real targets, we
@@ -210,7 +212,7 @@ running>
 You'll see several automatic actions on the SIMICS GUI, and you will end up with the
 console screen below.
 
-![The EFI console, with the prompt FS0: \\>](../../images/REQUIREMENTS_Test_Micro_Checkpoints_Pre.png)
+![The EFI console, with the prompt FS0: \\>](../images/REQUIREMENTS_Test_Micro_Checkpoints_Pre.png)
 
 First, we'll run our EFI app to make sure all is well.
 
@@ -220,7 +222,7 @@ running> $system.console.con.input "test.efi\n"
 
 You should see "Working..." print out on the console.
 
-![The EFI console, after test run](../../images/REQUIREMENTS_Test_Micro_Checkpoints_TestRun.png)
+![The EFI console, after test run](../images/REQUIREMENTS_Test_Micro_Checkpoints_TestRun.png)
 
 Now, we'll go ahead stop the simulation and take our micro checkpoint.
 
@@ -242,7 +244,7 @@ running> stop
 We stopped our execution after the app executed, so you should see the output from the
 second time we ran it ("Working...") printed on the GUI console.
 
-![The EFI console, after running again](../../images/REQUIREMENTS_Test_Micro_Checkpoints_Post.png)
+![The EFI console, after running again](../images/REQUIREMENTS_Test_Micro_Checkpoints_Post.png)
 
 Now, we will restore our micro checkpoint and clear the recorder. The second step is
 important, because if we did not clear the recorder we would *replay* the execution of
@@ -259,7 +261,7 @@ simics> continue
 The console should be back to the state it was before you ran the second app execution,
 and will look like this:
 
-![The EFI console, after test run](../../images/REQUIREMENTS_Test_Micro_Checkpoints_TestRun.png)
+![The EFI console, after test run](../images/REQUIREMENTS_Test_Micro_Checkpoints_TestRun.png)
 
 #### Testing for Your App
 
@@ -279,12 +281,12 @@ somewhat depending on your project. In general, try to follow this flow:
 
 ## Snapshots
 
-Newer versions of SIMICS (>= 6.0.175) support a new feature called snapshots, which are
+Newer versions of SIMICS (>= 7.0.0) support a new feature called snapshots, which are
 similar to micro checkpoints but do not rely on underlying rev-exec support. If your
 model supports a new version of SIMICS, follow the same instructions as for micro
 checkpoints, but replace:
 
-* `VT_save_micro_checkpoint("origin", 0)` with `VT_take_snapshot("origin")`
+* `VT_save_micro_checkpoint("origin", 0)` with `VT_save_snapshot("origin")`
 * `VT_restore_micro_checkpoint(0)` with `VT_restore_snapshot("origin")`
 
 And do not call `CORE_discard_future`.

docs/src/setup/linux.md

@@ -52,7 +52,7 @@ For users of the public distribution of SIMICS, visit the [SIMICS download
 page](https://www.intel.com/content/www/us/en/developer/articles/tool/simics-simulator.html),
 accept the EULA, and download the following files. Users of internal or commercial
 private Wind River or Intel SIMICS should follow internal documentation available
-[here](TODO).
+[here](https://goto/simics).
 
 * `intel-simics-package-manager-[VERSION].tar.gz`
 * `simics-6-packages-[VERSION].ispm`

docs/src/tutorials/README.md

@@ -4,4 +4,5 @@ We have several tutorials for harnessing and fuzzing various target software.
 
 - [Fuzzing an EDK2 UEFI Application](edk2-uefi/README.md)
 - [Fuzzing a Kernel Module](kernel-module/README.md)
-- [Fuzzing a Custom BIOS](edk2-simics-platform-bios/README.md)
+- [Fuzzing a Custom BIOS](edk2-simics-platform-bios/README.md)
+- [Fuzzing a Windows Kernel Mode Driver](windows-kernel/README.md)

docs/src/tutorials/edk2-simics-platform-bios/booting.md

@@ -5,7 +5,7 @@ add our fuzzing harness. This time, we'll add our harness to the boot flow, befo
 UEFI shell, so it is prudent to make sure everything looks OK first.
 
 Before this step, you'll need to have the TSFFS SIMICS package installed in your system
-by following the [setup steps](../setup/README.md) or by installing a prebuilt `ispm`
+by following the [setup steps](../../setup/README.md) or by installing a prebuilt `ispm`
 package. You'll also need the SIMICS base package (1000), the QSP-x86 package (2096),
 and the QSP-CPU (8112) package. All three are available in the public simics release.
 

docs/src/tutorials/edk2-uefi/testing-the-application.md

@@ -3,7 +3,7 @@
 Before we harness the application for fuzzing, we should test it to make sure it runs.
 
 Before this step, you'll need to have the TSFFS SIMICS package installed in your system
-by following the [setup steps](../setup/README.md) or by installing a prebuilt `ispm`
+by following the [setup steps](../../setup/README.md) or by installing a prebuilt `ispm`
 package. You'll also need the SIMICS base package (1000), the QSP-x86 package (2096),
 and the QSP-CPU (8112) package. All three are available in the public simics release.
 

docs/src/tutorials/windows-kernel/README.md

@@ -0,0 +1,9 @@
+# Fuzzing a Windows Kernel Mode Driver (KMD)
+
+This tutorial will walk you through the process of creating, building, and fuzzing a
+Windows Kernel Mode Driver (KMD) running on the simulated x86_64 platform on Windows 11.
+
+- [Building a Windows Image](building-windows-image/README.md)
+- [Create a Simics Project](create-a-project.md)
+- [Run and Set Up the Simulation](run-the-simulation.md)
+- [Run the Fuzzer](run-the-fuzzer.md)

docs/src/tutorials/windows-kernel/building-windows-image/README.md

@@ -0,0 +1,28 @@
+# Building a Simics-Compatible Windows Kernel Development VM
+
+We will use VirtualBox to create a Windows Kernel Development Virtual machine
+before converting the VirtualBox Virtual Disk Image (VDI) to the CRAFF format used by
+Simics.
+
+There are several advantages to creating the image this way:
+
+- Speed: VirtualBox runs faster than Simics and is easier to work with interactively
+- Compatibility: The image can be used for other purposes
+- Iteration: Speed and compatibility allow iterating on the image contents more quickly
+
+1. [Install VirtualBox](install-virtualbox.md)
+2. [Download Windows](download-windows.md)
+3. [Create a VM](create-a-vm.md)
+4. [Install Windows](install-windows.md)
+5. [Set Up SSH](set-up-ssh.md)
+6. [Enable SSH Port Forwarding in VirtualBox](enable-ssh-port-forwarding-in-virtualbox.md)
+7. [Change Default Shell to PowerShell](change-default-shell-to-powershell.md)
+8. [Installing the EWDK](installing-the-ewdk.md)
+9. [Installing Development Tools](installing-development-tools.md)
+10. [Install Simics Agent](install-simics-agent.md)
+11. [Clone and Build HEVD](clone-and-build-hevd.md)
+12. [Install the Code Signing Certificate](install-the-code-signing-certificate.md)
+13. [Install HEVD Driver](install-hevd-driver.md)
+14. [Create a Fuzz Harness](create-a-fuzz-harness.md)
+15. [Compile the Fuzz Harness](compile-the-fuzz-harness.md)
+16. [Convert the Image to CRAFF](convert-image.md)

docs/src/tutorials/windows-kernel/building-windows-image/change-default-shell-to-powershell.md

@@ -0,0 +1,21 @@
+# Change Default Shell to PowerShell
+
+This is a CMD command prompt. The remainder of the tutorials for Windows will
+provide only PowerShell commands. To change the default shell for OpenSSH to
+PowerShell, run:
+
+```cmd
+powershell.exe -Command "New-ItemProperty -Path 'HKLM:\SOFTWARE\OpenSSH' -Name DefaultShell -Value 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' -PropertyType String -Force"
+```
+
+Exiting the SSH session by running `exit`, then reconnecting with `ssh -p 2222
+user@localhost` should log you into a PowerShell session by default:
+
+```txt
+Windows PowerShell
+Copyright (C) Microsoft Corporation. All rights reserved.
+
+Try the new cross-platform PowerShell https://aka.ms/pscore6
+
+PS C:\Users\user>
+```

docs/src/tutorials/windows-kernel/building-windows-image/clone-and-build-hevd.md

@@ -0,0 +1,56 @@
+# Clone and Build HEVD
+
+We will use [HackSys Extreme Vulnerable Driver
+(HEVD)](https://github.com/hacksysteam/HackSysExtremeVulnerableDriver) as our windows
+driver target.
+
+We'll clone HEVD into our home directory and enter the EWDK build environment.
+
+```powershell
+cd ~
+git clone https://github.com/novafacing/HackSysExtremeVulnerableDriver -b windows-training
+cd HackSysExtremeVulnerableDriver/Driver
+W:\LaunchBuildEnv.cmd
+```
+
+Now, we can go ahead and build the driver:
+
+```cmd
+cmake -S . -B build -DKITS_ROOT="W:\Program Files\Windows Kits\10"
+cmake --build build --config Release
+```
+
+And exit our build environment:
+
+```cmd
+exit
+```
+
+Back in PowerShell, check to make sure there is a release directory:
+
+```powershell
+ls build/HEVD/Windows/
+```
+
+You should see:
+
+
+```txt
+
+    Directory: C:\Users\user\HackSysExtremeVulnerableDriver\Driver\build\HEVD\Windows
+
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+d-----        12/20/2023   7:16 PM                CMakeFiles
+d-----        12/20/2023   7:16 PM                HEVD.dir
+d-----        12/20/2023   7:17 PM                Release
+-a----        12/20/2023   7:16 PM           1073 cmake_install.cmake
+-a----        12/20/2023   7:17 PM           2275 hevd.cat
+-a----        12/20/2023   7:17 PM           1456 HEVD.inf
+-a----        12/20/2023   7:17 PM          32216 HEVD.sys
+-a----        12/20/2023   7:16 PM          45308 HEVD.vcxproj
+-a----        12/20/2023   7:16 PM           4117 HEVD.vcxproj.filters
+```
+
+If so, we're in business!