Skip to content

About

Cross-platform process memory read/write

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

Repository files navigation

procmod-core

procmod-core

Cross-platform process memory read/write for Rust.


Read and write memory in external processes on macOS, Linux, and Windows. Enumerate loaded modules and memory regions. Pure Rust, no C FFI wrappers.

Install

[dependencies]
procmod-core = "3"

Quick start

Read a game's player health from a known memory address:

use procmod_core::{Address, Process};

fn main() -> procmod_core::Result<()> {
    let game = Process::attach(pid)?;

    // read the player's health at a known offset
    let health: f32 = game.read(Address::new(0x7FF6_1A00_4200))?;
    println!("player health: {}", health);

    Ok(())
}

Usage

Attach to a process

// Existing read-write attachment
let process = Process::attach(1234)?;

// Capability-restricted attachment with no write methods and minimal Windows rights
let process = Process::attach_read_only(1234)?;
println!("target architecture: {:?}", process.architecture());

A 64-bit Windows inspector can attach to a 32-bit target. Use Address, Pointer32, and Pointer64 for target addresses rather than interpreting remote pointers as the inspector's usize.

Read memory

Typed reads accept any type that implements AnyBitPattern, meaning every byte sequence of the right size is a valid value. Numbers, arrays of numbers, Pointer32, and Pointer64 qualify. Read bool, char, and enums through their underlying integer type.

let hp: f32 = process.read(address)?;
let position: [f32; 3] = process.read(address)?;
let bytes = process.read_bytes(address, 64)?;

Game structs can derive the trait with bytemuck (bytemuck = { version = "1", features = ["derive"] }). Math types from crates such as glam implement it behind their bytemuck feature.

#[derive(Clone, Copy, bytemuck::AnyBitPattern)]
#[repr(C)]
struct Transform {
    position: [f32; 3],
    yaw: f32,
    flags: u8,
}

let transform: Transform = process.read(address)?;

Write memory

Writes are unsafe. Writing into the current process, or into memory it shares with the target, can break data that Rust code relies on, and procmod cannot tell which memory that is. Typed writes also require NoUninit, which rules out types with padding bytes.

// SAFETY: the target is a separate game process and the address is its health field
unsafe { process.write(address, &100.0_f32)? };

// SAFETY: patching code in the target process, not in this one
unsafe { process.write_bytes(address, &[0x90, 0x90, 0x90])? };

Enumerate modules

Find where a game's main executable or a specific DLL is loaded, then scan from its base address:

let modules = process.modules()?;
for m in &modules {
    println!("{}: base={:#x} size={:#x}", m.name, m.base.value(), m.size);
}

// find a specific module
let engine = modules.iter().find(|m| m.name == "engine.dll").unwrap();
let scan_region = process.read_bytes(engine.base, engine.size)?;

Query memory regions

Understand what memory is mapped and with what permissions - useful for finding writable data segments or executable code:

let regions = process.regions()?;
for r in &regions {
    println!("{:#x} ({} bytes) {}", r.base, r.size, r.protection);
}

// find all writable regions
let writable: Vec<_> = regions.iter().filter(|r| r.protection.write).collect();

Platform support

Platform Backend Architectures
macOS Mach VM (mach_vm_read_overwrite / mach_vm_write) x86_64, arm64
Linux process_vm_readv / process_vm_writev x86_64, arm64
Windows ReadProcessMemory / WriteProcessMemory x86, x86_64 targets from an x86_64 inspector

Permissions

  • macOS: Requires the com.apple.security.cs.debugger entitlement or running as root. SIP must allow task_for_pid on the target.
  • Linux: Requires CAP_SYS_PTRACE or appropriate ptrace_scope settings. Reading a child process's memory generally works without extra privileges.
  • Windows: Requires SeDebugPrivilege for system processes. Standard user can read/write processes they own.

Upgrading from 2.x

See CHANGELOG.md.

License

MIT

About

Cross-platform process memory read/write

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages