WIP: Add triaging tools for DR traces (use-def chains + leak root cause analysis)

.github/workflows/python-lint-and-test.yaml

@@ -10,12 +10,14 @@ on:
       - main-fixes
       - pre-release
       - dev
+      - feature-software-testing
   pull_request:
     branches:
       - main
       - main-fixes
       - pre-release
       - dev
+      - feature-software-testing
 
 jobs:
   build:

.gitignore

@@ -18,3 +18,6 @@ dbg/
 site
 dist/
 .cache/
+*.asm
+*.bin
+*.dat

consfuzz.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+"""
+File: Command Line Interface to Contract-based Software Fuzzer (ConSFuzz)
+
+Copyright (C) Microsoft Corporation
+SPDX-License-Identifier: MIT
+"""
+import sys
+from consfuzz.cli import main
+
+if __name__ == '__main__':
+    exit_code = main()
+    sys.exit(exit_code)

consfuzz/README.md

@@ -0,0 +1,122 @@
+# Software Leakage Fuzzer
+
+Note: This module is at the experimental stage of development and its interfaces
+        may (and likely will) change in the future.
+
+This module leverages a leakage model to detect side-channel information leaks
+in software binaries. The leakage model is the same one as used by the hardware fuzzer,
+and it is assumed to be already tested against the target CPU. The software fuzzer uses
+this model to collect contract traces for the target binary.
+
+The software fuzzer takes as input a target binary and a grammar describing the format of
+the binary's inputs. The grammar must specify which parts of the input are public and which
+are private.
+FIXME: the current prototype doesn't actually use a grammar, but instead assumes
+that the target binary takes two files as input: one for public data and one for private data.
+
+The goal of the software fuzzer is to identify cases where contract traces depend on
+the private data, which is a sign of information leakage. To this end, the fuzzer checks
+traces for the non-interference property: if two executions of the binary with different
+private values but identical public data produce different traces, then the binary is
+leaking information.
+
+The fuzzer operates in three stages:
+
+## THE BELOW IS NOT YET IMPLEMENTED (SEE "ACTUAL EXAMPLE" BELOW)
+
+## Stage 1: Public Input Generation
+
+The fuzzer uses AFL++ to generate a set of public inputs that cover a wide range of execution paths
+in the target binary.
+
+Example:
+```
+./consfuzz.py pub_gen -c config.yaml -w ~/consfuzz-results/ -t 60 --target-cov 5 -- /usr/bin/openssl enc -e -aes256 -out enc.bin -in @@ -pbkdf2 -pass @#
+```
+
+## Stage 2: [NAME TBD]
+
+The second stage combines generation of secret inputs (fully random) and tracing of the binary.
+The tracing is done for each pair of public and secret inputs, and the traces are
+collected in a directory. The underlying tracing engine is the DynamoRIO-based backend of Revizor
+(see `rvzr/model_dynamorio/backend`).
+
+Example:
+```
+./consfuzz.py stage2 -c config.yaml -w ~/consfuzz-results/ -n 10 -- /usr/bin/openssl enc -e -aes256 -out enc.bin -in @@ -pbkdf2 -pass @#
+```
+
+## Stage 3: Leakage Analysis & Reporting
+
+The third stage analyzes the traces collected in the previous stage and reports
+the results.
+
+Example:
+```
+./consfuzz.py report -c  config.yaml -w ~/consfuzz-results/ -b /usr/bin/openssl
+```
+
+## Stage 4: Triaging
+
+A line in the report might look something like this:
+
+
+```yaml
+{
+    "seq": {
+        "D": {
+            "lib/blockciphermodes.c:281": {
+                "4456491": [
+                    "/home/ubuntu/results/stage2/id:000022,src:000014,time:302,execs:289,op:havoc,rep:1/002.trace:155734:155734",
+```
+
+To triage a violation you can use `consfuzz inspect` to either:
+
+1. Inspect it with GDB
+1. Print a use-def graph, both a textual version and a `.dot` graph
+
+
+### GDB Script
+
+As an example for the above violation, you can run:
+
+```
+./consfuzz.py inspect -c consfuzz.yaml --violation "D" /home/ubuntu/results/stage2/id:000022,src:000014,time:302,execs:289,op:havoc,rep:1/002.trace:155734:155734
+```
+
+This will:
+1. analyze the trace to get the relevant PC
+2. generate a debug trace (`.dbgtrace`)
+    * the original command is taken from `<PATH_OF_TRACE>.log` which should be generated by the fuzzer
+3. find the same instruction in the debug trace
+4. generate a gdb script to reach the desired speculative instruction.
+
+Finally, a `gdb` command is printed at the end that can be used to spawn a shell at the leakage point. This gdb command will source a custom GDB plugin (`triage/plugin.py`) which makes the `spec` command available (`help spec`).
+
+Following invocations can be use `--skip-tracing` to avoid rebuilding a debug trace.
+
+### Use-Def Chains
+
+By adding `--usedef` to the command, the tool will also generate two files:
+
+* `/home/ubuntu/results/stage2/[...]/002.usedef` contains a textual representation of the reverse use-def analysis
+* `/home/ubuntu/results/stage2/[...]/002.usedef.dot` contains a graphiz representation of the same
+
+Such chains can be _very_ long. To enhance analysis, you can:
+
+* Add a **baseline** with `--baseline`: this will add a baseline trace that will be used for pruning values that are the same
+    * `--baseline='auto'` simply selects the corresponding `000.trace` in the same folder
+* Add **declassified symbols** and **key expansions** that cause the analysis to stop earlier. This should be done by
+    1. adding `--binary <PATH_OF_THE_BINARY>` to the command
+    2. adding the corresponding source_code_file:line entry in the dedicated list inside `config.yaml`
+
+
+## ACTUAL EXAMPLE
+
+```
+echo 0 | sudo tee /proc/sys/kernel/randomize_va_space
+
+./consfuzz.py pub_gen -c dbg/consfuzz.yaml -w ~/results/ -t 10 --target-cov 50 -- ~/eval-rvzr-sw/drivers/bearssl/bearssl -k @# -i ~/eval-rvzr-sw/drivers/bearssl/test/iv.bin -o enc.bin @@
+./consfuzz.py stage2 -c dbg/consfuzz.yaml -w ~/results/ -n 2 -- ~/eval-rvzr-sw/drivers/bearssl/bearssl -k @# -i ~/eval-rvzr-sw/drivers/bearssl/test/iv.bin -o enc.bin @@
+./consfuzz.py report -c dbg/consfuzz.yaml -w ~/results -b ~/eval-rvzr-sw/drivers/bearssl/bearssl
+```

consfuzz/__init__.py

@@ -0,0 +1,7 @@
+# flake8: noqa
+# pylint: skip-file
+
+from .config import *
+from .fuzzer import *
+
+__version__ = "0.0.1"