DOCSEARCHbyAlgolia
Submit Docs

x64dbg Automate RPC Server

repository·main·Indexed 41 days ago

https://github.com/dariushoule/x64dbg-automate

An RPC server for x64dbg that enables automation via ZeroMQ and messagepack serialization. It allows external clients, such as Python scripts, to control the debugger, receive real-time events, and execute commands through Request/Reply and Publish/Subscribe communication patterns. The server provides a comprehensive RPC interface for memory manipulation, register access, disassembly, and debugger state management.

Tokens
2.4K
Snippets
4
Records
12
Agent score
47%

What's inside x64dbg-automate

  1. Overview of x64dbg Automate RPC Server

    main

    The x64dbg Automate RPC Server acts as a broker for Inter-Process Communication (IPC) between x64dbg and client automation software (specifically the x64dbg Automate Python Client).

    Key technical details:

    • Transport: Built on ZeroMQ to support concurrent debug control and event notification.
    • Serialization: Uses messagepack for message serialization.
    • Prerequisite: For all automation examples to work correctly, x64dbg must be configured to stop on entry and system breakpoints, while skipping TLS breakpoints.

  2. How to add new request/reply style RPC calls

    main

    To extend the RPC interface with new request/reply functionality, you must implement a command handler in the C++ server.

    An RPC request consists of a command identifier followed by an argument tuple. The implementation workflow is:

    1. Create a new command identifier.
    2. Parse the incoming argument tuple.
    3. Execute the logic and serialize a response.

    For a reference implementation, see the XAUTO_REQ_DBG_EVAL command in the source code.

  3. How pub/sub style events work

    main

    Events in x64dbg Automate are typically published during plugin callback lifecycle events.

    When a registered callback is triggered, the server can publish data to the pub/sub ZMQ socket. The Python client then receives these messages and queues them for the user. This allows for asynchronous event notification from the debugger to the automation script.

  4. Build the x64dbg Automate RPC Server

    main

    The project uses CMake. You can build either the 64-bit or 32-bit version of the plugin from a Visual Studio command prompt.

    # Build the 64-bit plugin
cmake -B build64 -A x64
cmake --build build64 --config Release

# Build the 32-bit plugin
cmake -B build32 -A Win32
cmake --build build32 --config Release

  5. Configure x64dbg Automate Connection Modes

    main

    The x64dbg Automate plugin provides two connection modes for interacting with the debugger via ZMQ:

    1. Local: Uses automatic ports on localhost. This is the simplest mode for local automation.
    2. Remote: Uses a fixed address and specific ports. This is required when the automation client and x64dbg are running on different machines or when specific port mapping is necessary.

  6. Configure Remote Connection Settings

    main

    When using the Remote connection mode, you must specify the following network parameters:

    • Bind Address: The IP address or hostname the plugin should bind to.
    • REQ/REP Port: The port used for Request/Reply communication (used for direct command calls).
    • PUB/SUB Port: The port used for Publish/Subscribe communication (used for event notifications).

    Note: Changes to these settings take effect only after the next restart of x64dbg.

  7. Broadcast events using pub_send

    main

    To broadcast asynchronous events to all connected subscribers, use the pub_send method. This method is thread-safe and accepts a msgpack::sbuffer containing the serialized message payload. It uses the internal pub_socket to transmit the data.

    msgpack::sbuffer buf;
// ... serialize your event data into buf using msgpack ...
server.pub_send(buf);

  8. XAutoServer Request/Reply command identifiers

    main

    When performing Request/Reply (RPC) calls via the rep_socket, use the following string constants as command identifiers. These represent the available operations for interacting with the x64dbg debugger instance:

    // Debugger State & Info
const char* XAUTO_REQ_DEBUGGER_PID;
const char* XAUTO_REQ_COMPAT_VERSION;
const char* XAUTO_REQ_DEBUGGER_VERSION;
const char* XAUTO_REQ_DBG_IS_RUNNING;
const char* XAUTO_REQ_DBG_IS_DEBUGGING;
const char* XAUTO_REQ_DBG_IS_ELEVATED;
const char* XAUTO_REQ_DBG_GET_BITNESS;

// Memory & Registers
const char* XAUTO_REQ_DBG_READ_MEMORY;
const char* XAUTO_REQ_DBG_WRITE_MEMORY;
const char* XAUTO_REQ_DBG_READ_REGISTERS;
const char* XAUTO_REQ_DBG_IS_VALID_READ_PTR;
const char* XAUTO_REQ_DBG_MEMMAP;

// Execution & Commands
const char* XAUTO_REQ_DBG_CMD_EXEC_DIRECT;
const char* XAUTO_REQ_DBG_EVAL;
const char* XAUTO_REQ_QUIT;

// Disassembly & Symbols
const char* XAUTO_REQ_DISASSEMBLE;
const char* XAUTO_REQ_ASSEMBLE;
const char* XAUTO_REQ_GET_BREAKPOINTS;
const char* XAUTO_REQ_GET_LABEL;
const char* XAUTO_REQ_GET_COMMENT;
const char* XAUTO_REQ_GET_SYMBOL;

// Settings
const char* XAUTO_REQ_DBG_READ_SETTING_SZ;
const char* XAUTO_REQ_DBG_WRITE_SETTING_SZ;
const char* XAUTO_REQ_DBG_READ_SETTING_UINT;
const char* XAUTO_REQ_DBG_WRITE_SETTING_UINT;

// UI & Logging
const char* XAUTO_REQ_GUI_REFRESH_VIEWS;
const char* XAUTO_REQ_GET_LOG;

  9. Reference of complex data types (Tuples)

    main

    The RPC interface uses MessagePack-encoded tuples to return structured data. When consuming these responses, ensure your client-side parser matches the following tuple structures.

    Memory & Context

    • MemPageTup: Represents a memory page.
    • CtxTup64: Represents the 64-bit CPU context (includes GP regs, IP, flags, segments, DR regs, X87/FPU, and extended state).
    • CtxTup32: Represents the 32-bit CPU context.

    Disassembly & Breakpoints

    • DisasmTup: Represents disassembled instruction data, including arguments (DisasmArgTup).
    • BpxTup: Represents breakpoint information.

  10. XAutoServer configuration and socket properties

    main

    The XAutoServer class manages the ZMQ communication layer for x64dbg automation. It provides two primary socket types for different communication patterns:

    • rep_socket: A Request/Reply socket used for synchronous RPC-style calls.
    • pub_socket: A Publish/Subscribe socket used for asynchronous event broadcasting.

    Key configuration members include:

    • bind_address: The IP address to bind the server to (defaults to "localhost").
    • sess_req_rep_port: The port assigned for the Request/Reply session.
    • sess_pub_sub_port: The port assigned for the Pub/Sub session.
    XAutoServer server;
server.bind_address = "127.0.0.1";
// Access sockets via server.rep_socket and server.pub_socket

  11. Reference of available RPC command functions

    main

    The following functions define the available RPC interface for interacting with x64dbg. These functions are typically invoked via ZMQ requests and populate a msgpack::sbuffer with the response.

    Debugger State & Info

    • get_debugger_pid: Retrieves the PID of the debugger.
    • get_compat_v: Retrieves the compatibility version (defined by XAUTO_COMPAT_VERSION).
    • get_debugger_version: Retrieves the x64dbg version.
    • dbg_is_running: Checks if the debugger is currently running.
    • dbg_is_debugging: Checks if the debugger is currently in a debugging session.
    • dbg_is_elevated: Checks if the debugger is running with elevated privileges.
    • dbg_get_bitness: Returns the bitness of the debugger.

    Memory & Execution

    • dbg_memmap: Returns the memory map.
    • dbg_read_memory: Reads memory from the debugged process.
    • dbg_write_memory: Writes memory to the debugged process.
    • dbg_eval: Evaluates an expression.
    • dbg_cmd_exec_direct: Executes a direct command in x64dbg.
    • dbg_is_valid_read_ptr: Validates if a pointer is readable.

    Registers & Settings

    • dbg_read_regs: Reads the current CPU registers.
    • dbg_read_setting_sz: Reads a string-type setting.
    • dbg_write_setting_sz: Writes a string-type setting.
    • dbg_read_setting_uint: Reads a uint-type setting.
    • dbg_write_setting_uint: Writes a uint-type setting.

    Disassembly & Symbols

    • disassemble_at: Disassembles code at a specific address.
    • assemble_at: Assembles code at a specific address.
    • get_breakpoints: Retrieves the list of breakpoints.
    • get_label_at: Retrieves a label at a specific address.
    • get_comment_at: Retrieves a comment at a specific address.
    • get_symbol_at: Retrieves a symbol at a specific address.

    UI & Logs

    • gui_refresh_views: Refreshes the x64dbg GUI views.
    • get_log: Retrieves the debugger log.

  12. XAutoErrorResponse structure

    main

    When an RPC call fails, the response may follow the XAutoErrorResponse schema. This structure is used to communicate the success status and the error details via MessagePack.

    Fields:

    • success: A string indicating the success status.
    • error_string: A string containing the error message.