Developer Information

To run individual components manually

From the root of the project:

# General Pattern:
.\dynamorio\bin64\drrun.exe -c build\client_name\Debug\client.dll [client_args] -- C:\path\to\target_application [target_args]

# triage
.\dynamorio\bin64\drrun.exe -c build\tracer\Debug\tracer.dll -- corpus\win_asm\crashes.exe 7

# wizard
.\dynamorio\bin64\drrun.exe -c build\wizard\Debug\wizard.dll -- build\corpus\test_application\Debug\test_application.exe 0

# server
build\server\Debug\server.exe

# fuzzer
.\dynamorio\bin64\drrun.exe -c build\fuzzer\Debug\fuzzer.dll -- build\corpus\test_application\Debug\test_application.exe 0 -f

# triage crash
.\dynamorio\bin64\drrun.exe -c sienna-locomotive\build\tracer\Debug\tracer.dll -r [RUN_ID] -- build\corpus\test_application\Debug\test_application.exe 0 -f

# targeting
.\dynamorio\bin64\drrun.exe -c build\fuzzer\Debug\fuzzer.dll -t 0,ReadFile -- build\corpus\test_application\Debug\test_application.exe 0 -f

.\dynamorio\bin64\drrun.exe -c build\tracer\Debug\tracer.dll -r [RUN_ID] -t 0,ReadFile -- build\corpus\test_application\Debug\test_application.exe 0 -f

Regression Test

sl2-test runs the SL2 regression tests.

You can also run the tests directly via python sl2/test/__main__.py.

Sample triage.json

After the tracer has been run, triager.exe is run on the minidump file. It also loads any information generated by the tracer, and outputs the following json:

{
    // This is the called functions before the crash
    "callStack": [
        140699242310037,
        140718144357416,
        140718144581792,
        140718144447545
    ],

    // The offending memory address
    "crashAddress": 140699242310037,

    // The reason of exception type
    "crashReason": "EXCEPTION_BREAKPOINT",

    // Exploitability from High to None
    "exploitability": "Unknown",

    // The instruction pointer at the time of the crash
    "instructionPointer": 14757395258967641292,

    // Path to the minidump analyzed
    "minidumpPath": "C:\\Users\\IEUser\\AppData\\Roaming\\Trail of Bits\\sl2\\runs\\78f20c60-eb12-410a-8378-342c3afec986\\initial.dmp",

    // Rank, or numeric version of exploitability from 0-4
    "rank": 1,

    // The ranks generated by each of the 3 engines
    "ranks": [
        0,
        0,
        1
    ],

    // A unique identifier for the crash. The algorithm uses 12 bits from the called functions,
    // and is unaffected by ASLR, function call order, or function call count
    "crashash": "f96808cfc4798256",

    // Stack pointer at time of crash
    "stackPointer": 14757395258967641292,

    // Unique tag for the crash for binning purposes
    "tag": "Unknown/EXCEPTION_BREAKPOINT/f96808cfc4798256",

    // Complete output from the tracer run
    "tracer": {
        "exception": "EXCEPTION_BREAKPOINT",
        "instruction": "int3",
        "last_calls": [
            140699242861232,
            140699242861064,
            140699242861064,
            140699242861056,
            140699242861184
        ],
        "last_insns": [
            140699242309722,
            140699242309725,
            140699242309727,
            140699242309730,
            140699242310037
        ],
        "location": 140699242310037,
        "reason": "breakpoint",
        "regs": [
            {
                "reg": "rax",
                "tainted": false,
                "value": 1080890113
            },
            //...............................................
        ],
        "score": 25,
        "tainted_addrs": [
            {
                "size": 8,
                "start": 2645403054665
            }
        ]
    }
}

Version number

If you change anything that would break backwards compatibility, increment harness.config.VERSION. Examples of breaking changes include changes to the database structure, changes to various binary formats, directory structures, and so forth.