https://github.com/joaoviictorti/coffeeldr
A COFF Loader written in Rust
https://github.com/joaoviictorti/coffeeldr
coff loader redteam rust windows
Last synced: about 1 year ago
JSON representation
A COFF Loader written in Rust
- Host: GitHub
- URL: https://github.com/joaoviictorti/coffeeldr
- Owner: joaoviictorti
- License: mit
- Created: 2024-10-08T14:18:32.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-29T01:24:03.000Z (about 1 year ago)
- Last Synced: 2025-03-29T01:35:23.307Z (about 1 year ago)
- Topics: coff, loader, redteam, rust, windows
- Language: Rust
- Homepage: https://crates.io/crates/coffeeldr
- Size: 121 KB
- Stars: 63
- Watchers: 1
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# coffeeldr 🦀
`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](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Loading from File](#loading-from-file)
- [Loading from Buffer](#loading-from-buffer)
- [Executing a COFF File](#executing-a-coff-file)
- [CLI](#cli)
- [Input Processing in CLI](#input-processing-in-cli)
- [Contributing to coffeeldr](#contributing-to-coffeeldr)
- [References](#references)
- [License](#license)
## 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`:
```powershell
cargo add coffeeldr
```
## Usage
### Loading from File
To load a COFF file from the filesystem:
```rust
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:
```rust
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:
```rust
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:
```cmd
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:`: Adds a short (`i16`) value.
- `/int:`: Adds an integer (`i32`) value.
- `/str:`: Adds a string.
- `/wstr:`: Adds a wide string.
- `/bin:`: Adds binary data decoded from `base64`.
Example command using [`ntcreatethread.o`](https://github.com/trustedsec/CS-Remote-OPs-BOF/blob/main/Injection/ntcreatethread/ntcreatethread.x64.o):
```cmd
coffee.exe --bof ntcreatethread.o --entrypoint go /int:4732 /bin:Y29mZmVlbGRy..
```
Another example using [`dir.o`](https://github.com/trustedsec/CS-Situational-Awareness-BOF/blob/master/SA/dir/dir.x64.o):
```cmd
coffee.exe --bof dir.o --entrypoint go /str:C:\
```
### CLI Help
```
A COFF (Common Object File Format) loader written in Rust
Usage: coffee.exe [OPTIONS] --bof [INPUTS]...
Arguments:
[INPUTS]... Multiple arguments in the format `/short:`, `/int:`, `/str:`, `/wstr:`, `/bin:`
Options:
-b, --bof The command to be executed
-e, --entrypoint Entrypoint to use in the execution [default: go]
-v, --verbose... Verbose mode (-v, -vv, -vvv, etc.)
-h, --help Print help
```
## Contributing to coffeeldr
To contribute to **coffeeldr**, follow these steps:
1. Fork this repository.
2. Create a branch: `git checkout -b `.
3. Make your changes and commit them: `git commit -m ''`.
4. Push your changes to your branch: `git push origin `.
5. Create a pull request.
Alternatively, consult the [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) on how to create a pull request.
## References
-
-
-
## License
This project is licensed under the MIT License. See the [LICENSE](/LICENSE) file for details.