Crate faithe

Expand description

Warning

Unsafe code ahead!

This library’s internals may not mark some frequently used public api methods as unsafe although they may cause undefined behavior if used incorrectly. This is especially true for macros.

Installation

[dependencies]
faithe = "0.8.0"

[dependencies.faithe]
git = "https://github.com/sy1ntexx/faithe"

Opening processes

use faithe::types::access_rights::PROCESS_ALL_ACCESS;
use faithe::process as ps;

let process = ps::Processes::new()?
    .find(|p| p.sz_exe_file == "Process name.exe")
    .unwrap()
    .open(false, PROCESS_ALL_ACCESS)?;

Modules iterating

let process = get_process();
process
    .modules()?
    .for_each(|m| dbg!(m));

Reading / Writing memory

let process = get_process();
let mut value = process.read::<u32>(0xFF)?;
value += 100;

process.write(0xFF, value)?;

Allocating / Freeing / Protecting / Querying memory

use faithe::types::allocation_types::{MEM_COMMIT, MEM_RESERVE};
use faithe::types::free_types::MEM_RELEASE;
use faithe::memory::MemoryProtection;

let process = get_process();
let mut chunk = process.allocate(
    0,
    1000,
    MEM_COMMIT | MEM_RESERVE,
    MemoryProtection::READ_WRITE_EXECUTE
)?;
let info = process.query(chunk)?;

process.protect(chunk, 1000, MemoryProtection::Read)?;
process.free(chunk, 0, MEM_RELEASE)?;

Searching for patterns

use faithe::pattern::Pattern;

let process = get_process();
let address = process.find_pattern(
    "Something.exe",
    // Available styles: IDA, Code, PiDB
    Pattern::from_ida_style("48 89 85 F0 00 00 00 4C 8B ? ? ? ? ? 48 8D")
)?;

Macros

use faithe::{interface, xstruct};

// Creates a trait that will emulate behavior of virtual functions in C++.
struct CPlayer;
faithe::interface! {
    trait IEntity(CPlayer) {
        extern "C" fn get_health() -> i32 = 0;
        extern "C" fn set_health(new: i32) = 1;
    }
}
/*
C++ Equivalent
class CPlayer {
    virtual int get_health() = 0;
    virtual void set_health(int new_value) = 0;
};
*/

// Creates a function with explicitly defined RVA relative to some module.
faithe::function! {
    // Explicitly defined RVA offset relative to `01-hello` module.
    FUNC: extern "C" fn(a: i32) = "01-hello.exe"@0x1900;
}
FUNC.call(5);

faithe::global! {
    extern count: i32 = "01-hello.exe"%"8B ? ? ? ? ? 05 AD DE";
}

Modules

internal

APIs for internal interation with current process.

module

Module for dealing with processs’ modules.

pattern

Pattern searching.

process

Module for doing common things with processes.

thread

Iterator over threads and etc.

types

Re-exports of types used in windows.

Macros

c_str

Constructs a zero-terminated string at compile time.

containing_record

Resolves next link in doubly-linked list.

function

Creates function that resolves its address on the first call.

global

Creates global that resolves its address on the first access.

interface

Creates an trait that emulates virtual table behavior from C++. You can use 'this lifetime for arguments that requires self lifetime.

list_iter

Creates an iterator over doubly-linked list.

offset_of

Calculates the offset of the specified field from the start of the named struct.

parent

Creates C-like inherited structures. First member of the struct is instance of the parent class. This macro also implements core::ops::Deref for child class so you can easily access parent’s fields.

pc_str

Constructs new zero terminated string of type [windows::Win32::Foundation::PSTR].

size_of

Get size in bytes of types and variables.

str_ptr

Creates new StrPtr.

unicode_string

Creates new unicode string.

vmt

Creates a virtual method table.

wide

Encodes the input string as a wide string (utf-16) constant.

Enums

FaitheError

Error type for all mistakes made in faithe.

Functions

terminated_array^⚠

Creates an immutable slice from the terminated array by finding it’s last element. Returns a slice NOT INCLUDING the last element. Maximum length is usize::MAX

terminated_array_mut^⚠

Creates a mutable slice from the terminated array by finding it’s last element. Returns a slice NOT INCLUDING the last element. Maximum length is usize::MAX

terminated_slice

Creates an immutable slice from the terminated slice by finding it’s last element. Returns a slice NOT INCLUDING the last element. Returns an empty slice if failed to find the last element.

terminated_slice_mut

Creates a mutable slice from the terminated slice by finding it’s last element. Returns a slice NOT INCLUDING the last element. Returns an empty slice if failed to find the last element.

to_mut_ref^⚠

Casts a pointer to a mutable reference.

to_ref^⚠

Casts a pointer to an immutable reference.