# Structure Recovery Using BSim

The StructureRecovery plugin allows users to build a structure in a target program based on the field uses in a source program. The process involves three steps. First, a source program is mined for field references from a known version of the structure to recover the use addresses and offsets. Second, functions in the source program bookmarked by field use are matched to functions in the target program using the local variation of BSim, which does not require a database. Third, BSim is used to create 'pinnings' between the data-flow graphs for each pair of functions which identify vertex-vertex correspondences using the decoompiler's diffing algorithm. Vertices with addresses from the first step are examined to identify offset information, which then becomes input to the construction of a new structure in the target program.

The success of this process depends on a number of factors. There are cases, for instance, in which nested structures may be missed by the structure use task, and, of course, certain fields may not be referenced at all. BSim, here as elsewhere, depends on a number of parameters that determine what constitutes a match, which are exposed as options. Unmatched functions will potentially result in gaps in the structure. Finally, the pinning comparison attempts to reconcile disparate pcode representations, but may fail in more complicated scenarios. When successful, the resulting structure will be stored in the target program's DataTypeManager as "RECOVERED_structure_name".

Each of the three tasks is relatively expensive. It may be necessary to save results from each across sessions. This is done using bookmarks (viewable from the listing or the Bookmarks viewer), which capture the structure use and function-to-function matches. The former are represented as "USES_structure_name_offset:address"; the latter as "source function id→target function id". The function-match bookmarks will be present in both the source and target programs.

ALL tasks should run with the source program active.

## Principal Actions (Tools → Structure Recovery)

### Tag Structure Use

Locates all non-zero field uses within a program for a specified structure.

### Match Functions

Uses BSim to match functions with structure use in the source program to similar functions in a target program.

### Generate structure

Compares data-flow 'pinnings' for matched functions and uses the resulting offsets to reconstruct an approximate match to the original structure for the target progam.

## Secondary Actions (Tools → Structure Recovery)

### Structure Uses: map to bookmarks

Converts (persistent) bookmarks containing structure-use information, typically generated by the 'Tag Structure Use' action, to a (non-persistent) map and vice-versa.

### Function Matches: map to bookmarks

Converts (persistent) bookmarks containing function-function matches, typically generated by the 'Match Functions' action, to a (non-persistent) map and vice-versa.

## Tool Options (Options/Structure Recovery)

Options governing various aspects of the structure recovery.

### Structure to recover

The full path to the data type to be replicated ('Tag Structure Use' will query if empty).

### Add structure-use bookmarks

Should bookmarks by generated by 'Tag Structure Use'.

### Add function-match bookmarks

Should bookmarks by generated by 'Match Functions'.

### Match-confidence lower bound

Used by 'Match Functions' (see BSim documentation for details).

### Match-similarity lower bound

Used by 'Match Functions' (see BSim documentation for details).

### Match-similarity upper bound

Used by 'Match Functions' (see BSim documentation for details).

### Self-significance bound

Used by 'Match Functions' (see BSim documentation for details).

### Min confidence

Used by 'Match Functions' (see BSim documentation for details).

### Max structure offset

The largest offset considered valid by 'Generate structure' (prevents confusion between offsets and addresses).

### Excluded offsets (hex)

Comma-separated hex values to be ignored by 'Generate structure'. Principally used when analyzing a randomized structure that amalgamates randomized fields in a common block, e.g. 0x40 for the Linux task_struct randomized with symbols.

### Match on...

Should the function-function matching rely on solo matches, solo matches plus matches exceeding the 'Min confidence', or should a full maximum-weight bipartite match be computed.