coffee-ldr 0.2.2

Coffee: A COFF loader made in Rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

# Coffee


Coffee is a custom implementation of the original Cobalt Strike's [beacon_inline_execute](https://hstechdocs.helpsystems.com/manuals/cobaltstrike/current/userguide/content/topics_aggressor-scripts/as-resources_functions.htm#beacon_inline_execute). It is written in Rust and supports most of the features of the Cobalt Strike compatibility layer. Coffee is structured so it can be used as a library in other projects too.

The original blog post can be found here: <https://labs.hakaioffsec.com/coffee-a-coff-loader-made-in-rust/>

## Usage


```bash
$ coffee.exe -h
Coffee: A COFF loader made in Rust

Usage: coffee.exe [OPTIONS] --bof-path <BOF_PATH> [-- <ARGS>...]

Arguments:
  [ARGS]...  Arguments to the BOF passed after the "--" delimiter, supported types are: str, wstr, int, short, bin

Options:
  -b, --bof-path <BOF_PATH>      Path to the Beacon Object File (BOF)
  -e, --entrypoint <ENTRYPOINT>  The entrypoint name to execute in case of a custom entrypoint name [default: go]
  -v, --verbosity <VERBOSITY>    Verbosity level, 0 = ERROR, 1 = WARN, 2 = INFO, 3 = DEBUG, 4 = TRACE [default: 0]
  -h, --help                     Print help
  -V, --version                  Print version
```

### Arguments


Arguments for the BOF can be passed after the `--` delimiter. Each argument must be prefixed with the type of the argument followed by a colon (`:`). The following types are supported:

- `str` - A null-terminated string
- `wstr` - A wide null-terminated string
- `int` - A signed 32-bit integer
- `short` - A signed 16-bit integer
- `bin` - A base64-encoded binary blob

## Examples


Using the `dir.x64.o` BOF from the [trustedsec/CS-Situational-Awareness-BOF](https://github.com/trustedsec/CS-Situational-Awareness-BOF) repository and passing arguments to the BOF:

```bash
coffee.exe --bof-path .\dir.x64.o -- wstr:"C:\\Windows\\System32"
```

Using the `ntcreatethread.x64.o` BOF from the [trustedsec/CS-Remote-OPs-BOF](https://github.com/trustedsec/CS-Remote-OPs-BOF) repository and passing a PID and the shellcode to execute as base64-encoded binary data.

```bash
coffee.exe --bof-path .\ntcreatethread.x64.o -- int:1337 bin:/EiD5PDowAAAAEFRQVBSUVZIMdJlSItSYEiLUhhIi1IgSItyUEgPt0pKTTHJSDHArDxhfAIsIEHByQ1BAcHi7VJBUUiLUiCLQjxIAdCLgIgAAABIhcB0Z0gB0FCLSBhEi0AgSQHQ41ZI/8lBizSISAHWTTHJSDHArEHByQ1BAcE44HXxTANMJAhFOdF12FhEi0AkSQHQZkGLDEhEi0AcSQHQQYsEiEgB0EFYQVheWVpBWEFZQVpIg+wgQVL/4FhBWVpIixLpV////11IugEAAAAAAAAASI2NAQEAAEG6MYtvh//Vu+AdKgpBuqaVvZ3/1UiDxCg8BnwKgPvgdQW7RxNyb2oAWUGJ2v/VY2FsYy5leGUA
```

## Usage as library


```bash
cargo add coffee-ldr
```

Coffee can be used as a library in other projects. The following example shows how to use Coffee to load a BOF and execute the BOF:

```rust
use coffee_ldr::loader::Coffee;

fn main() {
    let whoami_bof: [u8; 6771] = [
        0x64, 0x86, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0A, 0x14, 0x00, 0x00, 0x33, 0x00, 0x00,
        ...
    ];

    let _ = Coffee::new(&whoami_bof).unwrap().execute(None, None, None);
}
```

The example above will execute the BOF passed as an array of bytes and show the output in console.

The detailed documentation can be found at: <https://docs.rs/coffee-ldr/latest/coffee_ldr/loader/struct.Coffee.html>

## Building from source


1. Install Rust from <https://rustup.rs/>
2. Clone the repository
3. Build the project using

```bash
cargo build --release
```

## License


Coffee is licensed under the GNU GPLv3 license. See [LICENSE](LICENSE) for more information.

## Contributing


Pull requests are welcome. Please open an issue first to discuss what you would like to change.

## References


Thanks to the amazing people who have written about COFF loaders and helped me understand the format:

- <https://github.com/trustedsec/COFFLoader>
- <https://github.com/Cracked5pider/CoffeeLdr>
- <https://github.com/yamakadi/ldr>
- <https://www.trustedsec.com/blog/coffloader-building-your-own-in-memory-loader-or-how-to-run-bofs/>
- <https://0xpat.github.io/Malware_development_part_8/>
- <https://otterhacker.github.io/Malware/CoffLoader.html>
- <https://signal-labs.com/trainings/offensive-tool-development/>
- <https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#coff-file-header-object-and-image>
- <https://blog.cloudflare.com/how-to-execute-an-object-file-part-1/>