pybridge

Drive x64dbg
from Python.

pybridge is an x64dbg plugin and a standard-library Python client: breakpoints, single-stepping, registers, memory, API hooks and traces — in the GUI or in headless.exe, with nothing to pip install.

Download View on GitHub Français 
from x64dbg_bridge import Debugger

with Debugger.launch(r"C:\Tools\x64dbg\release") as dbg:   # starts headless.exe
    dbg.init(r"C:\Windows\System32\whoami.exe")
    dbg.set_breakpoint("kernelbase.LoadLibraryExW", break_=False,
                       log="LoadLibrary({utf16@arg.get(0)})")
    dbg.set_breakpoint("kernelbase.CreateFileW")
    if dbg.run(wait=True, timeout=10):
        print(dbg.read_string(dbg.eval("arg.get(0)"), wide=True))
        print(dbg.regs())

What's inside

Works with official x64dbg, on x64 and x32 targets.

Plugin

pybridge.dp64 / .dp32: a local TCP server speaking one JSON request per line. Usable from any language.

Python client

x64dbg_bridge.Debugger: launch or attach, step, read and write memory, hook APIs — standard library only.

Headless templates

Twelve ready-made x64dbg scripts (API log, unpack dumps, pattern search, traces) run by one PowerShell launcher.

Dump emulation

emulate_dump.py runs a .dmp in Unicorn and serves it over the same protocol, so the client drives it like a live process.

Quick start

Windows, x64dbg, Python 3.10 or newer.

  1. Download pybridge_1.0.0.zip.
  2. Extract it into x64dbg's release folder (it adds x64\plugins\pybridge.dp64, x32\plugins\pybridge.dp32 and pybridge\).
  3. Point Python at the client and launch:
import sys
sys.path.insert(0, r"C:\Tools\x64dbg\release\pybridge\python")
from x64dbg_bridge import Debugger

with Debugger.launch(r"C:\Tools\x64dbg\release", arch="x64") as dbg:
    dbg.init(r"C:\Windows\System32\notepad.exe")
    print(dbg.regs())

Already in x64dbg? Run pybridge.start in the command bar (port 27041), then Debugger() connects to it.

API at a glance

Addresses accept integers or x64dbg expressions: "kernelbase.CreateFileW", "rsp+8", "[rsp]".

CategoryMethods
Sessionlaunch(), init(), attach(), stop(), close()
Executionrun(), pause(), step_into(), step_over(), step_out(), wait(), state()
Registersregs(), reg(), set_reg()
Memoryread(), write(), read_ptr(), read_string(), is_valid(), disasm()
Breakpointsset_breakpoint(), delete_breakpoint(), set_hardware_breakpoint()
API hookshook_api(), dump_memory()
Anti-anti-debughide_debugger(), scyllahide_profiles(), scyllahide_set_profile()
Tracestrace(), export_trace() (JSON / CSV / Tenet / Frinet, with Fathom)
Commandscmd(), command(), eval(), result

Headless templates

The launcher fills in the target, runs headless.exe with an isolated configuration and collects everything in out\<template>-<date>\.

.\headless\run-headless.ps1 -Template api-log -Target C:\Windows\System32\whoami.exe -X64dbgDir C:\Tools\x64dbg\release
.\headless\run-headless.ps1 -Template unpack-dump -Target .\sample.exe -X64dbgDir C:\Tools\x64dbg\release -Arch x32
TemplatePurpose
api-log, hook-apis-extendedlog API calls with their arguments, without pausing
hook-unpack, unpack-dumpfollow runtime unpacking and dump the region flipped to executable
dump-module, dump-at-delaysave the main module and a full minidump
break-on-fileconditional breakpoint followed by automatic actions
antidebughide the debugger and log anti-debug probes
find-patternsearch a hex or ASCII pattern over the whole memory map
trace-export, run-tracerecord a trace and export it (needs Fathom's TraceExport)
emulate-dumpserve a .dmp emulation on 127.0.0.1:27041

Security

The server only accepts local connections, but any local program that connects to it fully controls the debugger. Start it only when you need it, and use it on binaries you are allowed to study.