architecture module

binaryninja.architecture.Architecture()

class Architecture is the parent class for all CPU architectures.

binaryninja.architecture.ArchitectureHook(...)

binaryninja.architecture.CoreArchitecture(handle)

binaryninja.architecture.InstructionBranch(...)

binaryninja.architecture.InstructionInfo(...)

binaryninja.architecture.InstructionTextToken(...)

class InstructionTextToken is used to tell the core about the various components in the disassembly views.

binaryninja.architecture.IntrinsicInfo(...)

binaryninja.architecture.IntrinsicInput(type)

binaryninja.architecture.RegisterInfo(...)

binaryninja.architecture.RegisterStackInfo(...)

class Architecture[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: thumb2>, <arch: armv7eb>, <arch: thumb2eb>, <arch: mipsel32>, <arch: mips32>, <arch: ppc>, <arch: ppc64>, <arch: ppc_le>, <arch: ppc64_le>, <arch: x86_16>, <arch: x86>, <arch: x86_64>]
>>> #Register a new Architecture
>>> class MyArch(Architecture):
...  name = "MyArch"
...
>>> MyArch.register()
>>> list(Architecture)
[<arch: aarch64>, <arch: armv7>, <arch: thumb2>, <arch: armv7eb>, <arch: thumb2eb>, <arch: mipsel32>, <arch: mips32>, <arch: ppc>, <arch: ppc64>, <arch: ppc_le>, <arch: ppc64_le>, <arch: x86_16>, <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']

Note

The max_instr_length property of an architecture is not necessarily representative of the maximum instruction size of the associated CPU architecture. Rather, it represents the maximum size of a potential instruction that the architecture plugin can handle. So for example, the value for x86 is 16 despite the lagest valid instruction being only 15 bytes long, and the value for mips32 is currently 8 because multiple instrutions are decoded looking for delay slots so they can be reordered.

always_branch(data: bytes, addr: int = 0) Optional[bytes][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.

Note

Architecture subclasses should implement this method.

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
>>> data = arch.always_branch(arch.assemble("je 10"), 0)
>>> arch.get_instruction_text(data, 0)
(['nop', '     '], 1)
>>> arch.get_instruction_text(data[1:], 0)
(['jmp', '     ', '0x9'], 5)
>>>
assemble(code: str, addr: int = 0) bytes[source]

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

Note

Architecture subclasses should implement this method.

Architecture plugins can override this method to provide assembler functionality. This can be done by simply shelling out to an assembler like yasm or llvm-mc, since this method isn’t performance sensitive.

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.

If there is an error in the input assembly, this function should raise a ValueError (with a reasonable error message).

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

Return type

Python3 - a ‘bytes’ object; Python2 - a ‘bytes’ object

Example
>>> arch.assemble("je 10")
b'\x0f\x84\x04\x00\x00\x00'
>>>
convert_to_nop(data: bytes, addr: int = 0) Optional[bytes][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.

Note

Architecture subclasses should implement this method.

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(b"\x00\x00", 0)
b'\x90\x90'
>>>
get_associated_arch_by_address(addr: int) Tuple[Architecture, int][source]
Parameters

addr (int) –

Return type

Tuple[Architecture, int]

get_default_flag_condition_low_level_il(cond: LowLevelILFlagCondition, sem_class: Optional[Union[SemanticClassName, ILSemanticFlagClass, SemanticClassIndex]], il: LowLevelILFunction) ExpressionIndex[source]
Parameters
Return type

ExpressionIndex

get_default_flag_write_low_level_il(op: LowLevelILOperation, size: int, role: FlagRole, operands: List[Union[str, ILRegister, int]], il: LowLevelILFunction) ExpressionIndex[source]
Parameters
Return type

ExpressionIndex index

get_flag_by_name(flag: FlagName) FlagIndex[source]

get_flag_by_name get flag name for flag index.

Parameters

flag (FlagName) – flag name

Returns

flag index for flag name

Return type

FlagIndex

get_flag_condition_low_level_il(cond: LowLevelILFlagCondition, sem_class: Optional[Union[SemanticClassName, ILSemanticFlagClass, SemanticClassIndex]], il: LowLevelILFunction) ExpressionIndex[source]
Parameters
  • cond (LowLevelILFlagCondition) – Flag condition to be computed

  • sem_class (SemanticClassType) – Semantic class to be used (None for default semantics)

  • il (LowLevelILFunction) – LowLevelILFunction object to append ExpressionIndex objects to

Return type

ExpressionIndex

get_flag_index(flag: Union[FlagName, ILFlag, FlagIndex]) FlagIndex[source]
Parameters

flag (Union[FlagName, ILFlag, FlagIndex]) –

Return type

FlagIndex

get_flag_name(flag: FlagIndex) FlagName[source]

get_flag_name gets a flag name from a flag index.

Parameters

flag (int) – flag index

Returns

the corresponding flag name string

Return type

FlagName

get_flag_role(flag: FlagIndex, sem_class: Optional[SemanticClassIndex] = None) FlagRole[source]

get_flag_role gets the role of a given flag.

Parameters
  • flag (int) – flag

  • sem_class (int) – optional semantic flag class

Returns

flag role

Return type

FlagRole

get_flag_write_low_level_il(op: LowLevelILOperation, size: int, write_type: Optional[FlagWriteTypeName], flag: Union[FlagName, ILFlag, FlagIndex], operands: List[Union[str, ILRegister, int]], il: LowLevelILFunction) ExpressionIndex[source]
Parameters
Return type

lowlevelil.ExpressionIndex

get_flag_write_type_by_name(write_type: FlagWriteTypeName) FlagWriteTypeIndex[source]

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

Parameters

write_type (str) – flag write type

Returns

flag write type

Return type

int

get_flag_write_type_name(write_type: FlagWriteTypeIndex) FlagWriteTypeName[source]

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

Parameters

write_type (FlagWriteTypeIndex) – flag

Returns

flag write type name

Return type

FlagWriteTypeName

get_flags_required_for_flag_condition(cond: LowLevelILFlagCondition, sem_class: Optional[Union[SemanticClassName, ILSemanticFlagClass, SemanticClassIndex]] = None)[source]
Parameters
get_instruction_info(data: bytes, addr: int) Optional[InstructionInfo][source]

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

Note

Architecture subclasses should implement this method.

Note

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

If the instruction is a branch instruction architecture plugins 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

Branch destination is an unknown address

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: bytes, addr: int, il: LowLevelILFunction) Optional[int][source]

get_instruction_low_level_il appends lowlevelil.ExpressionIndex objects to il for the instruction at the given virtual address addr with data data.

This is used to analyze arbitrary data at an address, if you are working with an existing binary, you likely want to be using Function.get_low_level_il_at.

Note

Architecture subclasses should implement this method.

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: BinaryView, addr: int) LowLevelILInstruction[source]
Parameters
Return type

LowLevelILInstruction

get_instruction_text(data: bytes, addr: int) Optional[Tuple[List[InstructionTextToken], int]][source]

get_instruction_text returns a tuple containing a list of decoded InstructionTextToken objects and the bytes used at the given virtual address addr with data data.

Note

Architecture subclasses should implement this method.

Parameters
  • data (str) – max_instruction_length bytes from the binary at virtual address addr

  • addr (int) – virtual address of bytes in data

Returns

a tuple containing the InstructionTextToken list and length of bytes decoded

Return type

tuple(list(InstructionTextToken), int)

get_intrinsic_index(intrinsic: Union[IntrinsicName, ILIntrinsic, IntrinsicIndex]) IntrinsicIndex[source]

get_intrinsic_index gets an intrinsic index given an IntrinsicType.

Parameters

intrinsic (IntrinsicType) – intrinsic number

Returns

the corresponding intrinsic string

Return type

IntrinsicIndex

get_intrinsic_name(intrinsic: IntrinsicIndex) IntrinsicName[source]

get_intrinsic_name gets an intrinsic name from an intrinsic number.

Parameters

intrinsic (int) – intrinsic number

Returns

the corresponding intrinsic string

Return type

IntrinsicName

get_low_level_il_from_bytes(data: bytes, addr: int) LowLevelILInstruction[source]

get_low_level_il_from_bytes converts the instruction in bytes to il at the given virtual address

Parameters
  • data (str) – the bytes of the instruction

  • addr (int) – virtual address of bytes in data

Returns

a list of low level il instructions

Return type

LowLevelILInstruction

Example
>>> list(arch.get_low_level_il_from_bytes(b'\xeb\xfe', 0x40DEAD))
<il: jump(0x40dead)>
>>>
get_modified_regs_on_write(reg: RegisterName) List[RegisterName][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_index(reg: Union[RegisterName, ILRegister, RegisterIndex]) RegisterIndex[source]
Parameters

reg (Union[RegisterName, ILRegister, RegisterIndex]) –

Return type

RegisterIndex

get_reg_name(reg: RegisterIndex) RegisterName[source]

get_reg_name gets a register name from a register index.

Parameters

reg (RegisterIndex) – register index

Returns

the corresponding register name

Return type

RegisterName

get_reg_stack_for_reg(reg: RegisterName) Optional[RegisterStackName][source]
Parameters

reg (RegisterName) –

Return type

Optional[RegisterStackName]

get_reg_stack_index(reg_stack: Union[RegisterStackName, ILRegisterStack, RegisterStackIndex]) RegisterStackIndex[source]
Parameters

reg_stack (Union[RegisterStackName, ILRegisterStack, RegisterStackIndex]) –

Return type

RegisterStackIndex

get_reg_stack_name(reg_stack: RegisterStackIndex) RegisterStackName[source]

get_reg_stack_name gets a register stack name from a register stack number.

Parameters

reg_stack (int) – register stack number

Returns

the corresponding register string

Return type

RegisterStackName

get_semantic_flag_class_by_name(sem_class: SemanticClassName) SemanticClassIndex[source]

get_semantic_flag_class_by_name gets the semantic flag class index by name.

Parameters

sem_class (int) – semantic flag class

Returns

semantic flag class index

Return type

str

get_semantic_flag_class_index(sem_class: Optional[Union[SemanticClassName, ILSemanticFlagClass, SemanticClassIndex]]) SemanticClassIndex[source]
Parameters

sem_class (Optional[Union[SemanticClassName, ILSemanticFlagClass, SemanticClassIndex]]) –

Return type

SemanticClassIndex

get_semantic_flag_class_name(class_index: SemanticClassIndex) SemanticClassName[source]

get_semantic_flag_class_name gets the name of a semantic flag class from the index.

Parameters

class_index (int) – class_index

Returns

the name of the semantic flag class

Return type

str

get_semantic_flag_group_by_name(sem_group: SemanticGroupName) SemanticGroupIndex[source]

get_semantic_flag_group_by_name gets the semantic flag group index by name.

Parameters

sem_group (SemanticGroupName) – semantic flag group name

Returns

semantic flag group index

Return type

int

get_semantic_flag_group_index(sem_group: Union[SemanticGroupName, ILSemanticFlagGroup, SemanticGroupIndex]) SemanticGroupIndex[source]
Parameters

sem_group (Union[SemanticGroupName, ILSemanticFlagGroup, SemanticGroupIndex]) –

Return type

SemanticGroupIndex

get_semantic_flag_group_low_level_il(sem_group: Optional[Union[SemanticGroupName, ILSemanticFlagGroup, SemanticGroupIndex]], il: LowLevelILFunction) ExpressionIndex[source]
Parameters
Return type

lowlevelil.ExpressionIndex

get_semantic_flag_group_name(group_index: SemanticGroupIndex) SemanticGroupName[source]

get_semantic_flag_group_name gets the name of a semantic flag group from the index.

Parameters

group_index (int) – group_index

Returns

the name of the semantic flag group

Return type

str

get_view_type_constant(type_name: str, const_name: str, default_value: int = 0) int[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

  • default_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")
5
>>> arch.get_view_type_constant("ELF", "NOT_HERE", 100)
100
invert_branch(data: bytes, addr: int = 0) Optional[bytes][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.

Note

Architecture subclasses should implement this method.

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)
(['jne', '     ', '0xa'], 6)
>>> arch.get_instruction_text(arch.invert_branch(arch.assemble("jo 10"), 0), 0)
(['jno', '     ', '0xa'], 6)
>>> arch.get_instruction_text(arch.invert_branch(arch.assemble("jge 10"), 0), 0)
(['jl', '      ', '0xa'], 6)
>>>
is_always_branch_patch_available(data: bytes, addr: int = 0) bool[source]

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

Note

Architecture subclasses should implement this method.

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)
True
>>> arch.is_always_branch_patch_available(arch.assemble("nop"), 0)
False
>>>
is_invert_branch_patch_available(data: bytes, addr: int = 0) bool[source]

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

Note

Architecture subclasses should implement this method.

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)
True
>>> arch.is_invert_branch_patch_available(arch.assemble("nop"), 0)
False
>>>
is_never_branch_patch_available(data: bytes, addr: int = 0) bool[source]

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

Note

Architecture subclasses should implement this method.

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)
True
>>> arch.is_never_branch_patch_available(arch.assemble("nop"), 0)
False
>>>
is_skip_and_return_value_patch_available(data: bytes, addr: int = 0) bool[source]

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

Note

Architecture subclasses should implement this method.

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_value_patch_available(arch.assemble("call 0"), 0)
True
>>> arch.is_skip_and_return_value_patch_available(arch.assemble("jmp eax"), 0)
False
>>>
is_skip_and_return_zero_patch_available(data: bytes, addr: int = 0) bool[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.

Note

Architecture subclasses should implement this method.

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)
True
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("call eax"), 0)
True
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("jmp eax"), 0)
False
>>>
is_view_type_constant_defined(type_name: str, const_name: str) bool[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
>>> ELF_RELOC_COPY = 5
>>> 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
>>>
classmethod register() None[source]
Return type

None

register_calling_convention(cc: CallingConvention) None[source]

register_calling_convention registers a new calling convention for the Architecture.

Parameters

cc (CallingConvention) – CallingConvention object to be registered

Return type

None

set_view_type_constant(type_name: str, const_name: str, value: int) None[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: bytes, addr: int, value: int) Optional[bytes][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.

Note

Architecture subclasses should implement this method.

Parameters
  • data (str) – bytes for the instruction to be converted

  • addr (int) – the virtual address of the instruction to be patched

  • value (int) –

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)
(['mov', '     ', 'eax', ', ', '0x0'], 5)
>>>
address_size = 8
property calling_conventions: Mapping[str, CallingConvention]

Dict of CallingConvention objects (read-only)

property can_assemble: bool

returns if the architecture can assemble instructions (read-only)

default_int_size = 4
endianness = 0
flag_conditions_for_semantic_flag_group = {}
flag_roles: Dict[FlagName, FlagRole] = {}
flag_write_types: List[FlagWriteTypeName] = []
flags: List[FlagName] = []
flags_required_for_flag_condition: Dict[lowlevelil.LowLevelILFlagCondition, List[FlagName]] = {}
flags_required_for_semantic_flag_group: Dict[SemanticGroupName, List[FlagName]] = {}
flags_written_by_flag_write_type = {}
property full_width_regs: List[RegisterName]

List of full width register strings (read-only)

global_regs = []
instr_alignment = 1
intrinsics = {}
max_instr_length = 16
name = None
next_address = 0
opcode_display_length = 8
reg_stacks: Dict[RegisterStackName, RegisterStackInfo] = {}
regs: Dict[RegisterName, RegisterInfo] = {}
semantic_class_for_flag_write_type = {}
semantic_flag_classes: List[SemanticClassName] = []
semantic_flag_groups: List[SemanticGroupName] = []
stack_pointer = None
property standalone_platform: Platform

Architecture standalone platform (read-only)

system_regs = []
property type_libraries: List[TypeLibrary]

Architecture type libraries

class ArchitectureHook(base_arch: Architecture)[source]

Bases: binaryninja.architecture.CoreArchitecture

Parameters

base_arch (Architecture) –

register() None[source]
Return type

None

property base_arch: Architecture
class CoreArchitecture(handle: binaryninja._binaryninjacore.BNArchitecture)[source]

Bases: binaryninja.architecture.Architecture

Parameters

handle (binaryninja._binaryninjacore.BNArchitecture) –

always_branch(data: bytes, addr: int = 0) Optional[bytes][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
>>> data = arch.always_branch(arch.assemble("je 10"), 0)
>>> arch.get_instruction_text(data, 0)
(['nop', '     '], 1)
>>> arch.get_instruction_text(bytes[1:], 0)
(['jmp', '     ', '0x9'], 5)
>>>
assemble(code: str, addr: int = 0) bytes[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

Return type

Python3 - a ‘bytes’ object; Python2 - a ‘bytes’ object

Example
>>> arch.assemble("je 10")
b'\x0f\x84\x04\x00\x00\x00'
>>>
convert_to_nop(data: bytes, addr: int = 0) Optional[bytes][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(b"\x00\x00", 0)
b'\x90\x90'
>>>
get_associated_arch_by_address(addr: int) Tuple[Architecture, int][source]
Parameters

addr (int) –

Return type

Tuple[Architecture, int]

get_flag_condition_low_level_il(cond: LowLevelILFlagCondition, sem_class: Union[SemanticClassName, ILSemanticFlagClass, SemanticClassIndex], il: LowLevelILFunction) ExpressionIndex[source]
Parameters
  • cond (LowLevelILFlagCondition) – Flag condition to be computed

  • sem_class (str) – Semantic class to be used (None for default semantics)

  • il (LowLevelILFunction) – LowLevelILFunction object to append ExpressionIndex objects to

Return type

ExpressionIndex

get_flag_role(flag: FlagIndex, sem_class: Optional[SemanticClassIndex] = None) FlagRole[source]

get_flag_role gets the role of a given flag.

Parameters
  • flag (int) – flag

  • sem_class (int) – optional semantic flag class

Returns

flag role

Return type

FlagRole

get_flag_write_low_level_il(op: LowLevelILOperation, size: int, write_type: FlagWriteTypeName, flag: Union[FlagName, ILFlag, FlagIndex], operands: List[Union[str, ILRegister, int]], il: LowLevelILFunction) ExpressionIndex[source]
Parameters
Return type

ExpressionIndex

get_flags_required_for_flag_condition(cond: LowLevelILFlagCondition, sem_class: Optional[Union[SemanticClassName, ILSemanticFlagClass, SemanticClassIndex]] = None) List[FlagName][source]
Parameters
Return type

List[FlagName]

get_instruction_info(data: bytes, addr: int) Optional[InstructionInfo][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 should be added if the instruction is a branch.

Parameters
  • data (bytes) – 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: bytes, addr: int, il: LowLevelILFunction) Optional[int][source]

get_instruction_low_level_il appends lowlevelil.ExpressionIndex objects to il for the instruction at the given virtual address addr with data data.

This is used to analyze arbitrary data at an address, if you are working with an existing binary, you likely want to be using Function.get_low_level_il_at.

Parameters
  • data (bytes) – 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

Optional[int]

get_instruction_text(data: bytes, addr: int) Optional[Tuple[List[InstructionTextToken], int]][source]

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

Parameters
  • data (bytes) – 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_semantic_flag_group_low_level_il(sem_group: SemanticGroupName, il: LowLevelILFunction) ExpressionIndex[source]
Parameters
Return type

ExpressionIndex

invert_branch(data: bytes, addr: int = 0) Optional[bytes][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)
(['jne', '     ', '0xa'], 6)
>>> arch.get_instruction_text(arch.invert_branch(arch.assemble("jo 10"), 0), 0)
(['jno', '     ', '0xa'], 6)
>>> arch.get_instruction_text(arch.invert_branch(arch.assemble("jge 10"), 0), 0)
(['jl', '      ', '0xa'], 6)
>>>
is_always_branch_patch_available(data: bytes, addr: int = 0) bool[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)
True
>>> arch.is_always_branch_patch_available(arch.assemble("nop"), 0)
False
>>>
is_invert_branch_patch_available(data: bytes, addr: int = 0) bool[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)
True
>>> arch.is_invert_branch_patch_available(arch.assemble("nop"), 0)
False
>>>
is_never_branch_patch_available(data: bytes, addr: int = 0) bool[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)
True
>>> arch.is_never_branch_patch_available(arch.assemble("nop"), 0)
False
>>>
is_skip_and_return_value_patch_available(data: bytes, addr: int = 0) bool[source]

is_skip_and_return_value_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_value_patch_available(arch.assemble("call 0"), 0)
True
>>> arch.is_skip_and_return_value_patch_available(arch.assemble("jmp eax"), 0)
False
>>>
is_skip_and_return_zero_patch_available(data: bytes, addr: int = 0) bool[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)
True
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("call eax"), 0)
True
>>> arch.is_skip_and_return_zero_patch_available(arch.assemble("jmp eax"), 0)
False
>>>
skip_and_return_value(data: bytes, addr: int, value: int) Optional[bytes][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

  • value (int) – the value to return

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)
(['mov', '     ', 'eax', ', ', '0x0'], 5)
>>>
class InstructionBranch(type: BranchType, target: int, arch: Union[ForwardRef('Architecture'), NoneType])[source]

Bases: object

Parameters
Return type

None

arch: Optional[Architecture]
target: int
type: BranchType
class InstructionInfo(length: int = 0, arch_transition_by_target_addr: bool = False, branch_delay: bool = False, branches: List[binaryninja.architecture.InstructionBranch] = <factory>)[source]

Bases: object

Parameters
Return type

None

add_branch(branch_type: BranchType, target: int = 0, arch: Optional[Architecture] = None) None[source]
Parameters
Return type

None

arch_transition_by_target_addr: bool = False
branch_delay: bool = False
branches: List[InstructionBranch]
length: int = 0
class InstructionTextToken(type: typing.Union[binaryninja.enums.InstructionTextTokenType, int], text: str, value: int = 0, size: int = 0, operand: int = 4294967295, context: binaryninja.enums.InstructionTextTokenContext = InstructionTextTokenContext.NoTokenContext, address: int = 0, confidence: int = 255, typeNames: typing.List[str] = <factory>, width: int = 0)[source]

Bases: object

class InstructionTextToken is used to tell the core about the various components in the disassembly views.

The below table is provided for documentation purposes but the complete list of TokenTypes is available at: enums.InstructionTextTokenType. Note that types marked as Not emitted by architectures are not intended to be used by Architectures during lifting. Rather, they are added by the core during analysis or display. UI plugins, however, may make use of them as appropriate.

Uses of tokens include plugins that parse the output of an architecture (though parsing IL is recommended), or additionally, applying color schemes appropriately.

InstructionTextTokenType

Description

AddressDisplayToken

Not emitted by architectures

AnnotationToken

Not emitted by architectures

ArgumentNameToken

Not emitted by architectures

BeginMemoryOperandToken

The start of memory operand

CharacterConstantToken

A printable character

CodeRelativeAddressToken

Not emitted by architectures

CodeSymbolToken

Not emitted by architectures

DataSymbolToken

Not emitted by architectures

EndMemoryOperandToken

The end of a memory operand

ExternalSymbolToken

Not emitted by architectures

FieldNameToken

Not emitted by architectures

FloatingPointToken

Floating point number

HexDumpByteValueToken

Not emitted by architectures

HexDumpInvalidByteToken

Not emitted by architectures

HexDumpSkippedByteToken

Not emitted by architectures

HexDumpTextToken

Not emitted by architectures

ImportToken

Not emitted by architectures

IndirectImportToken

Not emitted by architectures

InstructionToken

The instruction mnemonic

IntegerToken

Integers

KeywordToken

Not emitted by architectures

LocalVariableToken

Not emitted by architectures

NameSpaceSeparatorToken

Not emitted by architectures

NameSpaceToken

Not emitted by architectures

OpcodeToken

Not emitted by architectures

OperandSeparatorToken

The comma or delimiter that separates tokens

PossibleAddressToken

Integers that are likely addresses

RegisterToken

Registers

StringToken

Not emitted by architectures

StructOffsetToken

Not emitted by architectures

TagToken

Not emitted by architectures

TextToken

Used for anything not of another type.

CommentToken

Comments

TypeNameToken

Not emitted by architectures

Parameters
Return type

None

address: int = 0
confidence: int = 255
context: InstructionTextTokenContext = 0
operand: int = 4294967295
size: int = 0
text: str
type: Union[InstructionTextTokenType, int]
typeNames: List[str]
value: int = 0
width: int = 0
class IntrinsicInfo(inputs: List[IntrinsicInput], outputs: List[ForwardRef('types.Type')], index: Union[int, NoneType] = None)[source]

Bases: object

Parameters
Return type

None

index: Optional[int] = None
inputs: List[IntrinsicInput]
outputs: List[Type]
class IntrinsicInput(type: 'types.Type', name: str = '')[source]

Bases: object

Parameters
Return type

None

name: str = ''
type: Type
class RegisterInfo(full_width_reg: <function NewType.<locals>.new_type at 0x7ff093d43820>, size: int, offset: int = 0, extend: binaryninja.enums.ImplicitRegisterExtend = <ImplicitRegisterExtend.NoExtend: 0>, index: Union[RegisterIndex, NoneType] = None)[source]

Bases: object

Parameters
Return type

None

extend: ImplicitRegisterExtend = 0
full_width_reg: RegisterName
index: Optional[RegisterIndex] = None
offset: int = 0
size: int
class RegisterStackInfo(storage_regs: List[RegisterName], top_relative_regs: List[RegisterName], stack_top_reg: <function NewType.<locals>.new_type at 0x7ff093d43820>, index: Union[RegisterStackIndex, NoneType] = None)[source]

Bases: object

Parameters
  • storage_regs (List[RegisterName]) –

  • top_relative_regs (List[RegisterName]) –

  • stack_top_reg (RegisterName) –

  • index (Optional[RegisterStackIndex]) –

Return type

None

index: Optional[RegisterStackIndex] = None
stack_top_reg: RegisterName
storage_regs: List[RegisterName]
top_relative_regs: List[RegisterName]