Windows kernel fuzzing docs (#70)

Author: novafacing

.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`.