NAME

ooanalyzer - Automated recovery of C++ objects from binaries

SYNOPSIS

ooanalyzer --json=JSON_FILE [--new-method=ADDRESS] [--ignore-rtti] [...Pharos options...] EXECUTABLE_FILE

ooanalyzer --prolog-facts=PROLOG_FILE --prolog-results=PROLOG_FILE [--prolog-loglevel={1-7}] [--prolog-trace] [...Pharos options...] EXECUTABLE_FILE

ooanalyzer --help

ooanalyzer --rose-version

@PHAROS_OPTS_POD@

DESCRIPTION

OOAnalyzer recovers object oriented constructs from the executable file being analyzed. OOAnalyzer is currently limited to 32-bit x86 executables compiled by Microsoft Visual C++. OOAnalyzer can recover the following kinds of information:

C++ classes
Association of methods with specific C++ classes
C++ class layout (member sizes and offsets)
Inheritance relationships between classes
Identification of constructors and destructors
Run Time Type Information (RTTI)
The resolution of virtual call to specific addresses

OOAnalyzer adopts a new approach compared to it's predecessor Objdigger, which is to encode the logical rules constraining class and method relationships as Prolog rules. OOAnalyzer first analyzes the executable to generate basic facts about the executable, and then uses Prolog to analyze those facts and recover object oriented constructs.

OPTIONS

OOAnalyzer OPTIONS

The following options are specific to the ooanalyzer program.

--json=JSON_FILE, -j=JSON_FILE: Cause the primary machine-readable output of OOAnalyzer to be written to the specified JSON file. This file will describe class member layout, the assignment of methods to classes, inheritance relationships between classes, special methods like constructors, and other object-oriented (OO) properties. While the JSON file is human readable to some extent, the results are intended to be used in conjunction with the OOAnalyzer IDA plugin which will present an interactive representation of the recovered classes. This option, --prolog-facts, or --prolog-results must be specified.
--new-method=ADDRESS, -n=ADDRESS: Mark a specific address as an implementation of the new() operator. Usually new() implementations are detected using a combination of import names and function hashes, but not all new() implementations are automatically recognized. If no new implementations are detected, it can dramatically affect the detection of dynamically allocated objects. This option may be specified multiple times.
--delete-method=ADDRESS: Mark a specific address as an implementation of the delete() operator. Usually delete() implementations are detected using a combination of import names and function hashes, but not all delete() implementations are automatically recognized. If no delete implementations are detected, it can dramatically affect the detection of destructor methods. This option may be specified multiple times.
--purecall=ADDRESS: Mark a specific address as an implementation of the purecall function that raises errors when incorrectly called. While this implementation is never supposed to be called during execution, it is present in the virtual function tables and can confused OOAnalyzer if it is not properly identified. This option can also be used to suppress merging of the specified function into any other class, which is sometimes useful when OOAnalyzer is confused about which class the method belongs to. This option may be specified multiple times.
--ignore-rtti: Do not use Run Time Type Information (RTTI), even if it is present in the executable being analyzed. Typically there's no reason to specify this option since using RTTI is almost always beneficial, but in some rare cases where the RTTI information is corrupt or misleading, it may be useful to disable it. This option can also used to compare the accuracy of OOAnalyzer with and without the assistance of RTTI.
--prolog-facts=PROLOG_FILE, -F=PROLOG_FILE: Causes a number of factual observations about the analyzed program to be written in a Prolog format to the specified file name. These facts are the input to the Prolog rule base that recovers the classes. This option is primarily useful for debugging logic defects in the Prolog rules, but the file can also be parsed to obtain these facts for other uses.
--prolog-results=PROLOG_FILE, -R=PROLOG_FILE: Causes the object-oriented detections to be written to a Prolog file in the format that the Prolog rules produced before conversion to JSON format. These results should be semantically equivalent to the JSON format, but might more convenient for certain uses. In particular, they can be correlated with the Prolog reasoning rules much more easily.
--prolog-loglevel={1-7}: Change the logging level of the prolog solver. Higher levels imply more logging. The solver can report new conclusions reached by the Prolog rules as it reasons about the program. This option can be very educational for understanding how OOAnalyzer reasons about the program, explores different possibilities, and handles contradictory data.

@PHAROS_OPTIONS_POD@

EXAMPLES

A typical invocation of OOAnalyzer to load the results into IDA Pro:

$ ooanalyzer --json=/tmp/output.json input.exe

To explore the Prolog rules that control the object detections, this is a more typical command:

$ ooanalyzer -F=/tmp/facts.txt -R=/tmp/results.txt input.exe

ENVIRONMENT

@PHAROS_ENV_POD@

FILES

@PHAROS_FILES_POD@

NOTES

OOAnalyzer is primarily targeted at executables compiled with Microsoft Visual Studio. While it may recover object oriented constructs produced by other compilers, it has not been tested extensively with other compilers.

OOAnalyzer has been tested primarily with 32-bit Windows executables. 64-bit Windows executables may work somewhat, but have not been tested extensively.

OOAnalyzer is not designed to be re-run using an existing set of fact files as an input. This can be achieved by using the ooprolog(1) program.

AUTHOR

Written by the Software Engineering Institute at Carnegie Mellon University. The primary authors were Cory Cohen, Edward Schwartz, and Wesley Jin.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!