function module

Class

Description

binaryninja.function.AdvancedFunctionAnalysisDataRequestor

binaryninja.function.ArchAndAddr

binaryninja.function.BasicBlockList

binaryninja.function.DisassemblySettings

binaryninja.function.DisassemblyTextLine

binaryninja.function.DisassemblyTextLineTypeInfo

binaryninja.function.DisassemblyTextRenderer

binaryninja.function.Function

binaryninja.function.FunctionViewType

binaryninja.function.HighLevelILBasicBlockList

binaryninja.function.ILReferenceSource

binaryninja.function.LowLevelILBasicBlockList

binaryninja.function.MediumLevelILBasicBlockList

binaryninja.function.TagList

binaryninja.function.VariableReferenceSource

class AdvancedFunctionAnalysisDataRequestor[source]

Bases: object

__init__(func: Function | None = None)[source]
Parameters:

func (Function | None) –

close() None[source]
Return type:

None

property function: Function | None
class ArchAndAddr[source]

Bases: object

ArchAndAddr(arch: ‘architecture.Architecture’, addr: int)

__init__(arch: Architecture, addr: int) None
Parameters:
Return type:

None

addr: int
arch: Architecture
class BasicBlockList[source]

Bases: object

__init__(function: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction)[source]
Parameters:

function (Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction) –

class DisassemblySettings[source]

Bases: object

__init__(handle: LP_BNDisassemblySettings | None = None)[source]
Parameters:

handle (LP_BNDisassemblySettings | None) –

static default_graph_settings() DisassemblySettings[source]
Return type:

DisassemblySettings

static default_linear_settings() DisassemblySettings[source]
Return type:

DisassemblySettings

static default_settings() DisassemblySettings[source]
Return type:

DisassemblySettings

is_option_set(option: DisassemblyOption) bool[source]
Parameters:

option (DisassemblyOption) –

Return type:

bool

set_option(option: DisassemblyOption, state: bool = True) None[source]
Parameters:
Return type:

None

property max_symbol_width: int
property width: int
class DisassemblyTextLine[source]

Bases: object

DisassemblyTextLine(tokens: List[ForwardRef(‘InstructionTextToken’)], address: Optional[int] = None, il_instr: Union[ForwardRef(‘lowlevelil.LowLevelILInstruction’), ForwardRef(‘mediumlevelil.MediumLevelILInstruction’), ForwardRef(‘highlevelil.HighLevelILInstruction’), NoneType] = None, color: Union[ForwardRef(‘_highlight.HighlightColor’), binaryninja.enums.HighlightStandardColor, NoneType] = None, tags: Optional[List[ForwardRef(‘binaryview.Tag’)]] = None, type_info: Optional[binaryninja.function.DisassemblyTextLineTypeInfo] = None)

__init__(tokens: List[InstructionTextToken], address: int | None = None, il_instr: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None = None, color: HighlightColor | HighlightStandardColor | None = None, tags: List[Tag] | None = None, type_info: DisassemblyTextLineTypeInfo | None = None)[source]
Parameters:
address: int | None
property address_and_indentation_tokens
property address_and_indentation_width
highlight: HighlightColor
il_instruction: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None
tags: List[Tag]
tokens: List[InstructionTextToken]
property total_width
type_info: DisassemblyTextLineTypeInfo | None
class DisassemblyTextLineTypeInfo[source]

Bases: object

DisassemblyTextLineTypeInfo(parent_type: Optional[ForwardRef(‘types.Type’)], field_index: int, offset: int)

__init__(parent_type: Type | None, field_index: int, offset: int) None
Parameters:
  • parent_type (Type | None) –

  • field_index (int) –

  • offset (int) –

Return type:

None

field_index: int
offset: int
parent_type: Type | None
class DisassemblyTextRenderer[source]

Bases: object

__init__(func: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None = None, settings: DisassemblySettings | None = None, handle: BNDisassemblySettings | None = None)[source]
Parameters:
add_integer_token(tokens: List[InstructionTextToken], int_token: InstructionTextToken, addr: int, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

add_stack_var_reference_tokens(tokens: List[InstructionTextToken], ref: StackVariableReference) None[source]
Parameters:
Return type:

None

add_symbol_token(tokens: List[InstructionTextToken], addr: int, size: int, operand: int | None = None) bool[source]
Parameters:
Return type:

bool

get_disassembly_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None][source]
Parameters:

addr (int) –

Return type:

Generator[Tuple[DisassemblyTextLine | None, int], None, None]

get_instruction_annotations(addr: int) List[InstructionTextToken][source]
Parameters:

addr (int) –

Return type:

List[InstructionTextToken]

get_instruction_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None][source]
Parameters:

addr (int) –

Return type:

Generator[Tuple[DisassemblyTextLine | None, int], None, None]

static is_integer_token(token: InstructionTextToken) bool[source]
Parameters:

token (InstructionTextToken) –

Return type:

bool

post_process_lines(addr: int, length: int, in_lines: str | List[str] | List[DisassemblyTextLine], indent_spaces: str = '')[source]
Parameters:
reset_deduplicated_comments() None[source]
Return type:

None

wrap_comment(lines: List[DisassemblyTextLine], cur_line: DisassemblyTextLine, comment: str, has_auto_annotations: bool, leading_spaces: str = '  ', indent_spaces: str = '') None[source]
Parameters:
Return type:

None

property arch: Architecture
property basic_block: BasicBlock | None
property function: Function
property has_data_flow: bool
property il: bool
property il_function: LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None
property settings: DisassemblySettings
class Function[source]

Bases: object

__init__(view: BinaryView | None = None, handle: LP_BNFunction | None = None)[source]
Parameters:
  • view (BinaryView | None) –

  • handle (LP_BNFunction | None) –

add_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None[source]

add_guided_source_blocks adds blocks to the guided source block list for this function. The specified blocks will have their direct outgoing branch targets analyzed. This automatically enables the analysis.guided.enable setting if it is not already enabled.

Parameters:
Return type:

None

add_tag(tag_type: str, data: str, addr: int | None = None, auto: bool = False, arch: Architecture | None = None)[source]

add_tag creates and adds a Tag object on either a function, or on an address inside of a function.

“Function tags” appear at the top of a function and are a good way to label an entire function with some information. If you include an address when you call Function.add_tag, you’ll create an “address tag”. These are good for labeling specific instructions.

For tagging arbitrary data, consider add_tag.

Parameters:
  • tag_type (str) – The name of the tag type for this Tag

  • data (str) – additional data for the Tag

  • addr (int) – address at which to add the tag

  • auto (bool) – Whether or not an auto tag

  • arch (Architecture) – Architecture for the block in which the Tag is added (optional)

Example:
>>> current_function.add_tag("Important", "I think this is the main function")
>>> current_function.add_tag("Crashes", "Nullpointer dereference", here)

Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.

add_user_code_ref(from_addr: int, to_addr: int, arch: Architecture | None = None) None[source]

add_user_code_ref places a user-defined cross-reference from the instruction at the given address and architecture to the specified target address. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, use remove_user_code_ref.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • to_addr (int) – virtual address of the xref’s destination.

  • arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.add_user_code_ref(here, 0x400000)
add_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None[source]

add_user_type_field_ref places a user-defined type field cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, use remove_user_type_field_ref.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • offset (int) – offset of the field, relative to the type

  • from_arch (Architecture) – (optional) architecture of the source instruction

  • size (int) – (optional) the size of the access

Return type:

None

Example:
>>> current_function.add_user_type_field_ref(here, 'A', 0x8)
add_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None[source]

add_user_type_ref places a user-defined type cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, use remove_user_type_ref.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • from_arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.add_user_code_ref(here, 'A')
analyze() None[source]

analyze causes this function to be analyzed if it’s out of date. This function does not wait for the analysis to finish.

Return type:

None

apply_auto_discovered_type(func_type: str | Type | TypeBuilder) None[source]
Parameters:

func_type (str | Type | TypeBuilder) –

Return type:

None

apply_imported_types(sym: CoreSymbol, type: str | Type | TypeBuilder | None = None) None[source]
Parameters:
Return type:

None

check_for_debug_report(name: str) bool[source]

check_for_debug_report checks if a function has had a debug report requested with the given name, and then, if one has been requested, clears the request internally so that future calls to this function for that report will return False.

If a function has had a debug report requested, it is the caller of this function’s responsibility to actually generate and show the debug report. You can use binaryninja.interaction.show_report_collection for showing a debug report from a workflow activity.

Parameters:

name (str) – Name of the debug report

Returns:

True if the report has been requested (and not checked for yet)

Return type:

bool

clear_all_user_var_values() None[source]

Clear all user defined variable values.

Return type:

None

clear_forced_var_version(var: Variable, def_addr: int) None[source]
Parameters:
Return type:

None

clear_user_var_value(var: Variable, def_addr: int, after: bool = True) None[source]

Clears a previously defined user variable value.

Parameters:
  • var (Variable) – Variable for which the value was informed

  • def_addr (int) – Address of the definition site of the variable

  • after (bool) –

Return type:

None

collapse_region(hash)[source]

Collapse a region during rendering :param hash: Hash value of region

create_auto_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None[source]
Parameters:
Return type:

None

create_auto_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None[source]
Parameters:
Return type:

None

create_forced_var_version(var: Variable, def_addr: int) None[source]
Parameters:
Return type:

None

create_graph(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph[source]

Create a flow graph with the disassembly of this function.

Note

This graph waits for function analysis, so Workflow Activities should instead use create_graph_immediate to create graphs with the function contents as-is.

Parameters:
Returns:

Flow graph object

Return type:

CoreFlowGraph

create_graph_immediate(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph[source]

Create a flow graph with the disassembly of this function, specifically using the instructions as they are in the function when this is called. You probably want to use this if you are creating a Debug Report in a Workflow Activity.

Parameters:
Returns:

Flow graph object

Return type:

CoreFlowGraph

create_user_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None[source]
Parameters:
Return type:

None

create_user_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None[source]
Parameters:
Return type:

None

delete_auto_stack_var(offset: int) None[source]
Parameters:

offset (int) –

Return type:

None

delete_user_stack_var(offset: int) None[source]
Parameters:

offset (int) –

Return type:

None

delete_user_var(var: Variable) None[source]
Parameters:

var (Variable) –

Return type:

None

expand_all()[source]

Expand all regions in the function

expand_region(hash)[source]

Un-collapse a region during rendering :param hash: Hash value of region

get_all_user_var_values() Dict[Variable, Dict[ArchAndAddr, PossibleValueSet]][source]

Returns a map of current defined user variable values.

Returns:

Map of user current defined user variable values and their definition sites.

Type:

dict of (Variable, dict of (ArchAndAddr, PossibleValueSet))

Return type:

Dict[Variable, Dict[ArchAndAddr, PossibleValueSet]]

get_basic_block_at(addr: int, arch: Architecture | None = None) BasicBlock | None[source]

get_basic_block_at returns the BasicBlock of the optionally specified Architecture arch at the given address addr.

Parameters:
  • addr (int) – Address of the BasicBlock to retrieve.

  • arch (Architecture) – (optional) Architecture of the basic block if different from the Function’s self.arch

Example:
>>> current_function.get_basic_block_at(current_function.start)
<block: x86_64@0x100000f30-0x100000f50>
Return type:

BasicBlock | None

get_block_annotations(addr: int, arch: Architecture | None = None) List[List[InstructionTextToken]][source]
Parameters:
Return type:

List[List[InstructionTextToken]]

get_call_reg_stack_adjustment(addr: int, arch: Architecture | None = None) Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence][source]
Parameters:
Return type:

Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]

get_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, arch: Architecture | None = None) RegisterStackAdjustmentWithConfidence[source]
Parameters:
Return type:

RegisterStackAdjustmentWithConfidence

get_call_stack_adjustment(addr: int, arch: Architecture | None = None) OffsetWithConfidence[source]
Parameters:
Return type:

OffsetWithConfidence

get_call_type_adjustment(addr: int, arch: Architecture | None = None) Type | None[source]
Parameters:
Return type:

Type | None

get_callee_for_analysis(platform: Platform, addr: int, exact: bool = False) Function | None[source]

get_callee_for_analysis retrieves the callee function for the specified address and platform.

Note

This method is intended for use by architecture plugins only.

Parameters:
  • platform (Platform) – Platform of the callee function

  • addr (int) – Address of the callee function

  • exact (bool) – If True, only return a function if it exactly matches the address and platform

Returns:

The callee function or None if not found

Return type:

Optional[Function]

get_comment_at(addr: int) str[source]
Parameters:

addr (int) –

Return type:

str

get_constant_data(state: RegisterValueType, value: int, size: int = 0) DataBuffer[source]
Parameters:
Return type:

DataBuffer

get_constant_data_and_builtin(state: RegisterValueType, value: int, size: int = 0) Tuple[DataBuffer, BuiltinType][source]
Parameters:
Return type:

Tuple[DataBuffer, BuiltinType]

get_constants_referenced_by(addr: int, arch: Architecture | None = None) List[ConstantReference][source]
Parameters:
Return type:

List[ConstantReference]

get_constants_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[ConstantReference][source]
Parameters:
Return type:

List[ConstantReference]

get_early_return(addr: int | HighLevelILInstruction) EarlyReturn[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

EarlyReturn

get_expr_folding(addr: int | HighLevelILInstruction) ExprFolding[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

ExprFolding

get_flags_read_by_lifted_il_instruction(i: InstructionIndex) List[FlagName][source]
Parameters:

i (InstructionIndex) –

Return type:

List[FlagName]

get_flags_written_by_lifted_il_instruction(i: InstructionIndex) List[FlagName][source]
Parameters:

i (InstructionIndex) –

Return type:

List[FlagName]

get_function_tags(auto: bool | None = None, tag_type: str | None = None) List[Tag][source]

get_function_tags gets a list of function Tags for the function.

Parameters:
  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags

  • tag_type (str) – If None, gets all tags, otherwise only gets tags of the given type

Return type:

list(Tag)

get_guided_source_blocks() List[Tuple[Architecture, int]][source]

get_guided_source_blocks returns the current list of guided source blocks for this function. These blocks have their direct outgoing branch targets analyzed.

Return type:

List[Tuple[Architecture, int]]

Returns:

List of (architecture, address) tuples representing current guided source blocks

get_hlil_var_refs(var: Variable) List[ILReferenceSource][source]

get_hlil_var_refs returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag.

Parameters:

var (Variable) – Variable for which to query the xref

Returns:

List of IL References for the given variable

Return type:

list(ILReferenceSource)

Example:
>>> mlil_var = current_hlil[0].operands[0]
>>> current_function.get_hlil_var_refs(mlil_var)
get_hlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource][source]

get_hlil_var_refs_from returns a list of variables referenced by code in the function func, of the architecture arch, and at the address addr. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used.

Parameters:
  • addr (int) – virtual address to query for variable references

  • length (int) – optional length of query

  • arch (Architecture) – optional architecture of query

Returns:

list of variables reference sources

Return type:

list(VariableReferenceSource)

get_indirect_branches_at(addr: int, arch: Architecture | None = None) List[IndirectBranchInfo][source]
Parameters:
Return type:

List[IndirectBranchInfo]

get_instr_highlight(addr: int, arch: Architecture | None = None) HighlightColor[source]
Example:
>>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0))
>>> current_function.get_instr_highlight(here)
<color: #ff00ff>
Parameters:
Return type:

HighlightColor

get_instruction_containing_address(addr: int, arch: Architecture | None = None) int | None[source]
Parameters:
Return type:

int | None

get_int_display_type(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) IntegerDisplayType[source]

Get the current text display type for an integer token in the disassembly or IL views

See also see get_int_display_type_and_typeid

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

Return type:

IntegerDisplayType

get_int_display_type_and_typeid(instr_addr: int, value: int, operand: int, arch: ~binaryninja.architecture.Architecture | None = None) -> (<enum 'IntegerDisplayType'>, <class 'str'>)[source]

Get the current text display type for an integer token in the disassembly or IL views

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

Return type:

(<enum ‘IntegerDisplayType’>, <class ‘str’>)

get_int_enum_display_typeid(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) str[source]

Get the current text display enum type for an integer token in the disassembly or IL views.

See also see get_int_display_type_and_typeid

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

Returns:

TypeID for the integer token

Return type:

str

get_lifted_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None[source]
Parameters:
Return type:

LowLevelILInstruction | None

get_lifted_il_flag_definitions_for_use(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[InstructionIndex][source]
Parameters:
  • i (InstructionIndex) –

  • flag (FlagName | ILFlag | FlagIndex) –

Return type:

List[InstructionIndex]

get_lifted_il_flag_uses_for_definition(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[LowLevelILInstruction][source]
Parameters:
  • i (InstructionIndex) –

  • flag (FlagName | ILFlag | FlagIndex) –

Return type:

List[LowLevelILInstruction]

get_lifted_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction][source]

get_lifted_ils_at gets the Lifted IL Instruction(s) corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the function to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

list(LowLevelILInstruction)

Example:
>>> func = next(bv.functions)
>>> func.get_lifted_ils_at(func.start)
[<il: push(rbp)>]
get_llil_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None[source]

get_llil_at gets the LowLevelILInstruction corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the instruction to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

LowLevelILInstruction

Example:
>>> func = next(bv.functions)
>>> func.get_llil_at(func.start)
<il: push(rbp)>
get_llils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction][source]

get_llils_at gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.

Parameters:
  • addr (int) – virtual address of the instruction to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

list(LowLevelILInstruction)

Example:
>>> func = next(bv.functions)
>>> func.get_llils_at(func.start)
[<il: push(rbp)>]
get_low_level_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None[source]

get_low_level_il_at gets the LowLevelILInstruction corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the function to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

LowLevelILInstruction

Example:
>>> func = next(bv.functions)
>>> func.get_low_level_il_at(func.start)
<il: push(rbp)>
get_low_level_il_exits_at(addr: int, arch: Architecture | None = None) List[int][source]
Parameters:
Return type:

List[int]

get_low_level_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction][source]

get_low_level_ils_at gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.

Parameters:
  • addr (int) – virtual address of the instruction to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

list(LowLevelILInstruction)

Example:
>>> func = next(bv.functions)
>>> func.get_low_level_ils_at(func.start)
[<il: push(rbp)>]
get_mlil_var_refs(var: Variable) List[ILReferenceSource][source]

get_mlil_var_refs returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag. This function is related to get_hlil_var_refs(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.

Parameters:

var (Variable) – Variable for which to query the xref

Returns:

List of IL References for the given variable

Return type:

list(ILReferenceSource)

Example:
>>> mlil_var = current_mlil[0].operands[0]
>>> current_function.get_mlil_var_refs(mlil_var)
get_mlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource][source]

get_mlil_var_refs_from returns a list of variables referenced by code in the function func, of the architecture arch, and at the address addr. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used. This function is related to get_hlil_var_refs_from(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.

Parameters:
  • addr (int) – virtual address to query for variable references

  • length (int) – optional length of query

  • arch (Architecture) – optional architecture of query

Returns:

list of variable reference sources

Return type:

list(VariableReferenceSource)

get_parameter_at(addr: int, func_type: Type | None, i: int, arch: Architecture | None = None) RegisterValue[source]
Parameters:
Return type:

RegisterValue

get_parameter_at_low_level_il_instruction(instr: InstructionIndex, func_type: Type, i: int) RegisterValue[source]
Parameters:
  • instr (InstructionIndex) –

  • func_type (Type) –

  • i (int) –

Return type:

RegisterValue

get_reg_value_after(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue[source]

get_reg_value_after gets the value instruction address corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the instruction to query

  • reg (str) – string value of native register to query

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

RegisterValue

Example:
>>> current_function.get_reg_value_after(0x400dbe, 'rdi')
<undetermined>
get_reg_value_at(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue[source]

get_reg_value_at gets the value the provided string register address corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the instruction to query

  • reg (str) – string value of native register to query

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

RegisterValue

Example:
>>> current_function.get_reg_value_at(0x400dbe, 'rdi')
<const 0x2>
get_reg_value_at_exit(reg: RegisterName | ILRegister | RegisterIndex) RegisterValue[source]
Parameters:

reg (RegisterName | ILRegister | RegisterIndex) –

Return type:

RegisterValue

get_regs_read_by(addr: int, arch: Architecture | None = None) List[RegisterName][source]
Parameters:
Return type:

List[RegisterName]

get_regs_written_by(addr: int, arch: Architecture | None = None) List[RegisterName][source]
Parameters:
Return type:

List[RegisterName]

get_stack_contents_after(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue[source]
Parameters:
Return type:

RegisterValue

get_stack_contents_at(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue[source]

get_stack_contents_at returns the RegisterValue for the item on the stack in the current function at the given virtual address addr, stack offset offset and size of size. Optionally specifying the architecture.

Parameters:
  • addr (int) – virtual address of the instruction to query

  • offset (int) – stack offset base of stack

  • size (int) – size of memory to query

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

RegisterValue

Note

Stack base is zero on entry into the function unless the architecture places the return address on the stack as in (x86/x86_64) where the stack base will start at address_size

Example:
>>> current_function.get_stack_contents_at(0x400fad, -16, 4)
<range: 0x8 to 0xffffffff>
Parameters:
Return type:

RegisterValue

get_stack_var_at_frame_offset(offset: int, addr: int, arch: Architecture | None = None) Variable | None[source]
Parameters:
Return type:

Variable | None

get_stack_var_at_frame_offset_after_instruction(offset: int, addr: int, arch: Architecture | None = None) Variable | None[source]
Parameters:
Return type:

Variable | None

get_stack_vars_referenced_by(addr: int, arch: Architecture | None = None) List[StackVariableReference][source]
Parameters:
Return type:

List[StackVariableReference]

get_stack_vars_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[StackVariableReference][source]
Parameters:
Return type:

List[StackVariableReference]

get_switch_recovery(addr: int | HighLevelILInstruction) SwitchRecovery[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

SwitchRecovery

get_tags_at(addr: int, arch: Architecture | None = None, auto: bool | None = None) List[Tag][source]

get_tags gets a list of Tags (but not function tags).

Parameters:
  • addr (int) – Address to get tags from.

  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags

  • arch (Architecture | None) –

Return type:

list((Architecture, int, Tag))

get_tags_in_range(address_range: AddressRange, arch: Architecture | None = None, auto: bool | None = None) List[Tuple[Architecture, int, Tag]][source]

get_address_tags_in_range gets a list of all Tags in the function at a given address. Range is inclusive at the start, exclusive at the end.

Parameters:
  • address_range (AddressRange) – Address range from which to get tags

  • arch (Architecture) – Architecture for the block in which the Tag is located (optional)

  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags

Returns:

A list of (arch, address, Tag) tuples

Return type:

list((Architecture, int, Tag))

get_type_tokens(settings: DisassemblySettings | None = None) List[DisassemblyTextLine][source]
Parameters:

settings (DisassemblySettings | None) –

Return type:

List[DisassemblyTextLine]

get_variable_by_name(name: str) Variable | None[source]

Get a specific variable or None if it doesn’t exist

Parameters:

name (str) –

Return type:

Variable | None

has_guided_source_blocks() bool[source]

has_guided_source_blocks checks if this function has any guided source blocks configured. This indicates whether guided analysis is active for this function.

Return type:

bool

Returns:

True if the function has guided source blocks, False otherwise

is_call_instruction(addr: int, arch: Architecture | None = None) bool[source]
Parameters:
Return type:

bool

is_condition_inverted(addr: int | HighLevelILInstruction) bool[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

bool

is_guided_source_block(arch: Architecture, addr: int) bool[source]

is_guided_source_block checks if the given address is a guided source block.

Parameters:
  • arch (Architecture) – Architecture of the address to check

  • addr (int) – Address to check

Return type:

bool

is_instruction_collapsed(instr: HighLevelILInstruction, discriminator: int = 0) bool[source]

Determine if a given HLIL instruction (with discriminator) is collapsed during rendering. :param instr: Instruction which might be collapsed :param discriminator: Unique discriminator id for the region :return: True if the instruction should be rendered as collapsed

Parameters:
Return type:

bool

is_region_collapsed(hash) bool[source]

Determine if a given region is collapsed during rendering. :param hash: Hash value of region :return: True if the region should be rendered as collapsed

Return type:

bool

is_var_user_defined(var: Variable) bool[source]
Parameters:

var (Variable) –

Return type:

bool

language_representation(language: str) LanguageRepresentationFunction | None[source]
Parameters:

language (str) –

Return type:

LanguageRepresentationFunction | None

language_representation_if_available(language: str) LanguageRepresentationFunction | None[source]
Parameters:

language (str) –

Return type:

LanguageRepresentationFunction | None

mark_caller_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None[source]

mark_caller_updates_required indicates that callers of this function need to be reanalyzed during the next update cycle

Parameters:

update_type (FunctionUpdateType) – (optional) Desired update type

Return type:

None

mark_recent_use() None[source]
Return type:

None

mark_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None[source]

mark_updates_required indicates that this function needs to be reanalyzed during the next update cycle

Parameters:

update_type (FunctionUpdateType) – (optional) Desired update type

Return type:

None

merge_vars(target: Variable, sources: List[Variable] | Variable) None[source]

merge_vars merges one or more variables in sources into the target variable. All variable accesses to the variables in sources will be rewritten to use target.

Parameters:
Return type:

None

query_metadata(key: str) metadata.MetadataValueType[source]

query_metadata retrieves metadata associated with the given key stored in the current function.

Parameters:

key (str) – key to query

Return type:

metadata associated with the key

reanalyze(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None[source]

reanalyze causes this function to be reanalyzed. This function does not wait for the analysis to finish.

Parameters:

update_type (FunctionUpdateType) – (optional) Desired update type

Return type:

None

Warning

If analysis_skipped is True, using this API will not trigger re-analysis. Instead, set analysis_skipped to False.

Return type:

None

Parameters:

update_type (FunctionUpdateType) –

release_advanced_analysis_data() None[source]
Return type:

None

remove_auto_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None[source]

remove_auto_address_tag removes a Tag object at a given address.

Parameters:
  • addr (int) – Address at which to add the tag

  • tag (Tag) – Tag object to be added

  • arch (Architecture) – Architecture for the block in which the Tag is added (optional)

Return type:

None

remove_auto_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]

remove_auto_address_tags_of_type removes all tags at the given address of the given type.

Parameters:
  • addr (int) – Address at which to remove the tags

  • tag_type (Tag) – TagType object to match for removing

  • arch (Architecture) – Architecture for the block in which the Tags is located (optional)

Return type:

None

remove_auto_function_tag(tag: Tag) None[source]

remove_user_function_tag removes a Tag object as a function tag.

Parameters:

tag (Tag) – Tag object to be added

Return type:

None

remove_auto_function_tags_of_type(tag_type: str)[source]

remove_user_function_tags_of_type removes all function Tag objects on a function of a given type

Parameters:

tag_type (TagType) – TagType object to match for removing

Return type:

None

remove_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None[source]

remove_guided_source_blocks removes blocks from the guided source block list for this function. The specified blocks will no longer have their direct outgoing branch targets analyzed. This automatically enables the analysis.guided.enable setting if it is not already enabled.

Parameters:
Return type:

None

remove_metadata(key: str) None[source]

remove_metadata removes the metadata associated with key from the current function.

Parameters:

key (str) – key associated with metadata to remove from the function

Return type:

None

remove_user_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None[source]

remove_user_address_tag removes a Tag object at a given address. Since this removes a user tag, it will be added to the current undo buffer.

Parameters:
  • addr (int) – Address at which to remove the tag

  • tag (Tag) – Tag object to be added

  • arch (Architecture) – Architecture for the block in which the Tag is added (optional)

Return type:

None

remove_user_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]

remove_user_address_tags_of_type removes all tags at the given address of the given type. Since this removes user tags, it will be added to the current undo buffer.

Parameters:
  • addr (int) – Address at which to remove the tag

  • tag_type (Tag) – TagType object to match for removing

  • arch (Architecture) – Architecture for the block in which the Tags is located (optional)

Return type:

None

remove_user_code_ref(from_addr: int, to_addr: int, from_arch: Architecture | None = None) None[source]

remove_user_code_ref removes a user-defined cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • to_addr (int) – virtual address of the xref’s destination.

  • from_arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.remove_user_code_ref(here, 0x400000)
remove_user_function_tag(tag: Tag) None[source]

remove_user_function_tag removes a Tag object as a function tag. Since this removes a user tag, it will be added to the current undo buffer.

Parameters:

tag (Tag) – Tag object to be added

Return type:

None

remove_user_function_tags_of_type(tag_type: str)[source]

remove_user_function_tags_of_type removes all function Tag objects on a function of a given type Since this removes user tags, it will be added to the current undo buffer.

Parameters:

tag_type (TagType) – TagType object to match for removing

Return type:

None

remove_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None[source]

remove_user_type_field_ref removes a user-defined type field cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • offset (int) – offset of the field, relative to the type

  • from_arch (Architecture) – (optional) architecture of the source instruction

  • size (int) – (optional) the size of the access

Return type:

None

Example:
>>> current_function.remove_user_type_field_ref(here, 'A', 0x8)
remove_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None[source]

remove_user_type_ref removes a user-defined type cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • from_arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.remove_user_type_ref(here, 'A')
request_advanced_analysis_data() None[source]
Return type:

None

request_debug_report(name: str) None[source]

request_debug_report can generate internal debug reports for a variety of analysis. Current list of possible values include:

  • mlil_translator

  • stack_adjust_graph

  • high_level_il

Parameters:

name (str) – Name of the debug report

Return type:

None

set_auto_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int], arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_calling_convention(value: CallingConvention) None[source]
Parameters:

value (CallingConvention) –

Return type:

None

set_auto_can_return(value: bool | BoolWithConfidence) None[source]
Parameters:

value (bool | BoolWithConfidence) –

Return type:

None

set_auto_clobbered_regs(value: List[RegisterName | ILRegister | RegisterIndex]) None[source]
Parameters:

value (List[RegisterName | ILRegister | RegisterIndex]) –

Return type:

None

set_auto_has_variable_arguments(value: bool | BoolWithConfidence) None[source]
Parameters:

value (bool | BoolWithConfidence) –

Return type:

None

set_auto_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_inline_during_analysis(value: bool | BoolWithConfidence)[source]
Parameters:

value (bool | BoolWithConfidence) –

set_auto_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]

set_auto_instr_highlight highlights the instruction at the specified address with the supplied color

Warning

Use only in analysis plugins. Do not use in regular plugins, as colors won’t be saved to the database.

Parameters:
set_auto_parameter_vars(value: List[Variable] | Variable | ParameterVariables | None) None[source]
Parameters:

value (List[Variable] | Variable | ParameterVariables | None) –

Return type:

None

set_auto_pure(value: bool | BoolWithConfidence) None[source]
Parameters:

value (bool | BoolWithConfidence) –

Return type:

None

set_auto_reg_stack_adjustments(value: Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence])[source]
Parameters:

value (Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence]) –

set_auto_return_regs(value: RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) None[source]
Parameters:

value (RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) –

Return type:

None

set_auto_return_type(value: str | Type | TypeBuilder) None[source]
Parameters:

value (str | Type | TypeBuilder) –

Return type:

None

set_auto_stack_adjustment(value: int | OffsetWithConfidence) None[source]
Parameters:

value (int | OffsetWithConfidence) –

Return type:

None

set_auto_type(value: str | Type | TypeBuilder) None[source]
Parameters:

value (str | Type | TypeBuilder) –

Return type:

None

set_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int | RegisterStackAdjustmentWithConfidence], arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust: int | RegisterStackAdjustmentWithConfidence, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None)[source]
Parameters:
set_call_type_adjustment(addr: int, adjust_type: str | Type | TypeBuilder | None = None, arch: Architecture | None = None) None[source]

set_call_type_adjustment sets or removes the call type override at a call site to the given type.

Parameters:
  • addr (int) – virtual address of the call instruction to adjust

  • adjust_type (str|Type|TypeBuilder) – (optional) overridden call type, or None to remove an existing adjustment

  • arch (Architecture) – (optional) Architecture of the instruction if different from self.arch

Example:
>>> # Change the current call site to no-return
>>> target = bv.get_function_at(list(filter(lambda ref: ref.address == here, current_function.call_sites))[0].mlil.dest.value.value)
>>> ft = target.type.mutable_copy()
>>> ft.can_return = False
>>> current_function.set_call_type_adjustment(here, ft)
Return type:

None

set_comment_at(addr: int, comment: str) None[source]

set_comment_at sets a comment for the current function at the address specified

Parameters:
  • addr (int) – virtual address within the current function to apply the comment to

  • comment (str) – string comment to apply

Return type:

None

Example:
>>> current_function.set_comment_at(here, "hi")
set_condition_inverted(addr: int | HighLevelILInstruction, invert: bool)[source]
Parameters:
static set_default_session_data(name: str, value) None[source]
Parameters:

name (str) –

Return type:

None

set_early_return(addr: int | HighLevelILInstruction, value: EarlyReturn)[source]
Parameters:
set_expr_folding(addr: int | HighLevelILInstruction, value: ExprFolding)[source]
Parameters:
set_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None[source]

set_guided_source_blocks sets the complete list of guided source blocks for this function. Only blocks in this set will have their direct outgoing branch targets analyzed. This replaces any existing guided source blocks and automatically enables or disables the analysis.guided.enable setting based on whether addresses are provided.

Parameters:
Return type:

None

set_int_display_type(instr_addr: int, value: int, operand: int, display_type: IntegerDisplayType, arch: Architecture | None = None, enum_display_typeid=None) None[source]

Change the text display type for an integer token in the disassembly or IL views

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • display_type (IntegerDisplayType) – Desired display type

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

  • enum_display_typeid (str) – (optional) Whenever passing EnumDisplayType to display_type, passing a type ID here will specify the Enumeration display type. Must be a valid type ID and resolve to an enumeration type.

Return type:

None

set_switch_recovery(addr: int | HighLevelILInstruction, value: SwitchRecovery)[source]
Parameters:
set_user_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_user_inline_during_analysis(value: bool | BoolWithConfidence)[source]
Parameters:

value (bool | BoolWithConfidence) –

set_user_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]

set_user_instr_highlight highlights the instruction at the specified address with the supplied color

Parameters:
Example:
>>> current_function.set_user_instr_highlight(here, HighlightStandardColor.BlueHighlightColor)
>>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0))

Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.

set_user_type(value: str | Type | TypeBuilder) None[source]
Parameters:

value (str | Type | TypeBuilder) –

Return type:

None

set_user_var_value(var: Variable, def_addr: int, value: PossibleValueSet, after: bool = True) None[source]

set_user_var_value allows the user to specify a PossibleValueSet value for an MLIL variable at its definition site.

Warning

Setting the variable value, triggers a reanalysis of the function and allows the dataflow to compute and propagate values which depend on the current variable. This implies that branch conditions whose values can be determined statically will be computed, leading to potential branch elimination at the HLIL layer.

Parameters:
  • var (Variable) – Variable for which the value is to be set

  • def_addr (int) – Address where the variable is set

  • value (PossibleValueSet) – Informed value of the variable

  • after (bool) – Whether the value happens before or after the instruction

Return type:

None

Example:
>>> mlil_var = current_mlil[0].operands[0]
>>> def_address = 0x40108d
>>> var_value = PossibleValueSet.constant(5)
>>> current_function.set_user_var_value(mlil_var, def_address, var_value)
split_var(var: Variable) None[source]

split_var splits a variable at the definition site. The given var must be the variable unique to the definition and should be obtained by using MediumLevelILInstruction.get_split_var_for_definition at the definition site.

This function is not meant to split variables that have been previously merged. Use unmerge_vars to split previously merged variables.

Warning

Binary Ninja automatically splits all variables that the analysis determines to be safely splittable. Splitting a variable manually with split_var can cause IL and decompilation to be incorrect. There are some patterns where variables can be safely split semantically but analysis cannot determine that it is safe. This function is provided to allow variable splitting to be performed in these cases by plugins or by the user.

Parameters:

var (Variable) – variable to split

Return type:

None

store_metadata(key: str, md: Metadata | int | bool | str | bytes | float | List[MetadataValueType] | Tuple[MetadataValueType] | dict, isAuto: bool = False) None[source]

store_metadata stores an object for the given key in the current Function. Objects stored using store_metadata can be retrieved when the database is reopened unless isAuto is set to True.

Parameters:
  • key (str) – key value to associate the Metadata object with

  • md (Varies) – object to store

  • isAuto (bool) – whether the metadata is an auto metadata

Return type:

None

toggle_region(hash)[source]

Toggle the collapsed state of a region during rendering, by hash value :param hash: Hash value of region

unmerge_vars(target: Variable, sources: List[Variable] | Variable) None[source]

unmerge_vars undoes variable merging performed with merge_vars. The variables in sources will no longer be merged into the target variable.

Parameters:
Return type:

None

unsplit_var(var: Variable) None[source]

unsplit_var undoes variable splitting performed with split_var. The given var must be the variable unique to the definition and should be obtained by using MediumLevelILInstruction.get_split_var_for_definition at the definition site.

Parameters:

var (Variable) – variable to unsplit

Return type:

None

property address_ranges: List[AddressRange]

All of the address ranges covered by a function

property analysis_performance_info: Dict[str, int]
property analysis_skip_override: FunctionAnalysisSkipOverride

Override for skipping of automatic analysis

property analysis_skip_reason: AnalysisSkipReason

Function analysis skip reason

property analysis_skipped: bool

Whether automatic analysis was skipped for this function. Can be set to false to re-enable analysis.

property arch: Architecture

Function architecture (read-only)

property auto: bool

Whether function was automatically discovered (read-only) as a result of some creation of a ‘user’ function. ‘user’ functions may or may not have been created by a user through the or API. For instance the entry point into a function is always created a ‘user’ function. ‘user’ functions should be considered the root of auto analysis.

property auto_metadata: Dict[str, metadata.MetadataValueType]

metadata retrieves the metadata associated with the current function.

Return type:

metadata associated with the function

property basic_blocks: BasicBlockList

function.BasicBlockList of BasicBlocks in the current function (read-only)

property call_sites: List[ReferenceSource]

call_sites returns a list of possible call sites contained in this function. This includes ordinary calls, tail calls, and indirect jumps. Not all of the returned call sites are necessarily true call sites; some may simply be unresolved indirect jumps, for example.

Returns:

List of References that represent the sources of possible calls in this function

Return type:

list(ReferenceSource)

property callee_addresses: List[int]

callee_addressses returns a list of start addresses for functions that this function calls. Does not point to the actual address where the call occurs, just the start of the function that contains the reference.

Returns:

List of start address for functions that this function calls

Return type:

list(int)

property callees: List[Function]

callees returns a list of functions that this function calls This does not include the address of those calls, rather just the function objects themselves. Use call_sites to identify the location of these calls.

Returns:

List of Functions that this function calls

Return type:

list(Function)

property caller_sites: Generator[ReferenceSource, None, None]

caller_sites returns a list of ReferenceSource objects corresponding to the addresses in functions which reference this function

Returns:

List of ReferenceSource objects of the call sites to this function

Return type:

list(ReferenceSource)

property callers: List[Function]

callers returns a list of functions that call this function Does not point to the actual address where the call occurs, just the start of the function that contains the call.

Returns:

List of Functions that call this function

Return type:

list(Function)

property calling_convention: CallingConvention | None

Calling convention used by the function

property can_return: BoolWithConfidence

Whether function can return

property clobbered_regs: RegisterSet

Registers that are modified by this function

property comment: str

Gets the comment for the current function

property comments: Dict[int, str]

Dict of comments (read-only)

property components
property core_var_stack_layout: List[CoreVariable]

List of function stack variables (read-only)

property core_vars: List[CoreVariable]

List of CoreVariable objects

property global_pointer_value: RegisterValue

Discovered value of the global pointer register, if the function uses one (read-only)

property has_explicitly_defined_type: bool

Whether function has explicitly defined types (read-only)

property has_unresolved_indirect_branches: bool

Has unresolved indirect branches (read-only)

property has_user_annotations: bool

Whether the function has ever been ‘user’ modified

property has_user_type: bool

True if the function has a user-defined type

property has_variable_arguments: BoolWithConfidence

Whether the function takes a variable number of arguments

property high_level_il: HighLevelILFunction | None

returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property highest_address: int

The highest (largest) virtual address contained in a function.

property hlil: HighLevelILFunction | None

returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property hlil_if_available: HighLevelILFunction | None

returns HighLevelILFunction used to represent high level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if high level IL is available without generating it.

property indirect_branches: List[IndirectBranchInfo]

List of indirect branches (read-only)

property inline_during_analysis: BoolWithConfidence

Whether the function’s IL should be inlined into all callers’ IL

property instructions: Generator[Tuple[List[InstructionTextToken], int], None, None]

A generator of instruction tokens and their start addresses for the current function

property is_collapsed

If the entire function is collapsed during rendering.

property is_pure: BoolWithConfidence

Whether function is pure

property is_thunk: bool

Returns True if the function starts with a Tailcall (read-only)

property lifted_il: LowLevelILFunction | None

returns LowLevelILFunction used to represent lifted IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes lifted IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property lifted_il_if_available: LowLevelILFunction | None

returns LowLevelILFunction used to represent lifted IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if lifted IL is available without generating it.

property llil: LowLevelILFunction | None

returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property llil_basic_blocks: Generator[LowLevelILBasicBlock, None, None]

A generator of all LowLevelILBasicBlock objects in the current function

property llil_if_available: LowLevelILFunction | None

returns LowLevelILFunction used to represent low level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if low level IL is available without generating it.

property low_level_il: LowLevelILFunction | None

returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property lowest_address: int

The lowest (smallest) virtual address contained in a function.

property mapped_medium_level_il: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property medium_level_il: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property merged_vars: Dict[Variable, List[Variable]]

Map of merged variables, organized by target variable (read-only). Use merge_vars and unmerge_vars to update merged variables.

property metadata: Dict[str, metadata.MetadataValueType]

metadata retrieves the metadata associated with the current function.

Return type:

metadata associated with the function

property mlil: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property mlil_basic_blocks: Generator[MediumLevelILBasicBlock, None, None]

A generator of all MediumLevelILBasicBlock objects in the current function

property mlil_if_available: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent medium level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if medium level IL is available without generating it.

property mmlil: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property mmlil_if_available: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent mapped medium level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if mapped medium level IL is available without generating it.

property name: str

Symbol name for the function

property needs_update: bool

Whether the function has analysis that needs to be updated (read-only)

property parameter_vars: ParameterVariables

List of variables for the incoming function parameters

property platform: Platform | None

Function platform (read-only)

property provenance

provenance returns a string representing the provenance. This portion of the API is under development. Currently the provenance information is undocumented, not persistent, and not saved to a database.

Returns:

string representation of the provenance

Return type:

str

property pseudo_c: LanguageRepresentationFunction | None
property pseudo_c_if_available: LanguageRepresentationFunction | None
property reg_stack_adjustments: Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]

Number of entries removed from each register stack after return

property return_regs: RegisterSet

Registers that are used for the return value

property return_type: Type | None

Return type of the function

property session_data: Any

Dictionary object where plugins can store arbitrary data associated with the function

property split_vars: List[Variable]

Set of variables that have been split with split_var. These variables correspond to those unique to each definition site and are obtained by using MediumLevelILInstruction.get_split_var_for_definition at the definitions.

property stack_adjustment: OffsetWithConfidence

Number of bytes removed from the stack after return

property stack_layout: List[Variable]

List of function stack variables (read-only)

property start: int

Function start address (read-only)

property symbol: CoreSymbol

Function symbol(read-only)

property tags: TagList

tags gets a TagList of all Tags in the function (but not “function tags”). Tags are returned as an iterable indexable object TagList of (arch, address, Tag) tuples.

Return type:

TagList((Architecture, int, Tag))

property too_large: bool

Whether the function is too large to automatically perform analysis (read-only)

property total_bytes: int

Total bytes of a function calculated by summing each basic_block. Because basic blocks can overlap and have gaps between them this may or may not be equivalent to a .size property.

property type: FunctionType

Function type object, can be set with either a string representing the function prototype (str(function) shows examples) or a Type object

property type_tokens: List[InstructionTextToken]

Text tokens for this function’s prototype

property unresolved_indirect_branches: List[Tuple[Architecture, int]]

List of unresolved indirect branches (read-only)

property unresolved_stack_adjustment_graph: CoreFlowGraph | None

Flow graph of unresolved stack adjustments (read-only)

property uses_incoming_global_pointer: bool

Whether the function uses the incoming global pointer value

property vars: List[Variable]

List of function variables (read-only)

property view: BinaryView

Function view (read-only)

property workflow
class FunctionViewType[source]

Bases: object

FunctionViewType(view_type: Union[ForwardRef(‘FunctionViewType’), binaryninja.enums.FunctionGraphType, str])

__init__(view_type: FunctionViewType | FunctionGraphType | str)[source]
Parameters:

view_type (FunctionViewType | FunctionGraphType | str) –

name: str | None
view_type: FunctionGraphType
class HighLevelILBasicBlockList[source]

Bases: BasicBlockList

class ILReferenceSource[source]

Bases: object

ILReferenceSource(func: Optional[ForwardRef(‘Function’)], arch: Optional[ForwardRef(‘architecture.Architecture’)], address: int, il_type: binaryninja.enums.FunctionGraphType, expr_id: int)

__init__(func: Function | None, arch: Architecture | None, address: int, il_type: FunctionGraphType, expr_id: int) None
Parameters:
Return type:

None

static get_il_name(il_type: FunctionGraphType) str[source]
Parameters:

il_type (FunctionGraphType) –

Return type:

str

address: int
arch: Architecture | None
expr_id: int
func: Function | None
il_type: FunctionGraphType
class LowLevelILBasicBlockList[source]

Bases: BasicBlockList

class MediumLevelILBasicBlockList[source]

Bases: BasicBlockList

class TagList[source]

Bases: object

__init__(function: Function)[source]
Parameters:

function (Function) –

class VariableReferenceSource[source]

Bases: object

VariableReferenceSource(var: ‘variable.Variable’, src: binaryninja.function.ILReferenceSource)

__init__(var: Variable, src: ILReferenceSource) None
Parameters:
Return type:

None

src: ILReferenceSource
var: Variable

AdvancedFunctionAnalysisDataRequestor

class AdvancedFunctionAnalysisDataRequestor[source]

Bases: object

__init__(func: Function | None = None)[source]
Parameters:

func (Function | None) –

close() None[source]
Return type:

None

property function: Function | None

ArchAndAddr

class ArchAndAddr[source]

Bases: object

ArchAndAddr(arch: ‘architecture.Architecture’, addr: int)

__init__(arch: Architecture, addr: int) None
Parameters:
Return type:

None

addr: int
arch: Architecture

BasicBlockList

class BasicBlockList[source]

Bases: object

__init__(function: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction)[source]
Parameters:

function (Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction) –

DisassemblySettings

class DisassemblySettings[source]

Bases: object

__init__(handle: LP_BNDisassemblySettings | None = None)[source]
Parameters:

handle (LP_BNDisassemblySettings | None) –

static default_graph_settings() DisassemblySettings[source]
Return type:

DisassemblySettings

static default_linear_settings() DisassemblySettings[source]
Return type:

DisassemblySettings

static default_settings() DisassemblySettings[source]
Return type:

DisassemblySettings

is_option_set(option: DisassemblyOption) bool[source]
Parameters:

option (DisassemblyOption) –

Return type:

bool

set_option(option: DisassemblyOption, state: bool = True) None[source]
Parameters:
Return type:

None

property max_symbol_width: int
property width: int

DisassemblyTextLine

class DisassemblyTextLine[source]

Bases: object

DisassemblyTextLine(tokens: List[ForwardRef(‘InstructionTextToken’)], address: Optional[int] = None, il_instr: Union[ForwardRef(‘lowlevelil.LowLevelILInstruction’), ForwardRef(‘mediumlevelil.MediumLevelILInstruction’), ForwardRef(‘highlevelil.HighLevelILInstruction’), NoneType] = None, color: Union[ForwardRef(‘_highlight.HighlightColor’), binaryninja.enums.HighlightStandardColor, NoneType] = None, tags: Optional[List[ForwardRef(‘binaryview.Tag’)]] = None, type_info: Optional[binaryninja.function.DisassemblyTextLineTypeInfo] = None)

__init__(tokens: List[InstructionTextToken], address: int | None = None, il_instr: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None = None, color: HighlightColor | HighlightStandardColor | None = None, tags: List[Tag] | None = None, type_info: DisassemblyTextLineTypeInfo | None = None)[source]
Parameters:
address: int | None
property address_and_indentation_tokens
property address_and_indentation_width
highlight: HighlightColor
il_instruction: LowLevelILInstruction | MediumLevelILInstruction | HighLevelILInstruction | None
tags: List[Tag]
tokens: List[InstructionTextToken]
property total_width
type_info: DisassemblyTextLineTypeInfo | None

DisassemblyTextLineTypeInfo

class DisassemblyTextLineTypeInfo[source]

Bases: object

DisassemblyTextLineTypeInfo(parent_type: Optional[ForwardRef(‘types.Type’)], field_index: int, offset: int)

__init__(parent_type: Type | None, field_index: int, offset: int) None
Parameters:
  • parent_type (Type | None) –

  • field_index (int) –

  • offset (int) –

Return type:

None

field_index: int
offset: int
parent_type: Type | None

DisassemblyTextRenderer

class DisassemblyTextRenderer[source]

Bases: object

__init__(func: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None = None, settings: DisassemblySettings | None = None, handle: BNDisassemblySettings | None = None)[source]
Parameters:
add_integer_token(tokens: List[InstructionTextToken], int_token: InstructionTextToken, addr: int, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

add_stack_var_reference_tokens(tokens: List[InstructionTextToken], ref: StackVariableReference) None[source]
Parameters:
Return type:

None

add_symbol_token(tokens: List[InstructionTextToken], addr: int, size: int, operand: int | None = None) bool[source]
Parameters:
Return type:

bool

get_disassembly_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None][source]
Parameters:

addr (int) –

Return type:

Generator[Tuple[DisassemblyTextLine | None, int], None, None]

get_instruction_annotations(addr: int) List[InstructionTextToken][source]
Parameters:

addr (int) –

Return type:

List[InstructionTextToken]

get_instruction_text(addr: int) Generator[Tuple[DisassemblyTextLine | None, int], None, None][source]
Parameters:

addr (int) –

Return type:

Generator[Tuple[DisassemblyTextLine | None, int], None, None]

static is_integer_token(token: InstructionTextToken) bool[source]
Parameters:

token (InstructionTextToken) –

Return type:

bool

post_process_lines(addr: int, length: int, in_lines: str | List[str] | List[DisassemblyTextLine], indent_spaces: str = '')[source]
Parameters:
reset_deduplicated_comments() None[source]
Return type:

None

wrap_comment(lines: List[DisassemblyTextLine], cur_line: DisassemblyTextLine, comment: str, has_auto_annotations: bool, leading_spaces: str = '  ', indent_spaces: str = '') None[source]
Parameters:
Return type:

None

property arch: Architecture
property basic_block: BasicBlock | None
property function: Function
property has_data_flow: bool
property il: bool
property il_function: LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction | None
property settings: DisassemblySettings

Function

class Function[source]

Bases: object

__init__(view: BinaryView | None = None, handle: LP_BNFunction | None = None)[source]
Parameters:
  • view (BinaryView | None) –

  • handle (LP_BNFunction | None) –

add_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None[source]

add_guided_source_blocks adds blocks to the guided source block list for this function. The specified blocks will have their direct outgoing branch targets analyzed. This automatically enables the analysis.guided.enable setting if it is not already enabled.

Parameters:
Return type:

None

add_tag(tag_type: str, data: str, addr: int | None = None, auto: bool = False, arch: Architecture | None = None)[source]

add_tag creates and adds a Tag object on either a function, or on an address inside of a function.

“Function tags” appear at the top of a function and are a good way to label an entire function with some information. If you include an address when you call Function.add_tag, you’ll create an “address tag”. These are good for labeling specific instructions.

For tagging arbitrary data, consider add_tag.

Parameters:
  • tag_type (str) – The name of the tag type for this Tag

  • data (str) – additional data for the Tag

  • addr (int) – address at which to add the tag

  • auto (bool) – Whether or not an auto tag

  • arch (Architecture) – Architecture for the block in which the Tag is added (optional)

Example:
>>> current_function.add_tag("Important", "I think this is the main function")
>>> current_function.add_tag("Crashes", "Nullpointer dereference", here)

Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.

add_user_code_ref(from_addr: int, to_addr: int, arch: Architecture | None = None) None[source]

add_user_code_ref places a user-defined cross-reference from the instruction at the given address and architecture to the specified target address. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, use remove_user_code_ref.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • to_addr (int) – virtual address of the xref’s destination.

  • arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.add_user_code_ref(here, 0x400000)
add_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None[source]

add_user_type_field_ref places a user-defined type field cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, use remove_user_type_field_ref.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • offset (int) – offset of the field, relative to the type

  • from_arch (Architecture) – (optional) architecture of the source instruction

  • size (int) – (optional) the size of the access

Return type:

None

Example:
>>> current_function.add_user_type_field_ref(here, 'A', 0x8)
add_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None[source]

add_user_type_ref places a user-defined type cross-reference from the instruction at the given address and architecture to the specified type. If the specified source instruction is not contained within this function, no action is performed. To remove the reference, use remove_user_type_ref.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • from_arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.add_user_code_ref(here, 'A')
analyze() None[source]

analyze causes this function to be analyzed if it’s out of date. This function does not wait for the analysis to finish.

Return type:

None

apply_auto_discovered_type(func_type: str | Type | TypeBuilder) None[source]
Parameters:

func_type (str | Type | TypeBuilder) –

Return type:

None

apply_imported_types(sym: CoreSymbol, type: str | Type | TypeBuilder | None = None) None[source]
Parameters:
Return type:

None

check_for_debug_report(name: str) bool[source]

check_for_debug_report checks if a function has had a debug report requested with the given name, and then, if one has been requested, clears the request internally so that future calls to this function for that report will return False.

If a function has had a debug report requested, it is the caller of this function’s responsibility to actually generate and show the debug report. You can use binaryninja.interaction.show_report_collection for showing a debug report from a workflow activity.

Parameters:

name (str) – Name of the debug report

Returns:

True if the report has been requested (and not checked for yet)

Return type:

bool

clear_all_user_var_values() None[source]

Clear all user defined variable values.

Return type:

None

clear_forced_var_version(var: Variable, def_addr: int) None[source]
Parameters:
Return type:

None

clear_user_var_value(var: Variable, def_addr: int, after: bool = True) None[source]

Clears a previously defined user variable value.

Parameters:
  • var (Variable) – Variable for which the value was informed

  • def_addr (int) – Address of the definition site of the variable

  • after (bool) –

Return type:

None

collapse_region(hash)[source]

Collapse a region during rendering :param hash: Hash value of region

create_auto_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None[source]
Parameters:
Return type:

None

create_auto_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None[source]
Parameters:
Return type:

None

create_forced_var_version(var: Variable, def_addr: int) None[source]
Parameters:
Return type:

None

create_graph(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph[source]

Create a flow graph with the disassembly of this function.

Note

This graph waits for function analysis, so Workflow Activities should instead use create_graph_immediate to create graphs with the function contents as-is.

Parameters:
Returns:

Flow graph object

Return type:

CoreFlowGraph

create_graph_immediate(graph_type: FunctionViewType | FunctionGraphType | str = FunctionGraphType.NormalFunctionGraph, settings: DisassemblySettings | None = None) CoreFlowGraph[source]

Create a flow graph with the disassembly of this function, specifically using the instructions as they are in the function when this is called. You probably want to use this if you are creating a Debug Report in a Workflow Activity.

Parameters:
Returns:

Flow graph object

Return type:

CoreFlowGraph

create_user_stack_var(offset: int, var_type: str | Type | TypeBuilder, name: str) None[source]
Parameters:
Return type:

None

create_user_var(var: Variable, var_type: str | Type | TypeBuilder, name: str, ignore_disjoint_uses: bool = False) None[source]
Parameters:
Return type:

None

delete_auto_stack_var(offset: int) None[source]
Parameters:

offset (int) –

Return type:

None

delete_user_stack_var(offset: int) None[source]
Parameters:

offset (int) –

Return type:

None

delete_user_var(var: Variable) None[source]
Parameters:

var (Variable) –

Return type:

None

expand_all()[source]

Expand all regions in the function

expand_region(hash)[source]

Un-collapse a region during rendering :param hash: Hash value of region

get_all_user_var_values() Dict[Variable, Dict[ArchAndAddr, PossibleValueSet]][source]

Returns a map of current defined user variable values.

Returns:

Map of user current defined user variable values and their definition sites.

Type:

dict of (Variable, dict of (ArchAndAddr, PossibleValueSet))

Return type:

Dict[Variable, Dict[ArchAndAddr, PossibleValueSet]]

get_basic_block_at(addr: int, arch: Architecture | None = None) BasicBlock | None[source]

get_basic_block_at returns the BasicBlock of the optionally specified Architecture arch at the given address addr.

Parameters:
  • addr (int) – Address of the BasicBlock to retrieve.

  • arch (Architecture) – (optional) Architecture of the basic block if different from the Function’s self.arch

Example:
>>> current_function.get_basic_block_at(current_function.start)
<block: x86_64@0x100000f30-0x100000f50>
Return type:

BasicBlock | None

get_block_annotations(addr: int, arch: Architecture | None = None) List[List[InstructionTextToken]][source]
Parameters:
Return type:

List[List[InstructionTextToken]]

get_call_reg_stack_adjustment(addr: int, arch: Architecture | None = None) Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence][source]
Parameters:
Return type:

Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]

get_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, arch: Architecture | None = None) RegisterStackAdjustmentWithConfidence[source]
Parameters:
Return type:

RegisterStackAdjustmentWithConfidence

get_call_stack_adjustment(addr: int, arch: Architecture | None = None) OffsetWithConfidence[source]
Parameters:
Return type:

OffsetWithConfidence

get_call_type_adjustment(addr: int, arch: Architecture | None = None) Type | None[source]
Parameters:
Return type:

Type | None

get_callee_for_analysis(platform: Platform, addr: int, exact: bool = False) Function | None[source]

get_callee_for_analysis retrieves the callee function for the specified address and platform.

Note

This method is intended for use by architecture plugins only.

Parameters:
  • platform (Platform) – Platform of the callee function

  • addr (int) – Address of the callee function

  • exact (bool) – If True, only return a function if it exactly matches the address and platform

Returns:

The callee function or None if not found

Return type:

Optional[Function]

get_comment_at(addr: int) str[source]
Parameters:

addr (int) –

Return type:

str

get_constant_data(state: RegisterValueType, value: int, size: int = 0) DataBuffer[source]
Parameters:
Return type:

DataBuffer

get_constant_data_and_builtin(state: RegisterValueType, value: int, size: int = 0) Tuple[DataBuffer, BuiltinType][source]
Parameters:
Return type:

Tuple[DataBuffer, BuiltinType]

get_constants_referenced_by(addr: int, arch: Architecture | None = None) List[ConstantReference][source]
Parameters:
Return type:

List[ConstantReference]

get_constants_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[ConstantReference][source]
Parameters:
Return type:

List[ConstantReference]

get_early_return(addr: int | HighLevelILInstruction) EarlyReturn[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

EarlyReturn

get_expr_folding(addr: int | HighLevelILInstruction) ExprFolding[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

ExprFolding

get_flags_read_by_lifted_il_instruction(i: InstructionIndex) List[FlagName][source]
Parameters:

i (InstructionIndex) –

Return type:

List[FlagName]

get_flags_written_by_lifted_il_instruction(i: InstructionIndex) List[FlagName][source]
Parameters:

i (InstructionIndex) –

Return type:

List[FlagName]

get_function_tags(auto: bool | None = None, tag_type: str | None = None) List[Tag][source]

get_function_tags gets a list of function Tags for the function.

Parameters:
  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags

  • tag_type (str) – If None, gets all tags, otherwise only gets tags of the given type

Return type:

list(Tag)

get_guided_source_blocks() List[Tuple[Architecture, int]][source]

get_guided_source_blocks returns the current list of guided source blocks for this function. These blocks have their direct outgoing branch targets analyzed.

Return type:

List[Tuple[Architecture, int]]

Returns:

List of (architecture, address) tuples representing current guided source blocks

get_hlil_var_refs(var: Variable) List[ILReferenceSource][source]

get_hlil_var_refs returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag.

Parameters:

var (Variable) – Variable for which to query the xref

Returns:

List of IL References for the given variable

Return type:

list(ILReferenceSource)

Example:
>>> mlil_var = current_hlil[0].operands[0]
>>> current_function.get_hlil_var_refs(mlil_var)
get_hlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource][source]

get_hlil_var_refs_from returns a list of variables referenced by code in the function func, of the architecture arch, and at the address addr. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used.

Parameters:
  • addr (int) – virtual address to query for variable references

  • length (int) – optional length of query

  • arch (Architecture) – optional architecture of query

Returns:

list of variables reference sources

Return type:

list(VariableReferenceSource)

get_indirect_branches_at(addr: int, arch: Architecture | None = None) List[IndirectBranchInfo][source]
Parameters:
Return type:

List[IndirectBranchInfo]

get_instr_highlight(addr: int, arch: Architecture | None = None) HighlightColor[source]
Example:
>>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0))
>>> current_function.get_instr_highlight(here)
<color: #ff00ff>
Parameters:
Return type:

HighlightColor

get_instruction_containing_address(addr: int, arch: Architecture | None = None) int | None[source]
Parameters:
Return type:

int | None

get_int_display_type(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) IntegerDisplayType[source]

Get the current text display type for an integer token in the disassembly or IL views

See also see get_int_display_type_and_typeid

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

Return type:

IntegerDisplayType

get_int_display_type_and_typeid(instr_addr: int, value: int, operand: int, arch: ~binaryninja.architecture.Architecture | None = None) -> (<enum 'IntegerDisplayType'>, <class 'str'>)[source]

Get the current text display type for an integer token in the disassembly or IL views

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

Return type:

(<enum ‘IntegerDisplayType’>, <class ‘str’>)

get_int_enum_display_typeid(instr_addr: int, value: int, operand: int, arch: Architecture | None = None) str[source]

Get the current text display enum type for an integer token in the disassembly or IL views.

See also see get_int_display_type_and_typeid

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

Returns:

TypeID for the integer token

Return type:

str

get_lifted_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None[source]
Parameters:
Return type:

LowLevelILInstruction | None

get_lifted_il_flag_definitions_for_use(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[InstructionIndex][source]
Parameters:
  • i (InstructionIndex) –

  • flag (FlagName | ILFlag | FlagIndex) –

Return type:

List[InstructionIndex]

get_lifted_il_flag_uses_for_definition(i: InstructionIndex, flag: FlagName | ILFlag | FlagIndex) List[LowLevelILInstruction][source]
Parameters:
  • i (InstructionIndex) –

  • flag (FlagName | ILFlag | FlagIndex) –

Return type:

List[LowLevelILInstruction]

get_lifted_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction][source]

get_lifted_ils_at gets the Lifted IL Instruction(s) corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the function to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

list(LowLevelILInstruction)

Example:
>>> func = next(bv.functions)
>>> func.get_lifted_ils_at(func.start)
[<il: push(rbp)>]
get_llil_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None[source]

get_llil_at gets the LowLevelILInstruction corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the instruction to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

LowLevelILInstruction

Example:
>>> func = next(bv.functions)
>>> func.get_llil_at(func.start)
<il: push(rbp)>
get_llils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction][source]

get_llils_at gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.

Parameters:
  • addr (int) – virtual address of the instruction to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

list(LowLevelILInstruction)

Example:
>>> func = next(bv.functions)
>>> func.get_llils_at(func.start)
[<il: push(rbp)>]
get_low_level_il_at(addr: int, arch: Architecture | None = None) LowLevelILInstruction | None[source]

get_low_level_il_at gets the LowLevelILInstruction corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the function to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

LowLevelILInstruction

Example:
>>> func = next(bv.functions)
>>> func.get_low_level_il_at(func.start)
<il: push(rbp)>
get_low_level_il_exits_at(addr: int, arch: Architecture | None = None) List[int][source]
Parameters:
Return type:

List[int]

get_low_level_ils_at(addr: int, arch: Architecture | None = None) List[LowLevelILInstruction][source]

get_low_level_ils_at gets the LowLevelILInstruction(s) corresponding to the given virtual address See the developer docs for more information.

Parameters:
  • addr (int) – virtual address of the instruction to be queried

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

list(LowLevelILInstruction)

Example:
>>> func = next(bv.functions)
>>> func.get_low_level_ils_at(func.start)
[<il: push(rbp)>]
get_mlil_var_refs(var: Variable) List[ILReferenceSource][source]

get_mlil_var_refs returns a list of ILReferenceSource objects (IL xrefs or cross-references) that reference the given variable. The variable is a local variable that can be either on the stack, in a register, or in a flag. This function is related to get_hlil_var_refs(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.

Parameters:

var (Variable) – Variable for which to query the xref

Returns:

List of IL References for the given variable

Return type:

list(ILReferenceSource)

Example:
>>> mlil_var = current_mlil[0].operands[0]
>>> current_function.get_mlil_var_refs(mlil_var)
get_mlil_var_refs_from(addr: int, length: int | None = None, arch: Architecture | None = None) List[VariableReferenceSource][source]

get_mlil_var_refs_from returns a list of variables referenced by code in the function func, of the architecture arch, and at the address addr. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used. This function is related to get_hlil_var_refs_from(), which returns variable references collected from HLIL. The two can be different in several cases, e.g., multiple variables in MLIL can be merged into a single variable in HLIL.

Parameters:
  • addr (int) – virtual address to query for variable references

  • length (int) – optional length of query

  • arch (Architecture) – optional architecture of query

Returns:

list of variable reference sources

Return type:

list(VariableReferenceSource)

get_parameter_at(addr: int, func_type: Type | None, i: int, arch: Architecture | None = None) RegisterValue[source]
Parameters:
Return type:

RegisterValue

get_parameter_at_low_level_il_instruction(instr: InstructionIndex, func_type: Type, i: int) RegisterValue[source]
Parameters:
  • instr (InstructionIndex) –

  • func_type (Type) –

  • i (int) –

Return type:

RegisterValue

get_reg_value_after(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue[source]

get_reg_value_after gets the value instruction address corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the instruction to query

  • reg (str) – string value of native register to query

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

RegisterValue

Example:
>>> current_function.get_reg_value_after(0x400dbe, 'rdi')
<undetermined>
get_reg_value_at(addr: int, reg: RegisterName | ILRegister | RegisterIndex, arch: Architecture | None = None) RegisterValue[source]

get_reg_value_at gets the value the provided string register address corresponding to the given virtual address

Parameters:
  • addr (int) – virtual address of the instruction to query

  • reg (str) – string value of native register to query

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

RegisterValue

Example:
>>> current_function.get_reg_value_at(0x400dbe, 'rdi')
<const 0x2>
get_reg_value_at_exit(reg: RegisterName | ILRegister | RegisterIndex) RegisterValue[source]
Parameters:

reg (RegisterName | ILRegister | RegisterIndex) –

Return type:

RegisterValue

get_regs_read_by(addr: int, arch: Architecture | None = None) List[RegisterName][source]
Parameters:
Return type:

List[RegisterName]

get_regs_written_by(addr: int, arch: Architecture | None = None) List[RegisterName][source]
Parameters:
Return type:

List[RegisterName]

get_stack_contents_after(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue[source]
Parameters:
Return type:

RegisterValue

get_stack_contents_at(addr: int, offset: int, size: int, arch: Architecture | None = None) RegisterValue[source]

get_stack_contents_at returns the RegisterValue for the item on the stack in the current function at the given virtual address addr, stack offset offset and size of size. Optionally specifying the architecture.

Parameters:
  • addr (int) – virtual address of the instruction to query

  • offset (int) – stack offset base of stack

  • size (int) – size of memory to query

  • arch (Architecture) – (optional) Architecture for the given function

Return type:

RegisterValue

Note

Stack base is zero on entry into the function unless the architecture places the return address on the stack as in (x86/x86_64) where the stack base will start at address_size

Example:
>>> current_function.get_stack_contents_at(0x400fad, -16, 4)
<range: 0x8 to 0xffffffff>
Parameters:
Return type:

RegisterValue

get_stack_var_at_frame_offset(offset: int, addr: int, arch: Architecture | None = None) Variable | None[source]
Parameters:
Return type:

Variable | None

get_stack_var_at_frame_offset_after_instruction(offset: int, addr: int, arch: Architecture | None = None) Variable | None[source]
Parameters:
Return type:

Variable | None

get_stack_vars_referenced_by(addr: int, arch: Architecture | None = None) List[StackVariableReference][source]
Parameters:
Return type:

List[StackVariableReference]

get_stack_vars_referenced_by_address_if_available(addr: int, arch: Architecture | None = None) List[StackVariableReference][source]
Parameters:
Return type:

List[StackVariableReference]

get_switch_recovery(addr: int | HighLevelILInstruction) SwitchRecovery[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

SwitchRecovery

get_tags_at(addr: int, arch: Architecture | None = None, auto: bool | None = None) List[Tag][source]

get_tags gets a list of Tags (but not function tags).

Parameters:
  • addr (int) – Address to get tags from.

  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags

  • arch (Architecture | None) –

Return type:

list((Architecture, int, Tag))

get_tags_in_range(address_range: AddressRange, arch: Architecture | None = None, auto: bool | None = None) List[Tuple[Architecture, int, Tag]][source]

get_address_tags_in_range gets a list of all Tags in the function at a given address. Range is inclusive at the start, exclusive at the end.

Parameters:
  • address_range (AddressRange) – Address range from which to get tags

  • arch (Architecture) – Architecture for the block in which the Tag is located (optional)

  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags

Returns:

A list of (arch, address, Tag) tuples

Return type:

list((Architecture, int, Tag))

get_type_tokens(settings: DisassemblySettings | None = None) List[DisassemblyTextLine][source]
Parameters:

settings (DisassemblySettings | None) –

Return type:

List[DisassemblyTextLine]

get_variable_by_name(name: str) Variable | None[source]

Get a specific variable or None if it doesn’t exist

Parameters:

name (str) –

Return type:

Variable | None

has_guided_source_blocks() bool[source]

has_guided_source_blocks checks if this function has any guided source blocks configured. This indicates whether guided analysis is active for this function.

Return type:

bool

Returns:

True if the function has guided source blocks, False otherwise

is_call_instruction(addr: int, arch: Architecture | None = None) bool[source]
Parameters:
Return type:

bool

is_condition_inverted(addr: int | HighLevelILInstruction) bool[source]
Parameters:

addr (int | HighLevelILInstruction) –

Return type:

bool

is_guided_source_block(arch: Architecture, addr: int) bool[source]

is_guided_source_block checks if the given address is a guided source block.

Parameters:
  • arch (Architecture) – Architecture of the address to check

  • addr (int) – Address to check

Return type:

bool

is_instruction_collapsed(instr: HighLevelILInstruction, discriminator: int = 0) bool[source]

Determine if a given HLIL instruction (with discriminator) is collapsed during rendering. :param instr: Instruction which might be collapsed :param discriminator: Unique discriminator id for the region :return: True if the instruction should be rendered as collapsed

Parameters:
Return type:

bool

is_region_collapsed(hash) bool[source]

Determine if a given region is collapsed during rendering. :param hash: Hash value of region :return: True if the region should be rendered as collapsed

Return type:

bool

is_var_user_defined(var: Variable) bool[source]
Parameters:

var (Variable) –

Return type:

bool

language_representation(language: str) LanguageRepresentationFunction | None[source]
Parameters:

language (str) –

Return type:

LanguageRepresentationFunction | None

language_representation_if_available(language: str) LanguageRepresentationFunction | None[source]
Parameters:

language (str) –

Return type:

LanguageRepresentationFunction | None

mark_caller_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None[source]

mark_caller_updates_required indicates that callers of this function need to be reanalyzed during the next update cycle

Parameters:

update_type (FunctionUpdateType) – (optional) Desired update type

Return type:

None

mark_recent_use() None[source]
Return type:

None

mark_updates_required(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None[source]

mark_updates_required indicates that this function needs to be reanalyzed during the next update cycle

Parameters:

update_type (FunctionUpdateType) – (optional) Desired update type

Return type:

None

merge_vars(target: Variable, sources: List[Variable] | Variable) None[source]

merge_vars merges one or more variables in sources into the target variable. All variable accesses to the variables in sources will be rewritten to use target.

Parameters:
Return type:

None

query_metadata(key: str) metadata.MetadataValueType[source]

query_metadata retrieves metadata associated with the given key stored in the current function.

Parameters:

key (str) – key to query

Return type:

metadata associated with the key

reanalyze(update_type: FunctionUpdateType = FunctionUpdateType.UserFunctionUpdate) None[source]

reanalyze causes this function to be reanalyzed. This function does not wait for the analysis to finish.

Parameters:

update_type (FunctionUpdateType) – (optional) Desired update type

Return type:

None

Warning

If analysis_skipped is True, using this API will not trigger re-analysis. Instead, set analysis_skipped to False.

Return type:

None

Parameters:

update_type (FunctionUpdateType) –

release_advanced_analysis_data() None[source]
Return type:

None

remove_auto_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None[source]

remove_auto_address_tag removes a Tag object at a given address.

Parameters:
  • addr (int) – Address at which to add the tag

  • tag (Tag) – Tag object to be added

  • arch (Architecture) – Architecture for the block in which the Tag is added (optional)

Return type:

None

remove_auto_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]

remove_auto_address_tags_of_type removes all tags at the given address of the given type.

Parameters:
  • addr (int) – Address at which to remove the tags

  • tag_type (Tag) – TagType object to match for removing

  • arch (Architecture) – Architecture for the block in which the Tags is located (optional)

Return type:

None

remove_auto_function_tag(tag: Tag) None[source]

remove_user_function_tag removes a Tag object as a function tag.

Parameters:

tag (Tag) – Tag object to be added

Return type:

None

remove_auto_function_tags_of_type(tag_type: str)[source]

remove_user_function_tags_of_type removes all function Tag objects on a function of a given type

Parameters:

tag_type (TagType) – TagType object to match for removing

Return type:

None

remove_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None[source]

remove_guided_source_blocks removes blocks from the guided source block list for this function. The specified blocks will no longer have their direct outgoing branch targets analyzed. This automatically enables the analysis.guided.enable setting if it is not already enabled.

Parameters:
Return type:

None

remove_metadata(key: str) None[source]

remove_metadata removes the metadata associated with key from the current function.

Parameters:

key (str) – key associated with metadata to remove from the function

Return type:

None

remove_user_address_tag(addr: int, tag: Tag, arch: Architecture | None = None) None[source]

remove_user_address_tag removes a Tag object at a given address. Since this removes a user tag, it will be added to the current undo buffer.

Parameters:
  • addr (int) – Address at which to remove the tag

  • tag (Tag) – Tag object to be added

  • arch (Architecture) – Architecture for the block in which the Tag is added (optional)

Return type:

None

remove_user_address_tags_of_type(addr: int, tag_type: str, arch=None)[source]

remove_user_address_tags_of_type removes all tags at the given address of the given type. Since this removes user tags, it will be added to the current undo buffer.

Parameters:
  • addr (int) – Address at which to remove the tag

  • tag_type (Tag) – TagType object to match for removing

  • arch (Architecture) – Architecture for the block in which the Tags is located (optional)

Return type:

None

remove_user_code_ref(from_addr: int, to_addr: int, from_arch: Architecture | None = None) None[source]

remove_user_code_ref removes a user-defined cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • to_addr (int) – virtual address of the xref’s destination.

  • from_arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.remove_user_code_ref(here, 0x400000)
remove_user_function_tag(tag: Tag) None[source]

remove_user_function_tag removes a Tag object as a function tag. Since this removes a user tag, it will be added to the current undo buffer.

Parameters:

tag (Tag) – Tag object to be added

Return type:

None

remove_user_function_tags_of_type(tag_type: str)[source]

remove_user_function_tags_of_type removes all function Tag objects on a function of a given type Since this removes user tags, it will be added to the current undo buffer.

Parameters:

tag_type (TagType) – TagType object to match for removing

Return type:

None

remove_user_type_field_ref(from_addr: int, name: types.QualifiedNameType, offset: int, from_arch: Architecture | None = None, size: int = 0) None[source]

remove_user_type_field_ref removes a user-defined type field cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • offset (int) – offset of the field, relative to the type

  • from_arch (Architecture) – (optional) architecture of the source instruction

  • size (int) – (optional) the size of the access

Return type:

None

Example:
>>> current_function.remove_user_type_field_ref(here, 'A', 0x8)
remove_user_type_ref(from_addr: int, name: types.QualifiedNameType, from_arch: Architecture | None = None) None[source]

remove_user_type_ref removes a user-defined type cross-reference. If the given address is not contained within this function, or if there is no such user-defined cross-reference, no action is performed.

Parameters:
  • from_addr (int) – virtual address of the source instruction

  • name (QualifiedName) – name of the referenced type

  • from_arch (Architecture) – (optional) architecture of the source instruction

Return type:

None

Example:
>>> current_function.remove_user_type_ref(here, 'A')
request_advanced_analysis_data() None[source]
Return type:

None

request_debug_report(name: str) None[source]

request_debug_report can generate internal debug reports for a variety of analysis. Current list of possible values include:

  • mlil_translator

  • stack_adjust_graph

  • high_level_il

Parameters:

name (str) – Name of the debug report

Return type:

None

set_auto_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int], arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_calling_convention(value: CallingConvention) None[source]
Parameters:

value (CallingConvention) –

Return type:

None

set_auto_can_return(value: bool | BoolWithConfidence) None[source]
Parameters:

value (bool | BoolWithConfidence) –

Return type:

None

set_auto_clobbered_regs(value: List[RegisterName | ILRegister | RegisterIndex]) None[source]
Parameters:

value (List[RegisterName | ILRegister | RegisterIndex]) –

Return type:

None

set_auto_has_variable_arguments(value: bool | BoolWithConfidence) None[source]
Parameters:

value (bool | BoolWithConfidence) –

Return type:

None

set_auto_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_auto_inline_during_analysis(value: bool | BoolWithConfidence)[source]
Parameters:

value (bool | BoolWithConfidence) –

set_auto_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]

set_auto_instr_highlight highlights the instruction at the specified address with the supplied color

Warning

Use only in analysis plugins. Do not use in regular plugins, as colors won’t be saved to the database.

Parameters:
set_auto_parameter_vars(value: List[Variable] | Variable | ParameterVariables | None) None[source]
Parameters:

value (List[Variable] | Variable | ParameterVariables | None) –

Return type:

None

set_auto_pure(value: bool | BoolWithConfidence) None[source]
Parameters:

value (bool | BoolWithConfidence) –

Return type:

None

set_auto_reg_stack_adjustments(value: Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence])[source]
Parameters:

value (Mapping[RegisterStackName, RegisterStackAdjustmentWithConfidence]) –

set_auto_return_regs(value: RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) None[source]
Parameters:

value (RegisterSet | List[RegisterName | ILRegister | RegisterIndex]) –

Return type:

None

set_auto_return_type(value: str | Type | TypeBuilder) None[source]
Parameters:

value (str | Type | TypeBuilder) –

Return type:

None

set_auto_stack_adjustment(value: int | OffsetWithConfidence) None[source]
Parameters:

value (int | OffsetWithConfidence) –

Return type:

None

set_auto_type(value: str | Type | TypeBuilder) None[source]
Parameters:

value (str | Type | TypeBuilder) –

Return type:

None

set_call_reg_stack_adjustment(addr: int, adjust: Mapping[RegisterStackName, int | RegisterStackAdjustmentWithConfidence], arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_call_reg_stack_adjustment_for_reg_stack(addr: int, reg_stack: RegisterStackName | ILRegisterStack | RegisterStackIndex, adjust: int | RegisterStackAdjustmentWithConfidence, arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_call_stack_adjustment(addr: int, adjust: int | OffsetWithConfidence, arch: Architecture | None = None)[source]
Parameters:
set_call_type_adjustment(addr: int, adjust_type: str | Type | TypeBuilder | None = None, arch: Architecture | None = None) None[source]

set_call_type_adjustment sets or removes the call type override at a call site to the given type.

Parameters:
  • addr (int) – virtual address of the call instruction to adjust

  • adjust_type (str|Type|TypeBuilder) – (optional) overridden call type, or None to remove an existing adjustment

  • arch (Architecture) – (optional) Architecture of the instruction if different from self.arch

Example:
>>> # Change the current call site to no-return
>>> target = bv.get_function_at(list(filter(lambda ref: ref.address == here, current_function.call_sites))[0].mlil.dest.value.value)
>>> ft = target.type.mutable_copy()
>>> ft.can_return = False
>>> current_function.set_call_type_adjustment(here, ft)
Return type:

None

set_comment_at(addr: int, comment: str) None[source]

set_comment_at sets a comment for the current function at the address specified

Parameters:
  • addr (int) – virtual address within the current function to apply the comment to

  • comment (str) – string comment to apply

Return type:

None

Example:
>>> current_function.set_comment_at(here, "hi")
set_condition_inverted(addr: int | HighLevelILInstruction, invert: bool)[source]
Parameters:
static set_default_session_data(name: str, value) None[source]
Parameters:

name (str) –

Return type:

None

set_early_return(addr: int | HighLevelILInstruction, value: EarlyReturn)[source]
Parameters:
set_expr_folding(addr: int | HighLevelILInstruction, value: ExprFolding)[source]
Parameters:
set_guided_source_blocks(addresses: List[Tuple[Architecture, int]]) None[source]

set_guided_source_blocks sets the complete list of guided source blocks for this function. Only blocks in this set will have their direct outgoing branch targets analyzed. This replaces any existing guided source blocks and automatically enables or disables the analysis.guided.enable setting based on whether addresses are provided.

Parameters:
Return type:

None

set_int_display_type(instr_addr: int, value: int, operand: int, display_type: IntegerDisplayType, arch: Architecture | None = None, enum_display_typeid=None) None[source]

Change the text display type for an integer token in the disassembly or IL views

Parameters:
  • instr_addr (int) – Address of the instruction or IL line containing the token

  • value (int) – value field of the InstructionTextToken object for the token, usually the constant displayed

  • operand (int) – Operand index of the token, defined as the number of OperandSeparatorTokens in the disassembly line before the token

  • display_type (IntegerDisplayType) – Desired display type

  • arch (Architecture) – (optional) Architecture of the instruction or IL line containing the token

  • enum_display_typeid (str) – (optional) Whenever passing EnumDisplayType to display_type, passing a type ID here will specify the Enumeration display type. Must be a valid type ID and resolve to an enumeration type.

Return type:

None

set_switch_recovery(addr: int | HighLevelILInstruction, value: SwitchRecovery)[source]
Parameters:
set_user_indirect_branches(source: int, branches: List[Tuple[Architecture, int]], source_arch: Architecture | None = None) None[source]
Parameters:
Return type:

None

set_user_inline_during_analysis(value: bool | BoolWithConfidence)[source]
Parameters:

value (bool | BoolWithConfidence) –

set_user_instr_highlight(addr: int, color: HighlightColor | HighlightStandardColor, arch: Architecture | None = None)[source]

set_user_instr_highlight highlights the instruction at the specified address with the supplied color

Parameters:
Example:
>>> current_function.set_user_instr_highlight(here, HighlightStandardColor.BlueHighlightColor)
>>> current_function.set_user_instr_highlight(here, highlight.HighlightColor(red=0xff, blue=0xff, green=0))

Warning: For performance reasons, this function does not ensure the address you have supplied is within the function’s bounds.

set_user_type(value: str | Type | TypeBuilder) None[source]
Parameters:

value (str | Type | TypeBuilder) –

Return type:

None

set_user_var_value(var: Variable, def_addr: int, value: PossibleValueSet, after: bool = True) None[source]

set_user_var_value allows the user to specify a PossibleValueSet value for an MLIL variable at its definition site.

Warning

Setting the variable value, triggers a reanalysis of the function and allows the dataflow to compute and propagate values which depend on the current variable. This implies that branch conditions whose values can be determined statically will be computed, leading to potential branch elimination at the HLIL layer.

Parameters:
  • var (Variable) – Variable for which the value is to be set

  • def_addr (int) – Address where the variable is set

  • value (PossibleValueSet) – Informed value of the variable

  • after (bool) – Whether the value happens before or after the instruction

Return type:

None

Example:
>>> mlil_var = current_mlil[0].operands[0]
>>> def_address = 0x40108d
>>> var_value = PossibleValueSet.constant(5)
>>> current_function.set_user_var_value(mlil_var, def_address, var_value)
split_var(var: Variable) None[source]

split_var splits a variable at the definition site. The given var must be the variable unique to the definition and should be obtained by using MediumLevelILInstruction.get_split_var_for_definition at the definition site.

This function is not meant to split variables that have been previously merged. Use unmerge_vars to split previously merged variables.

Warning

Binary Ninja automatically splits all variables that the analysis determines to be safely splittable. Splitting a variable manually with split_var can cause IL and decompilation to be incorrect. There are some patterns where variables can be safely split semantically but analysis cannot determine that it is safe. This function is provided to allow variable splitting to be performed in these cases by plugins or by the user.

Parameters:

var (Variable) – variable to split

Return type:

None

store_metadata(key: str, md: Metadata | int | bool | str | bytes | float | List[MetadataValueType] | Tuple[MetadataValueType] | dict, isAuto: bool = False) None[source]

store_metadata stores an object for the given key in the current Function. Objects stored using store_metadata can be retrieved when the database is reopened unless isAuto is set to True.

Parameters:
  • key (str) – key value to associate the Metadata object with

  • md (Varies) – object to store

  • isAuto (bool) – whether the metadata is an auto metadata

Return type:

None

toggle_region(hash)[source]

Toggle the collapsed state of a region during rendering, by hash value :param hash: Hash value of region

unmerge_vars(target: Variable, sources: List[Variable] | Variable) None[source]

unmerge_vars undoes variable merging performed with merge_vars. The variables in sources will no longer be merged into the target variable.

Parameters:
Return type:

None

unsplit_var(var: Variable) None[source]

unsplit_var undoes variable splitting performed with split_var. The given var must be the variable unique to the definition and should be obtained by using MediumLevelILInstruction.get_split_var_for_definition at the definition site.

Parameters:

var (Variable) – variable to unsplit

Return type:

None

property address_ranges: List[AddressRange]

All of the address ranges covered by a function

property analysis_performance_info: Dict[str, int]
property analysis_skip_override: FunctionAnalysisSkipOverride

Override for skipping of automatic analysis

property analysis_skip_reason: AnalysisSkipReason

Function analysis skip reason

property analysis_skipped: bool

Whether automatic analysis was skipped for this function. Can be set to false to re-enable analysis.

property arch: Architecture

Function architecture (read-only)

property auto: bool

Whether function was automatically discovered (read-only) as a result of some creation of a ‘user’ function. ‘user’ functions may or may not have been created by a user through the or API. For instance the entry point into a function is always created a ‘user’ function. ‘user’ functions should be considered the root of auto analysis.

property auto_metadata: Dict[str, metadata.MetadataValueType]

metadata retrieves the metadata associated with the current function.

Return type:

metadata associated with the function

property basic_blocks: BasicBlockList

function.BasicBlockList of BasicBlocks in the current function (read-only)

property call_sites: List[ReferenceSource]

call_sites returns a list of possible call sites contained in this function. This includes ordinary calls, tail calls, and indirect jumps. Not all of the returned call sites are necessarily true call sites; some may simply be unresolved indirect jumps, for example.

Returns:

List of References that represent the sources of possible calls in this function

Return type:

list(ReferenceSource)

property callee_addresses: List[int]

callee_addressses returns a list of start addresses for functions that this function calls. Does not point to the actual address where the call occurs, just the start of the function that contains the reference.

Returns:

List of start address for functions that this function calls

Return type:

list(int)

property callees: List[Function]

callees returns a list of functions that this function calls This does not include the address of those calls, rather just the function objects themselves. Use call_sites to identify the location of these calls.

Returns:

List of Functions that this function calls

Return type:

list(Function)

property caller_sites: Generator[ReferenceSource, None, None]

caller_sites returns a list of ReferenceSource objects corresponding to the addresses in functions which reference this function

Returns:

List of ReferenceSource objects of the call sites to this function

Return type:

list(ReferenceSource)

property callers: List[Function]

callers returns a list of functions that call this function Does not point to the actual address where the call occurs, just the start of the function that contains the call.

Returns:

List of Functions that call this function

Return type:

list(Function)

property calling_convention: CallingConvention | None

Calling convention used by the function

property can_return: BoolWithConfidence

Whether function can return

property clobbered_regs: RegisterSet

Registers that are modified by this function

property comment: str

Gets the comment for the current function

property comments: Dict[int, str]

Dict of comments (read-only)

property components
property core_var_stack_layout: List[CoreVariable]

List of function stack variables (read-only)

property core_vars: List[CoreVariable]

List of CoreVariable objects

property global_pointer_value: RegisterValue

Discovered value of the global pointer register, if the function uses one (read-only)

property has_explicitly_defined_type: bool

Whether function has explicitly defined types (read-only)

property has_unresolved_indirect_branches: bool

Has unresolved indirect branches (read-only)

property has_user_annotations: bool

Whether the function has ever been ‘user’ modified

property has_user_type: bool

True if the function has a user-defined type

property has_variable_arguments: BoolWithConfidence

Whether the function takes a variable number of arguments

property high_level_il: HighLevelILFunction | None

returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property highest_address: int

The highest (largest) virtual address contained in a function.

property hlil: HighLevelILFunction | None

returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes high level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property hlil_if_available: HighLevelILFunction | None

returns HighLevelILFunction used to represent high level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if high level IL is available without generating it.

property indirect_branches: List[IndirectBranchInfo]

List of indirect branches (read-only)

property inline_during_analysis: BoolWithConfidence

Whether the function’s IL should be inlined into all callers’ IL

property instructions: Generator[Tuple[List[InstructionTextToken], int], None, None]

A generator of instruction tokens and their start addresses for the current function

property is_collapsed

If the entire function is collapsed during rendering.

property is_pure: BoolWithConfidence

Whether function is pure

property is_thunk: bool

Returns True if the function starts with a Tailcall (read-only)

property lifted_il: LowLevelILFunction | None

returns LowLevelILFunction used to represent lifted IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes lifted IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property lifted_il_if_available: LowLevelILFunction | None

returns LowLevelILFunction used to represent lifted IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if lifted IL is available without generating it.

property llil: LowLevelILFunction | None

returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property llil_basic_blocks: Generator[LowLevelILBasicBlock, None, None]

A generator of all LowLevelILBasicBlock objects in the current function

property llil_if_available: LowLevelILFunction | None

returns LowLevelILFunction used to represent low level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if low level IL is available without generating it.

property low_level_il: LowLevelILFunction | None

returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes low level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property lowest_address: int

The lowest (smallest) virtual address contained in a function.

property mapped_medium_level_il: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property medium_level_il: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property merged_vars: Dict[Variable, List[Variable]]

Map of merged variables, organized by target variable (read-only). Use merge_vars and unmerge_vars to update merged variables.

property metadata: Dict[str, metadata.MetadataValueType]

metadata retrieves the metadata associated with the current function.

Return type:

metadata associated with the function

property mlil: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property mlil_basic_blocks: Generator[MediumLevelILBasicBlock, None, None]

A generator of all MediumLevelILBasicBlock objects in the current function

property mlil_if_available: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent medium level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if medium level IL is available without generating it.

property mmlil: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading the IL (read-only)

Note

This function causes mapped medium level IL to be generated if it has not been already. It is recommended to generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.

property mmlil_if_available: MediumLevelILFunction | None

returns MediumLevelILFunction used to represent mapped medium level IL, or None if not loaded or it cannot be generated (read-only)

Note

This function can be used to check if mapped medium level IL is available without generating it.

property name: str

Symbol name for the function

property needs_update: bool

Whether the function has analysis that needs to be updated (read-only)

property parameter_vars: ParameterVariables

List of variables for the incoming function parameters

property platform: Platform | None

Function platform (read-only)

property provenance

provenance returns a string representing the provenance. This portion of the API is under development. Currently the provenance information is undocumented, not persistent, and not saved to a database.

Returns:

string representation of the provenance

Return type:

str

property pseudo_c: LanguageRepresentationFunction | None
property pseudo_c_if_available: LanguageRepresentationFunction | None
property reg_stack_adjustments: Dict[RegisterStackName, RegisterStackAdjustmentWithConfidence]

Number of entries removed from each register stack after return

property return_regs: RegisterSet

Registers that are used for the return value

property return_type: Type | None

Return type of the function

property session_data: Any

Dictionary object where plugins can store arbitrary data associated with the function

property split_vars: List[Variable]

Set of variables that have been split with split_var. These variables correspond to those unique to each definition site and are obtained by using MediumLevelILInstruction.get_split_var_for_definition at the definitions.

property stack_adjustment: OffsetWithConfidence

Number of bytes removed from the stack after return

property stack_layout: List[Variable]

List of function stack variables (read-only)

property start: int

Function start address (read-only)

property symbol: CoreSymbol

Function symbol(read-only)

property tags: TagList

tags gets a TagList of all Tags in the function (but not “function tags”). Tags are returned as an iterable indexable object TagList of (arch, address, Tag) tuples.

Return type:

TagList((Architecture, int, Tag))

property too_large: bool

Whether the function is too large to automatically perform analysis (read-only)

property total_bytes: int

Total bytes of a function calculated by summing each basic_block. Because basic blocks can overlap and have gaps between them this may or may not be equivalent to a .size property.

property type: FunctionType

Function type object, can be set with either a string representing the function prototype (str(function) shows examples) or a Type object

property type_tokens: List[InstructionTextToken]

Text tokens for this function’s prototype

property unresolved_indirect_branches: List[Tuple[Architecture, int]]

List of unresolved indirect branches (read-only)

property unresolved_stack_adjustment_graph: CoreFlowGraph | None

Flow graph of unresolved stack adjustments (read-only)

property uses_incoming_global_pointer: bool

Whether the function uses the incoming global pointer value

property vars: List[Variable]

List of function variables (read-only)

property view: BinaryView

Function view (read-only)

property workflow

FunctionViewType

class FunctionViewType[source]

Bases: object

FunctionViewType(view_type: Union[ForwardRef(‘FunctionViewType’), binaryninja.enums.FunctionGraphType, str])

__init__(view_type: FunctionViewType | FunctionGraphType | str)[source]
Parameters:

view_type (FunctionViewType | FunctionGraphType | str) –

name: str | None
view_type: FunctionGraphType

HighLevelILBasicBlockList

class HighLevelILBasicBlockList[source]

Bases: BasicBlockList

ILReferenceSource

class ILReferenceSource[source]

Bases: object

ILReferenceSource(func: Optional[ForwardRef(‘Function’)], arch: Optional[ForwardRef(‘architecture.Architecture’)], address: int, il_type: binaryninja.enums.FunctionGraphType, expr_id: int)

__init__(func: Function | None, arch: Architecture | None, address: int, il_type: FunctionGraphType, expr_id: int) None
Parameters:
Return type:

None

static get_il_name(il_type: FunctionGraphType) str[source]
Parameters:

il_type (FunctionGraphType) –

Return type:

str

address: int
arch: Architecture | None
expr_id: int
func: Function | None
il_type: FunctionGraphType

LowLevelILBasicBlockList

class LowLevelILBasicBlockList[source]

Bases: BasicBlockList

MediumLevelILBasicBlockList

class MediumLevelILBasicBlockList[source]

Bases: BasicBlockList

TagList

class TagList[source]

Bases: object

__init__(function: Function)[source]
Parameters:

function (Function) –

VariableReferenceSource

class VariableReferenceSource[source]

Bases: object

VariableReferenceSource(var: ‘variable.Variable’, src: binaryninja.function.ILReferenceSource)

__init__(var: Variable, src: ILReferenceSource) None
Parameters:
Return type:

None

src: ILReferenceSource
var: Variable