OCaml Interface to Volatility

When writing OCaml code analysis modules, it is sometimes useful to be able to query a Volatility session to extract OS related information such as: _EPROCESS, _ETHREAD, etc. data structures; process address space memory pages; thread stacks, process heaps, etc.. The OCaml Volatility module provides this type of capability by allowing OCaml data structures to be mapped to equivalent Python data structures (and vice versa). As a result, it becomes possible to call methods belonging to Python Volatility objects.

Python Objects

In order to aid mapping between OCaml datatypes and Python objects, a py_obj OCaml datatype has been defined. This type allows OCaml to directly create Python objects (these OCaml heap objects get mapped to Python heap objects by the libbap C code).

To deal with Python objects being returned, as series of OCaml helper functions (i.e. as_PyInt, as_PyBool, etc.) have been defined.

Example usages may be seen in the libbap OCaml files bap_analysis.ml, bap_ast.ml, etc. - where we map BAP/OCaml return types into Python objects.

Volatility Objects

The OCaml abstract type vol_obj represents any Volatility object instance (i.e. instance of volatility.obj.BaseObject).

VolatilityObject instances are used to create an interface between Volatility base object instances and OCaml code. This interface is designed so that Volatility plugins (or similar) may be written in OCaml.

To do this in OCaml, a user implements a function with the type py_obj -> py_obj. Callbacks into Volatility code are possible within this function using the py_eval type to, for example, access members of the OCaml vol_obj type.

Finally, so that the OCaml code may be called from Python/Volatility, it is necessary to register the defined function as follows:

let _ = Callback.register "example_plugin" plugin_code

where plugin_code: py_obj -> py_obj is the OCaml plugin code.

This code can then be called from (for example) the Volatility shell as follows:

Volshell> from bap import *
Volshell> obj = VolatilityObject(x)
Volshell> obj("example_plugin")

where x is the Volatility object (of OCaml type vol_obj) to be passed as an argument to the plugin_code OCaml function.

Note: currently, it is necessary to add in your code explicitly to the build procedure (this code should be placed in the ocaml/plugins directory). Separate compilation of your OCaml code is not currently supported.

Example: Virtual Page Permissions

Here we examine how to create OCaml code that, when supplied with a Volatility _EPROCESS instance, iterates through each page of the processes address space printing out if the page has write or execute permissions.

To do this, we first need to define some OCaml code to model process address spaces (we place this code in the file ocaml/plugins/example.ml):

class _AddressSpace addrspace = 
object(self)
  method read addr length = (as_Option as_PyString)(_VolatilityObject_callback addrspace [
      PyMethod( "read", PyTuple [| PyInt addr; PyInt length |], empty_dict )
    ])

  method zread addr length = as_PyString(_VolatilityObject_callback addrspace [
      PyMethod( "zread", PyTuple [| PyInt addr; PyInt length |], empty_dict )
    ])

  method is_valid_address addr = as_PyBool(_VolatilityObject_callback addrspace [
      PyMethod( "is_valid_address", PyTuple [| PyInt addr |], empty_dict )
    ])

  method get_available_pages = 
    let pages = as_PyObject(_VolatilityObject_callback addrspace [ PyMethod( "get_available_pages", empty_tuple, empty_dict ) ])
    in
      py_iter as_PyTuple pages

  method get_pdpi addr = as_PyInt(_VolatilityObject_callback addrspace [
      PyMethod( "get_pdpi", PyTuple [| PyInt addr |], empty_dict )
    ])

  method get_pgd addr pdpte = as_PyInt(_VolatilityObject_callback addrspace [
      PyMethod( "get_pgd", PyTuple [| PyInt addr; PyInt pdpte |], empty_dict )
    ])

  method get_pte addr pde = as_PyInt(_VolatilityObject_callback addrspace [
      PyMethod( "get_pte", PyTuple [| PyInt addr; PyInt pde |], empty_dict )
    ])

  method is_writeable addr =
    let pdpte = self#get_pdpi addr in
    let pde = self#get_pgd addr pdpte in
    let pte = self#get_pte addr pde in
      (UInt64.logand (UInt64.shift_right pte 1) UInt64.one) = UInt64.one

  method is_executable addr =
    let pdpte = self#get_pdpi addr in
    let pde = self#get_pgd addr pdpte in
    let pte = self#get_pte addr pde in
      (UInt64.shift_right pte 63) = UInt64.zero
end

and _EPROCESS objects:

class _EPROCESS eproc =
object(self)
  method pid = as_PyInt(_VolatilityObject_callback eproc [
      PyMethod( "__getattr__", PyTuple [| PyString "UniqueProcessId" |], empty_dict );
      PyMethod( "v", empty_tuple, empty_dict )
    ])

  method get_process_address_space = as_PyObject(_VolatilityObject_callback eproc [
      PyMethod( "get_process_address_space", empty_tuple, empty_dict )
    ])
end

Next, we can define our example plugin code as follows:

let plugin_example vol_eproc =
  let eproc = new _EPROCESS(vol_eproc) in
  let addrspace = new _AddressSpace(eproc#get_process_address_space) in
  let process_page page =
    let base_addr = as_PyInt(Array.get page 0) in
      if addrspace#is_writeable base_addr || addrspace#is_executable base_addr then print_string ((Printf.sprintf "0x%08x" (UInt64.to_int base_addr)) ^ ": ");
      if addrspace#is_writeable base_addr then print_string "W";
      if addrspace#is_executable base_addr then print_string "X";
      if addrspace#is_writeable base_addr || addrspace#is_executable base_addr then print_endline ""
  in
    BatLazyList.iter process_page addrspace#get_available_pages

Finally, we can register this plugin code for callbacks as follows:

let _ = Callback.register "example" plugin_example

Once this code has been compiled into our libbap library code (i.e. rebuild libbap), it can then be accessed and used as follows:

Volshell> from bap import *
Volshell> cc(pid=1752)
Volshell> obj = VolatilityObject(self.proc) # Volatility/OCaml interface object
Volshell> obj("example")                    # Python wrapper for the OCaml call: plugin_example(PyObject self.proc)

0x00010000: W
0x00020000: W
0x00030000: WX
0x00031000: WX
0x00032000: WX
0x00033000: WX
0x00034000: WX
0x00035000: WX
0x00036000: WX
0x00037000: WX
0x00038000: WX
0x00039000: WX
...

Note: Here we assume that volshell has loaded the Honeynet Challenge 3 memory image (see http://honeynet.org/challenges/2010_3_banking_troubles).

Wiki

libbap / BAP

OCaml Interface to Volatility

Python Objects

Volatility Objects

Example: Virtual Page Permissions