diff --git a/README.md b/README.md index 8f1359b..815aa84 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,15 @@ ## haxor memory hacking library + +## using +```rust +let proc = Process::from("notepad.exe")?; +let some_val = proc.read_mem::(0xDEADBEEF)?; +``` + +```rust +let proc = Process::from(1337)?; +let chain: Vec = vec![proc.base_address, 0x4B1D, 0x8, 0x12]; +let some_addr: usize = proc.resolve_pointer_chain(&chain)?; +let some_val = proc.read_mem::(some_addr)?; +``` diff --git a/src/error.rs b/src/error.rs index 0c5816f..808bca9 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,15 +1,21 @@ use thiserror::Error; #[derive(Debug, Error)] +/// errors that can occur during interaction with a process pub enum Error { + /// there was a failure in obtaining the handle to a process #[error("failed to obtain handle")] ObtainHandleError(String), + /// there was a failure when reading or writing the process's memory #[error("failed to access process memory")] AccessMemoryError(String), + /// there was a failure in building the Process or Module struct #[error("failed to create process")] CreateProcessError(String), + /// there was a failure in creating a snapshot of processes or modules #[error("failed to create snapshot")] CreateSnapshotError(String), + /// there was a failure in conversion between integers #[error("failed to convert integer")] ConvertIntegerError(#[from] std::num::TryFromIntError), } diff --git a/src/lib.rs b/src/lib.rs index 4e3bdd1..dbbed8d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,8 @@ #![doc = include_str!("../README.md")] +#![warn(missing_docs)] mod error; +/// types and methods to ease the r/w of a process's memory pub mod process; pub use error::Error; diff --git a/src/process/module.rs b/src/process/module.rs index 4ad09a2..1a68913 100644 --- a/src/process/module.rs +++ b/src/process/module.rs @@ -1,8 +1,14 @@ #[derive(Debug, Default)] +/// a module running within a process pub struct Module { + /// the parent process id (th32ProcessID) pub process_id: u32, + /// the module name (szModule) pub name: String, + /// the module executable path (szExePath) pub path: String, + /// the module base address (modBaseAddr) pub base_address: usize, + /// the module base size (modBaseSize) pub base_size: usize, } diff --git a/src/process/process.rs b/src/process/process.rs index 3c52f4d..f7358f0 100644 --- a/src/process/process.rs +++ b/src/process/process.rs @@ -3,8 +3,11 @@ use super::{handle::Handle, memory, module::Module, snapshot}; use derive_more::derive::Display; #[derive(Display)] +/// an identifier for searching for a process pub enum Identifier { + /// the process id Pid(u32), + /// the process name Name(String), } @@ -21,10 +24,15 @@ impl From<&str> for Identifier { } #[derive(Debug, Default, Clone)] +/// a process running on the system pub struct Process { + /// the process name (szExeFile) pub name: String, + /// the process id (th32ProcessID) pub id: u32, + /// the base address of the module with the same name as `name` (modBaseAddr) pub base_address: usize, + /// the process handle (HANDLE) pub handle: Handle, } @@ -32,6 +40,7 @@ unsafe impl Send for Process {} unsafe impl Sync for Process {} impl Process { + /// initialize a `Process` from a pid or a process name pub fn from>(identifier: T) -> Result { let identifier = identifier.into(); let Some(snapshot) = (match identifier { @@ -56,6 +65,7 @@ impl Process { Ok(process) } + /// get the `Module` of a `Process` by name pub fn module(&self, name: &str) -> Result { let Some(snapshot) = snapshot::ModuleSnapshot::get_modules(self.id)? .into_iter() @@ -75,6 +85,7 @@ impl Process { Ok(module) } + /// follow a pointer chain to the end and return an address pub fn resolve_pointer_chain(&self, chain: &[usize]) -> Result { let mut chain = chain.to_vec(); let mut address = chain.remove(0); @@ -85,12 +96,14 @@ impl Process { Ok(address + chain.remove(0)) } + /// read a given `address` of process's memory pub fn read_mem(&self, address: usize) -> Result { let mut value = Default::default(); memory::read(&self.handle, address, &mut value)?; Ok(value) } + /// write a `value` at given `address` of process's memory pub fn write_mem(&self, address: usize, mut value: T) -> Result<(), crate::Error> { memory::write(&self.handle, address, &mut value)?; Ok(())