Crate navigator 

Navigator

A combined binary and library crate.

Binary

The main SaM binary. An async tokio::main program in a loop running either:

• a) an instrumented execution of the sample with drrun, or
• b) a fuzzing session with aflfuzz,

while calls to next_trajectory on the aggregated Network-Event Tree (NET) return some proposed trajectory.

This loop is the implementation of the high level exploration loop described in the SaM documentation.

The simplified source code is shown below:

#[tokio::main]
async fn main() {
    ...
    let mut net_flow_graph = NetGraph::new(None);

    while let Some(proposed_trajectory) = navigate::next_trajectory(&net_flow_graph) {
        let new_path = if requires_fuzzing(proposed_trajectory)
        {
            run::aflfuzz(...).await
        } else {
            run::drrun(...).await
        };

        net_flow_graph = net_flow_graph.append(new_path);

        // Write and over-write a digraph file so that the latest version is always written to disk
        // if an error occurs.
        fs::write("digraph.txt", net_flow_graph.to_string());
    }

    println!("Finished exploring, cumulative graph is:\n{net_flow_graph}");
}

Command Line Interface

The CLI documentation can be printed by running the following command at the workspace root:

cargo run -- --help

For convenience the CLI help string is shown below:

Usage: navigator [OPTIONS] --target-path <TARGET_PATH> --target-opts <TARGET_OPTS> --mutator-lib <MUTATOR_LIB> --target-module <TARGET_MODULE> --nargs <NARGS>

Options:
     --target-path <TARGET_PATH>
         Path to target binary

     --target-opts <TARGET_OPTS>
         CLI options for target binary

     --dr-client-lib <DR_CLIENT_LIB>
         Path to DynamoRIO client shared library
         
         [default: inject\build64\Release\inject.dll]

     --aflfuzz-path <AFLFUZZ_PATH>
         Path to afl-fuzz binary
         
         [default: winafl-netspoof\build64\bin\Release\afl-fuzz.exe]

     --mutator-lib <MUTATOR_LIB>
         An *absolute* path to a shared library defining a winafl mutator. Custom mutators are documented here: https://github.com/googleprojectzero/winafl/blob/master/README.md#custom-mutators

     --winafl-lib <WINAFL_LIB>
         Path to the winafl shared library (which is a DynamoRIO client)
         
         [default: winafl-netspoof\build64\bin\Release\winafl.dll]

     --dynamorio-bin-dir <DYNAMORIO_BIN_DIR>
         Path to the directory of binaries in a built (or pre_built) version of DynamoRIO
         
         [default: C:\Users\shared\dynamorio_prebuilt\bin64]

     --coverage-module <COVERAGE_MODULES>
         Modules in the target binary that will be instrumented to collect coverage information to guide fuzzing. (e.g. --coverage-module msvcrt.dll --covergage-module target-bin.exe)

     --coverage-type <COVERAGE_TYPE>
         Edge coverage (-coverage-type edge) or basic block coverage (-coverage-type bb)
         
         [default: edge]

     --target-module <TARGET_MODULE>
         The module in the target binary that contains the function that will be fuzzed. Used in conjuction with the target-offset

     --fuzz-iterations <FUZZ_ITERATIONS>
         The number of fuzz iterations to conduct with soft roll-back before restarting the target binary. If fuzzing stability is low, decrease this value
         
         [default: 3000]

     --nargs <NARGS>
         If the function targeted by the fuzzer takes m arguments, n of these arguments (where n <=m) may be reset to the value observed on the first run (before the subsequent soft rollbacks

     --parallel <PARALLEL>
         Use AFL parallel fuzzing. Specify the number of parallel fuzzing sessions. Values of 0 or 1 are both interpreted as **not** in parallel. The default value is 1. Parallel sessions are synced with one output directory. See the WinAFL docs to understand how this works. https://github.com/alan-turing-institute/winafl-netspoof/blob/8a703c301636c0669caf772a0f849995f175853d/afl_docs/parallel_fuzzing.txt
         
         Note that parallel fuzzing *cannot* be used with ServerManaged sockets. As such, parallel fuzzing cannot be used with target binaries that use async sockets, and it cannot be used in conjunction with the `--server-managed` flag.
         
         [default: 1]

     --seed-data <SEED_DATA>
        Optionally provide a path to a seed-data file that will be used to populate the seed
        inputs of the fuzzer. This file must be in a custom binary format. There is a binary in
        the `seeding` crate for creating seed-data files in this custom file format.

     --server-managed
         Use ServerManaged sockets in all cases (e.g. for both Sync and Async sockets). In the absence of this flag Sync sockets use a socket spoofing approach, where outbound traffic from the target binary is intercepted *before* it hits the OS. ServerManaged sockets use the TCP and UDP servers listening on ports 8080 and 8081 (respectivley) to receive requests and return responses. This assumes that outbound traffic from the target binary is looped back to 0.0.0.0:8080 (TCP traffic) and 0.0.0.0:8081 (UDP traffic), e.g. by using FakeNet.
         
         Note that ServerManaged sockets *cannot* be used with parallel fuzzing.

 -h, --help
         Print help (see a summary with '-h')

 -V, --version
         Print version

Library

See modules below.

Re-exports

pub use netgraph::core;

pub use netgraph::navigate;

pub use netgraph::trajectory;

Modules

aflfuzz

callstack

cli

drrun

fuzzer

log

netgraph

offsetism

pipe_event

protocol

run

server

socket

Utilities for socket simulation.

stream_utils

Additional Stream combinators: notably StreamSpanExt which implements a Haskell span.

subprocess

Abstraction for Windows subprocesses: a Future<ExitStatus> with a named pipe set up from the subprocess back to the parent.

substream

Subprocesses as streams of async events: transform a subprocess with a named pipe into a Stream of events which can then be chained and composed with the StreamExt and TryStreamExt stream adapters.