Source Tracer

This is a draft of a control flow tracer based on source code instrumentation with a low overhead. Instrument your software with instrumenter.py. When running instrumented software, the trace is written into a file. The format is basically one character (plus an optional number) for each source code block on the trace. For accurate retracing, retrace.py uses symbolic execution.

Which Software to Trace

Any software which is written in C/C++, with the source code available.

Dependencies

For the Instrumentation

• python3
• libclang (pip install libclang)

For the Trace Recording

• C compiler (or your build system at choice) to compile the instrumented software

For the Symbolic Replayer

• C compiler (or your build system at choice) to compile the instrumented software
• python3
• angr for symbolic execution (pip install angr)

Setup

• Run make

  make
  

• Install the python package

  pip install .
  

Example checksum.c

• Optionally: Change configuration in include/src_tracer/constants.h. The following assumes the standard-configuration.

• First run the pre-processor

  cd examples/
  cpp -I../include checksum.c -o checksum_inst.c
  

• Instrument it (the pre-processed version)

  python ../instrumenter.py checksum_inst.c
  

  For a list of functions together with the num generated by the instrumenter, have a look at the newly created functions_database.db.

Recording

• Compile it with _TRACE_MODE (you might also want different compiler optimizations for recording/replaying)

  gcc -D_TRACE_MODE -O3 -I../include -L../lib checksum_inst.c -o checksum_trace -lsrc_tracer
  

  (note: if you enabled TRACEFORK_ZSTD in include/src_tracer/constants.h, you would need -lzstd here)
• Run it (replace 42 to get another trace)

  ./checksum_trace 42
  

  The name of the recorded trace corresponds to the current time, e.g. 2023-04-28-143402-checksum.c.trace.
• Display the trace (replace the trace name with the correct one!)

  python ../print_trace.py 2023-04-28-143402-checksum.c.trace
  

  (note: if you enabled TRACEFORK_ZSTD in include/src_tracer/constants.h, you would need to decompress the trace first using zstd -d)

Retracing

• Compile it with _RETRACE_MODE (you might also want different compiler optimizations for recording/replaying)

  gcc -D_RETRACE_MODE -g -I../include -L../lib checksum_inst.c -o checksum_retrace -lsrc_tracer
  

• Retrace it (use python -i to work with the traced state in the interactive shell)

  python ../retrace.py checksum_retrace 2023-04-28-143402-checksum.c.trace
  echo "F1 IIO" > sub.trace.txt
  python ../retrace.py checksum_retrace sub.trace.txt
  

  The last one just retraces function checksum.

Other Example

An example to instrument and retrace busybox with musl-libc can be found in the wiki

Other Software

You can do it manually as for the checksum.c example.

For a more automatic way that works well with make scripts, make use of cc_wrapper/.

Recording

• Set some envirenmental variables. There are some variations, for example you might also add -save-temps to CFLAGS.

  export SRC_TRACER_DIR=.........
  export CC="gcc"
  export CFLAGS="-Wno-error -L${SRC_TRACER_DIR}/lib -I${SRC_TRACER_DIR}/include -no-integrated-cpp -B${SRC_TRACER_DIR}/cc_wrapper"
  export LIBS="-lsrc_tracer"
  export SRC_TRACER=""
  

  (note: in addition to -lsrc_tracer you might not need -lzstd if you configured include/src_tracer/constant.h)
• Now you can ./configure your project...
• You can copy the build directory here, if you want to reuse the configuration for retracing.
• Before the actual compilation:

  export SRC_TRACER="-D_TRACE_MODE"
  

• Then build your project with make, gcc, whatever

Retracing

• Same envirenmental variables as before. Only if you want to change some variables (e.g. CFLAGS with -g) make sure to set SRC_TRACER= (as empty string) before you ./configure your project again.
• Before the actual compilation:

  export SRC_TRACER="-D_RETRACE_MODE"
  

• Then build your project with make, gcc, whatever

It can be a bit tricky to get the binary linking correctly, make sure that the record/replay executable includes the record/replay version of the app and its libraries.