0.3.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "haxor"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 readme = "README.md"
 license = "Apache-2.0"
@@ -9,7 +9,7 @@ repository = "https://github.com/elituf/haxor"
 keywords = ["memory", "game", "hacking", "process"]
 
 [dependencies]
-derive_more = { version = "2", features = ["display"] }
+derive_more = { version = "2", features = ["debug", "display"] }
 log = "0.4"
 thiserror = "2"
 
@@ -21,3 +21,6 @@ features = [
     "Win32_System_Diagnostics_ToolHelp",
     "Win32_System_Diagnostics_Debug",
 ]
+
+[lib]
+doctest = false

README.md

@@ -1,14 +1,14 @@
 ## haxor
-memory hacking library
+windows external memory hacking library
 
 ## using
 ```rust
-let proc = Process::from("notepad.exe")?;
+let proc = Process::find("notepad.exe")?;
 let some_val = proc.read_mem::<i32>(0xDEADBEEF)?;
 ```
 
 ```rust
-let proc = Process::from(1337)?;
+let proc = Process::find(1337)?;
 let chain: Vec<usize> = vec![proc.base_address, 0x4B1D, 0x8, 0x12];
 let some_addr: usize = proc.resolve_pointer_chain(&chain)?;
 let some_val = proc.read_mem::<u8>(some_addr)?;

src/error.rs

@@ -9,12 +9,15 @@ pub enum Error {
     /// 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 building the Process or Module struct
+    #[error("failed to get process/module")]
+    ProcessError(String),
+    /// there was a failure in resolving a pointer chain
+    #[error("failed to resolve pointer chain")]
+    ResolvePointerChainError(String),
     /// there was a failure in conversion between integers
     #[error("failed to convert integer")]
     ConvertIntegerError(#[from] std::num::TryFromIntError),

src/lib.rs

@@ -5,5 +5,6 @@ mod error;
 /// types and methods to ease the r/w of a process's memory
 pub mod process;
 mod sys;
+mod tests;
 
 pub use error::Error;

src/process.rs

@@ -2,7 +2,140 @@ use crate::{
     Error,
     sys::{handle::Handle, memory, snapshot},
 };
-use derive_more::derive::Display;
+use derive_more::{Debug, derive::Display};
+
+#[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 name `name` (modBaseAddr)
+    #[debug("0x{base_address:X}")]
+    pub base_address: usize,
+    /// the process handle (HANDLE)
+    pub handle: Handle,
+}
+
+impl Process {
+    /// initialize a `Process` from a pid or a process name
+    ///
+    /// ### examples
+    ///
+    /// ```rust
+    /// let proc = Process::find(1337)?;
+    /// ```
+    ///
+    /// ```rust
+    /// let proc = Process::find("notepad.exe")?;
+    /// ```
+    pub fn find<T: Into<Identifier>>(identifier: T) -> Result<Self, Error> {
+        let identifier = identifier.into();
+        let snapshot = snapshot::ProcessSnapshot::get_processes()?
+            .into_iter()
+            .find(|snapshot| match identifier {
+                Identifier::Pid(pid) => snapshot.id == pid,
+                Identifier::Name(ref name) => snapshot.name == *name,
+            })
+            .ok_or_else(|| {
+                Error::ProcessError(format!(
+                    "failed to find a process with identifier `{identifier}`",
+                ))
+            })?;
+        let mut process = Self {
+            name: snapshot.name,
+            id: snapshot.id,
+            base_address: 0,
+            handle: Handle::from_pid(snapshot.id)?,
+        };
+        process.base_address = process.module(&process.name)?.base_address;
+        Ok(process)
+    }
+
+    /// get a `Module` of a `Process` by name (case-insensitive)
+    pub fn module<T: AsRef<str>>(&self, name: T) -> Result<Module, Error> {
+        let name = name.as_ref();
+        let Some(snapshot) = snapshot::ModuleSnapshot::get_modules(self.id)?
+            .into_iter()
+            .find(|snapshot| name.eq_ignore_ascii_case(&snapshot.name))
+        else {
+            return Err(Error::ProcessError(format!(
+                "failed to find a module with identifier `{name}`",
+            )));
+        };
+        let module = Module {
+            process_id: self.id,
+            name: snapshot.name,
+            path: snapshot.path,
+            base_address: snapshot.base_address,
+            base_size: snapshot.base_size,
+        };
+        Ok(module)
+    }
+
+    /// get all `Module`s of a `Process`
+    pub fn modules(&self) -> Result<Vec<Module>, Error> {
+        Ok(snapshot::ModuleSnapshot::get_modules(self.id)?
+            .iter()
+            .cloned()
+            .map(|snapshot| Module {
+                process_id: self.id,
+                name: snapshot.name,
+                path: snapshot.path,
+                base_address: snapshot.base_address,
+                base_size: snapshot.base_size,
+            })
+            .collect())
+    }
+
+    /// follow a pointer chain to the end and return an address
+    pub fn resolve_pointer_chain<T: AsRef<[usize]>>(&self, chain: T) -> Result<usize, Error> {
+        let chain = chain.as_ref();
+        if chain.is_empty() {
+            return Err(Error::ResolvePointerChainError("chain was empty".into()));
+        }
+        if chain.len() == 1 {
+            return Ok(chain[0]);
+        }
+        let mut address = chain[0];
+        for &offset in &chain[1..(chain.len() - 1)] {
+            address += offset;
+            address = self.read_mem(address)?;
+        }
+        Ok(address + chain.last().expect("chain should have a last element"))
+    }
+
+    /// read a given `address` of process's memory
+    pub fn read_mem<T: Default>(&self, address: usize) -> Result<T, Error> {
+        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<T>(&self, address: usize, mut value: T) -> Result<(), Error> {
+        memory::write(&self.handle, address, &mut value)?;
+        Ok(())
+    }
+}
+
+#[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)
+    #[debug("0x{base_address:X}")]
+    pub base_address: usize,
+    /// the module base size (modBaseSize)
+    #[debug("0x{base_size:X}")]
+    pub base_size: usize,
+}
 
 #[derive(Display)]
 /// an identifier for searching for a process
@@ -25,103 +158,8 @@ 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,
-}
-
-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<T: Into<Identifier>>(identifier: T) -> Result<Self, Error> {
-        let identifier = identifier.into();
-        let snapshot = snapshot::ProcessSnapshot::get_processes()?
-            .into_iter()
-            .find(|snapshot| match identifier {
-                Identifier::Pid(pid) => snapshot.id == pid,
-                Identifier::Name(ref name) => snapshot.name == *name,
-            })
-            .ok_or_else(|| {
-                Error::CreateProcessError(format!(
-                    "failed to find a process with identifier `{identifier}`",
-                ))
-            })?;
-        let mut process = Self {
-            name: snapshot.name,
-            id: snapshot.id,
-            base_address: 0,
-            handle: Handle::from_pid(snapshot.id)?,
-        };
-        process.base_address = process.module(&process.name)?.base_address;
-        Ok(process)
-    }
-
-    /// get a `Module` of a `Process` by name
-    pub fn module(&self, name: &str) -> Result<Module, Error> {
-        let Some(snapshot) = snapshot::ModuleSnapshot::get_modules(self.id)?
-            .into_iter()
-            .find(|snapshot| snapshot.name == name)
-        else {
-            return Err(Error::CreateProcessError(format!(
-                "failed to find a module with identifier `{name}`",
-            )));
-        };
-        let module = Module {
-            process_id: self.id,
-            name: snapshot.name,
-            path: snapshot.path,
-            base_address: snapshot.base_address,
-            base_size: snapshot.base_size,
-        };
-        Ok(module)
-    }
-
-    /// follow a pointer chain to the end and return an address
-    pub fn resolve_pointer_chain(&self, chain: &[usize]) -> Result<usize, Error> {
-        let mut chain = chain.to_vec();
-        let mut address = chain.remove(0);
-        while chain.len() > 1 {
-            address += chain.remove(0);
-            address = self.read_mem(address)?;
-        }
-        Ok(address + chain.remove(0))
-    }
-
-    /// read a given `address` of process's memory
-    pub fn read_mem<T: Default>(&self, address: usize) -> Result<T, Error> {
-        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<T: Default>(&self, address: usize, mut value: T) -> Result<(), Error> {
-        memory::write(&self.handle, address, &mut value)?;
-        Ok(())
+impl From<String> for Identifier {
+    fn from(value: String) -> Self {
+        Self::Name(value)
     }
 }
-
-#[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,
-}

src/sys/memory.rs

@@ -1,4 +1,4 @@
-use crate::{sys::handle::Handle, Error};
+use crate::{Error, sys::handle::Handle};
 use std::{ffi::c_void, ptr};
 use windows::Win32::System::Diagnostics::Debug::{ReadProcessMemory, WriteProcessMemory};
 

src/sys/snapshot.rs

@@ -41,7 +41,7 @@ impl ProcessSnapshot {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct ModuleSnapshot {
     pub name: String,
     pub path: String,

src/tests.rs

@@ -0,0 +1,29 @@
+#![cfg(test)]
+
+use super::process::*;
+
+#[test]
+fn resolve_pointer_chain_empty() {
+    let myself = Process::find(std::process::id()).unwrap();
+    let result = myself.resolve_pointer_chain(&[]);
+    assert!(result.is_err());
+}
+
+#[test]
+fn resolve_pointer_chain_single() {
+    let myself = Process::find(std::process::id()).unwrap();
+    let result = myself.resolve_pointer_chain(&[myself.base_address]);
+    assert_eq!(result.unwrap(), myself.base_address);
+}
+
+#[test]
+fn resolve_pointer_chain_multiple() {
+    let myself = Process::find(std::process::id()).unwrap();
+    let target_value = 1337;
+    let target_ptr = &target_value as *const i32 as usize;
+    let base_ptr = &target_ptr as *const usize as usize;
+    let address = myself.resolve_pointer_chain(&[base_ptr, 0x0, 0x0]).unwrap();
+    assert_eq!(address, target_ptr);
+    let value = myself.read_mem::<i32>(address).unwrap();
+    assert_eq!(value, target_value);
+}