Wakare

The goal of this project is to provide a set of tools able to transform hardware execution traces into formats more suitable for integration into other tools.

Transformation process

                                                                                       _ text
                  +------------------+                         +------------------+   /
input trace ----> | wakare-extractor | --> protobuf stream --> | wakare-converter | --
                  +------------------+                         +------------------+   \_ sqlite

Input trace

The first step of the process is to record an execution trace. For this purpose we use the perf tool as it is able to interact with hardware based tracing interfaces. For now only Intel Processor Trace traces captured by perf are supported. We can capture using the following command:

$ perf record -e intel_pt//u prog <args...>

Sometimes traces are dropped. The pt_trace.sh script tries to minimize this by applying a few optimizations (needs root).

# ./scripts/pt_trace.sh

wakare-extractor

Wakare-extractor is the program responsible for extracting intel pt traces from perf.data files, gathering branch information and writing the result to a protobuf file.

wakare-converter

Wakare-converter uses the protobuf file generated by wakare-extractor and converts it to formats more suitable for integration with other tools. For now wakare-converter supports two different output formats, sqlite and text.

Trace content

Traces produced by the tool contain the following pieces of information:

• Branches:
  • Type:
    • Jump
    • Indirect jump
    • Conditional jump
    • Call
    • Indirect call
  • Source address
  • Destination address
• Executable mappings:
  • Address range
  • File path
• Basic blocks:
  • Address
  • Hitcount

Limitations

For now the project has a few limitations:

• Only supports Linux x86_64
• No support for programs using multiple cores/threads

Disassembler plugins

Plugins for disassemblers can be found in the plugins/ folder.

• Binary ninja
• Radare2

Building

All dependencies can be installed through your package manager of choice. The only exception is libipt which needs to be built from source. Once all dependencies are installed you can build as follows:

$ cmake .
$ make

Additionally some sample programs are provided and traces in all formats can be generated by running:

./run_tests.sh

Dependencies

• protobuf
• capstone
• libipt
• sqlite3
• gflags
• cmake