architecture module

binaryninja.architecture.Architecture([handle]) class Architecture is the parent class for all CPU architectures. Subclasses of Architecture implement assembly,
binaryninja.architecture.ReferenceSource(...)
class binaryninja.architecture.Architecture(handle=None)[source]

Bases: object

class Architecture is the parent class for all CPU architectures. Subclasses of Architecture implement assembly, disassembly, IL lifting, and patching.

class Architecture has a __metaclass__ with the additional methods register, and supports iteration:

>>> #List the architectures
>>> list(Architecture)
[<arch: aarch64>, <arch: armv7>, <arch: armv7eb>, <arch: mipsel32>, <arch: mips32>, <arch: powerpc>,
<arch: x86>, <arch: x86_64>]
>>> #Register a new Architecture
>>> class MyArch(Architecture):
...  name = "MyArch"
...
>>> MyArch.register()
>>> list(Architecture)
[<arch: aarch64>, <arch: armv7>, <arch: armv7eb>, <arch: mipsel32>, <arch: mips32>, <arch: powerpc>,
<arch: x86>, <arch: x86_64>, <arch: MyArch>]
>>>

For the purposes of this documentation the variable arch will be used in the following context

>>> from binaryninja import *
>>> arch = Architecture['x86']
address_size = 8
always_branch(data, addr)[source]

always_branch reads the instruction(s) in data at virtual address addr and returns a string of bytes of the same length which always branches.

Parameters:
  • data (str) – bytes for the instruction to be converted
  • addr (int) – the virtual address of the instruction to be patched
Returns:

string containing len(data) which always branches to the same location as the provided instruction

Return type:

str

Example:
>>> bytes = arch.always_branch(arch.assemble("je 10")[0], 0)
>>> arch.get_instruction_text(bytes, 0)
(['nop     '], 1L)
>>> arch.get_instruction_text(bytes[1:], 0)
(['jmp     ', '0x9'], 5L)
>>>
assemble(code, addr=0)[source]

assemble converts the string of assembly instructions code loaded at virtual address addr to the byte representation of those instructions.

Parameters:
  • code (str) – string representation of the instructions to be assembled
  • addr (int) – virtual address that the instructions will be loaded at
Returns:

the bytes for the assembled instructions or error string

Return type:

(a tuple of instructions and empty string) or (or None and error string)

Example:
>>> arch.assemble("je 10")
('\x0f\x84\x04\x00\x00\x00', '')
>>>
calling_conventions

Dict of CallingConvention objects (read-only)

convert_to_nop(data, addr)[source]

convert_to_nop reads the instruction(s) in data at virtual address addr and returns a string of nop instructions of the same length as data.

Parameters:
  • data (str) – bytes for the instruction to be converted
  • addr (int) – the virtual address of the instruction to be patched
Returns:

string containing len(data) worth of no-operation instructions

Return type:

str

Example:
>>> arch.convert_to_nop("\x00\x00", 0)
'\x90\x90'
>>>
default_int_size = 4
endianness = <Endianness.LittleEndian: 0>
flag_roles = {}
flag_write_types = []
flags = []
flags_required_for_flag_condition = {}
flags_written_by_flag_write_type = {}
full_width_regs

List of full width register strings (read-only)

get_associated_arch_by_address(addr)[source]
get_default_flag_write_low_level_il(op, size, write_type, operands, il)[source]
Parameters:
Return type:

LowLevelILExpr index

get_flag_by_name(flag)[source]

get_flag_by_name get flag name for flag index.

Parameters:flag (int) – flag index
Returns:flag name for flag index
Return type:str
get_flag_condition_low_level_il(cond, il)[source]
Parameters:
Return type:

LowLevelILExpr

get_flag_name(flag)[source]

get_flag_name gets a flag name from a flag number.

Parameters:reg (int) – register number
Returns:the corresponding register string
Return type:str
get_flag_write_low_level_il(op, size, write_type, operands, il)[source]
Parameters:
Return type:

LowLevelILExpr

get_flag_write_type_by_name(write_type)[source]

get_flag_write_type_by_name gets the flag write type name for the flage write type.

Parameters:write_type (int) – flag write type
Returns:flag write type
Return type:str
get_flag_write_type_name(write_type)[source]

get_flag_write_type_name gets the flag write type name for the given flag.

Parameters:write_type (int) – flag
Returns:flag write type name
Return type:str
get_instruction_info(data, addr)[source]

get_instruction_info returns an InstructionInfo object for the instruction at the given virtual address addr with data data.

Note

The instruction info object should always set the InstructionInfo.length to the instruction length, and the branches of the proper types shoulde be added if the instruction is a branch.

Parameters:
  • data (str) – max_instruction_length bytes from the binary at virtual address addr
  • addr (int) – virtual address of bytes in data
Returns:

the InstructionInfo for the current instruction

Return type:

InstructionInfo

get_instruction_low_level_il(data, addr, il)[source]

get_instruction_low_level_il appends LowLevelILExpr objects for the instruction at the given virtual address addr with data data.

Parameters:
  • data (str) – max_instruction_length bytes from the binary at virtual address addr
  • addr (int) – virtual address of bytes in data
  • il (LowLevelILFunction) – The function the current instruction belongs to
Returns:

the length of the current instruction

Return type:

int

get_instruction_low_level_il_instruction(bv, addr)[source]
get_instruction_text(data, addr)[source]

get_instruction_text returns a list of InstructionTextToken objects for the instruction at the given virtual address addr with data data.

Parameters:
  • data (str) – max_instruction_length bytes from the binary at virtual address addr
  • addr (int) – virtual address of bytes in data
Returns:

an InstructionTextToken list for the current instruction

Return type:

list(InstructionTextToken)

get_modified_regs_on_write(reg)[source]

get_modified_regs_on_write returns a list of register names that are modified when reg is written.

Parameters:reg (str) – string register name
Returns:list of register names
Return type:list(str)
get_reg_name(reg)[source]

get_reg_name gets a register name from a register number.

Parameters:reg (int) – register number
Returns:the corresponding register string
Return type:str
get_view_type_constant(type_name, const_name, default_value=0)[source]

get_view_type_constant retrieves the view type constant for the given type_name and const_name.

Parameters:
  • type_name (str) – the BinaryView type name of the constant to be retrieved
  • const_name (str) – the constant name to retrieved
  • value (int) – optional default value if the type_name is not present. default value is zero.
Returns:

The BinaryView type constant or the default_value if not found

Return type:

int

Example:
>>> ELF_RELOC_COPY = 5
>>> arch.set_view_type_constant("ELF", "R_COPY", ELF_RELOC_COPY)
>>> arch.get_view_type_constant("ELF", "R_COPY")
5L
>>> arch.get_view_type_constant("ELF", "NOT_HERE", 100)
100L
invert_branch(data, addr)[source]

invert_branch reads the instruction(s) in data at virtual address addr and returns a string of bytes of the same length which inverts the branch of provided instruction.

Parameters:
  • data (str) – bytes for the instruction to be converted
  • addr (int) – the virtual address of the instruction to be patched
Returns:

string containing len(data) which always branches to the same location as the provided instruction

Return type:

str

Example:
>>> arch.get_instruction_text(arch.invert_branch(arch.assemble("je 10")[0], 0), 0)
(['jne     ', '0xa'], 6L)
>>> arch.get_instruction_text(arch.invert_branch(arch.assemble("jo 10")[0], 0), 0)
(['jno     ', '0xa'], 6L)
>>> arch.get_instruction_text(arch.invert_branch(arch.assemble("jge 10")[0], 0), 0)
(['jl      ', '0xa'], 6L)
>>>
is_always_branch_patch_available(data, addr)[source]

is_always_branch_patch_available determines if the instruction data at addr can be made to always branch.

Parameters:
  • data (str) – bytes for the instruction to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:
>>> arch.is_always_branch_patch_available(arch.assemble("je 10")[0], 0)
True
>>> arch.is_always_branch_patch_available(arch.assemble("nop")[0], 0)
False
>>>
is_invert_branch_patch_available(data, addr)[source]

is_always_branch_patch_available determines if the instruction data at addr can be inverted.

Parameters:
  • data (str) – bytes for the instruction to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:
>>> arch.is_invert_branch_patch_available(arch.assemble("je 10")[0], 0)
True
>>> arch.is_invert_branch_patch_available(arch.assemble("nop")[0], 0)
False
>>>
is_never_branch_patch_available(data, addr)[source]

is_never_branch_patch_available determines if the instruction data at addr can be made to never branch.

Parameters:
  • data (str) – bytes for the instruction to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:
>>> arch.is_never_branch_patch_available(arch.assemble("je 10")[0], 0)
True
>>> arch.is_never_branch_patch_available(arch.assemble("nop")[0], 0)
False
>>>
is_skip_and_return_value_patch_available(data, addr)[source]

is_skip_and_return_zero_patch_available determines if the instruction data at addr is a call-like instruction that can be made into an instruction returns a value.

Parameters:
  • data (str) – bytes for the instruction to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("call 0")[0], 0)
True
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("jmp eax")[0], 0)
False
>>>
is_skip_and_return_zero_patch_available(data, addr)[source]

is_skip_and_return_zero_patch_available determines if the instruction data at addr is a call-like instruction that can be made into an instruction returns zero.

Parameters:
  • data (str) – bytes for the instruction to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("call 0")[0], 0)
True
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("call eax")[0], 0)
True
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("jmp eax")[0], 0)
False
>>>
is_view_type_constant_defined(type_name, const_name)[source]
Parameters:
  • type_name (str) – the BinaryView type name of the constant to query
  • const_name (str) – the constant name to query
Return type:

None

Example:
>>> arch.set_view_type_constant("ELF", "R_COPY", ELF_RELOC_COPY)
>>> arch.is_view_type_constant_defined("ELF", "R_COPY")
True
>>> arch.is_view_type_constant_defined("ELF", "NOT_THERE")
False
>>>
max_instr_length = 16
name = None
next_address = 0
opcode_display_length = 8
parse_types_from_source(source, filename=None, include_dirs=[])[source]

parse_types_from_source parses the source string and any needed headers searching for them in the optional list of directories provided in include_dirs.

Parameters:
  • source (str) – source string to be parsed
  • filename (str) – optional source filename
  • include_dirs (list(str)) – optional list of string filename include directories
Returns:

py:class:TypeParserResult (a SyntaxError is thrown on parse error)

Return type:

TypeParserResult

Example:
>>> arch.parse_types_from_source('int foo;\nint bar(int x);\nstruct bas{int x,y;};\n')
({types: {'bas': <type: struct bas>}, variables: {'foo': <type: int32_t>}, functions:{'bar':
<type: int32_t(int32_t x)>}}, '')
>>>
parse_types_from_source_file(filename, include_dirs=[])[source]

parse_types_from_source_file parses the source file filename and any needed headers searching for them in the optional list of directories provided in include_dirs.

Parameters:
  • filename (str) – filename of file to be parsed
  • include_dirs (list(str)) – optional list of string filename include directories
Returns:

py:class:TypeParserResult (a SyntaxError is thrown on parse error)

Return type:

TypeParserResult

Example:
>>> file = "/Users/binja/tmp.c"
>>> open(file).read()
'int foo;\nint bar(int x);\nstruct bas{int x,y;};\n'
>>> arch.parse_types_from_source_file(file)
({types: {'bas': <type: struct bas>}, variables: {'foo': <type: int32_t>}, functions:
{'bar': <type: int32_t(int32_t x)>}}, '')
>>>
perform_always_branch(data, addr)[source]

perform_always_branch implements a method which converts the branch represented by the bytes in data to at addr to an unconditional branch.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

The bytes of the replacement unconditional branch instruction

Return type:

str

perform_assemble(code, addr)[source]

perform_assemble implements a method to convert the string of assembly instructions code loaded at virtual address addr to the byte representation of those instructions. This can be done by simply shelling out to an assembler like yasm or llvm-mc, since this method isn’t performance sensitive.

Note

Architecture subclasses should implement this method.

Note

It is important that the assembler used accepts a syntax identical to the one emitted by the disassembler. This will prevent confusing the user.

Warning

This method should never be called directly.

Parameters:
  • code (str) – string representation of the instructions to be assembled
  • addr (int) – virtual address that the instructions will be loaded at
Returns:

the bytes for the assembled instructions or error string

Return type:

(a tuple of instructions and empty string) or (or None and error string)

perform_convert_to_nop(data, addr)[source]

perform_convert_to_nop implements a method which returns a nop sequence of len(data) bytes long.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes at virtual address addr
  • addr (int) – the virtual address of the instruction to be patched
Returns:

nop sequence of same length as data or None

Return type:

str or None

perform_get_associated_arch_by_address(addr)[source]
perform_get_flag_condition_low_level_il(cond, il)[source]

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
Return type:

LowLevelILExpr

perform_get_flag_write_low_level_il(op, size, write_type, flag, operands, il)[source]

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
Return type:

LowLevelILExpr

perform_get_instruction_info(data, addr)[source]

perform_get_instruction_info implements a method which interpretes the bytes passed in data as an InstructionInfo object. The InstructionInfo object should have the length of the current instruction. If the instruction is a branch instruction the method should add a branch of the proper type:

BranchType Description
UnconditionalBranch Branch will always be taken
FalseBranch False branch condition
TrueBranch True branch condition
CallDestination Branch is a call instruction (Branch with Link)
FunctionReturn Branch returns from a function
SystemCall System call instruction
IndirectBranch Branch destination is a memory address or register
UnresolvedBranch Call instruction that isn’t
Parameters:
  • data (str) – bytes to decode
  • addr (int) – virtual address of the byte to be decoded
Returns:

a InstructionInfo object containing the length and branche types for the given instruction

Return type:

InstructionInfo

perform_get_instruction_low_level_il(data, addr, il)[source]

perform_get_instruction_low_level_il implements a method to interpret the bytes passed in data to low-level IL instructions. The il instructions must be appended to the LowLevelILFunction.

Note

Architecture subclasses should implement this method.

Parameters:
  • data (str) – bytes to be interpreted as low-level IL instructions
  • addr (int) – virtual address of start of data
  • il (LowLevelILFunction) – LowLevelILFunction object to append LowLevelILExpr objects to
Return type:

None

perform_get_instruction_text(data, addr)[source]

perform_get_instruction_text implements a method which interpretes the bytes passed in data as a list of InstructionTextToken objects.

Parameters:
  • data (str) – bytes to decode
  • addr (int) – virtual address of the byte to be decoded
Returns:

a tuple of list(InstructionTextToken) and length of instruction decoded

Return type:

tuple(list(InstructionTextToken), int)

perform_invert_branch(data, addr)[source]

perform_invert_branch implements a method which inverts the branch represented by the bytes in data to at addr.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

The bytes of the replacement unconditional branch instruction

Return type:

str

perform_is_always_branch_patch_available(data, addr)[source]

perform_is_always_branch_patch_available implements a check to determine if the instruction represented by the bytes contained in data at address addr is a conditional branch that can be made unconditional.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

perform_is_invert_branch_patch_available(data, addr)[source]

perform_is_invert_branch_patch_available implements a check to determine if the instruction represented by the bytes contained in data at address addr is a conditional branch which can be inverted.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:addr (int) – the virtual address of the instruction to be patched
Returns:True if the instruction can be patched, False otherwise
Return type:bool
perform_is_never_branch_patch_available(data, addr)[source]

perform_is_never_branch_patch_available implements a check to determine if the instruction represented by the bytes contained in data at address addr is a branch instruction that can be made to never branch.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

perform_is_skip_and_return_value_patch_available(data, addr)[source]

perform_is_skip_and_return_value_patch_available implements a check to determine if the instruction represented by the bytes contained in data at address addr is a call-like instruction which can made into instructions that are equivilent to “return 0”. For example if data was the x86 instruction call 0xdeadbeef which could be converted into mov eax, 42 thus this function would return True.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

perform_is_skip_and_return_zero_patch_available(data, addr)[source]

perform_is_skip_and_return_zero_patch_available implements a check to determine if the instruction represented by the bytes contained in data at address addr is a call-like instruction which can made into instructions that are equivilent to “return 0”. For example if data was the x86 instruction call eax which could be converted into xor eax,eax thus this function would return True.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes to be checked
  • addr (int) – the virtual address of the instruction to be patched
Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

perform_skip_and_return_value(data, addr, value)[source]

perform_skip_and_return_value implements a method which converts a call-like instruction represented by the bytes in data at addr to one or more instructions that are equivilent to a function returning a value.

Note

Architecture subclasses should implement this method.

Warning

This method should never be called directly.

Parameters:
  • data (str) – bytes to be checked
  • addr (int) – the virtual address of the instruction to be patched
  • value (int) – value to be returned
Returns:

The bytes of the replacement unconditional branch instruction

Return type:

str

register_calling_convention(cc)[source]

register_calling_convention registers a new calling convention for the Architecture.

Parameters:cc (CallingConvention) – CallingConvention object to be registered
Return type:None
regs = {}
set_view_type_constant(type_name, const_name, value)[source]

set_view_type_constant creates a new binaryview type constant.

Parameters:
  • type_name (str) – the BinaryView type name of the constant to be registered
  • const_name (str) – the constant name to register
  • value (int) – the value of the constant
Return type:

None

Example:
>>> ELF_RELOC_COPY = 5
>>> arch.set_view_type_constant("ELF", "R_COPY", ELF_RELOC_COPY)
>>>
skip_and_return_value(data, addr, value)[source]

skip_and_return_value reads the instruction(s) in data at virtual address addr and returns a string of bytes of the same length which doesn’t call and instead return a value.

Parameters:
  • data (str) – bytes for the instruction to be converted
  • addr (int) – the virtual address of the instruction to be patched
Returns:

string containing len(data) which always branches to the same location as the provided instruction

Return type:

str

Example:
>>> arch.get_instruction_text(arch.skip_and_return_value(arch.assemble("call 10")[0], 0, 0), 0)
(['mov     ', 'eax', ', ', '0x0'], 5L)
>>>
stack_pointer = None
standalone_platform

Architecture standalone platform (read-only)

class binaryninja.architecture.ReferenceSource(func, arch, addr)[source]

Bases: object