bap-std 2.3.0 · OCaml Package

Disassembled program.

Project contains data that we were able to reconstruct during the disassembly, semantic analysis, and other arbitrary amount of analyses.

Actually, project allows to associate arbitrary data with memory regions, program terms, and even attach them globally to itself. So it can be seen as a knowledge base of deeply interconnected facts.

Other than delivering information, from the bap to a passes, it can be also used as a communication media between different passes, (see Working with project).

type t = project

type state

val bin_shape_state : Core_kernel.Bin_prot.Shape.t

val bin_size_state : state Core_kernel.Bin_prot.Size.sizer

val bin_write_state : state Core_kernel.Bin_prot.Write.writer

val bin_writer_state : state Core_kernel.Bin_prot.Type_class.writer

val bin_read_state : state Core_kernel.Bin_prot.Read.reader

val __bin_read_state__ : (int -> state) Core_kernel.Bin_prot.Read.reader

val bin_reader_state : state Core_kernel.Bin_prot.Type_class.reader

val bin_state : state Core_kernel.Bin_prot.Type_class.t

type input

IO interface to a project data structure.

include Regular.Std.Data.S with type t := t

type info = string * [ `Ver of string ] * string option

val version : string

val size_in_bytes : ?ver:string -> ?fmt:string -> t -> int

val of_bytes : ?ver:string -> ?fmt:string -> Regular.Std.bytes -> t

val to_bytes : ?ver:string -> ?fmt:string -> t -> Regular.Std.bytes

val blit_to_bytes : 
  ?ver:string ->
  ?fmt:string ->
  Regular.Std.bytes ->
  t ->
  int ->
  unit

val of_bigstring : ?ver:string -> ?fmt:string -> Core_kernel.bigstring -> t

val to_bigstring : ?ver:string -> ?fmt:string -> t -> Core_kernel.bigstring

val blit_to_bigstring : 
  ?ver:string ->
  ?fmt:string ->
  Core_kernel.bigstring ->
  t ->
  int ->
  unit

module Io : sig ... end

module Cache : sig ... end

val add_reader : 
  ?desc:string ->
  ver:string ->
  string ->
  t Regular.Std.reader ->
  unit

val add_writer : 
  ?desc:string ->
  ver:string ->
  string ->
  t Regular.Std.writer ->
  unit

val available_readers : unit -> info list

val default_reader : unit -> info

val set_default_reader : ?ver:string -> string -> unit

val with_reader : ?ver:string -> string -> (unit -> 'a) -> 'a

val available_writers : unit -> info list

val default_writer : unit -> info

val set_default_writer : ?ver:string -> string -> unit

val with_writer : ?ver:string -> string -> (unit -> 'a) -> 'a

val default_printer : unit -> info option

val set_default_printer : ?ver:string -> string -> unit

val with_printer : ?ver:string -> string -> (unit -> 'a) -> 'a

val find_reader : ?ver:string -> string -> t Regular.Std.reader option

val find_writer : ?ver:string -> string -> t Regular.Std.writer option

val create : 
  ?package:string ->
  ?state:state ->
  ?disassembler:string ->
  ?brancher:brancher source ->
  ?symbolizer:symbolizer source ->
  ?rooter:rooter source ->
  ?reconstructor:reconstructor source ->
  input ->
  t Core_kernel.Or_error.t

from_file filename creates a project from the provided input source.

The input code regions are speculatively disassembled and the set of basic blocks is determined, using the algorithm described in Disasm.Driver. After that the concrete whole program control-flow graph (CFG) is built, which can be accessed with the Project.disasm function. The whole program CFG is then partitioned into a set of subroutines using the dominators analsysis, see Disasm.Subroutines for details. Based on this partition a symbol table, which is a set of a subroutines control-flow graphs, is built. The symbol table, which can be accessed with Project.symbols, also contains information about the interprocedural control flow. Finally, the symbol table is translated into the intermediate representation, which can be accessed using the Project.program function. The whole process is pictured below.

                         ---------------------
                        (    Disassembling    )
                         ---------------------
                                  |
                        +---------------------+
                        |                     |
                        |  All instructions   |
                        |  and basic blocks   |
                        |                     |
                        +---------------------+
                                  |
                         ---------------------
                        ( CFG  reconstruction )
                         ---------------------
                                  |
                        +---------------------+
                        |                     |
                        |  The whole program  |
                        |  control-flow graph |
                        |                     |
                        +---------------------+
                                  |
                         ---------------------
                        (    Partitioning     )
                         ---------------------
                                  |
                        +---------------------+
                        |                     |
                        | The quotient set of |
                        |    basic  blocks    |
                        |                     |
                        +---------------------+
                                  |
                         ---------------------
                        ( Constructing Symtab )
                         ---------------------
                                  |
                        +---------------------+
                        |                     |
                        |   The symbol table  |
                        |  and the  callgraph |
                        |                     |
                        +---------------------+
                                  |
                         ---------------------
                        (  IR Reconstruction  )
                         ---------------------
                                  |
                        +---------------------+
                        |                     |
                        |    The IR of the    |
                        |   binary  program   |
                        |                     |
                        +---------------------+

The disassembling process is fully integrated with the knowledge base. If the input source provides information about symbols and their location, then this information will be automatically reflected to the knowledge base.

The brancher, symbolizer, and rooter parameters are ignored since 2.0.0 and their information could be reflected to the knowledge base using, correspondingly, Brancher.provide, Symbolizer.provide, and Rooter.provide functions.

parameter state
if specified then the provided state will be used as the initial state

parameter package
if specified, then all symbols during the disassembly will be created (interned) in the specified package.

since 2.0.0 the state parameter is added

since 2.0.0 the parameter [disassembler] is unused

since 2.0.0 the parameter [brancher] is unused

since 2.0.0 the parameter [symbolizer] is unused

since 2.0.0 the parameter [rooter] is unused

since 2.0.0 the parameter [reconstructor] is unused

since 2.2.0 the package parameter is added

val empty : Bap_core_theory.Theory.Target.t -> t

empty target creates a for the given target.

val arch : t -> arch

arch project reveals the architecture of a loaded file

deprecated
use target project instead.

val target : t -> Bap_core_theory.Theory.Target.t

target project returns the target system of the project.

since 2.2.0

val specification : t -> Ogre.doc

specification p returns the specification of the binary.

since 2.2.0

val state : t -> state

state project returns the core state of the project.

since 2.0.0

val disasm : t -> disasm

disasm project returns results of disassembling

val program : t -> program term

program project returns a program lifted into IR

val with_program : t -> program term -> t

with_program project program updates a project program

val map_program : t -> f:(program term -> program term) -> t

map_program t ~f maps the IR representation of the program with function f.

Note: since the program is computed lazily this function should be preferred to program composed with_program for passes that transform the program representation so that they are not run if the program is never ever used.

val symbols : t -> symtab

symbols t returns reconstructed symbol table

val with_symbols : t -> symtab -> t

with_symbols project symbols updates project symbols

val storage : t -> dict

returns an attribute storage of the project

val with_storage : t -> dict -> t

updates the attribute storage

val memory : t -> value memmap

memory t returns the memory as an interval tree marked with arbitrary values.

val memory_slot : 
  (Bap_core_theory.Theory.Unit.cls, value memmap) Bap_core_theory.KB.slot

the memory of the unit in the knowledge base.

since 2.2.0

val tag_memory : t -> mem -> 'a tag -> 'a -> t

tag_memory project region tag value tags a given region of memory in project with a given tag and value. Example: Project.tag_memory project tained color red

val substitute : t -> mem -> string tag -> string -> t

substitute p region tag value is like tag_memory, but it will also apply substitutions in the provided string value, as per OCaml standard library's Buffer.add_substitute function.

Example:

Project.substitute project comment "$symbol starts at $symbol_addr"

The following substitutions are supported:

$section{_name,_addr,_min_addr,_max_addr} - name of region of file to which it belongs. For example, in ELF this name will correspond to the section name

$symbol{_name,_addr,_min_addr,_max_addr} - name or address of the symbol to which this memory belongs

$asm - assembler listing of the memory region

$bil - BIL code of the tagged memory region

$block{_name,_addr,_min_addr,_max_addr} - name or address of a basic block to which this region belongs

$min_addr, $addr - starting address of a memory region

$max_addr - address of the last byte of a memory region.

val with_memory : t -> value memmap -> t

with_memory project updates project memory. It is recommended to use tag_memory and substitute instead of this function, if possible.

Extensible record

Project can also be viewed as an extensible record, where one can store arbitrary values. Example,

let p = Project.set project color `green

This will set field color to a value `green.

val set : t -> 'a tag -> 'a -> t

set project field value sets a field to a give value. If field was already set, then new value overrides the old one. Otherwise the field is added.

val get : t -> 'a tag -> 'a option

get project field returns the value of the field if it exists

val has : t -> 'a tag -> bool

has project field checks whether field exists or not. Useful for fields of type unit, that actually isomorphic to bool fields, e.g., if Project.has project mark

val del : t -> 'a tag -> t

del project attr removes an attribute from a project

module Info : sig ... end

Information obtained during project reconstruction.

module State : sig ... end

The core state of the project.

module Input : sig ... end

Input information.

Registering passes

To add new pass one of the following register_* functions should be called.

type pass

val register_pass : 
  ?autorun:bool ->
  ?runonce:bool ->
  ?deps:string list ->
  ?name:string ->
  (t -> t) ->
  unit

register_pass ?autorun ?runonce ?deps ?name pass registers a pass over a project.

If autorun is true, then the host program will run this pass automatically. If runonce is true, then for a given project the pass will be run only once. Each repeating attempts to run the pass will be ignored. The runonce parameter defaults to false when autorun is false, and to true otherwise.

Parameter deps is list of dependencies. Each dependency is a name of a pass, that should be run before the pass. The dependencies will be run in a specified order every time the pass is run.

To get access to command line arguments use Plugin.argv

val register_pass' : 
  ?autorun:bool ->
  ?runonce:bool ->
  ?deps:string list ->
  ?name:string ->
  (t -> unit) ->
  unit

register_pass' pass registers pass that doesn't modify the project effect and is run only for side effect. (See register_pass)

val passes : unit -> pass list

passes () returns all currently registered passes.

val find_pass : string -> pass option

find_pass name returns a pass with the given name.

type second = float

time duration in seconds

module Pass : sig ... end

A program analysis pass.

module Collator : sig ... end

A pass that collates projects.

module Analysis : sig ... end

Knowledge base analyses.

package bap-std

Extensible record

Registering passes