mmap Inject

https://docs.rs/mmap_inject
Admin
mmap Inject is a Rust crate that manually maps DLL bytes into a specified process, primarily used...
Tokens:76,826
Snippets:646
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### IntoIterator Example (Ok)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Demonstrates converting an Ok Result into an iterator that yields the contained value once.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);
```

--------------------------------

### unwrap_or_else Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Demonstrates the use of unwrap_or_else with a closure to provide a default value when the Result is an Err.

```rust
assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);
```

--------------------------------

### FromIterator Example (Success)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Demonstrates collecting an iterator of Results into a single Result, where all elements are Ok. Requires T: FromIterator<A> and E.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

--------------------------------

### Unsafe unwrap_unchecked Example (Ok)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Shows how to use unwrap_unchecked to get the Ok value without safety checks. Calling this on an Err is undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

--------------------------------

### FromIterator Example (Error)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Demonstrates collecting an iterator of Results into a single Result, where an Err is encountered. The first Err stops the iteration.

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

--------------------------------

### IntoIterator Example (Err)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Demonstrates converting an Err Result into an iterator that yields no values.

```rust
let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```

--------------------------------

### Unsafe unwrap_err_unchecked Example (Err)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Shows how to use unwrap_err_unchecked to get the Err value without safety checks. Calling this on an Ok is undefined behavior.

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```

--------------------------------

### Handling File Metadata with Result::and_then

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

This example shows how `and_then` can be used with file system operations that return `Result`. It demonstrates handling both successful metadata retrieval and cases where the path is invalid.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Unsafe unwrap_err_unchecked Example (Ok)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Illustrates the undefined behavior of calling unwrap_err_unchecked on an Ok variant. This code should not be run.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

--------------------------------

### Read and Validate PE File Bytes

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Reads a DLL file into a byte vector and asserts its validity as an x64 PE file. Ensure the test_dll example is built before running.

```rust
let dll_path = manifest.join("target/debug/examples/test_dll.dll");
let bytes = std::fs::read(&dll_path)
    .unwrap_or_else(|_| panic!("build test_dll example first: {}", dll_path.display()));
assert!(validate(&bytes), "test_dll.dll should be a valid x64 PE");
```

--------------------------------

### Build Mapping Context for Remote Process

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/injector.rs.html

Initializes a MappingCtx struct with the base address of the mapped module in the remote process, function pointers for loading libraries and getting procedure addresses, and other relevant context.

```rust
let ctx = MappingCtx {
    base_addr: target_base,
    fn_load_lib: Some(std::mem::transmute(fn_load)),
    fn_get_proc: Some(std::mem::transmute(fn_get)),
    fn_add_table: fn_add_table.map(|f| std::mem::transmute(f)),
    mod_handle: ERR_NO_LOADLIB,
    reason: 1, // DLL_PROCESS_ATTACH
};
```

--------------------------------

### Read and Validate DLL Bytes

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html?search=

Reads a DLL file into bytes and validates if it's a valid x64 PE file. Panics if the file cannot be read, suggesting to build the example DLL first.

```rust
let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let dll_path = manifest.join("target/debug/examples/test_dll.dll");
let bytes = std::fs::read(&dll_path)
    .unwrap_or_else(|_| panic!("build test_dll example first: {}", dll_path.display()));
assert!(validate(&bytes), "test_dll.dll should be a valid x64 PE");
```

--------------------------------

### Rust Result is_ok Method Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Checks if a Result is the Ok variant. Returns true if it is Ok, false otherwise.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

--------------------------------

### Type Inference Example: u32 to bool

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=u32+-%3E+bool

Demonstrates type inference where a `u32` is matched against a generic parameter `U` and a `bool` against a generic parameter `T` in the context of `mmap_inject::Error::try_from`.

```rust
method
mmap_inject::Error::try_from
**U** -> Result<**T** >
where
u32 matches **U**
bool matches **T**
```

--------------------------------

### Rust Result copied Method Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Demonstrates mapping a Result<&T, E> to a Result<T, E> by copying the success value. Requires T to implement the Copy trait.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Unwrap with Panic on Error

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html

This example demonstrates that calling `unwrap()` on an `Err` variant will cause a panic with the provided error message.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`
```

--------------------------------

### Rust Result cloned Method Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Demonstrates mapping a Result<&T, E> to a Result<T, E> by cloning the success value. Requires T to implement the Clone trait.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Error::description Method (Deprecated)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/enum.Error.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Deprecated method for getting an error description. Use the Display impl or to_string() instead.

```rust
fn description(&self) -> &str
```

--------------------------------

### PE File Validation Success

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html?search=std%3A%3Avec

Tests that the `validate` function correctly identifies a valid PE file. This example uses a placeholder for locating a test DLL.

```rust
#[test]
fn validate_real_dll() {
    // Locate test_dll.dll from the examples output directory.
    let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));

```

--------------------------------

### Shellcode Execution Logic

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/shellcode.rs.html

Handles the execution of shellcode, including SEH setup and DllMain invocation. It determines the final module handle based on SEH success or failure.

```rust
let f: unsafe extern "system" fn(*mut u8, u32, *mut core::ffi::c_void) = 
                        core::mem::transmute(*cb);
                    f(base, 1, core::ptr::null_mut());
                    cb = cb.add(1);
                } 
            } 
        } 

        // SEH
        ctx.mod_handle = STEP_SEH;
        let mut seh_failed = false;
        if ctx.seh_enabled {
            let exc_va = *(opt.add(0x70 + IMAGE_DIRECTORY_ENTRY_EXCEPTION * 8) as *const u32);
            let exc_sz = *(opt.add(0x70 + IMAGE_DIRECTORY_ENTRY_EXCEPTION * 8 + 4) as *const u32);
            if exc_sz > 0 {
                if let Some(add_table) = ctx.fn_add_table {
                    let n = exc_sz as usize / core::mem::size_of::<ImageRuntimeFunctionEntry>();
                    let pdata = base.add(exc_va as usize) as *mut ImageRuntimeFunctionEntry;
                    if add_table(pdata, n as u32, base as u64) == 0 {
                        seh_failed = true;
                    }
                }
            }
        }

        // DllMain
        ctx.mod_handle = STEP_DLLMAIN;
        if entry != 0 {
            let dll_main: unsafe extern "system" fn(*mut u8, u32, *mut core::ffi::c_void) -> i32 = 
                core::mem::transmute(base.add(entry as usize));
            dll_main(base, ctx.reason, ctx.reserved);
        }

        ctx.mod_handle = if seh_failed {
            SEH_FAILED
        } else {
            base as usize
        };
```

--------------------------------

### Safely get Ok value without panicking (nightly)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

The `into_ok()` method (nightly-only) returns the contained `Ok` value without panicking. It's a compile-time safeguard against `Result` types that might later become fallible.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Get a reference to the Ok value

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Use `as_ref()` to obtain a `Result<&T, &E>` from a `&Result<T, E>`, providing immutable references to the contained values without consuming the original Result.

```Rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Check DLL Sections and Entry Point

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html?search=

Reads a DLL, validates it as a PE file, and checks for the presence of sections, a non-zero entry point, and 64KB alignment of the image base.

```rust
let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let dll_path = manifest.join("target/debug/examples/test_dll.dll");
let bytes = std::fs::read(&dll_path).expect("build test_dll example first");
assert!(validate(&bytes));

let nt = unsafe { nt_headers(bytes.as_ptr()) };
let opt = unsafe { &(*nt).optional_header };
let sections = unsafe { section_headers(nt) };

// Should have at least .text section
assert!(!sections.is_empty(), "DLL should have sections");

// Entry point should be non-zero
assert_ne!(
    opt.address_of_entry_point,
    0,
    "DLL should have an entry point"
);

// Image base should be 64-bit aligned for x64
assert_eq!(
    opt.image_base % 0x10000,
    0,
    "ImageBase should be 64K-aligned"
);
```

--------------------------------

### Shellcode Range Retrieval

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/shellcode.rs.html?search=

Provides a function to get the memory range (start pointer and byte count) of the shellcode blob. This is used by the injector to copy the shellcode into the target process.

```rust
/// Returns `(start_ptr, byte_count)` for the shellcode blob to copy.
pub(crate) fn shellcode_range() -> (*const u8, usize) {
    let start = shellcode as *const u8;
    let end = &raw const SC_END as *const u8;
    let size = unsafe { end.offset_from(start) } as usize;
    (start, size)
}
```

--------------------------------

### Any::type_id implementation

Source: https://docs.rs/mmap_inject/latest/mmap_inject/enum.Error.html?search=std%3A%3Avec

Gets the `TypeId` of `self`. This is part of the blanket implementation of the Any trait for all types.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### into_ok

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=

Returns the contained `Ok` value, but never panics. This is a nightly-only experimental API.

```APIDOC
## pub const fn into_ok(self) -> T

### Description
Returns the contained `Ok` value, but never panics. This is a nightly-only experimental API.

### Method
`into_ok`

### Examples
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```
```

--------------------------------

### Error::cause Method (Deprecated)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/enum.Error.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Deprecated method for getting the cause of an error. Replaced by Error::source.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### Unsafe unwrap_unchecked Example (Err)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Illustrates the undefined behavior of calling unwrap_unchecked on an Err variant. This code should not be run.

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### into_ok

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Returns the contained `Ok` value, but never panics. This is an experimental API.

```APIDOC
## pub const fn into_ok(self) -> T

### Description
Returns the contained `Ok` value, but never panics. This is an experimental API.

### Method
`into_ok`

### Notes
Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Examples
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```
```

--------------------------------

### into_ok

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=u32+-%3E+bool

Returns the contained `Ok` value, but never panics. This is an experimental API.

```APIDOC
## pub const fn into_ok(self) -> T

### Description
Returns the contained `Ok` value, but never panics.
Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Examples
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```
```

--------------------------------

### inject_dll

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/lib.rs.html

Manually maps DLL bytes into a target process using memory mapping. The target process handle must be opened with specific access rights including VM read/write/operation and thread creation. The function returns Ok(()) on successful injection, otherwise an Error.

```APIDOC
## inject_dll

### Description
Manually maps `dll_bytes` into the process identified by `process`. The `process` handle must be opened with at least `PROCESS_VM_READ | PROCESS_VM_WRITE | PROCESS_VM_OPERATION` and `PROCESS_CREATE_THREAD` access rights. PE headers are wiped, and shellcode and context are written to the remote process.

### Safety
The caller is responsible for providing a valid process handle.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
`unsafe fn inject_dll(process: HANDLE, dll_bytes: &[u8]) -> Result<()>`

### Parameters
* `process` (HANDLE) - A handle to the target process, opened with required access rights.
* `dll_bytes` (&[u8]) - A byte slice containing the DLL to be injected.

### Returns
* `Result<()>` - Returns `Ok(())` on success, or an `Error` variant on failure.
```

--------------------------------

### Shellcode Entry Point

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/shellcode.rs.html?search=

The `shellcode` function serves as the entry point for the shellcode executed in the target process. It uses `naked` assembly to set up the stack and call the inner shellcode logic, ensuring minimal overhead.

```rust
#[unsafe(link_section = ".sc$b")]
#[unsafe(naked)]
pub unsafe extern "system" fn shellcode(ctx: *mut MappingCtx) -> u32 {
    core::arch::naked_asm!(
        "sub rsp, 0x28",
        "call {inner}",
        "xor eax, eax",
        "add rsp, 0x28",
        "ret",
        inner = sym shellcode_inner,
    );
}
```

--------------------------------

### Rust Result is_err Method Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Checks if a Result is the Err variant. Returns true if it is Err, false otherwise.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### Analyze PE DLL Sections and Headers

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html

Reads a DLL file, validates it as a PE, and then extracts and asserts properties of its section headers and optional headers, such as the presence of sections and the entry point.

```rust
let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        let dll_path = manifest.join("target/debug/examples/test_dll.dll");
        let bytes = std::fs::read(&dll_path).expect("build test_dll example first");
        assert!(validate(&bytes));

        let nt = unsafe { nt_headers(bytes.as_ptr()) };
        let opt = unsafe { &(*nt).optional_header };
        let sections = unsafe { section_headers(nt) };

        // Should have at least .text section
        assert!(!sections.is_empty(), "DLL should have sections");

        // Entry point should be non-zero
        assert_ne!(
            opt.address_of_entry_point,
            0,
            "DLL should have an entry point"
        );

        // Image base should be 64-bit aligned for x64
        assert_eq!(
            opt.image_base % 0x10000,
            0,
            "ImageBase should be 64K-aligned"
        );
```

--------------------------------

### Shellcode Entry Point and Range Calculation

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/shellcode.rs.html

Provides the entry point for the shellcode and a function to determine the range of bytes to be copied into the target process. It uses linker section markers to define the shellcode's boundaries.

```rust
pub(crate) fn shellcode_range() -> (*const u8, usize) {
    let start = shellcode as *const u8;
    let end = &raw const SC_END as *const u8;
    let size = unsafe { end.offset_from(start) } as usize;
    (start, size)
}
```

--------------------------------

### Result<T, E> Termination Implementation

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=u32+-%3E+bool

Provides a `report` method to get the representation of the Result value as a status code, which is returned to the operating system.

```rust
impl<T, E> Termination for Result<T, E>
where T: Termination, E: Debug,
Source
```

--------------------------------

### Rust Result is_ok_and Method Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Checks if a Result is Ok and its contained value satisfies a given predicate. Returns false if the Result is Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Rust Result transpose Method Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Transposes a Result containing an Option into an Option containing a Result. Useful for simplifying nested Option/Result types.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### Validate PE File Bytes

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html

Reads a DLL file and validates if it's a correct x64 PE file. Panics if the file cannot be read, suggesting it might not be built.

```rust
let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        let dll_path = manifest.join("target/debug/examples/test_dll.dll");
        let bytes = std::fs::read(&dll_path)
            .unwrap_or_else(|_| panic!("build test_dll example first: {}", dll_path.display()));
        assert!(validate(&bytes), "test_dll.dll should be a valid x64 PE");
```

--------------------------------

### Allocate and Write Context to Target Process

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/injector.rs.html

Allocates memory in the target process for the context structure and writes the local context to it. Handles potential allocation failures.

```rust
    // ── Write ctx to target ───────────────────────────────────────────────
    let ctx_remote = VirtualAllocEx(
        process,
        std::ptr::null(),
        std::mem::size_of::<MappingCtx>(),
        MEM_COMMIT | MEM_RESERVE,
        PAGE_READWRITE,
    ) as *mut u8;
    if ctx_remote.is_null() {
        free_remote(process, target_base);
        return Err(Error::last_win32());
    }
    if !write_remote(
        process,
        ctx_remote,
        &ctx as *const MappingCtx as *const u8,
        std::mem::size_of::<MappingCtx>(),
    ) {
        free_remote(process, ctx_remote);
        free_remote(process, target_base);
        return Err(Error::last_win32());
    }
```

--------------------------------

### inject_dll

Source: https://docs.rs/mmap_inject/latest/mmap_inject/index.html

Manually maps DLL bytes into a target process.

```APIDOC
## inject_dll

### Description
Manually maps `dll_bytes` into the process identified by `process`.

### Parameters
- **process**: (usize) - The process identifier.
- **dll_bytes**: (&[u8]) - The byte slice representing the DLL to inject.

### Returns
- Result<(), Error> - Returns Ok(()) on success, or an Error if the injection fails.
```

--------------------------------

### inject_dll

Source: https://docs.rs/mmap_inject/latest/mmap_inject/fn.inject_dll.html?search=

Manually maps DLL bytes into the process identified by `process`. The `process` must be opened with specific access rights. Returns `Ok(())` on success. PE headers are wiped, shellcode and context are preserved.

```APIDOC
## Function inject_dll

### Description
Manually maps `dll_bytes` into the process identified by `process`. `process` must be opened with at minimum: `PROCESS_VM_READ | PROCESS_VM_WRITE | PROCESS_VM_OPERATION` and `PROCESS_CREATE_THREAD`. Returns `Ok(())` on success. PE headers are wiped, shellcode and context are preserved.

### Safety
The caller is responsible for providing a valid process handle.

### Signature
```rust
pub unsafe fn inject_dll(process: HANDLE, dll_bytes: &[u8]) -> Result<()>
```
```

--------------------------------

### Providing a Default Value with Result::unwrap_or

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Use `unwrap_or` to get the `Ok` value or a specified default if the `Result` is `Err`. The default value is eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### inject_dll

Source: https://docs.rs/mmap_inject/latest/mmap_inject/fn.inject_dll.html?search=std%3A%3Avec

Manually maps `dll_bytes` into the process identified by `process`. The `process` handle must be opened with specific access rights. Returns `Ok(())` on success.

```APIDOC
## Function inject_dll

### Description
Manually maps `dll_bytes` into the process identified by `process`. The caller is responsible for providing a valid process handle opened with at least `PROCESS_VM_READ | PROCESS_VM_WRITE | PROCESS_VM_OPERATION` and `PROCESS_CREATE_THREAD` access rights. PE headers are wiped, shellcode and context are preserved.

### Safety
The caller is responsible for providing a valid process handle.
```

--------------------------------

### Expect Err value or panic with custom message

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Use `expect_err()` to get the contained `Err` value. This method panics with a custom message if the `Result` is an `Ok`.

```rust
let x: Result<u32, &str> = Ok(10);
x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
```

--------------------------------

### inject_dll

Source: https://docs.rs/mmap_inject/latest/mmap_inject/fn.inject_dll.html

Manually maps `dll_bytes` into the process identified by `process`. The `process` handle must be opened with specific access rights. Returns `Ok(())` on success.

```APIDOC
## inject_dll

### Description
Manually maps `dll_bytes` into the process identified by `process`. `process` must be opened with at minimum:
  * `PROCESS_VM_READ | PROCESS_VM_WRITE | PROCESS_VM_OPERATION`
  * `PROCESS_CREATE_THREAD`

Returns `Ok(())` on success. PE headers are wiped, shellcode and context

### Safety
The caller is responsible for providing a valid process handle.

### Signature
```rust
pub unsafe fn inject_dll(process: HANDLE, dll_bytes: &[u8]) -> Result<()>
```
```

--------------------------------

### Error::provide Method (Nightly Only)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/enum.Error.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Nightly-only experimental API for providing type-based access to error context.

```rust
fn provide<'a>(&'a self, request: &mut Request<'a>)
```

--------------------------------

### Helper to Get Last Win32 Error

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/lib.rs.html?search=std%3A%3Avec

Provides a convenient method `last_win32` on the `Error` enum to capture the last error code from a Win32 API call.

```rust
impl Error {
    fn last_win32() -> Self {
        use windows_sys::Win32::Foundation::GetLastError;
        Error::Win32(unsafe { GetLastError() })
    }
}
```

--------------------------------

### FromIterator Example (Partial Iteration)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Shows that FromIterator stops processing the iterator upon encountering the first Err, as demonstrated by the 'shared' variable's final value.

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

--------------------------------

### Inject DLL into Process

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/injector.rs.html

Manually maps DLL bytes into a target process. The process handle must be valid and opened with sufficient access rights (PROCESS_ALL_ACCESS or PROCESS_VM_* + PROCESS_CREATE_THREAD).

```rust
/// Manually maps `dll_bytes` into `process`.
///
/// # Safety
/// `process` must be a valid handle opened with `PROCESS_ALL_ACCESS` (or at
/// minimum `PROCESS_VM_*` + `PROCESS_CREATE_THREAD`).
#[allow(unsafe_op_in_unsafe_fn)]
pub unsafe fn inject(process: HANDLE, dll_bytes: &[u8]) -> crate::Result<()> {
    if process == INVALID_HANDLE_VALUE || process == 0 as HANDLE {
        return Err(Error::InvalidArgument);
    }

    // ── Validate PE ───────────────────────────────────────────────────────
    if !pe::validate(dll_bytes) {
        return Err(Error::InvalidPe);
    }

    let base_ptr = dll_bytes.as_ptr();
    let nt = pe::nt_headers(base_ptr);
    let opt = &(*nt).optional_header;
    let _file_hdr = &(*nt).file_header;
    let image_size = opt.size_of_image as usize;
    let headers_size = opt.size_of_headers as usize;

    // ── Allocate image memory in target (3 random attempts + 1 fallback) ──
    let mut target_base: *mut u8 = std::ptr::null_mut();
    for _ in 0..3 {
        let hint = random_base(image_size);
        let p = VirtualAllocEx(
            process,
            hint as _,
            image_size,
            MEM_COMMIT | MEM_RESERVE,
            PAGE_EXECUTE_READWRITE,
        );
        if !p.is_null() {
            target_base = p as *mut u8;
            break;
        }
    }
    if target_base.is_null() {
        // OS-chosen address as fallback.
        target_base = VirtualAllocEx(
            process,
            std::ptr::null(),
            image_size,
            MEM_COMMIT | MEM_RESERVE,
            PAGE_EXECUTE_READWRITE,
        ) as *mut u8;
    }
    if target_base.is_null() {
        return Err(Error::last_win32());
    }
}
```

--------------------------------

### Termination for Result<T, E>

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=

Implementation of the Termination trait for Result. The `report` function is used to get a status code representation of the Result value, which is then returned to the operating system.

```APIDOC
## fn report(self) -> ExitCode

### Description
Is called to get the representation of the value as status code. This status code is returned to the operating system.

### Method
`report`

### Parameters
- `self`: The Result value itself.

### Return Value
- `ExitCode`: The status code representation of the Result.
```

--------------------------------

### inject_dll

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/lib.rs.html?search=u32+-%3E+bool

Manually maps DLL bytes into a target process. Requires specific process handle permissions.

```APIDOC
/// Manually maps `dll_bytes` into the process identified by `process`.
///
/// `process` must be opened with at minimum:
/// - `PROCESS_VM_READ | PROCESS_VM_WRITE | PROCESS_VM_OPERATION`
/// - `PROCESS_CREATE_THREAD`
///
/// Returns `Ok(())` on success. PE headers are wiped, shellcode and context
///
/// # Safety
/// The caller is responsible for providing a valid process handle.
pub unsafe fn inject_dll(process: HANDLE, dll_bytes: &[u8]) -> Result<()>
```

--------------------------------

### NT Headers Accessor

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html?search=std%3A%3Avec

Provides a function to safely get a pointer to the NT headers of a PE file mapped in memory. This is crucial for accessing file header information.

```APIDOC
## nt_headers

### Description
Returns a pointer to the NT headers within `base` (mapped in-process). This function is essential for accessing critical PE file metadata.

### Function Signature
`pub unsafe fn nt_headers(base: *const u8) -> *const ImageNtHeaders64`

### Parameters
- **base** (`*const u8`) - A raw pointer to the base address of the mapped PE image.

### Returns
- `*const ImageNtHeaders64` - A raw pointer to the `ImageNtHeaders64` structure.

### Safety
`base` must point to a fully-mapped PE image in addressable memory. Dereferencing the returned pointer is also subject to the safety requirements of the PE image's integrity.
```

--------------------------------

### Convert Result to Option (Ok value)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Use the `ok()` method to convert a `Result<T, E>` into an `Option<T>`. The `Ok` value is preserved, while `Err` becomes `None`. This consumes the Result.

```Rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### Shellcode Execution Logic

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/shellcode.rs.html?search=

This snippet outlines the core logic for executing shellcode, including handling callbacks, SEH, and DllMain. It demonstrates how to transmute function pointers and invoke them with specific arguments.

```rust
let mut cb = cb;
                    let f: unsafe extern "system" fn(*mut u8, u32, *mut core::ffi::c_void) =
                        core::mem::transmute(*cb);
                    f(base, 1, core::ptr::null_mut());
                    cb = cb.add(1);
```

```rust
let exc_va = *(opt.add(0x70 + IMAGE_DIRECTORY_ENTRY_EXCEPTION * 8) as *const u32);
            let exc_sz = *(opt.add(0x70 + IMAGE_DIRECTORY_ENTRY_EXCEPTION * 8 + 4) as *const u32);
            if exc_sz > 0 {
                if let Some(add_table) = ctx.fn_add_table {
                    let n = exc_sz as usize / core::mem::size_of::<ImageRuntimeFunctionEntry>();
                    let pdata = base.add(exc_va as usize) as *mut ImageRuntimeFunctionEntry;
                    if add_table(pdata, n as u32, base as u64) == 0 {
                        seh_failed = true;
                    }
                }
            }
```

```rust
let dll_main: unsafe extern "system" fn(*mut u8, u32, *mut core::ffi::c_void) -> i32 =
                core::mem::transmute(base.add(entry as usize));
            dll_main(base, ctx.reason, ctx.reserved);
```

--------------------------------

### Collecting Results into a Result with checked_add

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=u32+-%3E+bool

Demonstrates using collect on an iterator of Results to aggregate successful values or return the first error encountered. This example checks for integer overflow.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| 
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

--------------------------------

### Allocate and Write Shellcode to Target Process

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/injector.rs.html

Allocates executable memory in the target process and writes the shellcode to it. Includes error handling for allocation and writing.

```rust
    // ── Write shellcode to target ─────────────────────────────────────────
    let (sc_src, sc_size) = shellcode_range();
    let sc_remote = VirtualAllocEx(
        process,
        std::ptr::null(),
        sc_size,
        MEM_COMMIT | MEM_RESERVE,
        PAGE_EXECUTE_READWRITE,
    ) as *mut u8;
    if sc_remote.is_null() {
        free_remote(process, ctx_remote);
        free_remote(process, target_base);
        return Err(Error::last_win32());
    }
    // Copy the exact shellcode bytes (section `.sc$a` through `.sc$z`).
    if !write_remote(process, sc_remote, sc_src, sc_size) {
        free_remote(process, sc_remote);
        free_remote(process, ctx_remote);
        free_remote(process, target_base);
        return Err(Error::last_win32());
    }
```

--------------------------------

### Rust Result flatten Method Example

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Converts a nested Result<Result<T, E>, E> into a single Result<T, E>. This operation can be chained to flatten multiple levels of nesting.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Unwrap Ok value or panic

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Use `unwrap()` to get the contained `Ok` value. This method panics if the `Result` is an `Err`. Prefer `?` or pattern matching for robust error handling.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`
```

--------------------------------

### Get a mutable reference to the Ok value

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=std%3A%3Avec

Use `as_mut()` to obtain a `Result<&mut T, &mut E>` from a `&mut Result<T, E>`, providing mutable references to the contained values.

```Rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### inject_dll

Source: https://docs.rs/mmap_inject/latest/mmap_inject/fn.inject_dll.html?search=u32+-%3E+bool

Manually maps DLL bytes into the process identified by `process`. The caller is responsible for providing a valid process handle opened with the necessary permissions.

```APIDOC
## Function inject_dll

### Description
Manually maps `dll_bytes` into the process identified by `process`. `process` must be opened with at minimum:
  * `PROCESS_VM_READ | PROCESS_VM_WRITE | PROCESS_VM_OPERATION`
  * `PROCESS_CREATE_THREAD`

Returns `Ok(())` on success. PE headers are wiped, shellcode and context are preserved.

### Safety
The caller is responsible for providing a valid process handle.
```

--------------------------------

### Verify PE Struct Sizes

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html

Asserts that the defined Rust struct sizes match the expected sizes in the Windows PE specification. This is crucial for correct memory layout interpretation.

```rust
#[test]
fn struct_sizes_match_windows_pe() {
    // Verify our repr(C) structs match the Windows PE spec sizes.
    assert_eq!(mem::size_of::<ImageDosHeader>(), 64);
    assert_eq!(mem::size_of::<ImageFileHeader>(), 20);
    assert_eq!(mem::size_of::<ImageDataDirectory>(), 8);
    assert_eq!(mem::size_of::<ImageOptionalHeader64>(), 240);
    // Fixed header (112) + DataDirectory[16] (128) = 240
    assert_eq!(mem::align_of::<ImageOptionalHeader64>(), 8);
    assert_eq!(mem::size_of::<ImageSectionHeader>(), 40);
    assert_eq!(mem::size_of::<ImageImportDescriptor>(), 20);
    assert_eq!(mem::size_of::<ImageBaseRelocation>(), 8);
    assert_eq!(mem::size_of::<ImageRuntimeFunctionEntry>(), 12);
}
```

--------------------------------

### Get Section Headers Slice

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/pe.rs.html

Provides a slice of section headers for a PE image. This function requires a pointer to the NT headers and assumes the PE image is correctly mapped.

```rust
/// Returns a slice of section headers for the PE at `base`.
///
/// # Safety
/// Same as [`nt_headers`].
#[inline]
pub unsafe fn section_headers(nt: *const ImageNtHeaders64) -> &'static [ImageSectionHeader] {
    unsafe {
        let count = (*nt).file_header.number_of_sections as usize;
        // Section headers immediately follow the optional header.
        let opt_size = (*nt).file_header.size_of_optional_header as usize;
        let first = (nt as *const u8)
            .add(size_of::<u32>() + size_of::<ImageFileHeader>() + opt_size)
            as *const ImageSectionHeader;
        slice::from_raw_parts(first, count)
    }
}
```

--------------------------------

### Collecting Results into a Result with checked_sub (Underflow)

Source: https://docs.rs/mmap_inject/latest/mmap_inject/type.Result.html?search=u32+-%3E+bool

Shows collecting an iterator of Results, returning the first error if any operation results in underflow. This example demonstrates that processing stops at the first error.

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| 
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

--------------------------------

### Windows API Imports for mmap_inject

Source: https://docs.rs/mmap_inject/latest/src/mmap_inject/injector.rs.html?search=

Imports necessary Windows API functions and constants for memory manipulation and process interaction.

```rust
use windows_sys::Win32::Foundation::{CloseHandle, HANDLE, INVALID_HANDLE_VALUE};
use windows_sys::Win32::System::Diagnostics::Debug::WriteProcessMemory;
use windows_sys::Win32::System::LibraryLoader::{GetProcAddress, LoadLibraryA};
use windows_sys::Win32::System::Memory::{
    MEM_COMMIT,
    MEM_RELEASE,
    MEM_RESERVE,
    PAGE_EXECUTE_READWRITE,
    PAGE_READWRITE,
    VirtualAllocEx,
    VirtualFreeEx,
};
use windows_sys::Win32::System::Threading::{CreateRemoteThread, GetExitCodeThread, INFINITE, WaitForSingleObject};
```
Tokens:
Raw