API

API Usage (C++)

The C++ API lives in userland/include/libsnakedrv.hpp and wraps the IOCTL contract defined in snakedrv.h. Below is a concise workflow for privileged memory access and hardware breakpoints.

Setup

#include "libsnakedrv.hpp"
#include <iostream>

int main() {
    snake::Driver drv;
    if (!drv.open()) {
        std::cerr << "Driver open failed (is /dev/snakedrv accessible?)\n";
        return 1;
    }
    if (!drv.attach(/* target pid */)) {
        std::cerr << "Attach failed\n";
        return 1;
    }

    // Read a 32-bit value
    uint32_t val = drv.read<uint32_t>(0x7ffdf000);
    std::cout << "val=" << val << "\n";

    // Write a 32-bit value
    drv.write<uint32_t>(0x7ffdf000, 1337);

    // Set a read/write watchpoint on 4 bytes
    auto bp = drv.setBreakpoint(0x7ffdf000,
                                snake::BreakpointType::ReadWrite,
                                snake::BreakpointLength::Byte4);

    // Poll breakpoint hits
    for (auto& ev : drv.pollEvents(16)) {
        std::cout << "Hit at 0x" << std::hex << ev.address
                  << " accessed 0x" << ev.accessedAddress
                  << " size=" << std::dec << ev.accessSize
                  << (ev.isWrite ? " [W]" : " [R]") << "\n";
    }

    if (bp) drv.clearBreakpoint(*bp);
    drv.detach();
    return 0;
}

Key methods

• Connection: open(), close(), isOpen()
• Attachment: attach(pid), detach(), isAttached(), attachedPid()
• Memory:
  • readMemory(addr, buf, size) / writeMemory(addr, buf, size)
  • Templates: read<T>(addr), write<T>(addr, value)
  • Helpers: readBytes, writeBytes, readString, writeString
• Regions: queryMemoryRegions(start), findRegion(addr)
• Breakpoints: setBreakpoint(addr, type, length), clearBreakpoint, clearAllBreakpoints
• Debug events: pollEvents(maxEvents, timeout_ms)
• Event loop: setEventCallback, clearEventCallback, startEventLoop, stopEventLoop
• Registers: getRegisters(tid), setRegisters(tid, regs)
• Control: continueExecution, singleStep, suspend, resume, kill
• Physical: readPhys, writePhys, virtToPhys
• Injection helpers: injectAlloc, injectProtect, injectThread, manualMapLibrary, executeShellcode
• Utilities: isDriverAvailable(), getDriverVersion(), listProcesses(), findProcessByName()

Types and structs

• snake::MemoryRegion: base, size, protection, type, inode, path
• snake::Breakpoint: slot/id, address, type, length
• snake::DebugEvent: type, pid/tid, instruction address, accessed address, access size, DR slot, registers, instruction bytes, sequence, timestamp
• snake::Registers: general-purpose, DR0-DR7, XMM, flags

Notes

• Calls are synchronous; heavy polling should be rate-limited.
• Hardware breakpoints are limited to four slots (DR0-DR3) per attached process.
• Thread enumeration (getKernelThreads) is currently a stub and returns an empty list.
• Ensure the process remains alive and permissions allow access (group snakeengine).