intellicrack.bridges.base

Base protocol for tool bridges.

This module defines the abstract interface that all tool bridge implementations must follow, enabling consistent interaction across Ghidra, x64dbg, Frida, Cutter/Rizin, and other reverse engineering tools.

TOOL_CAPABILITY_MAP: dict[str, str] = {'allocate_memory': 'memory_access', 'animate_start': 'debugging', 'animate_stop': 'debugging', 'apply_patch': 'patching', 'attach': 'debugging', 'compile_typescript': 'scripting', 'configure_breakpoint': 'debugging', 'create_cmodule': 'scripting', 'decompile': 'decompilation', 'detach': 'debugging', 'disable_breakpoint': 'debugging', 'disassemble': 'static_analysis', 'disassemble_at': 'static_analysis', 'disassemble_function': 'static_analysis', 'disassemble_instruction': 'static_analysis', 'dump_memory_to_file': 'memory_access', 'enable_breakpoint': 'debugging', 'execute_script': 'scripting', 'execute_script_with_params': 'scripting', 'execute_til_return': 'debugging', 'export_patches': 'patching', 'export_patches_bps': 'patching', 'export_patches_ups': 'patching', 'free_memory': 'memory_access', 'frida.attach': 'dynamic_analysis', 'frida.detach': 'dynamic_analysis', 'frida.disassemble_instruction': 'dynamic_analysis', 'get_basic_blocks': 'static_analysis', 'get_breakpoints': 'debugging', 'get_call_graph': 'static_analysis', 'get_call_tree': 'static_analysis', 'get_callers': 'static_analysis', 'get_memory_map': 'memory_access', 'get_memory_regions': 'memory_access', 'get_modules': 'debugging', 'get_patches': 'patching', 'get_pcode': 'static_analysis', 'get_registers': 'debugging', 'get_threads': 'debugging', 'get_trace_record': 'debugging', 'get_watchpoints': 'debugging', 'get_xrefs_from': 'static_analysis', 'get_xrefs_to': 'static_analysis', 'ghidra.get_memory_map': 'static_analysis', 'ghidra.write_bytes': 'static_analysis', 'hex_editor.run_python_script': 'static_analysis', 'import_patches': 'patching', 'import_patches_bps': 'patching', 'import_patches_ups': 'patching', 'kernel_alloc': 'memory_access', 'kernel_protect': 'memory_access', 'kernel_read': 'memory_access', 'kernel_write': 'memory_access', 'nop_range': 'patching', 'patch_anti_debug': 'patching', 'patch_code': 'patching', 'patch_instruction': 'patching', 'pause': 'debugging', 'process.get_modules': 'memory_access', 'process.get_threads': 'memory_access', 'protect_memory': 'memory_access', 'read_memory': 'memory_access', 'read_peb': 'memory_access', 'read_teb': 'memory_access', 'remove_breakpoint': 'debugging', 'remove_watchpoint': 'debugging', 'replace_function': 'patching', 'restart': 'debugging', 'restore_patch': 'patching', 'revert_patch': 'patching', 'run': 'debugging', 'run_python_script': 'scripting', 'run_to': 'debugging', 'sandbox.stop': 'dynamic_analysis', 'scan_memory': 'memory_access', 'script_abort': 'scripting', 'script_cmd': 'scripting', 'script_load': 'scripting', 'script_run': 'scripting', 'set_breakpoint': 'debugging', 'set_breakpoint_on_api': 'debugging', 'set_dll_breakpoint': 'debugging', 'set_ip': 'debugging', 'set_logging_breakpoint': 'debugging', 'set_register': 'debugging', 'set_trace_record': 'debugging', 'set_watchpoint': 'debugging', 'skip_instruction': 'debugging', 'step_count': 'debugging', 'step_into': 'debugging', 'step_out': 'debugging', 'step_over': 'debugging', 'stop': 'debugging', 'trace_into': 'debugging', 'trace_over': 'debugging', 'trace_start': 'debugging', 'trace_stop': 'debugging', 'write_bytes': 'patching', 'write_code': 'patching', 'write_memory': 'memory_access'}

Mapping from bridge tool-function name to required capability.

Each key is either the unqualified method/tool name exposed by a bridge (the name field of its ToolFunction entries with the <bridge>. prefix stripped) or a fully-qualified <bridge>.<method> name. Each value is the capability name that would appear in BridgeCapabilities as supports_<value>. ToolRegistry consults this mapping in execute_tool_call and prefers a fully- qualified match over the short-name match, so a bridge whose method name collides with an unrelated bridge’s (for example the sandbox’s stop versus a debugger’s stop) can require the capability that actually fits its own operation instead of inheriting the short name’s capability. It raises ToolError when a bridge is asked to execute a tool whose required capability it does not advertise. The mapping lives in bridges.base so that bridge implementations and the registry share a single source of truth, and intellicrack.core.tools imports it from here.

class BinaryOperationsBridge[source]

Bases: ToolBridgeBase

Base class for direct binary file operations.

Provides interface for reading, modifying, and patching binary files without running a full analysis tool.

__init__()[source]

Initialize the BinaryOperationsBridge instance.

Return type:: None

abstractmethod async load_file(path)[source]

Load a binary file.

Parameters:: path (Path) – Path to the binary.
Returns:: Information about the loaded binary.
Return type:: BinaryInfo

abstractmethod async read_bytes(offset, size)[source]

Read bytes from file.

Parameters:

offset (int) – File offset.
size (int) – Number of bytes.

Returns:

Bytes read from the file.

Return type:

bytes

abstractmethod async write_bytes(offset, data)[source]

Write bytes to file.

Parameters:

offset (int) – File offset.
data (bytes) – Bytes to write.

Return type:

None

abstractmethod async apply_patch(patch)[source]

Apply a patch to the binary.

Parameters:: patch (PatchInfo) – Patch information.
Returns:: True if the patch was applied successfully.
Return type:: bool

abstractmethod async revert_patch(patch)[source]

Revert a previously applied patch.

Parameters:: patch (PatchInfo) – Patch to revert.
Returns:: True if the patch was reverted successfully.
Return type:: bool

abstractmethod async save(path=None)[source]

Save the binary to file.

Parameters:: path (Path | None) – Optional new path. Uses original if None.
Returns:: Path where the file was saved.
Return type:: Path

abstractmethod async search_pattern(pattern, start_offset=0, max_results=100)[source]

Search for byte pattern in file.

Parameters:

pattern (bytes) – Byte pattern to find.
start_offset (int) – Starting offset for search.
max_results (int) – Maximum results to return.

Returns:

List of file offsets where the pattern was found.

Return type:

list[int]

abstractmethod async calculate_checksum(algorithm='sha256')[source]

Calculate file checksum.

Parameters:: algorithm (str) – Hash algorithm (md5, sha256).
Returns:: Hex digest of the file hash.
Return type:: str

class BridgeCapabilities[source]

Bases: object

Describes the capabilities of a tool bridge.

Variables:

supports_static_analysis (bool) – Whether the tool supports static analysis.
supports_dynamic_analysis (bool) – Whether the tool supports dynamic analysis.
supports_decompilation (bool) – Whether the tool can decompile to pseudocode.
supports_debugging (bool) – Whether the tool can debug processes.
supports_patching (bool) – Whether the tool can patch binaries.
supports_scripting (bool) – Whether the tool supports custom scripts.
supports_memory_access (bool) – Whether the tool can read/write process memory.
supported_architectures (list[str]) – List of supported CPU architectures.
supported_formats (list[str]) – List of supported binary formats.

supports_static_analysis: bool = False

supports_dynamic_analysis: bool = False

supports_decompilation: bool = False

supports_debugging: bool = False

supports_patching: bool = False

supports_scripting: bool = False

supports_memory_access: bool = False

supported_architectures: list[str]

supported_formats: list[str]

has_capability(capability)[source]

Check if a specific capability is supported.

Parameters:: capability (str) – Name of the capability to check.
Returns:: True if the capability is supported.
Return type:: bool

supports_arch(arch)[source]

Check if an architecture is supported.

Parameters:: arch (str) – Architecture identifier to check.
Returns:: True if the architecture is in the supported set.
Return type:: bool

supports_format(fmt)[source]

Check if a binary format is supported.

Parameters:: fmt (str) – Binary format identifier to check.
Returns:: True if the format is in the supported set.
Return type:: bool

__init__(supports_static_analysis=False, supports_dynamic_analysis=False, supports_decompilation=False, supports_debugging=False, supports_patching=False, supports_scripting=False, supports_memory_access=False, supported_architectures=<factory>, supported_formats=<factory>)

Parameters:

supports_static_analysis (bool)
supports_dynamic_analysis (bool)
supports_decompilation (bool)
supports_debugging (bool)
supports_patching (bool)
supports_scripting (bool)
supports_memory_access (bool)
supported_architectures (list[str])
supported_formats (list[str])

Return type:

None

class BridgeState[source]

Bases: object

Current state of a tool bridge.

Variables:

connected (bool) – Whether connected to the tool.
tool_running (bool) – Whether the tool process is running.
binary_loaded (bool) – Whether a binary is loaded.
process_attached (bool) – Whether attached to a process.
target_path (Path | None) – Path to the loaded binary.
target_pid (int | None) – PID of attached process.
last_error (str | None) – Last error message if any.

connected: bool = False

tool_running: bool = False

binary_loaded: bool = False

process_attached: bool = False

target_path: Path | None = None

target_pid: int | None = None

last_error: str | None = None

is_ready()[source]

Check if bridge is connected and tool is running.

Returns:: True if both connected and tool_running are True.
Return type:: bool

clear_error()[source]

Clear the last error.

Return type:: None

__init__(connected=False, tool_running=False, binary_loaded=False, process_attached=False, target_path=None, target_pid=None, last_error=None)

Parameters:

connected (bool)
tool_running (bool)
binary_loaded (bool)
process_attached (bool)
target_path (Path | None)
target_pid (int | None)
last_error (str | None)

Return type:

None

class DebuggerBridge[source]

Bases: DynamicAnalysisBridge

Base class for full debuggers (x64dbg).

Extends DynamicAnalysisBridge with breakpoints, stepping, and register manipulation.

__init__()[source]

Initialize the DebuggerBridge instance.

Return type:: None

abstractmethod async run()[source]

Continue execution.

Return type:: None

abstractmethod async pause()[source]

Pause execution.

Return type:: None

abstractmethod async stop()[source]

Stop debugging (terminate process).

Return type:: None

abstractmethod async step_into()[source]

Single step into.

Returns:: New instruction pointer.
Return type:: int

abstractmethod async step_over()[source]

Single step over.

Returns:: New instruction pointer.
Return type:: int

abstractmethod async step_out()[source]

Step out of current function.

Returns:: New instruction pointer.
Return type:: int

abstractmethod async set_breakpoint(address, bp_type='software', condition=None)[source]

Set a breakpoint.

Parameters:

address (int) – Address for breakpoint.
bp_type (Literal['software', 'hardware', 'memory']) – Type (software, hardware, memory).
condition (str | None) – Optional condition expression.

Returns:

Breakpoint ID.

Return type:

int

abstractmethod async remove_breakpoint(address)[source]

Remove a breakpoint.

Parameters:: address (int) – Breakpoint address.
Returns:: True if removed successfully.
Return type:: bool

abstractmethod async get_breakpoints()[source]

Get all breakpoints.

Returns:: List of breakpoint information.
Return type:: list[BreakpointInfo]

abstractmethod async get_registers()[source]

Get all register values.

Returns:: Current register state.
Return type:: RegisterState

abstractmethod async set_register(register, value)[source]

Set a register value.

Parameters:

register (str) – Register name (rax, rbx, etc.).
value (int) – New value.

Returns:

True if set successfully.

Return type:

bool

abstractmethod async get_stack_trace()[source]

Get current stack trace.

Returns:: List of stack frames.
Return type:: list[StackFrame]

abstractmethod async disassemble_at(address, count=10)[source]

Disassemble at runtime address.

Parameters:

address (int) – Start address.
count (int) – Number of instructions.

Returns:

List of disassembly lines.

Return type:

list[DisassemblyLine]

abstractmethod async assemble_at(address, instruction)[source]

Assemble instruction at address.

Parameters:

address (int) – Target address.
instruction (str) – Assembly instruction.

Returns:

Assembled bytes.

Return type:

bytes

class DisassemblyLine[source]

Bases: object

Single line of disassembly output.

Variables:

address (int) – Virtual address of the instruction.
bytes_str (str) – Raw bytes of the instruction as a hex string.
mnemonic (str) – Assembly mnemonic (e.g. MOV, JMP).
operands (str) – Instruction operands as a string.
comment (str | None) – Optional comment at this line.

address: int

bytes_str: str

mnemonic: str

operands: str

comment: str | None = None

__init__(address, bytes_str, mnemonic, operands, comment=None)

Parameters:

address (int)
bytes_str (str)
mnemonic (str)
operands (str)
comment (str | None)

Return type:

None

class DynamicAnalysisBridge[source]

Bases: ToolBridgeBase

Base class for dynamic analysis tools (x64dbg, Frida).

Provides interface for process attachment, memory manipulation, breakpoints, and runtime instrumentation.

__init__()[source]

Initialize the DynamicAnalysisBridge instance.

Return type:: None

abstractmethod async attach(pid)[source]

Attach to a running process.

Parameters:: pid (int) – Process ID to attach to.
Return type:: None

abstractmethod async spawn(path, args=None)[source]

Spawn a new process.

Parameters:

path (Path) – Path to executable.
args (Sequence[str] | None) – Command line arguments.

Returns:

PID of spawned process.

Return type:

int

abstractmethod async detach()[source]

Detach from current process.

Return type:: None

abstractmethod async read_memory(address, size)[source]

Read process memory.

Parameters:

address (int) – Memory address.
size (int) – Number of bytes to read.

Returns:

Memory contents.

Return type:

bytes

abstractmethod async write_memory(address, data)[source]

Write to process memory.

Parameters:

address (int) – Memory address.
data (bytes) – Bytes to write.

Returns:

Number of bytes written.

Return type:

int

abstractmethod async get_memory_regions()[source]

Get process memory map.

Returns:: List of memory regions.
Return type:: list[MemoryRegion]

abstractmethod async scan_memory(pattern)[source]

Scan process memory for a pattern.

Parameters:: pattern (bytes) – Byte pattern to search for.
Returns:: List of matches with context.
Return type:: list[MemorySearchResult]

class InstrumentationBridge[source]

Bases: DynamicAnalysisBridge

Base class for instrumentation tools (Frida).

Extends DynamicAnalysisBridge with function hooking and script execution capabilities.

__init__()[source]

Initialize the InstrumentationBridge instance.

Return type:: None

abstractmethod async enumerate_modules()[source]

List all loaded modules in the process.

Returns:: List of loaded module information.
Return type:: list[ModuleInfo]

abstractmethod async enumerate_exports(module_name)[source]

List exports of a module.

Parameters:: module_name (str) – Name of the module.
Returns:: List of export information.
Return type:: list[ExportInfo]

abstractmethod async hook_function(target, on_enter=None, on_leave=None)[source]

Attach a hook to a function by name or address.

Parameters:

target (str) – Function name (module!func) or hex address.
on_enter (str | None) – Script code to run on function entry.
on_leave (str | None) – Script code to run on function exit.

Returns:

Information about the installed hook.

Return type:

HookInfo

abstractmethod async remove_hook(hook_id)[source]

Remove a previously installed hook.

Parameters:: hook_id (str) – ID of the hook to remove.
Returns:: True if hook was removed successfully.
Return type:: bool

abstractmethod async get_hooks()[source]

Get all active hooks.

Returns:: List of active hook information.
Return type:: list[HookInfo]

abstractmethod async execute_script(script)[source]

Execute custom script code.

Parameters:: script (str) – Script code to execute.
Returns:: Script execution result.
Return type:: str

abstractmethod async intercept_return(target, return_value)[source]

Intercept a function and replace its return value.

Parameters:

target (str) – Function to hook.
return_value (int) – Value to return instead.

Returns:

Information about the installed interception hook.

Return type:

HookInfo

abstractmethod async call_function(address, args=None)[source]

Call a function in the target process.

Parameters:

address (int) – Function address.
args (Sequence[int] | None) – Function arguments.

Returns:

Function return value.

Return type:

int

abstractmethod async enumerate_imports(module_name)[source]

List imports of a module.

Parameters:: module_name (str) – Name of the module.
Returns:: List of import information.
Return type:: list[ImportInfo]

abstractmethod async enumerate_threads()[source]

List all threads in the attached process.

Returns:: List of thread information.
Return type:: list[ThreadInfo]

class MemorySearchResult[source]

Bases: object

Result from a memory pattern search.

Variables:

address (int) – Virtual address of the match.
matched_bytes (str) – Matched bytes as a hex string.
context_before (str) – Bytes preceding the match as a hex string.
context_after (str) – Bytes following the match as a hex string.

address: int

matched_bytes: str

context_before: str

context_after: str

__init__(address, matched_bytes, context_before, context_after)

Parameters:

address (int)
matched_bytes (str)
context_before (str)
context_after (str)

Return type:

None

class StackFrame[source]

Bases: object

Single stack frame in a call stack.

Variables:

index (int) – Frame index (0 = top/current).
address (int) – Instruction pointer for this frame.
return_address (int) – Return address for this frame.
frame_pointer (int) – Base/frame pointer (RBP/EBP).
stack_pointer (int) – Stack pointer (RSP/ESP).
function_name (str | None) – Function name if resolved, None otherwise.
module_name (str | None) – Module name if resolved, None otherwise.

index: int

address: int

return_address: int

frame_pointer: int

stack_pointer: int

function_name: str | None

module_name: str | None

__init__(index, address, return_address, frame_pointer, stack_pointer, function_name, module_name)

Parameters:

index (int)
address (int)
return_address (int)
frame_pointer (int)
stack_pointer (int)
function_name (str | None)
module_name (str | None)

Return type:

None

class StaticAnalysisBridge[source]

Bases: ToolBridgeBase

Base class for static analysis tools (Ghidra, Cutter/Rizin).

Provides interface for binary loading, disassembly, decompilation, and cross-reference analysis without executing the target.

__init__()[source]

Initialize the StaticAnalysisBridge instance.

Return type:: None

abstractmethod async load_binary(path)[source]

Load a binary for analysis.

Parameters:: path (Path) – Path to the binary file.
Returns:: Information about the loaded binary.
Return type:: BinaryInfo

abstractmethod async analyze()[source]

Run full analysis on loaded binary.

Return type:: None

abstractmethod async get_functions(filter_pattern=None)[source]

Get all analyzed functions.

Parameters:: filter_pattern (str | None) – Optional regex pattern to filter function names.
Returns:: List of analyzed function information.
Return type:: list[FunctionInfo]

abstractmethod async get_function(address)[source]

Get function at specific address.

Parameters:: address (int) – Function address.
Returns:: Function info or None if not found.
Return type:: FunctionInfo | None

abstractmethod async decompile(address)[source]

Decompile function at address.

Parameters:: address (int) – Function address.
Returns:: Decompiled C pseudocode.
Return type:: str

abstractmethod async disassemble(address, count=20)[source]

Disassemble instructions at address.

Parameters:

address (int) – Start address.
count (int) – Number of instructions.

Returns:

List of disassembly lines.

Return type:

list[DisassemblyLine]

abstractmethod async get_xrefs_to(address)[source]

Get cross-references to an address.

Parameters:: address (int) – Target address.
Returns:: List of cross-references to the address.
Return type:: list[CrossReference]

abstractmethod async get_xrefs_from(address)[source]

Get cross-references from an address.

Parameters:: address (int) – Source address.
Returns:: List of cross-references from the address.
Return type:: list[CrossReference]

abstractmethod async search_strings(pattern)[source]

Search for strings matching pattern.

Parameters:: pattern (str) – Regex pattern to match.
Returns:: List of matching strings.
Return type:: list[StringInfo]

abstractmethod async search_bytes(pattern)[source]

Search for byte pattern.

Parameters:: pattern (bytes) – Byte sequence to find.
Returns:: List of match addresses.
Return type:: list[int]

abstractmethod async get_imports()[source]

Get all imported functions.

Returns:: List of import information.
Return type:: list[ImportInfo]

abstractmethod async get_exports()[source]

Get all exported functions.

Returns:: List of export information.
Return type:: list[ExportInfo]

abstractmethod async rename_function(address, new_name)[source]

Rename a function.

Parameters:

address (int) – Function address.
new_name (str) – New function name.

Returns:

True if rename succeeded.

Return type:

bool

abstractmethod async add_comment(address, comment, comment_type='EOL')[source]

Add a comment at an address.

Parameters:

address (int) – Address for comment.
comment (str) – Comment text.
comment_type (str) – Type of comment (EOL, PRE, POST, PLATE).

Returns:

True if comment was added.

Return type:

bool

class ToolBridgeBase[source]

Bases: ABC

Base class for tool bridges.

All bridge implementations must inherit from this class and override the methods defined here. This ensures a consistent interface for the orchestrator to interact with any reverse engineering tool.

Note

The use of a per-instance self._logger attribute is intentional and justified in this class to dynamically encode the concrete subclass name into the logger metadata.

__init__()[source]

Initialize the ToolBridgeBase instance.

Return type:: None

abstract property name: ToolName

Tool name enum value.

Returns:: The tool’s name enum value.
Return type:: ToolName

property state: BridgeState

Current bridge state.

Returns:: Current BridgeState instance.
Return type:: BridgeState

set_session(session)[source]

Attach (or detach) the session that this bridge reports state into.

When a session is attached, the bridge immediately publishes its current BridgeState as a ToolState entry on the session so the persisted view reflects any state changes that happened before the session was wired in. Passing None detaches the bridge without modifying the previously held session.

Parameters:: session (Session | None) – The active Session whose tool_states registry should receive this bridge’s lifecycle updates, or None to detach.
Return type:: None

property capabilities: BridgeCapabilities

Bridge capabilities.

Returns:: BridgeCapabilities describing what this tool can do.
Return type:: BridgeCapabilities

abstract property tool_definition: ToolDefinition

Tool definition for LLM function calling.

Returns:: Tool definition with available functions.
Return type:: ToolDefinition

abstractmethod async initialize(tool_path=None)[source]

Initialize the tool bridge.

Parameters:: tool_path (Path | None) – Optional path to tool installation. If None, will auto-detect or download.
Return type:: None

abstractmethod async shutdown()[source]

Shutdown the tool and cleanup resources.

Each concrete bridge MUST override this method to release any external handles (debugger sessions, RPC bridges, sandbox VMs, etc.). Subclasses should call await super().shutdown() at the end of their cleanup so the shared bookkeeping in _finalize_shutdown() runs after tool-specific teardown.

Return type:: None

abstractmethod async is_available()[source]

Check if the tool is installed and available.

Returns:: True if the tool is ready.
Return type:: bool

class WatchpointInfo[source]

Bases: object

Memory watchpoint information.

Variables:

id (int) – Watchpoint identifier.
address (int) – Memory address being watched.
size (int) – Size of the watched region in bytes.
watch_type (str) – Access type to watch (read, write, or exec).
enabled (bool) – Whether the watchpoint is active.
hit_count (int) – Number of times the watchpoint has triggered.

id: int

address: int

size: int

watch_type: str

enabled: bool

hit_count: int

__init__(id, address, size, watch_type, enabled, hit_count)

Parameters:

id (int)
address (int)
size (int)
watch_type (str)
enabled (bool)
hit_count (int)

Return type:

None