Breakpoints

Management of breakpoints are supported nearly completely by x64dbg Automate.

Software, hardware, and memory breakpoints are usable, but their condition and log components are not yet exposed.

Example: Breakpoints

"""
Example: Breakpoints (64 bit)
"""
"""
Example: Breakpoints (64 bit)
"""
import sys
from x64dbg_automate import X64DbgClient
from x64dbg_automate.events import EventType

if len(sys.argv) != 2:
    print("Usage: python sessions.py <x64dbg_path>")
    quit(1)

print('[+] Creating the x64dbg Automate session')
client = X64DbgClient(x64dbg_path=sys.argv[1])
client.start_session(r'c:\Windows\system32\winver.exe')

print('[+] Writing shellcode to demonstrate breakpoint features')
sys_entry, _ = client.eval_sync('rip')
i = sys_entry
i = i + client.assemble_at(i, 'mov rax, GetCurrentProcessId')
i = i + client.assemble_at(i, 'call rax')

print('[+] Setting a standard breakpoint at GetCurrentProcessId')
client.set_breakpoint('GetCurrentProcessId', singleshoot=True)
client.go()

print('[+] Waiting until the debugee is stopped at the software breakpoint')
bp = client.wait_for_debug_event(EventType.EVENT_BREAKPOINT)
client.clear_debug_events()
print(f'[+] Breakpoint "{bp.event_data.name}" hit at {bp.event_data.addr:X} with singleshoot={bp.event_data.singleshoot}')

print('[+] Resetting and setting a hardware breakpoint at GetCurrentProcessId')
client.set_reg('rip', sys_entry)
client.set_hardware_breakpoint('GetCurrentProcessId')
client.go()

print('[+] Waiting until the debugee is stopped at the hardware breakpoint')
client.wait_for_debug_event(EventType.EVENT_BREAKPOINT)
client.clear_debug_events()

print('[+] Clearing hardware breakpoint')
client.clear_hardware_breakpoint('GetCurrentProcessId')

print('[+] Resetting and setting a memory breakpoint at GetCurrentProcessId')
client.set_reg('rip', sys_entry)
client.set_memory_breakpoint('GetCurrentProcessId', restore=False)
client.go()

print('[+] Waiting until the debugee is stopped at the memory breakpoint')
client.wait_for_debug_event(EventType.EVENT_BREAKPOINT)
client.clear_debug_events()

print('[+] Cleaning up')
client.terminate_session()
[+] Creating the x64dbg Automate session
[+] Writing shellcode to demonstrate breakpoint features
[+] Setting a standard breakpoint at GetCurrentProcessId
[+] Waiting until the debugee is stopped at the software breakpoint
[+] Breakpoint "bpx_GetCurrentProcessId" hit at 7FFC973A36E0 with singleshoot=True
[+] Resetting and setting a hardware breakpoint at GetCurrentProcessId
[+] Waiting until the debugee is stopped at the hardware breakpoint
[+] Clearing hardware breakpoint
[+] Resetting and setting a memory breakpoint at GetCurrentProcessId
[+] Waiting until the debugee is stopped at the memory breakpoint
[+] Cleaning up

API Method Reference

get_breakpoints(bp_type)

Retrieves all breakpoints of the specified type

Parameters:

Name Type Description Default
bp_type BreakpointType

The type of breakpoint to get

required

Returns:

Type Description
list[Breakpoint]

A list of Breakpoint objects

Source code in x64dbg_automate/commands_xauto.py
def get_breakpoints(self, bp_type: BreakpointType) -> list[Breakpoint]:
    """
    Retrieves all breakpoints of the specified type

    Args:
        bp_type: The type of breakpoint to get

    Returns:
        A list of Breakpoint objects
    """
    resp = self._send_request(XAutoCommand.XAUTO_REQ_GET_BREAKPOINTS, bp_type)
    return [Breakpoint(
        type=BreakpointType(bp[0]),
        addr=bp[1],
        enabled=bp[2],
        singleshoot=bp[3],
        active=bp[4],
        name=bp[5],
        mod=bp[6],
        slot=bp[7],
        typeEx=bp[8],
        hwSize=bp[9],
        hitCount=bp[10],
        fastResume=bp[11],
        silent=bp[12],
        breakCondition=bp[13],
        logText=bp[14],
        logCondition=bp[15],
        commandText=bp[16],
        commandCondition=bp[17]
    ) for bp in resp]

set_breakpoint(address_or_symbol, name=None, bp_type=StandardBreakpointType.Short, singleshoot=False)

Sets a software breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_or_symbol int | str

Address or symbol to set the breakpoint at

required
name str | None

Optional name for the breakpoint

None
bp_type StandardBreakpointType

Type of software breakpoint to set

Short
singleshoot bool

Set a single-shot breakpoint

False

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def set_breakpoint(self, address_or_symbol: int | str, name: str | None = None, bp_type: StandardBreakpointType = StandardBreakpointType.Short, singleshoot: bool = False) -> bool:
    """
    Sets a software breakpoint at the specified address or symbol.

    Args:
        address_or_symbol: Address or symbol to set the breakpoint at
        name: Optional name for the breakpoint
        bp_type: Type of software breakpoint to set
        singleshoot: Set a single-shot breakpoint

    Returns:
        Success
    """
    bp_type_str = str(bp_type).lower()
    if singleshoot and bp_type_str != "ss":
        bp_type_str = f'ss{bp_type_str}'
    if isinstance(address_or_symbol, int):
        name = name or f"bpx_{address_or_symbol:x}"
        return self.cmd_sync(f'bpx 0x{address_or_symbol:x}, "{name}", {bp_type_str}')
    else:
        name = name or f"bpx_{address_or_symbol.replace(' ', '_')}"
        if '"' in name:
            raise ValueError("Name cannot contain double quotes")
        return self.cmd_sync(f'bpx {address_or_symbol}, "{name}", {bp_type_str}')

set_hardware_breakpoint(address_or_symbol, bp_type=HardwareBreakpointType.x, size=1)

Sets a hardware breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_or_symbol int | str

Address or symbol to set the breakpoint at

required
bp_type HardwareBreakpointType

Type of software breakpoint to set

x
size int

breakpoint size, one of [1, 2, 4, 8]

1

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def set_hardware_breakpoint(self, address_or_symbol: int | str, bp_type: HardwareBreakpointType = HardwareBreakpointType.x, size: int = 1) -> bool:
    """
    Sets a hardware breakpoint at the specified address or symbol.

    Args:
        address_or_symbol: Address or symbol to set the breakpoint at
        bp_type: Type of software breakpoint to set
        size: breakpoint size, one of [1, 2, 4, 8]

    Returns:
        Success
    """
    if size not in [1, 2, 4, 8]:
        raise ValueError("Invalid size")
    if isinstance(address_or_symbol, int):
        return self.cmd_sync(f'bph 0x{address_or_symbol:x}, {bp_type}, {size}')
    else:
        return self.cmd_sync(f'bph {address_or_symbol}, {bp_type}, {size}')

set_memory_breakpoint(address_or_symbol, bp_type=MemoryBreakpointType.a, singleshoot=False)

Sets a memory breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_or_symbol int | str

Address or symbol to set the breakpoint at

required
bp_type MemoryBreakpointType

Type of software breakpoint to set

a
singleshoot bool

Set a single-shot breakpoint

False

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def set_memory_breakpoint(self, address_or_symbol: int | str, bp_type: MemoryBreakpointType = MemoryBreakpointType.a, singleshoot: bool = False) -> bool:
    """
    Sets a memory breakpoint at the specified address or symbol.

    Args:
        address_or_symbol: Address or symbol to set the breakpoint at
        bp_type: Type of software breakpoint to set
        singleshoot: Set a single-shot breakpoint

    Returns:
        Success
    """
    if isinstance(address_or_symbol, int):
        return self.cmd_sync(f'bpm 0x{address_or_symbol:x}, {int(not singleshoot)}, {bp_type}')
    else:
        return self.cmd_sync(f'bpm {address_or_symbol}, {int(not singleshoot)}, {bp_type}')

clear_breakpoint(address_name_symbol_or_none=None)

Clears software breakpoint at the specified address, name, or symbol.

Parameters:

Name Type Description Default
address_name_symbol_or_none int | str | None

Address or symbol to remove the breakpoint at (None removes all breakpoints of this type)

None

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def clear_breakpoint(self, address_name_symbol_or_none: int | str | None = None) -> bool:
    """
    Clears software breakpoint at the specified address, name, or symbol.

    Args:
        address_name_symbol_or_none: Address or symbol to remove the breakpoint at (None removes all breakpoints of this type)

    Returns:
        Success
    """
    if address_name_symbol_or_none is None:
        return self.cmd_sync('bpc')
    if isinstance(address_name_symbol_or_none, int):
        return self.cmd_sync(f'bpc 0x{address_name_symbol_or_none:x}')
    return self.cmd_sync(f'bpc "{address_name_symbol_or_none}"')

clear_hardware_breakpoint(address_symbol_or_none=None)

Clears hardware breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_symbol_or_none int | str | None

Address or symbol to remove the breakpoint at (None removes all breakpoints of this type)

None

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def clear_hardware_breakpoint(self, address_symbol_or_none: int | str | None = None) -> bool:
    """
    Clears hardware breakpoint at the specified address or symbol.

    Args:
        address_symbol_or_none: Address or symbol to remove the breakpoint at (None removes all breakpoints of this type)

    Returns:
        Success
    """
    if address_symbol_or_none is None:
        return self.cmd_sync('bphc')
    if isinstance(address_symbol_or_none, int):
        return self.cmd_sync(f'bphc 0x{address_symbol_or_none:x}')
    return self.cmd_sync(f'bphc {address_symbol_or_none}')

clear_memory_breakpoint(address_symbol_or_none=None)

Clears memory breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_symbol_or_none int | str | None

Address or symbol to remove the breakpoint at (None removes all breakpoints of this type)

None

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def clear_memory_breakpoint(self, address_symbol_or_none: int | str | None = None) -> bool:
    """
    Clears memory breakpoint at the specified address or symbol.

    Args:
        address_symbol_or_none: Address or symbol to remove the breakpoint at (None removes all breakpoints of this type)

    Returns:
        Success
    """
    if address_symbol_or_none is None:
        return self.cmd_sync('bpmc')
    if isinstance(address_symbol_or_none, int):
        return self.cmd_sync(f'bpmc 0x{address_symbol_or_none:x}')
    return self.cmd_sync(f'bpmc {address_symbol_or_none}')

toggle_breakpoint(address_name_symbol_or_none=None, on=True)

Toggles software breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_name_symbol_or_none int | str | None

Address, name, or symbol to toggle the breakpoint at

None
on bool

Enable or disable the breakpoint

True

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def toggle_breakpoint(self, address_name_symbol_or_none: int | str | None = None, on: bool = True) -> bool:
    """
    Toggles software breakpoint at the specified address or symbol.

    Args:
        address_name_symbol_or_none: Address, name, or symbol to toggle the breakpoint at
        on: Enable or disable the breakpoint

    Returns:
        Success
    """
    toggle_cmd = 'bpe' if on else 'bpd'
    if isinstance(address_name_symbol_or_none, int):
        return self.cmd_sync(f'{toggle_cmd} 0x{address_name_symbol_or_none:x}')
    elif address_name_symbol_or_none is None:
        return self.cmd_sync(f'{toggle_cmd}')
    else:
        return self.cmd_sync(f'{toggle_cmd} {address_name_symbol_or_none}')

toggle_hardware_breakpoint(address_symbol_or_none=None, on=True)

Toggles hardware breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_symbol_or_none int | str | None

Address or symbol to toggle the breakpoint at

None
on bool

Enable or disable the breakpoint

True

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def toggle_hardware_breakpoint(self, address_symbol_or_none: int | str | None = None, on: bool = True) -> bool:
    """
    Toggles hardware breakpoint at the specified address or symbol.

    Args:
        address_symbol_or_none: Address or symbol to toggle the breakpoint at
        on: Enable or disable the breakpoint

    Returns:
        Success
    """
    toggle_cmd = 'bphe' if on else 'bphd'
    if isinstance(address_symbol_or_none, int):
        return self.cmd_sync(f'{toggle_cmd} 0x{address_symbol_or_none:x}')
    elif address_symbol_or_none is None:
        return self.cmd_sync(f'{toggle_cmd}')
    else:
        return self.cmd_sync(f'{toggle_cmd} {address_symbol_or_none}')

toggle_memory_breakpoint(address_symbol_or_none=None, on=True)

Toggles memory breakpoint at the specified address or symbol.

Parameters:

Name Type Description Default
address_symbol_or_none int | str | None

Address or symbol to toggle the breakpoint at

None
on bool

Enable or disable the breakpoint

True

Returns:

Type Description
bool

Success

Source code in x64dbg_automate/hla_xauto.py
def toggle_memory_breakpoint(self, address_symbol_or_none: int | str | None = None, on: bool = True) -> bool:
    """
    Toggles memory breakpoint at the specified address or symbol.

    Args:
        address_symbol_or_none: Address or symbol to toggle the breakpoint at
        on: Enable or disable the breakpoint

    Returns:
        Success
    """
    toggle_cmd = 'bpme' if on else 'bpmd'
    if isinstance(address_symbol_or_none, int):
        return self.cmd_sync(f'{toggle_cmd} 0x{address_symbol_or_none:x}')
    elif address_symbol_or_none is None:
        return self.cmd_sync(f'{toggle_cmd}')
    else:
        return self.cmd_sync(f'{toggle_cmd} {address_symbol_or_none}')

API Model Reference

Breakpoint

Source code in x64dbg_automate/models.py
class Breakpoint(BaseModel):
    type: BreakpointType
    addr: int
    enabled: bool
    singleshoot: bool
    active: bool
    name: str
    mod: str
    slot: int
    typeEx: int
    hwSize: int
    hitCount: int
    fastResume: bool
    silent: bool
    breakCondition: str
    logText: str
    logCondition: str
    commandText: str
    commandCondition: str

BreakpointType

Source code in x64dbg_automate/models.py
class BreakpointType(IntEnum):
    BpNone = 0,
    BpNormal = 1,
    BpHardware = 2,
    BpMemory = 4,
    BpDll = 8,
    BpException = 16

StandardBreakpointType

Source code in x64dbg_automate/models.py
class StandardBreakpointType(StrEnum):
    SingleShotInt3 = 'ss' # CC (SingleShoot)
    Long = 'long' # CD03
    Ud2 = 'ud2' # 0F0B
    Short = 'short' # CC

HardwareBreakpointType

Source code in x64dbg_automate/models.py
class HardwareBreakpointType(StrEnum):
    r = 'r'
    w = 'w'
    x = 'x'

MemoryBreakpointType

Source code in x64dbg_automate/models.py
class MemoryBreakpointType(StrEnum):
    r = 'r'
    w = 'w'
    x = 'x'
    a = 'a'