architecture module ¶

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)
>>>

analyze_basic_blocks(func: Function, context: BasicBlockAnalysisContext) → None[source]

analyze_basic_blocks performs basic block recovery and commits the results to the function analysis

Note

Architecture subclasses should only implement this method if function-level analysis is required

Parameters:

func (Function) – the function to analyze
context (BasicBlockAnalysisContext) – the analysis context

Return type:

None

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) → bytes | None[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:

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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None, il: LowLevelILFunction) → ExpressionIndex[source]

Parameters:

cond (LowLevelILFlagCondition) –
sem_class (SemanticClassType) –
il (LowLevelILFunction) –

Return type:

ExpressionIndex

get_default_flag_write_low_level_il(op: lowlevelil.LowLevelILOperation, size: int, role: FlagRole, operands: List[lowlevelil.ILRegisterType], il: LowLevelILFunction) → lowlevelil.ExpressionIndex[source]

Parameters:

op (LowLevelILOperation) –
size (int) –
role (FlagRole) –
operands (list(str) or list(int)) – a list of either items that are either string register names or constant integer values
il (LowLevelILFunction) –

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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None, 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: FlagName | ILFlag | FlagIndex) → FlagIndex[source]

Parameters:: flag (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: SemanticClassIndex | None = 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:

get_flag_write_low_level_il(op: LowLevelILOperation, size: int, write_type: FlagWriteTypeName | None, flag: FlagName | ILFlag | FlagIndex, operands: List[lowlevelil.ILRegisterType], il: LowLevelILFunction) → lowlevelil.ExpressionIndex[source]

Parameters:

op (LowLevelILOperation) –
size (int) –
write_type (str) –
flag (FlagType) –
operands (list(str) or list(int)) – a list of either items that are either string register names or constant integer values
il (LowLevelILFunction) –

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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None = None)[source]

Parameters:

cond (LowLevelILFlagCondition) –
sem_class (SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) –

get_instruction_info(data: bytes, addr: int) → InstructionInfo | None[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) – a maximum of 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:

get_instruction_low_level_il(data: bytes, addr: int, il: LowLevelILFunction) → int | None[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) – a maximum of 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:

bv (BinaryView) –
addr (int) –

Return type:

get_instruction_text(data: bytes, addr: int) → Tuple[List[InstructionTextToken], int] | None[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) – a maximum of 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_class(intrinsic: IntrinsicIndex) → IntrinsicClass[source]

get_intrinsic_class gets the intrinsic class from an intrinsic number.

Parameters:: intrinsic (int) – intrinsic number
Returns:: intrinsic class
Return type:: IntrinsicClass

get_intrinsic_index(intrinsic: 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:

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: RegisterName | ILRegister | RegisterIndex) → RegisterIndex[source]

Parameters:: reg (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) → RegisterStackName | None[source]

Parameters:: reg (RegisterName) –
Return type:: RegisterStackName | None

get_reg_stack_index(reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex) → RegisterStackIndex[source]

Parameters:: reg_stack (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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) → SemanticClassIndex[source]

Parameters:: sem_class (SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) –
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: SemanticGroupName | ILSemanticFlagGroup | SemanticGroupIndex) → SemanticGroupIndex[source]

Parameters:: sem_group (SemanticGroupName | ILSemanticFlagGroup | SemanticGroupIndex) –
Return type:: SemanticGroupIndex

get_semantic_flag_group_low_level_il(sem_group: SemanticGroupName | ILSemanticFlagGroup | SemanticGroupIndex | None, il: LowLevelILFunction) → ExpressionIndex[source]

Parameters:

sem_group (Optional[SemanticGroupType]) –
il (LowLevelILFunction) –

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

invert_branch(data: bytes, addr: int = 0) → bytes | None[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:

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:

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:

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:

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:

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:

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
>>>

classmethod register() → Architecture[source]

Return type:: Architecture

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

skip_and_return_value(data: bytes, addr: int, value: int) → bytes | None[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:

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)

property cdecl_calling_convention

Cdecl calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the cdecl calling convention, if one exists.
Setter:: sets the cdecl calling convention
Type:: Optional[’callingconvention.CallingConvention’]

property default_calling_convention

Default calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the default calling convention, if one exists.
Setter:: sets the default calling convention
Type:: Optional[’callingconvention.CallingConvention’]

default_int_size = 4

endianness = 0

property fastcall_calling_convention

Fastcall calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the fastcall calling convention, if one exists.
Setter:: sets the fastcall calling convention
Type:: Optional[’callingconvention.CallingConvention’]

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[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 = {}

link_reg = None

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)

property stdcall_calling_convention

Stdcall calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the stdcall calling convention, if one exists.
Setter:: sets the stdcall calling convention
Type:: Optional[’callingconvention.CallingConvention’]

system_regs = []

property type_libraries: List[TypeLibrary]: Architecture type libraries

class ArchitectureHook[source]

Bases: CoreArchitecture

__init__(base_arch: Architecture)[source]

Parameters:: base_arch (Architecture) –

register() → None[source]

Return type:: None

property base_arch: Architecture

class BasicBlockAnalysisContext[source]

Bases: object

Used by analyze_basic_blocks and contains analysis settings and other contextual information.

Note

This class is meant to be used by Architecture plugins only

__init__(_handle: BNBasicBlockAnalysisContext, _function: Function, _contextual_returns_dirty: bool, _indirect_branches: List[IndirectBranchInfo], _indirect_no_return_calls: Set[ArchAndAddr], _analysis_skip_override: FunctionAnalysisSkipOverride, _guided_analysis_mode: bool, _trigger_guided_on_invalid_instruction: bool, _translate_tail_calls: bool, _disallow_branch_to_string: bool, _max_function_size: int, _max_size_reached: bool, _contextual_returns: Dict[ArchAndAddr, bool], _direct_code_references: Dict[int, ArchAndAddr], _direct_no_return_calls: Set[ArchAndAddr], _halted_disassembly_addresses: Set[ArchAndAddr]) → None

Parameters:

_handle (BNBasicBlockAnalysisContext) –
_function (Function) –
_contextual_returns_dirty (bool) –
_indirect_branches (List[IndirectBranchInfo]) –
_indirect_no_return_calls (Set[ArchAndAddr]) –
_analysis_skip_override (FunctionAnalysisSkipOverride) –
_guided_analysis_mode (bool) –
_trigger_guided_on_invalid_instruction (bool) –
_translate_tail_calls (bool) –
_disallow_branch_to_string (bool) –
_max_function_size (int) –
_max_size_reached (bool) –
_contextual_returns (Dict[ArchAndAddr, bool]) –
_direct_code_references (Dict[int, ArchAndAddr]) –
_direct_no_return_calls (Set[ArchAndAddr]) –
_halted_disassembly_addresses (Set[ArchAndAddr]) –

Return type:

None

add_basic_block(block: BasicBlock) → None[source]

add_basic_block adds a BasicBlock to the current function.

Parameters:: block (BasicBlock) – The BasicBlock to add
Return type:: None

add_contextual_return(loc: ArchAndAddr, value: bool) → None[source]

add_contextual_return adds a contextual function return location and its value to the current function.

Parameters:

loc (ArchAndAddr) – The location of the contextual function return
value (bool) – The value of the contextual function return

Return type:

None

add_direct_code_reference(target: int, source: ArchAndAddr) → None[source]

add_direct_code_reference adds a direct code reference to the current function.

Parameters:

target (int) – The target address of the direct code reference
source (ArchAndAddr) – The source location of the direct code reference

Return type:

None

add_direct_no_return_call(loc: ArchAndAddr) → None[source]

add_direct_no_return_call adds a direct no-return call location to the current function.

Parameters:: loc (ArchAndAddr) – The location of the direct no-return call
Return type:: None

add_halted_disassembly_address(loc: ArchAndAddr) → None[source]

add_halted_disassembly_address adds an address to the set of halted disassembly addresses.

Parameters:: loc (ArchAndAddr) – The location of the halted disassembly address
Return type:: None

add_temp_outgoing_reference(target: Function) → None[source]

add_temp_outgoing_reference adds a temporary outgoing reference to the specified function.

Parameters:: target (Function) – The target function to add a temporary outgoing reference to
Return type:: None

create_basic_block(arch: Architecture, start: int) → BasicBlock | None[source]

create_basic_block creates a new BasicBlock at the specified address for the given Architecture.

Parameters:

arch (Architecture) – Architecture of the BasicBlock to create
start (int) – Address of the BasicBlock to create

Return type:

BasicBlock | None

finalize() → None[source]

finalize finalizes the function’s basic block analysis

Return type:: None

static from_core_struct(bn_bb_context: BNBasicBlockAnalysisContext) → BasicBlockAnalysisContext[source]

Create a BasicBlockAnalysisContext from a core.BNBasicBlockAnalysisContext structure.

Parameters:: bn_bb_context (BNBasicBlockAnalysisContext) –
Return type:: BasicBlockAnalysisContext

property analysis_skip_override: FunctionAnalysisSkipOverride: Get the analysis skip override setting for this context.

property contextual_returns: Dict[ArchAndAddr, bool]: Get the mapping of contextual function return locations to their values.

property direct_code_references: Dict[int, ArchAndAddr]: Get the mapping of direct code reference targets to their source locations.

property direct_no_return_calls: Set[ArchAndAddr]: Get the set of direct no-return call locations in this context.

property disallow_branch_to_string: bool: Get setting from context that determines if branches to string addresses should be disallowed.

property guided_analysis_mode: bool: Get the setting that determines if functions start in guided analysis mode.

property halt_on_invalid_instruction: bool: Get the setting from context that determines if analysis should halt on invalid instructions.

property halted_disassembly_addresses: Set[ArchAndAddr]: Get the set of addresses where disassembly has been halted.

property indirect_branches: List[IndirectBranchInfo]: Get the list of indirect branches in this context.

property indirect_no_return_calls: Set[ArchAndAddr]: Get the set of indirect no-return calls in this context.

property max_function_size: int: Get the maximum function size setting for this context.

property max_size_reached: bool: Get boolean that indicates if the maximum function size has been reached.

property translate_tail_calls: bool: Get setting from context that determines if tail calls should be translated.

property trigger_guided_on_invalid_instruction: bool: Get the setting that determines if guided mode should be triggered on invalid instructions.

class CoreArchitecture[source]

Bases: Architecture

__init__(handle: BNArchitecture)[source]

Parameters:: handle (BNArchitecture) –

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

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) → bytes | None[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:

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: 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: SemanticClassIndex | None = 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:

get_flag_write_low_level_il(op: LowLevelILOperation, size: int, write_type: FlagWriteTypeName, flag: FlagName | ILFlag | FlagIndex, operands: List[lowlevelil.ILRegisterType], il: LowLevelILFunction) → lowlevelil.ExpressionIndex[source]

Parameters:

op (LowLevelILOperation) –
size (int) –
write_type (str) –
operands (list(str) or list(int)) – a list of either items that are either string register names or constant integer values
il (LowLevelILFunction) –
flag (FlagName | ILFlag | FlagIndex) –

Return type:

ExpressionIndex

get_flags_required_for_flag_condition(cond: LowLevelILFlagCondition, sem_class: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None = None) → List[FlagName][source]

Parameters:

cond (LowLevelILFlagCondition) –
sem_class (SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) –

Return type:

List[FlagName]

get_instruction_info(data: bytes, addr: int) → InstructionInfo | None[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) – a maximum of 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:

list(InstructionTextToken)

get_instruction_low_level_il(data: bytes, addr: int, il: LowLevelILFunction) → int | None[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) – a maximum of 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) → Tuple[List[InstructionTextToken], int] | None[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) – a maximum of 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:

get_semantic_flag_group_low_level_il(sem_group: SemanticGroupName, il: LowLevelILFunction) → ExpressionIndex[source]

Parameters:

sem_group (str) –
il (LowLevelILFunction) –

Return type:

ExpressionIndex

invert_branch(data: bytes, addr: int = 0) → bytes | None[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:

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:

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:

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:

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:

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:

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) → bytes | None[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:

Example:

>>> arch.get_instruction_text(arch.skip_and_return_value(arch.assemble("call 10"), 0, 0), 0)
(['mov', '     ', 'eax', ', ', '0x0'], 5)
>>>

class InstructionBranch[source]

Bases: object

InstructionBranch(type: binaryninja.enums.BranchType, target: int, arch: Optional[ForwardRef(‘Architecture’)])

__init__(type: BranchType, target: int, arch: Architecture | None) → None

Parameters:

type (BranchType) –
target (int) –
arch (Architecture | None) –

Return type:

None

arch: Architecture | None

target: int

type: BranchType

class InstructionInfo[source]

Bases: object

InstructionInfo(length: int = 0, arch_transition_by_target_addr: bool = False, branch_delay: int = 0, branches: List[binaryninja.architecture.InstructionBranch] = <factory>)

__init__(length: int = 0, arch_transition_by_target_addr: bool = False, branch_delay: int = 0, branches: ~typing.List[~binaryninja.architecture.InstructionBranch] = <factory>) → None

Parameters:

length (int) –
arch_transition_by_target_addr (bool) –
branch_delay (int) –
branches (List[InstructionBranch]) –

Return type:

None

add_branch(branch_type: BranchType, target: int = 0, arch: Architecture | None = None) → None[source]

Parameters:

branch_type (BranchType) –
target (int) –
arch (Architecture | None) –

Return type:

None

arch_transition_by_target_addr: bool = False

branch_delay: int = 0

branches: List[InstructionBranch]

length: int = 0

class InstructionTextToken[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

StackVariableToken

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

AddressSeparatorToken

Not emitted by architectures

__init__(type: ~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, il_expr_index: int = 18446744073709551615) → None

Parameters:

type (InstructionTextTokenType | int) –
text (str) –
value (int) –
size (int) –
operand (int) –
context (InstructionTextTokenContext) –
address (int) –
confidence (int) –
typeNames (List[str]) –
width (int) –
il_expr_index (int) –

Return type:

None

address: int = 0

confidence: int = 255

context: InstructionTextTokenContext = 0

il_expr_index: int = 18446744073709551615

operand: int = 4294967295

size: int = 0

text: str

type: InstructionTextTokenType | int

typeNames: List[str]

value: int = 0

width: int = 0

class IntrinsicInfo[source]

Bases: object

IntrinsicInfo(inputs: List[binaryninja.architecture.IntrinsicInput], outputs: List[ForwardRef(‘types.Type’)], index: Optional[int] = None)

__init__(inputs: List[IntrinsicInput], outputs: List[Type], index: int | None = None) → None

Parameters:

inputs (List[IntrinsicInput]) –
outputs (List[Type]) –
index (int | None) –

Return type:

None

index: int | None = None

inputs: List[IntrinsicInput]

outputs: List[Type]

class IntrinsicInput[source]

Bases: object

IntrinsicInput(type: ‘types.Type’, name: str = ‘’)

__init__(type: Type, name: str = '') → None

Parameters:

type (Type) –
name (str) –

Return type:

None

name: str = ''

type: Type

class RegisterInfo[source]

Bases: object

RegisterInfo(full_width_reg: binaryninja.architecture.RegisterName, size: int, offset: int = 0, extend: binaryninja.enums.ImplicitRegisterExtend = <ImplicitRegisterExtend.NoExtend: 0>, index: Optional[binaryninja.architecture.RegisterIndex] = None)

__init__(full_width_reg: RegisterName, size: int, offset: int = 0, extend: ImplicitRegisterExtend = ImplicitRegisterExtend.NoExtend, index: RegisterIndex | None = None) → None

Parameters:

full_width_reg (RegisterName) –
size (int) –
offset (int) –
extend (ImplicitRegisterExtend) –
index (RegisterIndex | None) –

Return type:

None

extend: ImplicitRegisterExtend = 0

full_width_reg: RegisterName

index: RegisterIndex | None = None

offset: int = 0

size: int

class RegisterStackInfo[source]

Bases: object

RegisterStackInfo(storage_regs: List[binaryninja.architecture.RegisterName], top_relative_regs: List[binaryninja.architecture.RegisterName], stack_top_reg: binaryninja.architecture.RegisterName, index: Optional[binaryninja.architecture.RegisterStackIndex] = None)

__init__(storage_regs: List[RegisterName], top_relative_regs: List[RegisterName], stack_top_reg: RegisterName, index: RegisterStackIndex | None = None) → None

Parameters:

storage_regs (List[RegisterName]) –
top_relative_regs (List[RegisterName]) –
stack_top_reg (RegisterName) –
index (RegisterStackIndex | None) –

Return type:

None

index: RegisterStackIndex | None = None

stack_top_reg: RegisterName

storage_regs: List[RegisterName]

top_relative_regs: List[RegisterName]

Architecture¶

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 largest valid instruction being only 15 bytes long, and the value for mips32 is currently 8 because multiple instructions are decoded looking for delay slots so they can be reordered.

__init__()[source]¶

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

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)
>>>

analyze_basic_blocks(func: Function, context: BasicBlockAnalysisContext) → None[source]¶

analyze_basic_blocks performs basic block recovery and commits the results to the function analysis

Note

Architecture subclasses should only implement this method if function-level analysis is required

Parameters:

func (Function) – the function to analyze
context (BasicBlockAnalysisContext) – the analysis context

Return type:

None

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) → bytes | None[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:

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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None, il: LowLevelILFunction) → ExpressionIndex[source]¶

Parameters:

cond (LowLevelILFlagCondition) –
sem_class (SemanticClassType) –
il (LowLevelILFunction) –

Return type:

ExpressionIndex

get_default_flag_write_low_level_il(op: lowlevelil.LowLevelILOperation, size: int, role: FlagRole, operands: List[lowlevelil.ILRegisterType], il: LowLevelILFunction) → lowlevelil.ExpressionIndex[source]¶

Parameters:

op (LowLevelILOperation) –
size (int) –
role (FlagRole) –
operands (list(str) or list(int)) – a list of either items that are either string register names or constant integer values
il (LowLevelILFunction) –

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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None, 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: FlagName | ILFlag | FlagIndex) → FlagIndex[source]¶

Parameters:: flag (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: SemanticClassIndex | None = 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:

get_flag_write_low_level_il(op: LowLevelILOperation, size: int, write_type: FlagWriteTypeName | None, flag: FlagName | ILFlag | FlagIndex, operands: List[lowlevelil.ILRegisterType], il: LowLevelILFunction) → lowlevelil.ExpressionIndex[source]¶

Parameters:

op (LowLevelILOperation) –
size (int) –
write_type (str) –
flag (FlagType) –
operands (list(str) or list(int)) – a list of either items that are either string register names or constant integer values
il (LowLevelILFunction) –

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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None = None)[source]¶

Parameters:

cond (LowLevelILFlagCondition) –
sem_class (SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) –

get_instruction_info(data: bytes, addr: int) → InstructionInfo | None[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) – a maximum of 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:

get_instruction_low_level_il(data: bytes, addr: int, il: LowLevelILFunction) → int | None[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) – a maximum of 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:

bv (BinaryView) –
addr (int) –

Return type:

get_instruction_text(data: bytes, addr: int) → Tuple[List[InstructionTextToken], int] | None[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) – a maximum of 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_class(intrinsic: IntrinsicIndex) → IntrinsicClass[source]¶

get_intrinsic_class gets the intrinsic class from an intrinsic number.

Parameters:: intrinsic (int) – intrinsic number
Returns:: intrinsic class
Return type:: IntrinsicClass

get_intrinsic_index(intrinsic: 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:

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: RegisterName | ILRegister | RegisterIndex) → RegisterIndex[source]¶

Parameters:: reg (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) → RegisterStackName | None[source]¶

Parameters:: reg (RegisterName) –
Return type:: RegisterStackName | None

get_reg_stack_index(reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex) → RegisterStackIndex[source]¶

Parameters:: reg_stack (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: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) → SemanticClassIndex[source]¶

Parameters:: sem_class (SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) –
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: SemanticGroupName | ILSemanticFlagGroup | SemanticGroupIndex) → SemanticGroupIndex[source]¶

Parameters:: sem_group (SemanticGroupName | ILSemanticFlagGroup | SemanticGroupIndex) –
Return type:: SemanticGroupIndex

get_semantic_flag_group_low_level_il(sem_group: SemanticGroupName | ILSemanticFlagGroup | SemanticGroupIndex | None, il: LowLevelILFunction) → ExpressionIndex[source]¶

Parameters:

sem_group (Optional[SemanticGroupType]) –
il (LowLevelILFunction) –

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

invert_branch(data: bytes, addr: int = 0) → bytes | None[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:

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:

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:

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:

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:

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:

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
>>>

classmethod register() → Architecture[source]¶

Return type:: Architecture

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

skip_and_return_value(data: bytes, addr: int, value: int) → bytes | None[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:

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)

property cdecl_calling_convention¶

Cdecl calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the cdecl calling convention, if one exists.
Setter:: sets the cdecl calling convention
Type:: Optional[’callingconvention.CallingConvention’]

property default_calling_convention¶

Default calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the default calling convention, if one exists.
Setter:: sets the default calling convention
Type:: Optional[’callingconvention.CallingConvention’]

default_int_size = 4¶

endianness = 0¶

property fastcall_calling_convention¶

Fastcall calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the fastcall calling convention, if one exists.
Setter:: sets the fastcall calling convention
Type:: Optional[’callingconvention.CallingConvention’]

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[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 = {}¶

link_reg = None¶

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)

property stdcall_calling_convention¶

Stdcall calling convention.

Note

Make sure the calling convention has been registered with Architecture.register_calling_convention.

Getter:: returns a CallingConvention object for the stdcall calling convention, if one exists.
Setter:: sets the stdcall calling convention
Type:: Optional[’callingconvention.CallingConvention’]

system_regs = []¶

property type_libraries: List[TypeLibrary]¶: Architecture type libraries

ArchitectureHook¶

class ArchitectureHook[source]¶

Bases: CoreArchitecture

__init__(base_arch: Architecture)[source]¶

Parameters:: base_arch (Architecture) –

register() → None[source]¶

Return type:: None

property base_arch: Architecture¶

BasicBlockAnalysisContext¶

class BasicBlockAnalysisContext[source]¶

Bases: object

Used by analyze_basic_blocks and contains analysis settings and other contextual information.

Note

This class is meant to be used by Architecture plugins only

__init__(_handle: BNBasicBlockAnalysisContext, _function: Function, _contextual_returns_dirty: bool, _indirect_branches: List[IndirectBranchInfo], _indirect_no_return_calls: Set[ArchAndAddr], _analysis_skip_override: FunctionAnalysisSkipOverride, _guided_analysis_mode: bool, _trigger_guided_on_invalid_instruction: bool, _translate_tail_calls: bool, _disallow_branch_to_string: bool, _max_function_size: int, _max_size_reached: bool, _contextual_returns: Dict[ArchAndAddr, bool], _direct_code_references: Dict[int, ArchAndAddr], _direct_no_return_calls: Set[ArchAndAddr], _halted_disassembly_addresses: Set[ArchAndAddr]) → None¶

Parameters:

_handle (BNBasicBlockAnalysisContext) –
_function (Function) –
_contextual_returns_dirty (bool) –
_indirect_branches (List[IndirectBranchInfo]) –
_indirect_no_return_calls (Set[ArchAndAddr]) –
_analysis_skip_override (FunctionAnalysisSkipOverride) –
_guided_analysis_mode (bool) –
_trigger_guided_on_invalid_instruction (bool) –
_translate_tail_calls (bool) –
_disallow_branch_to_string (bool) –
_max_function_size (int) –
_max_size_reached (bool) –
_contextual_returns (Dict[ArchAndAddr, bool]) –
_direct_code_references (Dict[int, ArchAndAddr]) –
_direct_no_return_calls (Set[ArchAndAddr]) –
_halted_disassembly_addresses (Set[ArchAndAddr]) –

Return type:

None

add_basic_block(block: BasicBlock) → None[source]¶

add_basic_block adds a BasicBlock to the current function.

Parameters:: block (BasicBlock) – The BasicBlock to add
Return type:: None

add_contextual_return(loc: ArchAndAddr, value: bool) → None[source]¶

add_contextual_return adds a contextual function return location and its value to the current function.

Parameters:

loc (ArchAndAddr) – The location of the contextual function return
value (bool) – The value of the contextual function return

Return type:

None

add_direct_code_reference(target: int, source: ArchAndAddr) → None[source]¶

add_direct_code_reference adds a direct code reference to the current function.

Parameters:

target (int) – The target address of the direct code reference
source (ArchAndAddr) – The source location of the direct code reference

Return type:

None

add_direct_no_return_call(loc: ArchAndAddr) → None[source]¶

add_direct_no_return_call adds a direct no-return call location to the current function.

Parameters:: loc (ArchAndAddr) – The location of the direct no-return call
Return type:: None

add_halted_disassembly_address(loc: ArchAndAddr) → None[source]¶

add_halted_disassembly_address adds an address to the set of halted disassembly addresses.

Parameters:: loc (ArchAndAddr) – The location of the halted disassembly address
Return type:: None

add_temp_outgoing_reference(target: Function) → None[source]¶

add_temp_outgoing_reference adds a temporary outgoing reference to the specified function.

Parameters:: target (Function) – The target function to add a temporary outgoing reference to
Return type:: None

create_basic_block(arch: Architecture, start: int) → BasicBlock | None[source]¶

create_basic_block creates a new BasicBlock at the specified address for the given Architecture.

Parameters:

arch (Architecture) – Architecture of the BasicBlock to create
start (int) – Address of the BasicBlock to create

Return type:

BasicBlock | None

finalize() → None[source]¶

finalize finalizes the function’s basic block analysis

Return type:: None

static from_core_struct(bn_bb_context: BNBasicBlockAnalysisContext) → BasicBlockAnalysisContext[source]¶

Create a BasicBlockAnalysisContext from a core.BNBasicBlockAnalysisContext structure.

Parameters:: bn_bb_context (BNBasicBlockAnalysisContext) –
Return type:: BasicBlockAnalysisContext

property analysis_skip_override: FunctionAnalysisSkipOverride¶: Get the analysis skip override setting for this context.

property contextual_returns: Dict[ArchAndAddr, bool]¶: Get the mapping of contextual function return locations to their values.

property direct_code_references: Dict[int, ArchAndAddr]¶: Get the mapping of direct code reference targets to their source locations.

property direct_no_return_calls: Set[ArchAndAddr]¶: Get the set of direct no-return call locations in this context.

property disallow_branch_to_string: bool¶: Get setting from context that determines if branches to string addresses should be disallowed.

property guided_analysis_mode: bool¶: Get the setting that determines if functions start in guided analysis mode.

property halt_on_invalid_instruction: bool¶: Get the setting from context that determines if analysis should halt on invalid instructions.

property halted_disassembly_addresses: Set[ArchAndAddr]¶: Get the set of addresses where disassembly has been halted.

property indirect_branches: List[IndirectBranchInfo]¶: Get the list of indirect branches in this context.

property indirect_no_return_calls: Set[ArchAndAddr]¶: Get the set of indirect no-return calls in this context.

property max_function_size: int¶: Get the maximum function size setting for this context.

property max_size_reached: bool¶: Get boolean that indicates if the maximum function size has been reached.

property translate_tail_calls: bool¶: Get setting from context that determines if tail calls should be translated.

property trigger_guided_on_invalid_instruction: bool¶: Get the setting that determines if guided mode should be triggered on invalid instructions.

CoreArchitecture¶

class CoreArchitecture[source]¶

Bases: Architecture

__init__(handle: BNArchitecture)[source]¶

Parameters:: handle (BNArchitecture) –

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

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) → bytes | None[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:

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: 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: SemanticClassIndex | None = 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:

get_flag_write_low_level_il(op: LowLevelILOperation, size: int, write_type: FlagWriteTypeName, flag: FlagName | ILFlag | FlagIndex, operands: List[lowlevelil.ILRegisterType], il: LowLevelILFunction) → lowlevelil.ExpressionIndex[source]¶

Parameters:

op (LowLevelILOperation) –
size (int) –
write_type (str) –
operands (list(str) or list(int)) – a list of either items that are either string register names or constant integer values
il (LowLevelILFunction) –
flag (FlagName | ILFlag | FlagIndex) –

Return type:

ExpressionIndex

get_flags_required_for_flag_condition(cond: LowLevelILFlagCondition, sem_class: SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None = None) → List[FlagName][source]¶

Parameters:

cond (LowLevelILFlagCondition) –
sem_class (SemanticClassName | ILSemanticFlagClass | SemanticClassIndex | None) –

Return type:

List[FlagName]

get_instruction_info(data: bytes, addr: int) → InstructionInfo | None[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) – a maximum of 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:

list(InstructionTextToken)

get_instruction_low_level_il(data: bytes, addr: int, il: LowLevelILFunction) → int | None[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) – a maximum of 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) → Tuple[List[InstructionTextToken], int] | None[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) – a maximum of 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:

get_semantic_flag_group_low_level_il(sem_group: SemanticGroupName, il: LowLevelILFunction) → ExpressionIndex[source]¶

Parameters:

sem_group (str) –
il (LowLevelILFunction) –

Return type:

ExpressionIndex

invert_branch(data: bytes, addr: int = 0) → bytes | None[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:

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:

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:

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:

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:

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:

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) → bytes | None[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: