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'