Skip to main content

​
Instance

The Instance class provides access to normal angr project objects like a Project, CFG, and other analyses.

​
Constructor

Instance()
Creates a new instance with default containers for project data.

​
Properties

​
project
ObjectContainer[angr.Project | None]
The current angr project
​
cfg
ObjectContainer[CFGModel | None]
The current control flow graph
​
cfb
ObjectContainer[CFBlanket | None]
The current CFBlanket (fast CFG representation)
​
kb
KnowledgeBase | None
The knowledge base from the current project (read-only property)
​
simgrs
ObjectContainer[list[SimulationManager]]
Global simulation managers list
​
states
ObjectContainer[list[SimState]]
Global states list
​
patches
ObjectContainer
Global patches update notifier
​
log
ObjectContainer[list[LogRecord]]
Saved log messages
​
current_trace
ObjectContainer[Trace]
Currently selected trace
​
traces
ObjectContainer[list[Trace]]
Global traces list
​
active_view_state
ObjectContainer[ViewState]
Currently focused view state
​
breakpoint_mgr
BreakpointManager
Manager for breakpoints
​
signature_mgr
SignatureManager
Manager for function signatures
​
debugger_list_mgr
DebuggerListManager
Manager for the list of available debuggers
​
debugger_mgr
DebuggerManager
Manager for the active debugger
​
analysis_configuration
AnalysesConfiguration | None
Configuration for analyses to run
​
binary_path
str | None
Current path to the loaded binary (local path if loaded from URL)
​
original_binary_path
str | None
Original path or URL of the loaded binary
​
database_path
str | None
Path to the angrDB database file
​
cfg_args
dict | None
Arguments used for CFG generation
​
variable_recovery_args
dict | None
Arguments used for variable recovery
​
pseudocode_variable_kb
KnowledgeBase | None
Separate knowledge base for pseudocode variable information

​
Methods

​
register_container

register_container(
    name: str,
    default_val_func: Callable,
    ty: type,
    description: str,
    logging_permitted: bool = True
) -> None
Register a new object container in the instance.
​
name
str
required
Name of the container (will be accessible as instance attribute)
​
default_val_func
Callable
required
Function that returns the default value for this container
​
ty
type
required
Type of the container’s value
​
description
str
required
Human-readable description of the container
​
logging_permitted
bool
default:"True"
Whether logging is allowed for this container’s events

​
initialize

initialize(initialized: bool = False) -> None
Initialize the instance after a project is loaded.
​
initialized
bool
default:"False"
Whether the instance has already been initialized

​
initialize_pseudocode_variable_kb

initialize_pseudocode_variable_kb() -> None
Initialize a separate knowledge base for pseudocode variable information.

​
get_instruction_text_at

get_instruction_text_at(addr: int) -> str | None
Get the text representation of an instruction at the specified address.
​
addr
int
required
Address of the instruction
​
return
str | None
Text representation of the instruction, or None if no instruction is found

​
delete_hook

delete_hook(addr: int) -> None
Remove a SimProcedure hook at the specified address.
​
addr
int
required
Address of the hook to remove

​
add_breakpoint

add_breakpoint(
    obj: str | int,
    type_: str | None = None,
    size: int | None = None
) -> None
Add a breakpoint at the specified location.
​
obj
str | int
required
Address (int) or symbol name (str) for the breakpoint
​
type_
str
Breakpoint type: “execute”, “write”, or “read”. Auto-detected if not provided.
​
size
int
Size of the breakpoint in bytes
Examples: 
# Set execution breakpoint at address
instance.add_breakpoint(0x1234)

# Set execution breakpoint on main function
instance.add_breakpoint('main')

# Set write breakpoint on global variable
instance.add_breakpoint('global_value')

# Set 1-byte read breakpoint
instance.add_breakpoint('global_value', 'read', 1)

​
set_comment

set_comment(addr: int, comment_text: str) -> None
Set or update a comment at the specified address.
​
addr
int
required
Address to set the comment at
​
comment_text
str
required
The comment text. Pass empty string or None to delete the comment.

​
Callbacks

​
insn_backcolor_callback
Callable[[int, bool], None] | None
Callback for instruction background color: (addr: int, is_selected: bool) -> None
​
label_rename_callback
Callable[[int, str], None] | None
Callback for label rename: (addr: int, new_name: str) -> None
​
set_comment_callback
Callable[[int, str], None] | None
Callback when a comment is set: (addr: int, comment_text: str) -> None
​
handle_comment_changed_callback
Callable[[int, str, bool, bool, bool], None] | None
Callback when a comment changes: (addr: int, comment: str, created: bool, decomp: bool, deleted: bool) -> None

​
ObjectContainer

The ObjectContainer class is a proxy wrapper that adds event notification functionality to any object.

​
Constructor

ObjectContainer(
    obj: Any,
    name: str | None = None,
    logging_permitted: bool = True
)
​
obj
Any
required
The object to wrap
​
name
str
Name for the container (auto-generated if not provided)
​
logging_permitted
bool
default:"True"
Whether logging is permitted for this container

​
Properties

​
am_obj
Any
The wrapped object (read/write)
​
am_none
bool
True if the wrapped object is None
​
am_name
str
The container’s name

​
Methods

​
am_subscribe

am_subscribe(listener: Callable) -> None
Subscribe to events from this container.
​
listener
Callable
required
Callback function to invoke on events: (**kwargs) -> None

​
am_unsubscribe

am_unsubscribe(listener: Callable) -> None
Unsubscribe from events.
​
listener
Callable
required
The listener to remove

​
am_event

am_event(**kwargs) -> None
Trigger an event, notifying all subscribers.
​
**kwargs
Any
Arbitrary keyword arguments to pass to listeners

​
am_event_gui

am_event_gui(**kwargs) -> None
Trigger an event on the GUI thread.
​
**kwargs
Any
Arbitrary keyword arguments to pass to listeners

Build docs developers (and LLMs) love

Get started for freeTalk to us