Merge pull request BinaryAnalysisPlatform#186 from ivg/refining-project

Final refining before release.

.travis.yml

@@ -8,9 +8,5 @@ compiler:
 env:
   - OCAML_VERSION=4.01.0 OPAM_VERSION=1.1.0
   - OCAML_VERSION=4.01.0 OPAM_VERSION=1.2.0
-  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.2.0 TEST_TARGETS=arm BAP_LOADER=llvm
-  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.2.0 TEST_TARGETS=x86 BAP_LOADER=llvm
-  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.2.0 TEST_TARGETS=x86_64 BAP_LOADER=llvm
-  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.2.0 TEST_TARGETS=arm BAP_LOADER=bap-elf
-  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.2.0 TEST_TARGETS=x86 BAP_LOADER=bap-elf
-  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.2.0 TEST_TARGETS=x86_64 BAP_LOADER=bap-elf
+  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.1.0
+  - OCAML_VERSION=4.02.1 OPAM_VERSION=1.2.0

_oasis

@@ -84,7 +84,7 @@ Library bap
                    dynlink,
                    findlib
   Modules:         Bap,
-                   Bap_program_visitor
+                   Bap_project
 
 
 Library plugins
@@ -385,7 +385,7 @@ Executable "bap-server"
   Install:        true
   MainIs:         start_server.ml
 
-Executable "bap-objdump"
+Executable "bap"
   Path:           src/readbin
   MainIs:         readbin.ml
   Install:        true

lib/bap/bap.ml

@@ -94,9 +94,9 @@ module Std = struct
 
   (** {3 Auxiliary libraries} *)
 
-  (** {3 Program visitor}
-      An extension point for program visiting plugins.  *)
-  module Program_visitor = Bap_program_visitor
+  (** {3 Project}
+      A big view on a dissassembled binary  *)
+  module Project = Bap_project
 
   (** {4 Dwarf library}
       This library gives an access to debugging information stored

lib/bap/bap_program_visitor.ml → lib/bap/bap_project.ml

@@ -3,14 +3,13 @@ open Bap_types.Std
 open Image_internal_std
 open Bap_disasm
 
-type project = {
+type t = {
   arch    : arch;
-  argv    : string array;
-  program : disasm;
+  disasm  : disasm;
+  memory  : value memmap;
+  storage : value String.Map.t;
   symbols : string table;
-  memory  : mem;
-  annots  : value memmap;
-  bil_of_insns : (mem * insn) list -> bil;
+  base    : mem;
 }
 
 type color = [
@@ -33,7 +32,11 @@ let mark = Tag.register "mark" sexp_of_unit
 let color = Tag.register "color" sexp_of_color
 let weight = Tag.register "weight" sexp_of_float
 
-let visitors = ref []
-let register v = visitors := v :: !visitors
-let register' v = register (fun p -> v p; p)
-let registered () = List.rev !visitors
+let plugins : (string array -> t -> t) list ref = ref []
+let register_plugin_with_args p =
+  plugins := p :: !plugins
+let register_plugin_with_args' v =
+  register_plugin_with_args (fun a p -> v a p; p)
+let register_plugin v = register_plugin_with_args (fun _arg p -> v p)
+let register_plugin' v = register_plugin (fun p -> v p; p)
+let plugins () = List.rev !plugins

lib/bap/bap_project.mli

@@ -0,0 +1,126 @@
+(** Interface for the BAP project.
+
+    Project represents the results of analysis applied to a certain
+    binary object. It is slightly more abstract, then binary image,
+    thus allowing to apply analysis on arbitrary binary blobs.
+
+    Project is also a common ground, where different plugins can meet,
+    talk and exchange with information. Each plugin is barely a
+    function of type [t -> t], i.e., it can functionally update
+    project, e.g., add annotations, discover new symbols, remove
+    incorrect and, even, change architecture and redisassemble
+    everything.
+
+
+    {3 Exchanging information}
+
+    For exchanging information in type safe manner we use universal
+    values. Values can be attached to a particular memory region, or to
+    a key of type [string]. For the first case we use `memmap` data
+    structure that is an interval tree containing all the memory
+    regions that were used during analysis. For the latter a simple
+    [String.Map] is used.
+
+
+    {4 Annotating memory}
+
+    Depending on the analysis performed and input parameters, one can
+    expect that memory may be annotated with the following tags:
+
+    - [Image.region] -- for regions of memory, that had some
+      particular name in the original binary. For example, in ELF
+      sections have names, that will be used to annotate corresponding
+      memory regions.
+
+    - [Image.section] -- if the binary data was loaded from a binary
+      format that contains sections (aka segments), then corresponding
+      memory regions would be marked. Sections gives you access
+
+*)
+open Core_kernel.Std
+open Bap_types.Std
+open Image_internal_std
+open Bap_disasm_std
+
+(** The result of Binary analysis.  *)
+type t = {
+  arch    : arch;               (** architecture  *)
+  disasm  : disasm;             (** disassembly of a program *)
+  memory  : value memmap;       (** annotations  *)
+  storage : value String.Map.t; (** arbitrary data storage *)
+
+  (** Deprecated fields, the will be removed in a next release. *)
+  symbols : string table;       (** symbol table  @deprecated *)
+  base    : mem;                (** base memory   @deprecated *)
+}
+
+type color = [
+  | `black
+  | `red
+  | `green
+  | `yellow
+  | `blue
+  | `magenta
+  | `cyan
+  | `white
+] with sexp
+
+(** all string tags supports the following substitutions:
+
+    - $region_{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} - 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} - 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.
+*)
+
+
+(** an arbitrary text *)
+val text : string tag
+
+(** the associated data is an html markup *)
+val html : string tag
+
+(** associate a comment string with a memory region  *)
+val comment : string tag
+
+(** to assosiate a python command with a region *)
+val python : string tag
+
+(** to assosiate a shell command with a region  *)
+val shell : string tag
+
+(** just mark a region  *)
+val mark : unit tag
+
+(** attach a color  *)
+val color : color tag
+
+(** attach a weight to a memory  *)
+val weight : float tag
+
+(** [register plugin] registers [plugin] in the system  *)
+val register_plugin : (t -> t) -> unit
+
+(** [register' plugin] registers a [plugin] that will be
+    evaluated only for side effect. *)
+val register_plugin': (t -> unit) -> unit
+
+val register_plugin_with_args : (string array -> t -> t) -> unit
+
+val register_plugin_with_args' : (string array -> t -> unit) -> unit
+
+(** A list of registered plugins in the order of registration  *)
+val plugins : unit -> (string array -> t -> t) list

lib/bap_image/bap_image.ml

@@ -63,7 +63,7 @@ type sec = Sec.t with bin_io, compare, sexp
 type sym = Sym.t with bin_io, compare, sexp
 
 let section = Tag.register "section" sexp_of_sec
-let symbol  = Tag.register "symbol" sexp_of_sym
+let symbol  = Tag.register "symbol" sexp_of_string
 let region  = Tag.register "region" sexp_of_string
 let file    = Tag.register "file"   sexp_of_string
 
@@ -123,7 +123,8 @@ let add_sym memory errs secs syms sym =
             | Error err -> memory, Error err
             | Ok mem ->
               let memory =
-                Memmap.add memory mem (Tag.create symbol sym) in
+                let tag = Tag.create symbol (Sym.name sym) in
+                Memmap.add memory mem tag in
               match Table.add map mem sym with
               | Error err ->
                 memory,Error Error.(tag err "intersecting symbol")

lib/bap_image/bap_image.mli

@@ -54,14 +54,16 @@ val data : t -> Bigstring.t
 (** {2 Tables }  *)
 val words : t -> size -> word table
 val sections : t -> sec table
+
+(** @deprecated: this will be removed in a next release  *)
 val symbols : t -> sym table
 
 
 val section : sec tag
-val symbol  : sym tag
+val symbol  : string tag
 val region  : string tag
 
-(** returns memory tagged with arbitrary [(name,data)] tags  *)
+(** returns memory  *)
 val memory : t -> value memmap
 
 (** {2 Mappings }  *)