Chronicler: a Pin execution capture tool

Chronicler v0.1 can be downloaded here

Usage

	Usage: pin -t chronicler_[vistasp2/xpsp3].dll [options] -- [application]
	
	Options for Chronicler [default]:
        -o              Output filename ["chronicler.out"]
        -i              Append pid to output [0]
        -watch_thread   Thread to watch, -1 for all [-1]
        -flush          Flush output after every instruction [0]
        -symbols        Include symbol information [1]
        -lines          Include line number information [0]
        -instruction    Trace instructions [1]
        -startaddress   Start Address [0]
        -stopaddress    Stop Address [0]
        -filefilter     File to trace [""]
        -filefilterhits Number of hits [1]
        -syscall        Trace system calls [0]
        -memory         Trace memory [1]
        -silent         Do everything but write file (for debugging) [0]
        -early_out      Exit after tracing the first region [0]

Building

Dependencies:

Chronicler depends on Pin and the zlib library.

Example chronicle applications

Automated unpacking for malware analysis

Install the Zlib::Compress Perl library.

Run chronicler.

    pin -smc_strict -t chronicler_[vistasp2/xpsp3].dll -- [packed_sample]

Run autounpack.pl on the output log

    utils\autounpack.pl [chronicler_log]

The output of autounpack.pl are files of the form [chronicler_log]_[code_wave].txt

    address  byte_value
    00401000 85
    00401001 139
    00401002 236
    00401003 139
    00401004 69
    00401005 12
    00401006 80
    00401007 139
    00401008 77
    00401009 8
    0040100A 81
    0040100B 232
    0040100C 231
    0040100D 3
    0040100E 9
    0040100F 251

Notes

Chronicler does instruction-level execution tracing and is based on the Pin binary instrumentation framework. Gzip is used to compress the resulting log file. The automatic unpacking algorithm is based on work by Renovo and TraceSurfer.

Run without any parameters, Chronicler will output an execution trace. Run with the "-filefilter [file]" option, Chronicler will output an execution trace starting at the point [file] is read (via NtReadFile), as well as all the system calls involving [file]. If [file] is read multiple times, the trace can be delayed using the "-filefilterhits [num]" or "-startaddress [address]" options.

Currently tested on Windows XP (SP3) and Vista (SP2).