coffeeldr 0.1.6

A COFF (Common Object File Format) loader written in Rust
Documentation

coffeeldr 🦀

Rust crate docs Forks Stars License

coffeeldr is a modern and lightweight COFF (Common Object File Format) loader for Windows written in Rust, designed to run COFF files on Windows. It supports both 32-bit and 64-bit architectures and allows you to load and execute COFF files from files or memory buffers with Rust’s safety and performance guarantees.

Table of Contents

Features

  • ✅ Load COFF files from disk or in-memory buffers.
  • ✅ 32-bit and 64-bit support.
  • ✅ Memory management: Automatically adjusts memory protections to ensure execution (read, write, execute permissions).
  • ✅ Dynamic relocation handling.
  • ✅ Fully written in Rust with safety and performance in mind.
  • ✅ Easy CLI integration with flexible input handling.

Installation

Add coffeeldr to your project by updating your Cargo.toml:

cargo add coffeeldr

Usage

Loading from File

To load a COFF file from the filesystem:

use coffeeldr::CoffeeLdr;

let mut loader = CoffeeLdr::new("path/to/coff_file.o");
match loader {
    Ok(ldr) => {
        println!("COFF successfully loaded from file!");
        // Execute the entry point or manipulate the COFF as needed
    },
    Err(e) => println!("Error loading COFF: {:?}", e),
}

Loading from Buffer

To load a COFF from an in-memory buffer:

use coffeeldr::CoffeeLdr;

let coff_data = include_bytes!("path/to/coff_file.o");
let mut loader = CoffeeLdr::new(coff_data);
match loader {
    Ok(ldr) => {
        println!("COFF successfully loaded from buffer!");
        // Execute the entry point or manipulate the COFF as needed
    },
    Err(e) => println!("Error loading COFF: {:?}", e),
}

Executing a COFF File

Once the COFF file is loaded, you can execute it by specifying the entry point:

let mut coffee = CoffeeLdr::new("path/to/coff_file.o").unwrap();
coffee.run("entry_point_function_name", None, None).unwrap();

This method will search for the specified entry point and execute it.

CLI

coffeeldr also provides a convenient CLI tool for interacting with COFF files directly from the command line.

Example Command:

coffee.exe --bof path/to/coff_file.o --entrypoint go

Input Processing in CLI

These are the types of parameters that the tool accepts for processing:

  • /short:<value>: Adds a short (i16) value.
  • /int:<value>: Adds an integer (i32) value.
  • /str:<value>: Adds a string.
  • /wstr:<value>: Adds a wide string.
  • /bin:<base64-data>: Adds binary data decoded from base64.

Example command using ntcreatethread.o:

coffee.exe --bof ntcreatethread.o --entrypoint go /int:4732 /bin:Y29mZmVlbGRy..

Another example using dir.o:

coffee.exe --bof dir.o --entrypoint go /str:C:\

Contributing to coffeeldr

To contribute to coffeeldr, follow these steps:

  1. Fork this repository.
  2. Create a branch: git checkout -b <branch_name>.
  3. Make your changes and commit them: git commit -m '<commit_message>'.
  4. Push your changes to your branch: git push origin <branch_name>.
  5. Create a pull request.

Alternatively, consult the GitHub documentation on how to create a pull request.

References

License

This project is licensed under the MIT License. See the LICENSE file for details.