Architecture

Architecture

SnakeEngine Driver is a two-part system: a kernel module (snakedrv.ko) and a userland C++ library (libsnakedrv). The design mirrors Cheat Engine's DBK approach: minimal kernel surface area with a typed userland API.

Components

• Kernel module (kernel/snakedrv_main.c)

  • Character device /dev/snakedrv
  • Process attach/detach with refcounts and locking
  • Memory read/write (forced) via access_process_vm
  • Region enumeration (protection/type/inode/path)
  • Hardware breakpoints DR0-DR3 using perf_event/hw_breakpoint
  • Debug event queue (instruction address, accessed address, access type/size, DR slot, sequence)
  • Module parameters: max_attached_processes, event_queue_size, debug_level

• Shared ABI (userland/include/snakedrv.h)

  • IOCTL magic 0x53
  • Structs: snake_memory_op, snake_memory_region, snake_memory_query, snake_process_op/info, snake_hw_breakpoint, snake_debug_event, snake_cpu_regs
  • Error codes for consistent mapping in userland

• Userland library (userland/src/libsnakedrv.cpp, include/libsnakedrv.hpp)

  • RAII wrapper on /dev/snakedrv
  • High-level API: open/close, attach/detach, read/write, query regions, set/clear HW breakpoints, register access, and event polling/callbacks
  • Utilities: process listing, driver availability checks
  • Injection helpers: allocation, protection, thread start, manual ELF mapping

• Automation (deploy.sh)

  • Build (kernel + userland), install (DKMS or direct), udev, modprobe config, SELinux/AppArmor (optional), status, clean, VM sync helper

• Security artifacts (security/)

  • 99-snakedrv.rules (udev), snakeengine.apparmor, snakeengine.te/.fc (SELinux)

Data flow

1. Userland opens /dev/snakedrv and issues IOCTLs defined in snakedrv.h.
2. Kernel module validates, executes memory/process/debug operations, and emits debug events.
3. Userland polls events (or uses the callback loop) and maps kernel structs to C++ types (DebugEvent, Registers, Breakpoint, MemoryRegion).

Hardware breakpoints

• Types: execute, write, read/write
• Lengths: 1, 2, 4, 8 bytes
• Backed by perf_event for stability; events captured and queued for userland

Manual mapping (high level)

• Allocate memory in the target process via the driver.
• Resolve imports by scanning the target process modules.
• Apply relocations and write the payload in chunks.
• Optionally unlink the VMA to hide the mapping (kernel 6.1+ Maple Tree).
• Start a remote thread at the payload's entry point.

Versioning

• Version constants live in snakedrv.h (SNAKEDRV_VERSION_*).
• DKMS uses dkms.conf for kernel-version portability.

Limits and parameters

• max_attached_processes (default 16): concurrent attachments
• event_queue_size (default 256): pending debug events before drop
• debug_level (0-3): kernel log verbosity