basicblock module

binaryninja.basicblock.BasicBlock(handle[, view])

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

binaryninja.basicblock.BasicBlockEdge(type, ...)

class BasicBlockEdge represents the edges that connect basic blocks in graph view.
class BasicBlock(handle: LP_BNBasicBlock, view: BinaryView | None = None)[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
Parameters:

  • handle (LP_BNBasicBlock) –

  • view (BinaryView | 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_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]

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 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(type: BranchType, source: BasicBlock, target: BasicBlock, back_edge: bool, fall_through: bool)[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:

Parameters:
>>> current_basic_block.outgoing_edges
[<TrueBranch: x86_64@0x6>, <FalseBranch: x86_64@0x1f>]
back_edge: bool
fall_through: bool
source: BasicBlock
target: BasicBlock
type: BranchType