ptrace.hxx File Reference

#include <optional>
#include <stdint.h>
#include <elf.h>
#include <linux/audit.h>
#include <sys/ptrace.h>
#include <linux/ptrace.h>
#include <cosmos/BitMask.hxx>
#include <cosmos/dso_export.h>
#include <cosmos/memory.hxx>
#include <cosmos/proc/types.hxx>

Go to the source code of this file.

Classes
struct	cosmos::ptrace::SyscallInfo
	Wrapper around data structure used with ptrace::Request::GET_SYSCALL_INFO. More...
class	cosmos::ptrace::PeekSigInfo
	Wrapper around data structure used with ptrace::Request::PEEKSIGINFO. More...

Typedefs
using	cosmos::ptrace::Opts = BitMask<Opt>

Enumerations
enum class	cosmos::ptrace::Opt : intptr_t {   EXITKILL = PTRACE_O_EXITKILL , TRACECLONE = PTRACE_O_TRACECLONE , TRACEEXEC = PTRACE_O_TRACEEXEC , TRACEEXIT = PTRACE_O_TRACEEXIT ,   TRACEFORK = PTRACE_O_TRACEFORK , TRACEVFORK = PTRACE_O_TRACEVFORK , TRACEVFORKDONE = PTRACE_O_TRACEVFORKDONE , TRACESYSGOOD = PTRACE_O_TRACESYSGOOD ,   TRACESECCOMP = PTRACE_O_TRACESECCOMP , SUSPENDSECCOMP = PTRACE_O_SUSPEND_SECCOMP }
	Different options which can be set for a tracee. More...
enum class	cosmos::ptrace::Event {   VFORK = PTRACE_EVENT_VFORK , FORK = PTRACE_EVENT_FORK , CLONE = PTRACE_EVENT_CLONE , VFORK_DONE = PTRACE_EVENT_VFORK_DONE ,   EXEC = PTRACE_EVENT_EXEC , EXIT = PTRACE_EVENT_EXIT , STOP = PTRACE_EVENT_STOP , SECCOMP = PTRACE_EVENT_SECCOMP }
	Different events that can occur in a tracee leading to ptrace-event-stop. More...
enum class	cosmos::ptrace::RegisterType { GENERAL_PURPOSE = NT_PRSTATUS , FLOATING_POINT = NT_FPREGSET }
	Different types of register sets that can be read from a tracee via Request::GETREGSET. More...
enum class	cosmos::ptrace::Request {   TRACEME = PTRACE_TRACEME , PEEKDATA = PTRACE_PEEKDATA , PEEKTEXT = PTRACE_PEEKTEXT , PEEKUSER = PTRACE_PEEKUSER ,   POKEDATA = PTRACE_POKEDATA , POKEUSER = PTRACE_POKEUSER , GETREGS = PTRACE_GETREGS , GETFPREGS = PTRACE_GETFPREGS ,   GETREGSET = PTRACE_GETREGSET , SETREGS = PTRACE_SETREGS , SETFPREGS = PTRACE_SETFPREGS , SETREGSET = PTRACE_SETREGSET ,   GETSIGINFO = PTRACE_GETSIGINFO , SETSIGINFO = PTRACE_SETSIGINFO , PEEKSIGINFO = PTRACE_PEEKSIGINFO , GETSIGMASK = PTRACE_GETSIGMASK ,   SETSIGMASK = PTRACE_SETSIGMASK , SETOPTIONS = PTRACE_SETOPTIONS , GETEVENTMSG = PTRACE_GETEVENTMSG , CONT = PTRACE_CONT ,   SYSCALL = PTRACE_SYSCALL , SINGLESTEP = PTRACE_SINGLESTEP , LISTEN = PTRACE_LISTEN , KILL = PTRACE_KILL ,   INTERRUPT = PTRACE_INTERRUPT , ATTACH = PTRACE_ATTACH , SEIZE = PTRACE_SEIZE , SECCOMP_GET_FILTER = PTRACE_SECCOMP_GET_FILTER ,   DETACH = PTRACE_DETACH , GET_THREAD_AREA = PTRACE_GET_THREAD_AREA , GET_SYSCALL_INFO = PTRACE_GET_SYSCALL_INFO }
	Basic requests that can be passed to the ptrace() system call. More...
enum class	cosmos::ptrace::Arch : uint32_t { X86_64 = AUDIT_ARCH_X86_64 , I386 = AUDIT_ARCH_I386 }
	System call ABI architecture. More...

Functions
std::optional< long >	cosmos::ptrace::trace (const ptrace::Request req, const ProcessID pid, void *addr=nullptr, void *data=nullptr)
	Perform a tracer request.
void	cosmos::ptrace::traceme ()
	Inform the kernel that this process is to be traced by its parent.

Detailed Description

Wrappers around data structures for the ptrace() system call.

ptrace() is a complex ioctl() like system call using varargs. To improve readability and type safety, every ptrace command is made available through an individual wrapper found in the Tracee class.

Definition in file ptrace.hxx.

Typedef Documentation

Opts

using cosmos::ptrace::Opts = BitMask<Opt>

Definition at line 55 of file ptrace.hxx.

Enumeration Type Documentation

Arch

enum class cosmos::ptrace::Arch : uint32_t

strong

System call ABI architecture.

This is currently shortened just for x86 ABIs until we add support for more exotics archs.

Definition at line 174 of file ptrace.hxx.

                : uint32_t {
        X86_64 = AUDIT_ARCH_X86_64,
        I386   = AUDIT_ARCH_I386
};

Event

enum class cosmos::ptrace::Event

strong

Different events that can occur in a tracee leading to ptrace-event-stop.

Enumerator
VFORK	vfork() (or clone with VFORK flag) is upcoming.
FORK	fork() (or clone with SIGCHLD as exit signal) is upcoming.
CLONE	clone() is upcoming.
VFORK_DONE	vfork() (or clone() with VFORK flag) was finished but not yet returned.
EXEC	exec() is in progress, the thread ID is the new one already.
EXIT	exit() is upcoming.
STOP	Initial tracee stop after SEIZE or on new child creations.
SECCOMP	Stop triggered by a seccomp rule on tracee syscall entry.

Definition at line 58 of file ptrace.hxx.

                 {
        VFORK      = PTRACE_EVENT_VFORK,
        FORK       = PTRACE_EVENT_FORK,
        CLONE      = PTRACE_EVENT_CLONE,
        VFORK_DONE = PTRACE_EVENT_VFORK_DONE,
        EXEC       = PTRACE_EVENT_EXEC,
        EXIT       = PTRACE_EVENT_EXIT,
        STOP       = PTRACE_EVENT_STOP,
        SECCOMP    = PTRACE_EVENT_SECCOMP
};

Opt

enum class cosmos::ptrace::Opt : intptr_t

strong

Different options which can be set for a tracee.

Enumerator
EXITKILL	When the tracer exits, the tracees will be sent SIGKILL.
TRACECLONE	Stop on clone(2) and automatically trace the newly cloned process.
TRACEEXEC	Stop on execve(2).
TRACEEXIT	Stop the tracee at when it exits.
TRACEFORK	Stop on fork(2) and automatically trace the newly forked process.
TRACEVFORK	Stop on vfork(2) and automatically trace the newly forked proc.
TRACEVFORKDONE	Stop tracee at completion of vfork(2).
TRACESYSGOOD	For better detection of system-call-stops, sets bit 7 in the si_code field (WSTOPSIG() == SIGTRAP|0x80).
TRACESECCOMP	Stop when a SECCOMP_RET_TRACE rule is triggered.
SUSPENDSECCOMP	Suspends the tracee's seccomp protections.

Definition at line 32 of file ptrace.hxx.

               : intptr_t { /* is a void* in ptrace(2), so we need pointer width */
        EXITKILL       = PTRACE_O_EXITKILL,
        TRACECLONE     = PTRACE_O_TRACECLONE,
        TRACEEXEC      = PTRACE_O_TRACEEXEC,
        TRACEEXIT      = PTRACE_O_TRACEEXIT,
        TRACEFORK      = PTRACE_O_TRACEFORK,
        TRACEVFORK     = PTRACE_O_TRACEVFORK,
        TRACEVFORKDONE = PTRACE_O_TRACEVFORKDONE,
        TRACESYSGOOD   = PTRACE_O_TRACESYSGOOD,
        TRACESECCOMP   = PTRACE_O_TRACESECCOMP,
        SUSPENDSECCOMP = PTRACE_O_SUSPEND_SECCOMP,
};

RegisterType

enum class cosmos::ptrace::RegisterType

strong

Different types of register sets that can be read from a tracee via Request::GETREGSET.

Definition at line 78 of file ptrace.hxx.

                        {
        GENERAL_PURPOSE = NT_PRSTATUS,
        FLOATING_POINT  = NT_FPREGSET
};

Request

enum class cosmos::ptrace::Request

strong

Basic requests that can be passed to the ptrace() system call.

Note

On system call level this has an actual enum __ptrace_request type, thus there is no defined underlying type and we keep the compiler's default.

Enumerator
TRACEME	The tracee asks to be traced by its parent.
PEEKDATA	Read a word at a given address of the tracee's memory.
PEEKTEXT	Read a word at a given offset of the tracee's TEXT data (the same as PEEKDATA on Linux).
PEEKUSER	Read a word at a given offset of the tracee's USER data (holds registers and other metadata).
POKEDATA	Write a word at the given address into the tracee's memory.
POKEUSER	Write a word at the given offset into the tracee's USER data.
GETREGS	Copy the tracee's general-purpose registers to the given address in the tracer.
GETFPREGS	Copy the tracee's floating-point registers to the given address in the tracer.
GETREGSET	Reg the tracee's registers in an architecture dependent way.
SETREGS	Modify the tracee's general-purpose registers (not available on all architectures).
SETFPREGS	Modify the tracee's floating-point registers.
SETREGSET	Modify the tracee's registers, analogous to GETREGSET.
GETSIGINFO	Retrieve information about the signal that cause the tracee to stop. Copies a siginfo_t structure.
SETSIGINFO	Modify the tracee's signal information (used when the tracer catched a signal that would normally be delivered to the tracee).
PEEKSIGINFO	Retrieve siginfo_t structures without removing them from the tracee's queue.
GETSIGMASK	Retrieves a copy of the mask of blocked signals from the tracee.
SETSIGMASK	Change the tracee's mask of blocked signals.
SETOPTIONS	Set ptrace options (see ptrace::Opts)
GETEVENTMSG	Retrieve a message (unsigned long) about the ptrace event that just happened.
CONT	Restart the stopped tracee. Non-zero data is interpreted as a signal number to be delivered to the tracee.
SYSCALL	Restart the stopped tracee like CONT, but arrange for the tracee to be stopped at entry/exit to/from a system call.
SINGLESTEP	Like SYSCALL, but arrange for the tracee to be stopped after a single instruction.
LISTEN	Restart a stopped tracee, but let it enter a SIGSTOP like state. Works only for SEIZE'd tracees.
KILL	Send a SIGKILL to the tracee (this is buggy, don't use it).
INTERRUPT	Stop a tracee. Works only for SIZE'd tracees.
ATTACH	Attach to the specified process, making it a tracee of the caller.
SEIZE	Like ATTACH but does not stop the process.
SECCOMP_GET_FILTER	Dump the tracee's classic BPF filters.
DETACH	Restart the stopped tracee, but first detach from it.
GET_THREAD_AREA	Performs an operation similar to get_thread_area().
GET_SYSCALL_INFO	Retrieve information about the system call that cause the stop.

Definition at line 89 of file ptrace.hxx.

                   {
        TRACEME            = PTRACE_TRACEME,
        PEEKDATA           = PTRACE_PEEKDATA,
        PEEKTEXT           = PTRACE_PEEKTEXT,
        PEEKUSER           = PTRACE_PEEKUSER,
        POKEDATA           = PTRACE_POKEDATA,
        POKEUSER           = PTRACE_POKEUSER,
        GETREGS            = PTRACE_GETREGS,
        GETFPREGS          = PTRACE_GETFPREGS,
        GETREGSET          = PTRACE_GETREGSET,
        SETREGS            = PTRACE_SETREGS,
        SETFPREGS          = PTRACE_SETFPREGS,
        SETREGSET          = PTRACE_SETREGSET,
        GETSIGINFO         = PTRACE_GETSIGINFO,
        SETSIGINFO         = PTRACE_SETSIGINFO,
        PEEKSIGINFO        = PTRACE_PEEKSIGINFO,
        GETSIGMASK         = PTRACE_GETSIGMASK,
        SETSIGMASK         = PTRACE_SETSIGMASK,
        SETOPTIONS         = PTRACE_SETOPTIONS,
        GETEVENTMSG        = PTRACE_GETEVENTMSG,
        CONT               = PTRACE_CONT,
        SYSCALL            = PTRACE_SYSCALL,
        SINGLESTEP         = PTRACE_SINGLESTEP,
        // When in syscall-enter-stop, change the number of the system call to execute (only supported on arm)
        // (it seems this has been removed from system headers by now)
#ifdef PTRACE_SET_SYSCALL
        SET_SYSCALL        = PTRACE_SET_SYSCALL,
#endif
#ifdef PTRACE_SYSEMU
        SYSEMU             = PTRACE_SYSEMU,
        SYSEMU_SINGLESTEP  = PTRACE_SYSEMU_SINGLESTEP,
#endif
        LISTEN             = PTRACE_LISTEN,
        KILL               = PTRACE_KILL,
        INTERRUPT          = PTRACE_INTERRUPT,
        ATTACH             = PTRACE_ATTACH,
        SEIZE              = PTRACE_SEIZE,
        SECCOMP_GET_FILTER = PTRACE_SECCOMP_GET_FILTER,
        DETACH             = PTRACE_DETACH,
        GET_THREAD_AREA    = PTRACE_GET_THREAD_AREA,
#if PTRACE_SET_THREAD_AREA
        SET_THREAD_AREA    = PTRACE_SET_THREAD_AREA,
#endif
        GET_SYSCALL_INFO   = PTRACE_GET_SYSCALL_INFO,
};

Function Documentation

trace()

std::optional< long > COSMOS_API cosmos::ptrace::trace	(	const ptrace::Request	req,
		const ProcessID	pid,
		void *	addr = nullptr,
		void *	data = nullptr )

Perform a tracer request.

This is only a thin wrapper around the actual ptrace() system call. For a more convenient and safe interface use the Tracee class which splits this call into its individual sub-operations.

On error conditions this throws an ApiError. Depending on req a long value is returned (for PEEK operations, SECCOMP_GET_FILTER and GET_SYSCALL_INFO), otherwise std::nullopt.

The necessity and meaning of addr and data are also depending on the actual req.

Definition at line 8 of file ptrace.cxx.

                                                                                        {
        const auto is_peek =
                req == Request::PEEKDATA ||
                req == Request::PEEKTEXT ||
                req == Request::PEEKUSER;
 
        if (is_peek) {
                // PEEK requests have difficult error handling, we need to
                // explicitly reset the errno.
                reset_errno();
        }
 
        const auto ret = ::ptrace(
                        static_cast<__ptrace_request>(to_integral(req)),
                        to_integral(pid), addr, data);
 
        if (ret == -1) {
                if (is_peek && !is_errno_set()) {
                        // we actually peeked a -1
                        return ret;
                }
 
                cosmos_throw (ApiError("ptrace()"));
        }
 
        // only these ptrace requests return meaningful data, otherwise just
        // zero on success.
        if (is_peek || req == Request::SECCOMP_GET_FILTER || req == Request::GET_SYSCALL_INFO) {
                return ret;
        }
 
        return std::nullopt;
}

traceme()

void COSMOS_API cosmos::ptrace::traceme

(

)

Inform the kernel that this process is to be traced by its parent.

A typical pattern for tracing a child process is to:

• fork()
• traceme() and raise(SIGSTOP) in the child process
• wait for ptrace-signal-stop in the parent

Since this does not rely on ptrace::Request::SEIZE to attach to the tracee, certain features of the ptrace API won't be available when using the TRACEME approach.

Definition at line 42 of file ptrace.cxx.

               {
        // all arguments except the request are ignored.
        // this is not clearly documented but I checked the kernel code to verify.
        trace(Request::TRACEME, ProcessID{0}, nullptr, nullptr);
}