A class for tracing and controlling the execution of processes in a debugging environment. More...

#include <KittyTrace.hpp>

Public Member Functions
	KittyTraceMgr (pid_t pid, uintptr_t defaultCaller=0, bool autoRestoreRegs=true, int remoteCallTimeout=0, uintptr_t syscallGadget=0)
	Constructs a new KittyTraceMgr object.
pid_t	pid () const
	Returns the PID of the process being traced.
bool	isAlive () const
	Check if the process is alive.
bool	isAttached () const
	Check if the process is currently attached.
std::vector< pid_t >	threads () const
	Get a list of all threads in the traced process.
bool	attach (int options=0)
	Attach to the process.
bool	seize (int options=0)
	Seize the process.
bool	setOptions (int options)
	Set options for the process being traced.
bool	detach ()
	Detach from the process.
bool	stop ()
	Stop the traced process thread.
bool	cont (int sig=0)
	Continue the traced process thread.
pid_t	wait (int *status, int options, int timeout_ms=0) const
	Wait for the process.
bool	waitSyscall () const
	Wait for the process to enter or exit a syscall.
bool	step (int steps=1) const
	Single-step the process.
bool	waitStep (int steps=1) const
	Single-step and wait the process.
bool	getSignalInfo (siginfo_t *si) const
	Get the signal information of the process.
bool	getRegs (user_regs_struct *regs) const
	Get the current registers of the process.
bool	setRegs (user_regs_struct *regs) const
	Set the current registers of the process.
uintptr_t	getReturnAddressFromRegs (user_regs_struct *regs)
	Get the return address value from registers.
template<typename T>
T	getArgFromRegs (user_regs_struct *regs, uint32_t arg_num)
	Get the n-th argument value from registers.
size_t	peekMem (uintptr_t addr, void *buf, size_t size) const
	Reads memory from a traced process using PTRACE_PEEKTEXT. Works around ptrace's word-sized limitation by reading aligned machine words and copying only the requested byte ranges.
size_t	pokeMem (uintptr_t addr, const void *buf, size_t size) const
	Writes memory from a traced process using PTRACE_POKETEXT. Works around ptrace's word-sized limitation by reading aligned machine words and copying only the requested byte ranges.
uintptr_t	defaultCaller () const
	Returns the default caller address for remote function calls.
void	setDefaultCaller (uintptr_t caller)
	Sets the default caller address for remote function calls.
bool	autoRestoreRegs () const
	Returns true if automatic registers restore for remote function calls is enabled, false otherwise.
void	setAutoRestoreRegs (bool flag)
	Sets the automatic registers restore flag for remote function calls.
int	remoteCallTimeout () const
	Returns the default timeout (ms) for remote function calls.
void	setRemoteCallTimeout (int ms)
	Sets the default remote function call timeout in milliseconds.
uintptr_t	syscallGadget () const
	Returns the syscall gadget address for remote syscalls.
void	setSyscallGadget (uintptr_t address)
	Sets the syscall gadget address for remote syscalls.
template<class... Args>
kitty_rp_call_t	callFunctionFrom (uintptr_t callerAddress, uintptr_t functionAddress, Args &&...a)
	Call a function in the remote process and spoof return address.
template<class... Args>
kitty_rp_call_t	callFunction (uintptr_t functionAddress, Args &&...a)
	Call a function in the remote process.
template<class... Args>
kitty_rp_call_t	callSyscall (long sysnr, Args &&...a)
	Call a syscall in the remote process.
KT_BP_RESULT	setSoftBreakpointAndWait (uintptr_t address, const std::function< bool(uintptr_t bp_addr, user_regs_struct regs)> &cb, int timeout_ms)
	Sets and wait for software breakpoint at a given address.
KT_BP_RESULT	setHardBreakpointAndWait (uintptr_t address, KT_HW_BP_TYPE type, KT_HW_BP_SIZE size, int slot, const std::function< bool(uintptr_t bp_addr, user_regs_struct regs)> &cb, int timeout_ms)
	Set and wait for a hardware breakpoint/watchpoint at a single address.
KT_BP_RESULT	setHardExecBreakpointsAndWait (const std::vector< uintptr_t > &addresses, const std::function< bool(uintptr_t bp_addr, user_regs_struct regs)> &cb, int timeout_ms)
	Set hardware execute breakpoints on several addresses (one per debug slot) and wait for whichever is hit first. Thumb/ARM width is chosen per address.
bool	setHwBreakpoint (uintptr_t address, KT_HW_BP_TYPE type, KT_HW_BP_SIZE size, int slot)
	Sets a hardware breakpoint on a specified address for traced thread.
bool	clearHwBreakpoint (KT_HW_BP_TYPE type, int slot)
	Clears a hardware breakpoint on a specified address for traced thread.

Detailed Description

A class for tracing and controlling the execution of processes in a debugging environment.

Constructor & Destructor Documentation

◆ KittyTraceMgr()

KittyTraceMgr::KittyTraceMgr	(	pid_t	pid,
		uintptr_t	defaultCaller = 0,
		bool	autoRestoreRegs = true,
		int	remoteCallTimeout = 0,
		uintptr_t	syscallGadget = 0 )

inline

Constructs a new KittyTraceMgr object.

Parameters

pid	The process ID to trace.
defaultCaller	The default caller for remote function calls (optional).
autoRestoreRegs	Whether to automatically restore registers on remote function calls (optional).
remoteCallTimeout	The default remote call timeout (optional).

Here is the call graph for this function:

Member Function Documentation

◆ attach()

bool KittyTraceMgr::attach ( int options = 0 )

Attach to the process.

Parameters

options PTRACE options to use (optional).

Returns: True if the attach was successful, false otherwise.

◆ callFunction()

template<class... Args>

kitty_rp_call_t KittyTraceMgr::callFunction	(	uintptr_t	functionAddress,
		Args &&...	a )

inline

Call a function in the remote process.

Parameters

functionAddress	The address of the function to call.
...	Arguments to pass to the function.

Returns: The address of the return value.

◆ callFunctionFrom()

template<class... Args>

kitty_rp_call_t KittyTraceMgr::callFunctionFrom	(	uintptr_t	callerAddress,
		uintptr_t	functionAddress,
		Args &&...	a )

inline

Call a function in the remote process and spoof return address.

Parameters

callerAddress	The address of the caller.
functionAddress	The address of the function to call.
...	Arguments to pass to the function.

Returns: The address of the return value.

◆ callSyscall()

template<class... Args>

kitty_rp_call_t KittyTraceMgr::callSyscall	(	long	sysnr,
		Args &&...	a )

inline

Call a syscall in the remote process.

Note: If syscall gadget was not set then this function will write syscall instruction at PC/IP so PC/IP must be at valid executable address.

Parameters

sysnr	The syscall number.
...	Arguments to pass to the syscall.

Returns: The result of the syscall.

◆ clearHwBreakpoint()

bool KittyTraceMgr::clearHwBreakpoint	(	KT_HW_BP_TYPE	type,
		int	slot )

Clears a hardware breakpoint on a specified address for traced thread.

Parameters

type	The type of hardware breakpoint (e.g., execute, read, write, access).
slot	The slot number for the breakpoint.

Returns: True if the breakpoint was successfully cleared, false otherwise.

◆ cont()

bool KittyTraceMgr::cont ( int sig = 0 )

Continue the traced process thread.

Parameters

sig	Signal to send to the process (optional).

Returns: True if the continue was successful, false otherwise.

◆ detach()

bool KittyTraceMgr::detach ( )

Detach from the process.

Returns: True if the detach was successful, false otherwise.

◆ getArgFromRegs()

template<typename T>

T KittyTraceMgr::getArgFromRegs	(	user_regs_struct *	regs,
		uint32_t	arg_num )

inline

Get the n-th argument value from registers.

Parameters

regs	Pointer to the registers.
arg_num	The zero-indexed argument number (0 for 1st arg, 1 for 2nd, etc.).

Returns: Value of the requested argument.

Note: T must be a numeric type.

Here is the call graph for this function:

◆ getRegs()

bool KittyTraceMgr::getRegs ( user_regs_struct * regs ) const

Get the current registers of the process.

Parameters

regs	Pointer to store the registers.

Returns: True if the registers were retrieved successfully, false otherwise.

◆ getReturnAddressFromRegs()

uintptr_t KittyTraceMgr::getReturnAddressFromRegs ( user_regs_struct * regs )

inline

Get the return address value from registers.

Parameters

regs	Pointer to the registers.

Returns: Value of the return address.

Here is the call graph for this function:

◆ getSignalInfo()

bool KittyTraceMgr::getSignalInfo ( siginfo_t * si ) const

inline

Get the signal information of the process.

Parameters

si	Pointer to store the signal information.

Returns: True if the signal information was retrieved successfully, false otherwise.

◆ peekMem()

size_t KittyTraceMgr::peekMem	(	uintptr_t	addr,
		void *	buf,
		size_t	size ) const

Reads memory from a traced process using PTRACE_PEEKTEXT. Works around ptrace's word-sized limitation by reading aligned machine words and copying only the requested byte ranges.

Parameters

addr	Remote address to read from.
buf	Buffer to store the read data.
size	Size of the data to read.

Returns: Bytes read.

Here is the caller graph for this function:

◆ pokeMem()

size_t KittyTraceMgr::pokeMem	(	uintptr_t	addr,
		const void *	buf,
		size_t	size ) const

Writes memory from a traced process using PTRACE_POKETEXT. Works around ptrace's word-sized limitation by reading aligned machine words and copying only the requested byte ranges.

Parameters

addr	Remote address to write to.
buf	Buffer containing the data to write.
size	Size of the data to write.

Returns: Bytes written.

◆ seize()

bool KittyTraceMgr::seize ( int options = 0 )

Seize the process.

Parameters

options PTRACE options to use (optional).

Returns: True if the seize was successful, false otherwise.

◆ setAutoRestoreRegs()

void KittyTraceMgr::setAutoRestoreRegs ( bool flag )

inline

Sets the automatic registers restore flag for remote function calls.

Parameters

flag	True to enable automatic restore, false otherwise.

◆ setDefaultCaller()

void KittyTraceMgr::setDefaultCaller ( uintptr_t caller )

inline

Sets the default caller address for remote function calls.

Parameters

caller The default caller address.

◆ setHardBreakpointAndWait()

KT_BP_RESULT KittyTraceMgr::setHardBreakpointAndWait	(	uintptr_t	address,
		KT_HW_BP_TYPE	type,
		KT_HW_BP_SIZE	size,
		int	slot,
		const std::function< bool(uintptr_t bp_addr, user_regs_struct regs)> &	cb,
		int	timeout_ms )

Set and wait for a hardware breakpoint/watchpoint at a single address.

Parameters

address	The address to break/watch.
type	The type of hardware breakpoint (execute, read, write, access).
size	The size to watch (ignored for execute breakpoints; width is picked per address).
slot	The debug slot to use.
cb	Callback run on a hit; return true to accept (stop), false to skip and keep waiting.
timeout_ms	Timeout in milliseconds (0 or negative disables it).

Returns: Value of KT_BP_RESULT enum.

◆ setHardExecBreakpointsAndWait()

KT_BP_RESULT KittyTraceMgr::setHardExecBreakpointsAndWait	(	const std::vector< uintptr_t > &	addresses,
		const std::function< bool(uintptr_t bp_addr, user_regs_struct regs)> &	cb,
		int	timeout_ms )

Set hardware execute breakpoints on several addresses (one per debug slot) and wait for whichever is hit first. Thumb/ARM width is chosen per address.

Parameters

addresses	Code addresses to break on (capped to the number of debug slots).
cb	Callback run on a hit; return true to accept (stop), false to skip and keep waiting.
timeout_ms	Timeout in milliseconds (0 or negative disables it).

Returns: Value of KT_BP_RESULT enum.

◆ setHwBreakpoint()

bool KittyTraceMgr::setHwBreakpoint	(	uintptr_t	address,
		KT_HW_BP_TYPE	type,
		KT_HW_BP_SIZE	size,
		int	slot )

Sets a hardware breakpoint on a specified address for traced thread.

Parameters

address	The address to set the breakpoint at.
type	The type of hardware breakpoint (e.g., execute, read, write, access).
size	The size of the data to watch (ignored if bp type is KT_HW_BP_EXECUTE).
slot	The slot number for the breakpoint.

Returns: True if the breakpoint was successfully set, false otherwise.

◆ setOptions()

bool KittyTraceMgr::setOptions ( int options )

Set options for the process being traced.

Parameters

options PTRACE options to set.

Returns: True if the options were set successfully, false otherwise.

◆ setRegs()

bool KittyTraceMgr::setRegs ( user_regs_struct * regs ) const

Set the current registers of the process.

Parameters

regs	Pointer to the registers to set.

Returns: True if the registers were set successfully, false otherwise.

◆ setRemoteCallTimeout()

void KittyTraceMgr::setRemoteCallTimeout ( int ms )

inline

Sets the default remote function call timeout in milliseconds.

Parameters

ms	Timeout in milliseconds (0 or negaive to disable).

◆ setSoftBreakpointAndWait()

KT_BP_RESULT KittyTraceMgr::setSoftBreakpointAndWait	(	uintptr_t	address,
		const std::function< bool(uintptr_t bp_addr, user_regs_struct regs)> &	cb,
		int	timeout_ms )

Sets and wait for software breakpoint at a given address.

Parameters

address	The address to set the breakpoint at.
cb	Callback function to be executed when the breakpoint is hit.
timeout_ms	timeout in milliseconds (0 or negative value, will disable timeout)

Returns: Value of KT_BP_RESULT enum.

Note: Breakpoint will be set into on traced thread.

◆ setSyscallGadget()

void KittyTraceMgr::setSyscallGadget ( uintptr_t address )

inline

Sets the syscall gadget address for remote syscalls.

Parameters

address The address of syscall gadget.

◆ step()

bool KittyTraceMgr::step ( int steps = 1 ) const

Single-step the process.

Parameters

steps Number of steps to single-step (default is 1).

Returns: True if the step was successful, false otherwise.

◆ stop()

bool KittyTraceMgr::stop ( )

Stop the traced process thread.

Returns: True if the stop was successful, false otherwise.

◆ threads()

std::vector< pid_t > KittyTraceMgr::threads ( ) const

inline

Get a list of all threads in the traced process.

Returns: A vector of thread IDs.

Here is the call graph for this function:

◆ wait()

pid_t KittyTraceMgr::wait	(	int *	status,
		int	options,
		int	timeout_ms = 0 ) const

Wait for the process.

Parameters

status	Pointer to store the status of the process.
options	waitpid options to use.
timeout_ms	timeout in milliseconds (optional, default is 0)

Returns: The PID of the process.

◆ waitStep()

bool KittyTraceMgr::waitStep ( int steps = 1 ) const

Single-step and wait the process.

Parameters

steps Number of steps to single-step (default is 1).

Returns: True if the step was successful, false otherwise.

◆ waitSyscall()

bool KittyTraceMgr::waitSyscall ( ) const

Wait for the process to enter or exit a syscall.

Returns: True if the wait was successful, false otherwise.

The documentation for this class was generated from the following file:

/home/runner/work/KittyMemoryEx/KittyMemoryEx/KittyMemoryEx/KittyTrace.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ KittyTraceMgr()

Member Function Documentation

◆ attach()

◆ callFunction()

◆ callFunctionFrom()

◆ callSyscall()

◆ clearHwBreakpoint()

◆ cont()

◆ detach()

◆ getArgFromRegs()

◆ getRegs()

◆ getReturnAddressFromRegs()

◆ getSignalInfo()

◆ peekMem()

◆ pokeMem()

◆ seize()

◆ setAutoRestoreRegs()

◆ setDefaultCaller()

◆ setHardBreakpointAndWait()

◆ setHardExecBreakpointsAndWait()

◆ setHwBreakpoint()

◆ setOptions()

◆ setRegs()

◆ setRemoteCallTimeout()

◆ setSoftBreakpointAndWait()

◆ setSyscallGadget()

◆ step()

◆ stop()

◆ threads()

◆ wait()

◆ waitStep()

◆ waitSyscall()