references/cookbook.md

GitHub

Cookbook

Common analysis recipes and patterns for working with Binary Ninja.

Loading & Navigation

Load a binary (headless)

from binaryninja import load
with load('/bin/ls') as bv:
    print(f"{bv.arch.name}: {hex(bv.entry_point)}")

Get all functions

for func in bv.functions:
    print(func.name, hex(func.start), func.return_type)

Find a function

func = bv.get_functions_by_name("main")[0]     # by name (may return multiple)
func = bv.get_function_at(addr)                 # exact start address
func = bv.get_functions_containing(addr)[0]     # contains address

Largest function

max(bv.functions, key=lambda x: x.total_bytes)

IL & Decompilation

Access all IL forms

for func in bv.functions:
    llil     = func.llil          # Low Level IL
    llil_ssa = func.llil.ssa_form # LLIL SSA
    mlil     = func.mlil          # Medium Level IL
    mlil_ssa = func.mlil.ssa_form # MLIL SSA
    hlil     = func.hlil          # High Level IL (decompilation)
    hlil_ssa = func.hlil.ssa_form # HLIL SSA

Iterate all decompiled instructions

for func in bv.functions:
    for inst in func.hlil.instructions:
        print(f"{inst.address} : {inst}")

# Or across entire binary:
for inst in bv.hlil_instructions:
    print(f"{inst.address} : {inst}")

Map between IL levels

hlil_inst = func.hlil[0]
hlil_inst.mlil    # approximate single MLIL mapping
hlil_inst.mlils   # all contributing MLIL instructions (most accurate)
hlil_inst.llil    # approximate single LLIL mapping
hlil_inst.llils   # all contributing LLIL instructions

Call Graph Analysis

Callers and callees

func.callers    # list of functions that call this function
func.callees    # list of functions called by this function

All call sites into a function

for site in func.caller_sites:
    print(site.address, site.hlil)

All calls made by a function

for site in func.call_sites:
    print(site.address, site.hlil)

Most connected function

max(bv.functions, key=lambda x: len(x.callers + x.callees))

Cross-References

# HLIL cross-references of a function's callers
for ref in func.caller_sites:
    print(ref.hlil)

Variables & Parameters

Access variables

all_vars      = func.vars               # all variables
hlil_vars     = func.hlil.vars          # variables used in HLIL
aliased_vars  = func.hlil.aliased_vars  # aliased variables
param_vars    = func.parameter_vars     # function parameters

Stack variable info

var = hlil_vars[0]
if var.source_type == StackVariableSourceType:
    print(var.storage)                    # stack offset
    print(var.offset_to_next_variable)    # distance to next var
    print(abs(var.type.width))            # type-based size

SSA: find definition and uses

ssa_vars = func.hlil.ssa_vars
def_inst = func.hlil.ssa_form.get_ssa_var_definition(ssa_vars[0])
use_insts = func.hlil.ssa_form.get_ssa_var_uses(ssa_vars[0])

Query possible values of a call parameter

for ref in func.caller_sites:
    if isinstance(ref.hlil, Call) and len(ref.hlil.params) >= 3:
        print(ref.hlil.params[2].possible_values)

Pattern Matching with Traverse

Find all calls to a specific function

def find_calls(i, target_addr) -> str:
    match i:
        case HighLevelILCall(dest=HighLevelILConstPtr(constant=c)) if c == target_addr:
            return str(i)

for result in current_hlil.traverse(find_calls, target_addr):
    print(result)

Collect all call targets

def collect_targets(i) -> int:
    match i:
        case HighLevelILCall(dest=HighLevelILConstPtr(constant=c)):
            return c

targets = set(hex(a) for a in current_hlil.traverse(collect_targets))

Count parameters per call

def param_counter(i) -> int:
    match i:
        case HighLevelILCall():
            return len(i.params)

list(current_hlil.traverse(param_counter))

Annotations & Types

Rename a function

func.name = "newName"

Change function type signature

func.type = Type.function(Type.void(), [])
func.type = Type.function(Type.int(4), [('buf', Type.pointer(bv.arch, Type.char())), ('len', Type.int(4))])

Change parameter type

func.parameter_vars[0].type = Type.pointer(bv.arch, Type.char())

Create and apply a struct

bv.define_user_type('MyStruct', Type.structure(members=[
    (Type.int(4), 'field_0'),
    (Type.pointer(bv.arch, Type.char()), 'name'),
    (Type.int(8), 'size')
]))

Apply type to data variable

bv.define_user_data_var(addr, "char*")
bv.get_data_var_at(addr).type = Type.int(4)

Tags and bookmarks

bv.add_tag(addr, "Crashes", "buffer overflow here")
func.add_tag("Important", "needs code-review")
func.add_tag("Bug", "off-by-one", addr)