basicblock module¶

Class	Description
`binaryninja.basicblock.BasicBlock`	The `class BasicBlock` object is returned during analysis and should not be directly instantiated.
`binaryninja.basicblock.BasicBlockEdge`	`class BasicBlockEdge` represents the edges that connect basic blocks in graph view.
`binaryninja.basicblock.PendingBasicBlockEdge`	`class PendingBasicBlockEdge` represents a pending edge that has not yet been resolved.

class BasicBlock[source]

Bases: object

The class BasicBlock object is returned during analysis and should not be directly instantiated.

Basic blocks contain a sequence of instructions that must execute in-order with no branches. We include calls in basic blocks, which technically violates that assumption, but you can mark functions as func.can_return = False if a given function should terminate basic blocks. :Example:

>>> for func in bv.functions:
>>>   for bb in func:
>>>     # Any block-based analysis could start here
>>>     for inst in bb:
>>>       pass # Optionally do something here with instructions

__init__(handle: LP_BNBasicBlock, view: BinaryView | None = None)[source]

Parameters:

handle (LP_BNBasicBlock) –
view (BinaryView | None) –

add_instruction_data(data: bytes) → None[source]

Adds raw instruction data to the basic block.

Note

This method is intended for use by architecture plugins only.

Parameters:: data (bytes) – Raw instruction data to add to the basic block.
Return type:: None

add_pending_outgoing_edge(typ: BranchType, addr: int, arch: Architecture, fallthrough: bool = False) → None[source]

Adds a pending outgoing edge to the basic block. This is used to add edges that are not yet resolved.

Note

This method is intended for use by architecture plugins only.

Parameters:

typ (BranchType) – The type of the branch.
addr (int) – The address of the target basic block.
arch (Architecture) – The architecture of the target basic block.
fallthrough (bool) – Whether this edge is a fallthrough edge.

Return type:

None

clear_pending_outgoing_edges() → None[source]

Clears all pending outgoing edges for the basic block. This is used to remove edges that have not yet been resolved.

Note

This method is intended for use by architecture plugins only.

Return type:: None

get_disassembly_text(settings: DisassemblySettings | None = None) → List[DisassemblyTextLine][source]

get_disassembly_text returns a list of DisassemblyTextLine objects for the current basic block.

Parameters:

settings (DisassemblySettings) – (optional) DisassemblySettings object

Example:

>>> current_basic_block.get_disassembly_text()
[<0x100000f30: _main:>, <0x100000f30: push    rbp>, ... ]

Return type:

List[DisassemblyTextLine]

get_instruction_containing_address(addr: int) → Tuple[bool, int][source]

Parameters:: addr (int) –
Return type:: Tuple[bool, int]

get_instruction_data(addr: int) → bytes[source]

Returns the raw instruction data for the basic block at the specified address.

Note

This method is intended for use by architecture plugins only.

Returns:: Raw instruction data as bytes.
Parameters:: addr (int) –
Return type:: bytes

get_iterated_dominance_frontier(blocks: List[BasicBlock]) → List[BasicBlock][source]

Calculates the iterated dominance frontier of the given blocks (this is used to determine φ node placement)

Parameters:: blocks (List[BasicBlock]) –
Return type:: List[BasicBlock]

get_pending_outgoing_edges() → list[PendingBasicBlockEdge][source]

Returns a list of pending outgoing edges for the basic block. These are edges that have not yet been resolved.

Note

This method is intended for use by architecture plugins only.

Returns:: List of PendingBasicBlockEdge objects.
Return type:: list[PendingBasicBlockEdge]

mark_recent_use() → None[source]

Return type:: None

set_auto_highlight(color: HighlightColor) → None[source]

set_auto_highlight highlights the current BasicBlock 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:

color (HighlightColor) – Color value to use for highlighting
color –

Return type:

None

set_user_highlight(color: HighlightColor) → None[source]

set_user_highlight highlights the current BasicBlock with the supplied color

Parameters:

color (HighlightColor) – Color value to use for highlighting
color –

Example:

>>> current_basic_block.set_user_highlight(_highlight.HighlightColor(red=0xff, blue=0xff, green=0))
>>> current_basic_block.set_user_highlight(HighlightStandardColor.BlueHighlightColor)

Return type:

None

property annotations: List[List[InstructionTextToken]]: List of automatic annotations for the start of this block (read-only)

property arch: Architecture: Basic block architecture (read-only)

property can_exit: bool: Whether basic block can return or is tagged as ‘No Return’ (read-only)

property disassembly_text: List[DisassemblyTextLine]

disassembly_text property which returns a list of function.DisassemblyTextLine objects for the current basic block.

Example:

>>> current_basic_block.disassembly_text
[<0x100000f30: _main:>, ...]

property dominance_frontier: List[BasicBlock]

Dominance frontier for this basic block (read-only)

The dominance frontier of a basic block B is the set of blocks that are not strictly dominated by B, but are immediately control-dependent on B. In other words, it contains the blocks where B’s dominance “stops” - the blocks that have at least one predecessor not dominated by B, while having another predecessor that is dominated by B.

property dominator_tree_children: List[BasicBlock]

List of child blocks in the dominator tree for this basic block (read-only)

The dominator tree children of a basic block B are the blocks dominated by B. See BasicBlock.dominators for the definition of a dominator.

property dominators: List[BasicBlock]

List of dominators for this basic block (read-only).

A dominator of a basic block B is a block that must be executed before B can be executed. In other words, every path from the entry block to B must go through the dominator. This includes B itself - every block dominates itself. See BasicBlock.strict_dominators for dominators that don’t include B.

property end: int: Basic block end (read-only)

property fallthrough_to_function: bool: Whether the basic block has a fallthrough edge to a function.

property function: Function | None: Basic block function (read-only)

property function_graph_type: FunctionGraphType: Type of function graph from which this block represents instructions

property has_invalid_instructions: bool: Whether basic block has any invalid instructions (read-only)

property has_undetermined_outgoing_edges: bool: Whether basic block has undetermined outgoing edges (read-only)

property highlight: HighlightColor

Gets or sets the highlight color for basic block

Example:

>>> current_basic_block.highlight = HighlightStandardColor.BlueHighlightColor
>>> current_basic_block.highlight
<color: blue>

property il_function: _function.ILFunctionType | None: IL Function of which this block is a part, if the block is part of an IL Function.

property il_function_if_available: _function.ILFunctionType | None: IL Function of which this block is a part, if the block is part of an IL Function, and if the function has generated IL already.

property immediate_dominator: BasicBlock | None

Immediate dominator of this basic block (read-only)

The immediate dominator of a basic block B is the dominator closest to B in the control flow graph. In other words, among all dominators of B, it is the dominator that doesn’t dominate any other dominator of B except itself. Each basic block except the entry block has a unique immediate dominator.

property immediate_post_dominator: BasicBlock | None

Immediate post-dominator of this basic block (read-only)

The immediate post-dominator of a basic block B is the post-dominator closest to B in the control flow graph. In other words, among all post-dominators of B, it is the post-dominator that doesn’t post-dominate any other post-dominator of B except itself. If B has outgoing edges that can lead to different exit blocks, then this will not exist.

property incoming_edges: List[BasicBlockEdge]: List of basic block incoming edges (read-only)

property index: int: Basic block index in list of blocks for the function (read-only)

property instruction_count: int

property is_high_level_il: bool: Whether the basic block contains High Level IL

property is_il: bool: Whether the basic block contains IL

property is_low_level_il: bool: Whether the basic block contains Low Level IL

property is_medium_level_il: bool: Whether the basic block contains Medium Level IL

property length: int: Basic block length (read-only)

property outgoing_edges: List[BasicBlockEdge]: List of basic block outgoing edges (read-only)

property post_dominance_frontier: List[BasicBlock]

Post-dominance frontier for this basic block (read-only)

The post-dominance frontier of a basic block B is the set of blocks that are not strictly post-dominated by B, but have at least one successor that is post-dominated by B. In other words, it contains the blocks where B’s post-dominance “stops” - the blocks that have at least one successor not post-dominated by B, while having another successor that is post-dominated by B.

property post_dominator_tree_children: List[BasicBlock]

List of child blocks in the post-dominator tree for this basic block (read-only)

The post-dominator tree children of a basic block B are the blocks post-dominated by B. See BasicBlock.post_dominators for the definition of a post-dominator.

property post_dominators: List[BasicBlock]

List of post-dominators for this basic block (read-only)

A post-dominator of a basic block B is a block that must be executed after B is executed. In other words, every path from B to an exit block must go through the post-dominator. This includes B itself - every block post-dominates itself. See BasicBlock.strict_post_dominators for post-dominators that don’t include B. If B has outgoing edges that can lead to different exit blocks, then this will only include B.

property source_block: BasicBlock | None: The corresponding assembly-level basic block for this basic block (read-only)

property start: int: Basic block start (read-only)

property strict_dominators: List[BasicBlock]

List of strict dominators for this basic block (read-only)

A strict dominator of a basic block B is a dominator of B that is not B itself. See BasicBlock.dominators for the definition of a dominator.

property strict_post_dominators: List[BasicBlock]

List of strict post-dominators for this basic block (read-only)

A strict post-dominator of a basic block B is a post-dominator of B that is not B itself. See BasicBlock.post_dominators for the definition of a post-dominator.

property view: BinaryView | None: BinaryView that contains the basic block (read-only)

class BasicBlockEdge[source]

Bases: object

class BasicBlockEdge represents the edges that connect basic blocks in graph view.

Variables:

type – The enums.BranchType of the edge; Whether the edge is a true branch, false branch, unconditional, etc.
source – The basic block that the edge originates from.
target – The basic block that the edge is going to.
backedge – Whether this edge targets to a node whose control flow can eventually flow back through the source node of this edge.

Example:

>>> current_basic_block.outgoing_edges
[<TrueBranch: x86_64@0x6>, <FalseBranch: x86_64@0x1f>]

__init__(type: BranchType, source: BasicBlock, target: BasicBlock, back_edge: bool, fall_through: bool) → None

Parameters:

type (BranchType) –
source (BasicBlock) –
target (BasicBlock) –
back_edge (bool) –
fall_through (bool) –

Return type:

None

back_edge: bool

fall_through: bool

source: BasicBlock

target: BasicBlock

type: BranchType

class PendingBasicBlockEdge[source]

Bases: object

class PendingBasicBlockEdge represents a pending edge that has not yet been resolved.

Variables:

type – The edge branch type.
arch – The architecture of the target basic block.
target – The address of the target basic block.
fall_through – Whether this edge is a fallthrough edge.

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

Parameters:

type (BranchType) –
arch (Architecture) –
target (int) –
fallthrough (bool) –

Return type:

None

arch: Architecture

fallthrough: bool

target: int

type: BranchType

BasicBlock¶

class BasicBlock[source]¶

Bases: object

The class BasicBlock object is returned during analysis and should not be directly instantiated.

Basic blocks contain a sequence of instructions that must execute in-order with no branches. We include calls in basic blocks, which technically violates that assumption, but you can mark functions as func.can_return = False if a given function should terminate basic blocks. :Example:

>>> for func in bv.functions:
>>>   for bb in func:
>>>     # Any block-based analysis could start here
>>>     for inst in bb:
>>>       pass # Optionally do something here with instructions

__init__(handle: LP_BNBasicBlock, view: BinaryView | None = None)[source]¶

Parameters:

handle (LP_BNBasicBlock) –
view (BinaryView | None) –

add_instruction_data(data: bytes) → None[source]¶

Adds raw instruction data to the basic block.

Note

This method is intended for use by architecture plugins only.

Parameters:: data (bytes) – Raw instruction data to add to the basic block.
Return type:: None

add_pending_outgoing_edge(typ: BranchType, addr: int, arch: Architecture, fallthrough: bool = False) → None[source]¶

Adds a pending outgoing edge to the basic block. This is used to add edges that are not yet resolved.

Note

This method is intended for use by architecture plugins only.

Parameters:

typ (BranchType) – The type of the branch.
addr (int) – The address of the target basic block.
arch (Architecture) – The architecture of the target basic block.
fallthrough (bool) – Whether this edge is a fallthrough edge.

Return type:

None

clear_pending_outgoing_edges() → None[source]¶

Clears all pending outgoing edges for the basic block. This is used to remove edges that have not yet been resolved.

Note

This method is intended for use by architecture plugins only.

Return type:: None

get_disassembly_text(settings: DisassemblySettings | None = None) → List[DisassemblyTextLine][source]¶

get_disassembly_text returns a list of DisassemblyTextLine objects for the current basic block.

Parameters:

settings (DisassemblySettings) – (optional) DisassemblySettings object

Example:

>>> current_basic_block.get_disassembly_text()
[<0x100000f30: _main:>, <0x100000f30: push    rbp>, ... ]

Return type:

List[DisassemblyTextLine]

get_instruction_containing_address(addr: int) → Tuple[bool, int][source]¶

Parameters:: addr (int) –
Return type:: Tuple[bool, int]

get_instruction_data(addr: int) → bytes[source]¶

Returns the raw instruction data for the basic block at the specified address.

Note

This method is intended for use by architecture plugins only.

Returns:: Raw instruction data as bytes.
Parameters:: addr (int) –
Return type:: bytes

get_iterated_dominance_frontier(blocks: List[BasicBlock]) → List[BasicBlock][source]¶

Calculates the iterated dominance frontier of the given blocks (this is used to determine φ node placement)

Parameters:: blocks (List[BasicBlock]) –
Return type:: List[BasicBlock]

get_pending_outgoing_edges() → list[PendingBasicBlockEdge][source]¶

Returns a list of pending outgoing edges for the basic block. These are edges that have not yet been resolved.

Note

This method is intended for use by architecture plugins only.

Returns:: List of PendingBasicBlockEdge objects.
Return type:: list[PendingBasicBlockEdge]

mark_recent_use() → None[source]¶

Return type:: None

set_auto_highlight(color: HighlightColor) → None[source]¶

set_auto_highlight highlights the current BasicBlock 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:

color (HighlightColor) – Color value to use for highlighting
color –

Return type:

None

set_user_highlight(color: HighlightColor) → None[source]¶

set_user_highlight highlights the current BasicBlock with the supplied color

Parameters:

color (HighlightColor) – Color value to use for highlighting
color –

Example:

>>> current_basic_block.set_user_highlight(_highlight.HighlightColor(red=0xff, blue=0xff, green=0))
>>> current_basic_block.set_user_highlight(HighlightStandardColor.BlueHighlightColor)

Return type:

None

property annotations: List[List[InstructionTextToken]]¶: List of automatic annotations for the start of this block (read-only)

property arch: Architecture¶: Basic block architecture (read-only)

property can_exit: bool¶: Whether basic block can return or is tagged as ‘No Return’ (read-only)

property disassembly_text: List[DisassemblyTextLine]¶

disassembly_text property which returns a list of function.DisassemblyTextLine objects for the current basic block.

Example:

>>> current_basic_block.disassembly_text
[<0x100000f30: _main:>, ...]

property dominance_frontier: List[BasicBlock]¶

Dominance frontier for this basic block (read-only)

The dominance frontier of a basic block B is the set of blocks that are not strictly dominated by B, but are immediately control-dependent on B. In other words, it contains the blocks where B’s dominance “stops” - the blocks that have at least one predecessor not dominated by B, while having another predecessor that is dominated by B.

property dominator_tree_children: List[BasicBlock]¶

List of child blocks in the dominator tree for this basic block (read-only)

The dominator tree children of a basic block B are the blocks dominated by B. See BasicBlock.dominators for the definition of a dominator.

property dominators: List[BasicBlock]¶

List of dominators for this basic block (read-only).

A dominator of a basic block B is a block that must be executed before B can be executed. In other words, every path from the entry block to B must go through the dominator. This includes B itself - every block dominates itself. See BasicBlock.strict_dominators for dominators that don’t include B.

property end: int¶: Basic block end (read-only)

property fallthrough_to_function: bool¶: Whether the basic block has a fallthrough edge to a function.

property function: Function | None¶: Basic block function (read-only)

property function_graph_type: FunctionGraphType¶: Type of function graph from which this block represents instructions

property has_invalid_instructions: bool¶: Whether basic block has any invalid instructions (read-only)

property has_undetermined_outgoing_edges: bool¶: Whether basic block has undetermined outgoing edges (read-only)

property highlight: HighlightColor¶

Gets or sets the highlight color for basic block

Example:

>>> current_basic_block.highlight = HighlightStandardColor.BlueHighlightColor
>>> current_basic_block.highlight
<color: blue>

property il_function: _function.ILFunctionType | None¶: IL Function of which this block is a part, if the block is part of an IL Function.

property il_function_if_available: _function.ILFunctionType | None¶: IL Function of which this block is a part, if the block is part of an IL Function, and if the function has generated IL already.

property immediate_dominator: BasicBlock | None¶

Immediate dominator of this basic block (read-only)

The immediate dominator of a basic block B is the dominator closest to B in the control flow graph. In other words, among all dominators of B, it is the dominator that doesn’t dominate any other dominator of B except itself. Each basic block except the entry block has a unique immediate dominator.

property immediate_post_dominator: BasicBlock | None¶

Immediate post-dominator of this basic block (read-only)

The immediate post-dominator of a basic block B is the post-dominator closest to B in the control flow graph. In other words, among all post-dominators of B, it is the post-dominator that doesn’t post-dominate any other post-dominator of B except itself. If B has outgoing edges that can lead to different exit blocks, then this will not exist.

property incoming_edges: List[BasicBlockEdge]¶: List of basic block incoming edges (read-only)

property index: int¶: Basic block index in list of blocks for the function (read-only)

property instruction_count: int¶

property is_high_level_il: bool¶: Whether the basic block contains High Level IL

property is_il: bool¶: Whether the basic block contains IL

property is_low_level_il: bool¶: Whether the basic block contains Low Level IL

property is_medium_level_il: bool¶: Whether the basic block contains Medium Level IL

property length: int¶: Basic block length (read-only)

property outgoing_edges: List[BasicBlockEdge]¶: List of basic block outgoing edges (read-only)

property post_dominance_frontier: List[BasicBlock]¶

Post-dominance frontier for this basic block (read-only)

The post-dominance frontier of a basic block B is the set of blocks that are not strictly post-dominated by B, but have at least one successor that is post-dominated by B. In other words, it contains the blocks where B’s post-dominance “stops” - the blocks that have at least one successor not post-dominated by B, while having another successor that is post-dominated by B.

property post_dominator_tree_children: List[BasicBlock]¶

List of child blocks in the post-dominator tree for this basic block (read-only)

The post-dominator tree children of a basic block B are the blocks post-dominated by B. See BasicBlock.post_dominators for the definition of a post-dominator.

property post_dominators: List[BasicBlock]¶

List of post-dominators for this basic block (read-only)

A post-dominator of a basic block B is a block that must be executed after B is executed. In other words, every path from B to an exit block must go through the post-dominator. This includes B itself - every block post-dominates itself. See BasicBlock.strict_post_dominators for post-dominators that don’t include B. If B has outgoing edges that can lead to different exit blocks, then this will only include B.

property source_block: BasicBlock | None¶: The corresponding assembly-level basic block for this basic block (read-only)

property start: int¶: Basic block start (read-only)

property strict_dominators: List[BasicBlock]¶

List of strict dominators for this basic block (read-only)

A strict dominator of a basic block B is a dominator of B that is not B itself. See BasicBlock.dominators for the definition of a dominator.

property strict_post_dominators: List[BasicBlock]¶

List of strict post-dominators for this basic block (read-only)

A strict post-dominator of a basic block B is a post-dominator of B that is not B itself. See BasicBlock.post_dominators for the definition of a post-dominator.

property view: BinaryView | None¶: BinaryView that contains the basic block (read-only)

BasicBlockEdge¶

class BasicBlockEdge[source]¶

Bases: object

class BasicBlockEdge represents the edges that connect basic blocks in graph view.

Variables:

type – The enums.BranchType of the edge; Whether the edge is a true branch, false branch, unconditional, etc.
source – The basic block that the edge originates from.
target – The basic block that the edge is going to.
backedge – Whether this edge targets to a node whose control flow can eventually flow back through the source node of this edge.

Example:

>>> current_basic_block.outgoing_edges
[<TrueBranch: x86_64@0x6>, <FalseBranch: x86_64@0x1f>]

__init__(type: BranchType, source: BasicBlock, target: BasicBlock, back_edge: bool, fall_through: bool) → None¶

Parameters:

type (BranchType) –
source (BasicBlock) –
target (BasicBlock) –
back_edge (bool) –
fall_through (bool) –

Return type:

None

back_edge: bool¶

fall_through: bool¶

source: BasicBlock¶

target: BasicBlock¶

type: BranchType¶

PendingBasicBlockEdge¶

class PendingBasicBlockEdge[source]¶

Bases: object

class PendingBasicBlockEdge represents a pending edge that has not yet been resolved.

Variables:

type – The edge branch type.
arch – The architecture of the target basic block.
target – The address of the target basic block.
fall_through – Whether this edge is a fallthrough edge.

__init__(type: BranchType, arch: Architecture, target: int, fallthrough: bool) → None¶

Parameters:

type (BranchType) –
arch (Architecture) –
target (int) –
fallthrough (bool) –

Return type:

None

arch: Architecture¶

fallthrough: bool¶

target: int¶

type: BranchType¶