diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/README.md b/README.md index 7cf64cd..04ef446 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,51 @@ This repository contains initial code for comprehensive testing of binary translators. +## Snapshot-comparison framework + +The following files belong to a rough framework for the snapshot comparison engine: + + - `main.py`: Entry point to the tool. Handling of command line arguments, pre-processing of input +logs, etc. + + - `snapshot.py`: Internal structures used to work with snapshots. Contains the previous +`ContextBlock` class, which has been renamed to `ProgramState` to make its purpose as a snapshot of +the program state clearer. + + - `compare.py`: The central algorithms that work on snapshots. + + - `run.py`: Tools to execute native programs and capture their state via an external debugger. + + - `arancini.py`: Functionality specific to working with arancini. Parsing of arancini's logs into our +snapshot structures. + + - `arch/`: Abstractions over different processor architectures. Will be used to integrate support for +more architectures later. Currently, we only have X86. + +## Symbolic execution + +The following files belong to a prototype of a data-dependency generator based on symbolic +execution: + + - `gen_trace.py`: An invokable tool that generates an instruction trace for an executable's native +execution. Is imported into `trace_symbols.py`, which uses the core function that records a trace. + + - `trace_symbols.py`: A simple proof of concept for symbolic data-dependency tracking. Takes an +executable as an argument and does the following: + + 1. Executes the program natively (starting at `main`) and records a trace of every instruction +executed, stopping when exiting `main`. + + 2. Tries to follow this trace of instructions concolically (keeps a concrete program state from +a native execution in parallel to a symbolic program state), recording after each instruction the +changes it has made to the program state before that instruction. + + 3. Writes the program state at each instruction to log files; writes the concrete state of the +real execution to 'concrete.log' and the symbolic difference to 'symbolic.log'. + + This first version is very fragile. As soon as angr can't handle a branch instruction (which is +the case for almost any branch instruction), it aborts with an error. + +## Helpers + + - `lldb_target.py`: Implements angr's `ConcreteTarget` interface for [LLDB](https://lldb.llvm.org/). |