Return the authoritative debugger bridge and debug-session identity.

Diagnostic only for a debugger that is already running. When a target EXE path is known, call InitDebuggee directly instead of using BridgeHello as a preflight check; InitDebuggee selects and starts x32dbg/x64dbg from the configured X64DBG_ROOT and waits for this bridge automatically.

This is the identity used by every state-changing operation. ok is false for a legacy bridge because it cannot provide atomic stale-session protection.

Attach x64dbg/x32dbg to an already-running process.

Args: pid: Exact target PID. Preferred when known. exe_filter: Process name or image-path substring when pid is not provided. arch: Desired debugger architecture. Auto prefers the target process architecture. restart_debugger: When true, restart the debugger before attach. stop_first: When true, stop the current debug session before attaching. timeout_ms: Maximum time to wait for the attach to complete.

Preferred first call when the target executable path is known.

Reliably start a new debuggee with retries and state verification. This tool detects the target architecture, resolves X64DBG_ROOT, starts the matching x32dbg/x64dbg instance, waits for its authenticated bridge, and opens the target. Do not preflight BridgeHello, probe port 8888, or search debugger installation paths manually before calling InitDebuggee.

Args: exe_path: Absolute path to the executable. timeout_ms: Maximum total time to spend retrying. retries: Maximum number of init attempts. stop_first: When true, stop the current debug session before init. use_scyllahide: off (default), auto (same as off), or force (explicit injection). scyllahide_profile: Optional explicit ScyllaHide profile override. arguments: Argument vector excluding argv[0]. Mutually exclusive with command_line. command_line: Explicit Windows command-line tail. working_directory: Current directory for the new process. environment: Per-launch environment overrides. The current bridge reports this unsupported and the call fails explicitly instead of ignoring it. inherit_environment: Whether the target should inherit the debugger environment. stdin: Typed stdin object (inherit/null/file/bytes/pipe). stdout: Typed stdout object (inherit/null/file/pipe). stderr: Typed stderr object (inherit/null/file/pipe). All streams must be explicit together, or all omitted for console inheritance. child_policy: none, attach-first, attach-all, or break-on-create. capture_limit_bytes: Bounded pipe retention/queue capacity in bytes.

Get a normalized debugger state snapshot.

Args: include_console: When true, read visible console text if available. include_callstack: When true, include the current call stack while paused. include_registers: When true, include the current register dump while paused. include_breakpoints: When true, include breakpoint lists and hit counts. include_session: When true, include the raw session payload from the bridge. max_console_chars: Maximum visible console characters to read.

Wait until the debuggee reaches a paused state or exits.

Wait until the debuggee exits.

Read a memory range in a RE-friendly format.

Args: addr: Address or expression such as 0x401000, module!func+0x10, or [rbp+0x20]. size: Number of bytes to read. ty: One of hex, bytes, ascii, utf8, utf16, u8, u16, u32, u64. max_chars: Text decoding limit for ascii/utf8/utf16 views.

Evaluate a batch of expressions.

Args: expressions_json: JSON array or newline/comma-separated expressions.

Set a breakpoint, wait for it to hit, and capture structured context.

Set up (but do not yet run) an API call trace session.

Enumerates imports matching filter_json in modules_json and sets silent+continue-on-hit breakpoints on each target. Use RunApiTrace to drive the debuggee and collect calls.

Args: modules_json: JSON array of module names (e.g. ["kernel32.dll","ws2_32.dll"]). Empty → typical OS modules (kernel32/user32/advapi32/ws2_32/wininet/ntdll). filter_json: JSON array of substrings to match module!func. Empty → DEFAULT_API_FILTERS (file I/O, memory, process, net, crypto, etc.) custom_targets_json: Strict JSON array of explicit loaded-module targets. Each item selects exactly one symbol, RVA, or address. kind="import-resolver" records custom/hash resolver returns as exact PE exports using supplied resolver argument metadata. arg_count: Number of args to sample per call (default 4, max 8). label: Optional session label. max_targets: Max number of BPs to actually set (default 200). If the filter matches more, returns an error listing counts per module so the caller can narrow the filter. subscribe_modules: Periodically discover matching exports in modules that load after the trace starts. discover_dynamic_resolvers: Add a bounded owned breakpoint for a matching function pointer returned by GetProcAddress. native_return_hooks: Let the native breakpoint callback install and remove return hooks. Python remains a fail-safe if native scheduling is unavailable or rejects a hook.

Returns summary: {ok, traceId, targetCount, modules, filters, warnings}.

Run the debuggee and collect API calls into the given trace session.

Blocks until either max_calls calls are recorded, timeout_ms elapses, or the debuggee exits. Returns compact summary; use GetApiTraceLog for per-call details.

Stop a running API trace and optionally delete its breakpoints.

Read API trace log with pagination.

Args: trace_id: Session id from StartApiTrace. offset: Start index (0-based). limit: Max calls to return (default 100, max 5000). func_filter: Optional case-insensitive substring for "module!func".

Recover comparison candidates from exact API-trace operand evidence.

This consumes completed strcmp/strncmp/memcmp/wide-string calls. With a known probe it distinguishes the user-controlled operand and recovers a direct peer or a single-byte-XOR-transformed peer. A returned candidate must still be verified with an independent launch of the target.

Find the Original Entry Point (OEP) of a packed executable and, optionally, produce a VERIFIED unpacked dump.

Engine: a packer-agnostic dynamic approach for the unpack-in-memory-then-jump class (UPX, ASPack, FSG, MPRESS, PECompact, Petite, simple crypters):

1. ESP-anchor fast-forward -- a hardware breakpoint on the stub's saved register slot skips past the decompression loop and is immune to the page writes that defeat memory breakpoints.

2. Section-hop conditional trace -- single-steps in the engine until execution enters a non-stub executable section (the OEP). Virtualizing protectors have no generic recoverable OEP contract here; they are reported honestly via isLikelyVirtualized rather than faked. The optional virtualization research backend is disabled in this build.

When dump_to_path is set, the dump is written via Scylla and VERIFIED before ok:true (entry moved out of the packer section to the OEP, IAT resolved, imports richer than the packed baseline). The raw memory dump is always kept, so a failed verification still leaves something for manual recovery.

timeline_to_path optionally writes a canonical unpack-workflow-v1 evidence artifact. Returns {ok, status, stages, artifacts, oepAddr, detectedVia, confidence, moduleBase, moduleSize, packerEntry, verified, reason, rawDumpPath, isLikelyVirtualized, ...}.

Write memory using enhanced Script API

Parameters: addr: Memory address (in hex format, e.g. "0x1000") data: Hexadecimal string representing the data to write

Returns: Structured write/verification result from bridge v2 (legacy bridges may still return a status string).

Resume execution without blocking the MCP HTTP server.

This intentionally uses a non-blocking debugger command path so the bridge can continue to service Pause/Status requests while the target is running.

Returns: Status message

Pause execution without blocking the MCP HTTP server.

Returns: Status message

Stop debugging using Script API

Returns: Status message

Step into the next instruction without blocking the MCP HTTP server.

Returns: Command execution result

Step over the next instruction without blocking the MCP HTTP server.

Returns: Command execution result

Step out of the current function without blocking the MCP HTTP server.

Returns: Command execution result

Delete breakpoint at address using Script API

Parameters: addr: Memory address (in hex format, e.g. "0x1000")

Returns: Status message

Get list of loaded modules.

Returns: Dictionary with count, modules (list of objects), and summary (human-readable lines).

Get list of all threads in the debugged process with detailed information.

Returns: Dictionary with: - count: Number of threads - currentThread: Index of the currently focused thread - threads: List of thread objects with threadNumber, threadId, threadName, startAddress, localBase, cip, suspendCount, priority, waitReason, lastError, cycles

Get the current call stack of the debugged thread. Returns the full stack trace with addresses, return addresses, and comments.

Returns: Dictionary with: - total: Number of stack frames - entries: List of call stack entries, each with: - addr: Current address in the frame - from: Return address (caller) - to: Called address (callee) - comment: Auto-generated comment (function name, etc.)

Get a complete dump of all CPU registers in one call. Returns general purpose registers, segment registers, debug registers, flags, and last error/status information.

Much more efficient than reading registers individually.

Returns: Dictionary with all register values (cax/ccx/cdx/cbx/csp/cbp/csi/cdi, r8-r15 on x64, cip, eflags, segment regs, debug regs, flags object, lastError, lastStatus)

Export static annotations plus hash+RVA runtime evidence for IDA.

Inspect CLR metadata, type/method tokens and optional bounded IL bytes.

Capture CLR/AppDomain/module/thread/stack/JIT state via a passive sidecar.

The target must be paused for a coherent ClrMD read. The sidecar never claims the debug port and performs no target mutation. Optional token resolution is intentionally scoped to methods present on active managed stacks; unavailable pre-JIT methods are reported as not found.

Return the currently bound session identity and whether it matches the live state.

One-call health check.

Returns {ok, reasons[], hints[]}. Tells whether x64dbg is running, a process is loaded, it is paused, and whether analysis has been run.

Search ASCII/UTF-16 strings referenced by the current debuggee module.

Uses x64dbg's strref view under the hood, then filters client-side. Returns deterministic pages of matches with module/RVA identity. detail=full adds scan diagnostics but does not bypass pagination.

Disassemble a raw address range without guessing function bounds. Pages resume from the opaque nextCursor address.

Return the import table for a loaded module.

If module is empty, uses the current debuggee's main module. Each entry: {module, function, iatVa, thunkVa}. Falls back to QuerySymbols('Import*') if the plugin has no dedicated endpoint. Works on any PE loaded in the debugger.

Validate PE structure/imports and optionally run a bounded smoke process.

The optional isolated run is placed in a kill-on-close Windows Job Object so descendants cannot outlive the validation. network_policy remains an explicit policy marker; this process-local harness does not pretend to be a firewall sandbox.

Capture a rich, structured snapshot of the current stop — registers, selected memory/stack slots, the call stack, and disassembly around the instruction pointer — in one payload. Ideal right after a breakpoint hit so the model gets full context in a single round-trip.

Args: registers_json: Optional JSON array of register names to include (empty = the standard set). expressions_json: Optional JSON array of x64dbg expressions to evaluate. ranges_json: Optional JSON array of {label, expr, size, format} memory ranges to read. stack_slots_json: Optional JSON array describing stack slots to decode. disasm_before: Instructions to disassemble before the IP (default 2). disasm_after: Instructions to disassemble after the IP (default 4). callstack_limit: Maximum call-stack frames to include (default 12).

Returns: {"ok": bool, "registers": ..., "memory": ..., "callStack": ..., "disasm": ...} structured context, or an error envelope.

Return the export table for a loaded module.

Reconstruct a disk-layout PE from a loaded memory-layout image.

For destroyed/headerless images, header_template_path is accepted only after executable-section identity verification by default. Writable sections are reset from the bound template by default so CRT and loader state captured after DllMain cannot poison a later reload. entry_rva_override is bounded to an executable template section and can record a recovered manual-loader OEP without trusting stale headers. source_layout=auto|memory|disk also supports an embedded reflective raw PE staged inside a larger private allocation.

Produce a VERIFIED unpacked dump of a module to disk. With find_oep=True (default) this drives the packer-agnostic OEP engine (FindOEP) — which works for the unpack-in-memory-then-jump class (UPX, ASPack, FSG, MPRESS, PECompact, Petite, simple crypters) — then dumps via Scylla and VERIFIES the result before reporting ok: the entry must have moved out of the packer stub to the real OEP, the IAT must resolve cleanly (no garbage descriptors), and the imports must be non-trivial. A dump that merely landed on disk is NOT a success. On failure it returns ok:false with a reason and keeps the raw memory dump for manual recovery. Virtualizing protectors have no generic recoverable OEP contract here and are reported honestly (isLikelyVirtualized), never faked. The optional virtualization research backend is disabled in this build.

find_oep=False dumps the selected loaded module at the current/module entry. It still performs independent PE/IAT verification by default and never treats mere file creation as success.

Args: module: Module name to dump (e.g. "target.exe"). Empty = the main debuggee module. output_path: Destination path for the dumped file. Empty = a default path derived from the module. find_oep: When True (default) find + verify the OEP before dumping; when False dump from the current state (no verification). timeout_ms: Budget for OEP discovery (default 30000). fix_imports: Reconstruct imports with Scylla (default true). verify: Require independent PE/IAT verification (default true). overwrite: Explicitly authorize replacing dump artifacts. keep_raw_dump: Preserve Scylla's pre-IAT raw image. iat_start/iat_size: Optional exact live IAT range; both are required together. module_strategy: auto, overlay, or scylla. Auto uses a reloadable source-backed executable overlay for non-main DLLs. timeline_path: Optional unpack-workflow-v1 JSON path. When OEP discovery is enabled and omitted, <output>.workflow.json is written automatically.

Returns: {"ok": bool, "verified": bool, "path": str, "exists": bool, "size": int, "module": str, "findOep": bool, "oep"?: str, "confidence"?: str, "reason"?: str, "isLikelyVirtualized"?: bool, "rawDumpPath"?: str, "result": ..., "hint"?: str}.