This is a blog post written for a project I recently released. The source code for it can be found here on Github.

Background

The design of Cobalt Strike’s Beacon Object Files is rather unique when compared to other runtime code execution implementations. These are small programs compiled into COFF object files which are loaded and executed by a COFF loader. Another addition that Beacon Object Files make is the concept of dynamic function resolution or DFR which allows the COFF to invoke functions from external DLLs.

The popularity of Beacon Object Files has exploded since they were first introduced in Cobalt Strike. Due to their popularity, many projects have been released to take advantage of this new technique. TrustedSec released a blog post on developing a Beacon Object File loader shortly after the initial concept was introduced. The blog post and COFFLoader implementation made it easier for developers to both develop their own BOFs and also include this capability into their own tools. BOF loaders have become widely adopted by many different red team tools. They can provide a fairly lightweight extension system that is agnostic to the underlying platform which makes BOFs ideal from a developer standpoint.

Although the concept behind BOFs was first introduced back in 2020, the development process and tooling has largely stayed the same. There has been an increase in public project templates for BOF development, such as the bof-vs template, which can help with some development aspects.

These templates still suffer some of the same limitations that come with the nature of Beacon Object Files.

Current Beacon Object File Limitations

One of the limitations with BOFs is the way it handles external imports. It uses a method known as DFR which consists of changing the names of imported symbols to include the name of the library the symbol is from. I wrote a previous blog post on the complications that come with this: “Writing Beacon Object Files Without DFR”.

Another design limitation is that BOFs rely on using object files as a “final file format”. The main purpose of object files is to act as an intermediary compilation artifact during the build process rather than a complete file suitable for other uses. This makes the raw object files produced by compilers optimized more for later use by a system linker for building a complete executable file.

Compilers may emit various symbols and other compilation artifacts inside the object file which are useful to the linker but may cause issues if not handled properly by a loader. This results in the loader requiring extra logic to handle these cases in order to make a decision on how to handle certain artifacts depending on the context. If these are not handled properly, it may cause issues where the compiler generated code assumes that the artifact was processed correctly.

Object files are also the product of compiling a single translation unit which typically means a single C or C++ source file. The source can be split up between multiple files but ultimately, these files will have to be combined either through #include statements or by concatenating their contents in order for the compiler to compile it. This can potentially make things difficult to maintain or debug.

Introducing Boflink

Boflink is a tool designed to act as a sort of fill-in for the missing linking stage that comes with the BOF development process. It is a linker that takes unmodified object files generated by a compiler and links them together into a Beacon Object File capable of being loaded by a BOF loader.

Its main goal is to act as a bridge between the BOF development and the BOF loading process to help simplify them.

On the BOF development side, Boflink will perform symbol resolution on imported symbols and rewrite them to match the BOF DFR format. BOF developers can use symbols imported from DLLs normally without needing to first prefix them with the library name they are imported from. Another feature is that it is capable of linking multiple COFFs together. These aspects help make the source code for BOFs more similar to the source code for traditional executables since the BOF specific artifacts are handled by Boflink.

On the BOF loader side, Boflink will create COFFs that are better optimized for BOF loaders to process rather than system linkers. Compilers will oftentimes include artifacts and structure things in ways that are more ideal for a linker to process rather than a loader. Some examples of this include COMDAT sections, relocation labels, grouped sections, COMMON symbols and linker metadata sections. Simplifying the COFFs loaded by a BOF loader can help reduce the risk of a BOF crashing since the loader will not need to include additional complexities for handling these cases.

Setup and Usage

Pre-built artifacts are provided on the releases page for download. These are built in CI and published for each release.

Setting up Boflink on Windows only requires the boflink executable. This executable can be placed in one of the %PATH% directories so that it is easier to run.

On Linux, Boflink is designed to integrate with the MinGW toolchain and invoked via a compile driver. It is possible to use it with a custom toolchain; however, the MinGW one provided by many Linux distributions is the easiest to get started with.

A special symlink needs to be created for integrating Boflink with MinGW GCC. The reasoning for this is because GCC does not support using a custom linker directly. This symlink is used to get around that limitation. This workaround was used by the mold linker when it did not have GCC support initially. A symlink needs to be created in an empty directory with the symlink name being ld and the target being the path to the installed boflink executable

The release archives include a small install script which will install the executable to ~/.local/bin/boflink and create the symlink at ~/.local/libexec/boflink/ld.

Install From Source

Installing from source requires Rust version >=1.85. This can be checked by running rustc --version in a terminal window.

Building and installing from source requires downloading the source code and then running cargo xtask install.

The cargo xtask ... command is not any form of external plugin that needs to be installed but is an alias for cargo to build and run a small executable for installing the program correctly.

It will run cargo install –path . –bin boflink to build the executable from source and copy it into the $CARGO_HOME/bin path. On Linux, it also sets up the ld symlink for MinGW GCC by placing it in the ~/.local/libexec/boflink directory.

The cargo xtask uninstall command can be used to undo everything from the install command. This only works as a means of uninstalling the program if it was installed using cargo xtask install and will not uninstall the executable if it was installed from a release archive.

Usage

Boflink acts as a sort of “dumb linker”. This means that it does not include any form of default configuration and expects it to be provided from the command line or by other means.

Windows

On Windows, Boflink should be used while inside a Visual Studio developer console. This environment includes a list of search paths that will be automatically included when searching for link libraries.

The boflink executable can be invoked directly in a Visual Studio developer console passing in any command line options.

boflink [-o <output>] [options] <files>...
boflink -o mybof.bof file1.obj file2.obj -lkernel32 -ladvapi32

Linux

On Linux, the boflink executable is not meant to be invoked directly and instead should be used through a compile driver such as MinGW GCC or Clang. The compile driver will then invoke boflink passing in its default configuration for boflink to use.

For MinGW GCC, this requires the following command line flags.

x86_64-w64-mingw32-gcc -B ~/.local/libexec/boflink -fno-lto -nostartfiles <args>...
x86_64-w64-mingw32-gcc -B ~/.local/libexec/boflink -fno-lto -nostartfiles -o mybof.bof source.c object.o

The example above assumes that the ~/.local/libexec/boflink directory has the ld symlink set up as mentioned in the setup section. The -fno-lto and -nostartfiles flags are also required for it to work properly.

Clang includes a --ld-path= flag for setting the linker. This needs to be the absolute path to the boflink executable.

clang --ld-path=/path/to/boflink --target=x86_64-windows-gnu -nostartfiles <args>...
clang --ld-path=/path/to/boflink --target=x86_64-windows-gnu -nostartfiles -o mybof.bof source.c object.o

The --ld-path= flag is very particular on its formatting and requires two hyphens for the flag prefix and an equal = sign. The -nostartfiles option is also required like with MinGW GCC to exclude startup files from the linker inputs.

Features

These are some of the currently implemented features of Boflink and how to use them.

Symbol Resolution

Boflink will resolve undefined symbols using the link libraries and library search paths specified on the command line. In the output BOF, the undefined symbols will have the resolved library names included in the symbol name to match the BOF DFR format.

For this example source file.

#include <windows.h>

#include "beacon.h"


void go(void) {
    DWORD pid = GetCurrentProcessId();
    BeaconPrintf(CALLBACK_OUTPUT, "pid: %lu\n", pid);
}

Compiling it will cause the GetCurrentProcessId and BeaconPrintf symbols to show up as being undefined.

matt@laptop ~> ls
beacon.h  example.c  Makefile
matt@laptop ~> make example.o
x86_64-w64-mingw32-gcc    -c -o example.o example.c
matt@laptop ~> rabin2 -s example.o
[Symbols]
nth paddr      vaddr      bind   type size lib name                          demangled
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x00000000 0x00000000 LOCAL  FILE 4        .file
0   0x0000012c 0x00000000 GLOBAL FUNC 4        go
0   0x0000012c 0x00000000 LOCAL  SECT 4        .text
0   0x00000000 0x00000040 LOCAL  SECT 4        .data
0   0x00000000 0x00000050 LOCAL  SECT 4        .bss
0   0x0000016c 0x00000060 LOCAL  SECT 4        .rdata
0   0x0000017c 0x00000070 LOCAL  SECT 4        .xdata
0   0x00000188 0x00000080 LOCAL  SECT 4        .pdata
0   0x00000194 0x00000090 LOCAL  UNK  4        .rdata$zzz
0   ---------- ---------- NONE   UNK  4        imp.__imp_GetCurrentProcessId
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
matt@laptop ~>

Passing the built example.o COFF through Boflink will result in Boflink resolving these symbols and rewriting them in the BOF DFR format with the name of the DLL that Boflink finds them defined in.

matt@laptop ~> ls
beacon.h  example.c  example.o  Makefile
matt@laptop ~> x86_64-w64-mingw32-gcc -B ~/.local/libexec/boflink -fno-lto -nostartfiles -o example.bof example.o
matt@laptop ~> rabin2 -s example.bof
[Symbols]
nth paddr      vaddr      bind   type size lib name                                   demangled
―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x00000104 0x00000000 LOCAL  SECT 4        .text
0   0x00000104 0x00000000 GLOBAL FUNC 4        go
0   0x00000000 0x00000040 LOCAL  SECT 4        .data
0   0x00000000 0x00000050 LOCAL  SECT 4        .bss
0   0x00000144 0x00000060 LOCAL  SECT 4        .rdata
0   0x00000194 0x000000b0 LOCAL  SECT 4        .xdata
0   0x000001a0 0x000000c0 LOCAL  SECT 4        .pdata
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_KERNEL32$GetCurrentProcessId
matt@laptop ~>

MinGW GCC includes kernel32 as a search library in its default configuration which is why it does not need to be included manually. In order to link against kernel32 on Windows using MSVC, Boflink needs to be run in a Visual Studio developer console with kernel32 passed as an additional link library on the command line.

 matth@laptop ~> ls

        Directory: C:\Users\matth


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         5/27/2025   1:50 PM          15962  beacon.h
-a---         5/27/2025   1:50 PM            162  example.c

 matth@laptop ~> cl /c /GS- .\example.c
Microsoft (R) C/C++ Optimizing Compiler Version 19.44.35207.1 for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

example.c
 matth@laptop ~> ls

        Directory: C:\Users\matth


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         5/27/2025   1:50 PM          15962 beacon.h
-a---         5/27/2025   1:50 PM            162 example.c
-a---         5/27/2025   1:52 PM           1225 example.obj

 matth@laptop ~> rabin2 -s .\example.obj
[Symbols]
nth paddr      vaddr      bind   type size lib name                          demangled
--------------------------------------------------------------------------------------
0   ---------- ---------- LOCAL  ABS  4        @comp.id-0x01048987
0   ---------- ---------- LOCAL  ABS  4        @feat.00-0x80010090
0   ---------- ---------- LOCAL  ABS  4        @vol.md-0x00000003
0   0x0000012c 0x00000000 LOCAL  SECT 4        .drectve
0   0x00000189 0x00000060 LOCAL  SECT 4        .debug$S
0   0x00000219 0x000000f0 LOCAL  SECT 4        .text$mn
0   ---------- ---------- NONE   UNK  4        imp.__imp_GetCurrentProcessId
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   0x00000219 0x000000f0 GLOBAL FUNC 4        go
0   0x00000219 0x000000f0 LOCAL  6    4        $LN3
0   0x0000025f 0x00000120 LOCAL  SECT 4        .xdata
0   0x0000025f 0x00000120 LOCAL  UNK  4        $unwind$go
0   0x00000267 0x00000130 LOCAL  SECT 4        .pdata
0   0x00000267 0x00000130 LOCAL  UNK  4        $pdata$go
0   0x00000291 0x00000140 LOCAL  SECT 4        .data
0   0x00000291 0x00000140 LOCAL  UNK  4        $SG74138
0   0x0000029b 0x00000150 LOCAL  SECT 4        .chks64
 matth@laptop ~> boflink -o example.bof .\example.obj -lkernel32
 matth@laptop ~> rabin2 -s .\example.bof
[Symbols]
nth paddr      vaddr      bind   type size lib name                                   demangled
-----------------------------------------------------------------------------------------------
0   0x000000b4 0x00000000 LOCAL  SECT 4        .text
0   0x000000b4 0x00000000 GLOBAL FUNC 4        go
0   0x000000dc 0x00000030 LOCAL  SECT 4        .xdata
0   0x000000dc 0x00000030 LOCAL  UNK  4        $unwind$go
0   0x000000e4 0x00000040 LOCAL  SECT 4        .pdata
0   0x000000e4 0x00000040 LOCAL  UNK  4        $pdata$go
0   0x000000f0 0x00000050 LOCAL  SECT 4        .data
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_KERNEL32$GetCurrentProcessId
 matth@laptop  ~>

If any symbols could not be resolved, Boflink will return an error listing out what symbols were left undefined.

#include <windows.h>

#include <lmcons.h>

#include "beacon.h"


extern void UnresolvedSymbol(void);


static void my_function(void) {
    UnresolvedSymbol();
}

void go(void) {
    my_function();

    char username[UNLEN + 1] = {0};
    if (GetUserNameA(username, &(DWORD){sizeof(username)}) != 0) {
        BeaconPrintf(CALLBACK_OUTPUT, "Your username is %s", username);
    }
}

 matth@laptop ~> cl /c /GS- .\example.c
Microsoft (R) C/C++ Optimizing Compiler Version 19.44.35207.1 for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

example.c
 matth@laptop ~> boflink -o example.bof .\example.obj -lkernel32
boflink: error: undefined symbol: __declspec(dllimport) GetUserNameA
>>> referenced by .\example.obj:(go)

boflink: error: undefined symbol: UnresolvedSymbol
>>> referenced by .\example.obj:(my_function)
 matth@laptop ~ [1]>

Linking Multiple Files

Boflink is also capable of linking multiple object files together into a single BOF. This is commonly referred to as “partial linking” where multiple object files are combined to produce a single object file rather than a full executable or shared library.

go.c

#include "beacon.h"

#include "other.h"


void go(void) {
    BeaconPrintf(CALLBACK_OUTPUT, "Hello world from the go() function");
    other_function();
}

other.h

#ifndef OTHER_H
#define OTHER_H


void other_function(void);


#endif // OTHER_H

other.c

#include "other.h"

#include "beacon.h"


void other_function() {
    BeaconPrintf(CALLBACK_OUTPUT, "Hello world from other_function()");
}

Using MinGW GCC

matt@laptop ~> ls
beacon.h  go.c  Makefile  other.c  other.h
matt@laptop ~> x86_64-w64-mingw32-gcc -B ~/.local/libexec/boflink -fno-lto -nostartfiles -o mybof.bof go.c other.c
matt@laptop ~> ls
beacon.h  go.c  Makefile  mybof.bof  other.c  other.h
matt@laptop ~> rabin2 -s mybof.bof
[Symbols]
nth paddr      vaddr      bind   type size lib name                                   demangled
―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x00000104 0x00000000 LOCAL  SECT 4        .text
0   0x00000104 0x00000000 GLOBAL FUNC 4        go
0   0x00000134 0x00000030 GLOBAL FUNC 4        other_function
0   0x00000000 0x00000090 LOCAL  SECT 4        .data
0   0x00000000 0x000000a0 LOCAL  SECT 4        .bss
0   0x00000194 0x000000b0 LOCAL  SECT 4        .rdata
0   0x00000244 0x00000160 LOCAL  SECT 4        .xdata
0   0x0000025c 0x00000180 LOCAL  SECT 4        .pdata
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_KERNEL32$GetCurrentProcessId
matt@laptop ~>

Using MSVC on Windows

matth@laptop ~> ls

        Directory: C:\Users\matth
 

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         5/27/2025   1:50 PM          15962 beacon.h
-a---         5/27/2025   2:33 PM            164 go.c
-a---         5/27/2025   2:33 PM            273 other.c
-a---         5/27/2025   2:33 PM             85 other.h
 
 matth@laptop ~> cl /c /GS- .\go.c .\other.c
Microsoft (R) C/C++ Optimizing Compiler Version 19.44.35207.1 for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

go.c
other.c
Generating Code...
 matth@laptop ~> ls

        Directory: C:\Users\matth


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         5/27/2025   1:50 PM          15962 beacon.h
-a---         5/27/2025   2:33 PM            164 go.c
-a---         5/27/2025   2:35 PM           1225 go.obj
-a---         5/27/2025   2:33 PM            273 other.c
-a---         5/27/2025   2:33 PM             85 other.h
-a---         5/27/2025   2:35 PM           1364 other.obj

 matth@laptop ~> boflink -o mybof.bof .\go.obj .\other.obj -lkernel32
 matth@laptop ~> ls

        Directory: C:\Users\matth
 

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         5/27/2025   1:50 PM          15962 beacon.h
-a---         5/27/2025   2:33 PM            164 go.c
-a---         5/27/2025   2:35 PM           1225 go.obj
-a---         5/27/2025   2:35 PM            947 mybof.bof
-a---         5/27/2025   2:33 PM            273 other.c
-a---         5/27/2025   2:33 PM             85 other.h
-a---         5/27/2025   2:35 PM           1364 other.obj

 matth@laptop ~> rabin2 -s .\mybof.bof
[Symbols]
nth paddr      vaddr      bind   type size lib name                                   demangled
-----------------------------------------------------------------------------------------------
0   0x000000b4 0x00000000 LOCAL  SECT 4        .text
0   0x000000b4 0x00000000 GLOBAL FUNC 4        go
0   0x000000d4 0x00000020 GLOBAL FUNC 4        other_function
0   0x0000010c 0x00000060 LOCAL  SECT 4        .xdata
0   0x0000010c 0x00000060 LOCAL  UNK  4        $unwind$go
0   0x00000114 0x00000068 LOCAL  UNK  4        $unwind$other_function
0   0x0000011c 0x00000070 LOCAL  SECT 4        .pdata
0   0x0000011c 0x00000070 LOCAL  UNK  4        $pdata$go
0   0x00000128 0x0000007c LOCAL  UNK  4        $pdata$other_function
0   0x00000134 0x00000090 LOCAL  SECT 4        .data
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_KERNEL32$GetCurrentProcessId
 matth@laptop ~>

Partial linking is a feature also supported in GNU ld. The difference between partial linking in Boflink and GNU ld is that GNU ld’s partial linking is mainly for doing incremental linking in a larger build process.

Incremental linking is an optimization feature used to help speed up rebuilds for a program. This works by linking multiple object files together to produce a new “pre-linked” object file for the final linking stage.

It is pretty common for linkers to embed additional metadata in the “pre-linked” object file during incremental linking to help speed up the final linking process.

Here is an example of using MinGW ld to perform partial linking with the files above.

matt@laptop ~> x86_64-w64-mingw32-gcc -r -o combined.o go.c other.c
matt@laptop ~> ls
beacon.h  combined.o  go.c  Makefile  other.c  other.h
matt@laptop ~> rabin2 -s combined.o
[Symbols]
nth paddr      vaddr      bind   type size lib name                          demangled
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x00000000 0x00000000 LOCAL  FILE 4        .file
0   0x0000012c 0x00000000 GLOBAL FUNC 4        go
0   0x0000012c 0x00000000 LOCAL  SECT 4        .text
0   0x00000000 0x00000090 LOCAL  SECT 4        .data
0   0x00000000 0x000001d0 LOCAL  SECT 4        .bss
0   0x000001bc 0x000000a0 LOCAL  SECT 4        .rdata
0   0x000002c4 0x000001b0 LOCAL  SECT 4        .xdata
0   0x000002ac 0x00000190 LOCAL  SECT 4        .pdata
0   0x0000026c 0x00000150 LOCAL  UNK  4        .rdata$zzz
0   0x00000000 0x00000000 LOCAL  FILE 4        .file
0   0x0000015c 0x00000030 GLOBAL FUNC 4        other_function
0   0x0000015c 0x00000030 LOCAL  SECT 4        .text
0   0x00000000 0x00000090 LOCAL  SECT 4        .data
0   0x00000000 0x000001d0 LOCAL  SECT 4        .bss
0   0x000001ec 0x000000d0 LOCAL  SECT 4        .rdata
0   0x000002d0 0x000001bc LOCAL  SECT 4        .xdata
0   0x000002b8 0x0000019c LOCAL  SECT 4        .pdata
0   0x0000022c 0x00000110 LOCAL  UNK  4        .rdata$zzz
0   ---------- ---------- NONE   UNK  4        imp.__imp_GetCurrentProcessId
0   ---------- ---------- NONE   UNK  4        imp._pei386_runtime_relocator
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
matt@laptop ~>

You can see above that MinGW ld does not deduplicate the section symbols. It will also embed the undefined _pei386_runttime_relocator symbol because it knows that it will need it later on in the final linking process. This is helpful for further linking together a full program but can cause issues in a BOF loader.

Boflink’s partial linking process includes various linker passes specifically designed for tailoring the COFF for a loader to process. This includes: deduplicating section symbols, discarding linker metadata sections, merging grouped sections, applying relocations to same-section defined symbols, allocating space for COMMON symbols, handling COMDAT sections and some others. The result of this is that the final output COFF is much simpler than what MinGW ld produces which makes it easier for BOF loaders to load.

Comment Pragma Link Libraries

When using MSVC toolchains, it is common for them to embed additional metadata inside the compiled COFF for the linker to process. These are known as comment records and are added using the #pragma comment preprocessor directive. Some of these comment records include additional options for the linker to process.

Boflink currently supports processing lib records for including additional search libraries when resolving symbols.

#include <windows.h>

#include <lmcons.h>

#include "beacon.h"


#pragma comment(lib, "kernel32")
#pragma comment(lib, "advapi32")


void go(void) {
    DWORD pid = GetCurrentProcessId();
    BeaconPrintf(CALLBACK_OUTPUT, "Current process id is %lu", pid);

    char username[UNLEN + 1] = {0};
    if (GetUserNameA(username, &(DWORD){sizeof(username)}) != 0) {
        BeaconPrintf(CALLBACK_OUTPUT, "Your username is %s", username);
    }
}

When processing this file, Boflink will see the “kernel32” and “advapi32” link libraries and include them in the symbol resolution phase.

matth@laptop ~> ls

        Directory: C:\Users\matth


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         5/27/2025   1:50 PM          15962 beacon.h
-a---         5/27/2025   3:33 PM            457 example.c

 matth@laptop ~> cl /c /GS- .\example.c
Microsoft (R) C/C++ Optimizing Compiler Version 19.44.35207.1 for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

example.c
 matth@laptop ~> ls

        Directory: C:\Users\matth


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a---         5/27/2025   1:50 PM          15962 beacon.h
-a---         5/27/2025   3:33 PM            457 example.c
-a---         5/27/2025   3:36 PM           1476 example.obj

 matth@laptop ~> boflink -o example.bof .\example.obj
 matth@laptop ~> rabin2 -s .\example.bof
[Symbols]
nth paddr      vaddr      bind   type size lib name                                   demangled
-----------------------------------------------------------------------------------------------
0   0x000000b4 0x00000000 LOCAL  SECT 4        .text
0   0x000000b4 0x00000000 GLOBAL FUNC 4        go
0   0x00000128 0x00000080 LOCAL  SECT 4        .xdata
0   0x00000128 0x00000080 LOCAL  UNK  4        $unwind$go
0   0x00000134 0x00000090 LOCAL  SECT 4        .pdata
0   0x00000134 0x00000090 LOCAL  UNK  4        $pdata$go
0   0x00000140 0x000000a0 LOCAL  SECT 4        .data
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_KERNEL32$GetCurrentProcessId
0   ---------- ---------- NONE   UNK  4        imp.__imp_ADVAPI32$GetUserNameA
 matth@laptop ~>

Note that this method of passing link libraries to Boflink depends on if the compiler used to compile the source files supports embedding comment records.

BSS Handling

A common limitation with many BOF loaders is that they do not support loading the .bss section. Boflink includes a --merge-bss flag to add .bss compatibility for BOF loaders that do not support it. This will zero-initialize .bss defined symbols and place them at the end of the .data section. It effectively does what many BOF developers will do in their code where they default initialize global variables or use attributes to have the compiler define them in the .data section. It does not “magically fix” the .bss section for BOF loaders but instead offloads the task of zero-initializing them to Boflink.

I am curious what the reasonings are for many BOF loaders not adding support for loading the .bss section. From the BOF loader perspective, an uninitialized data section and a file-backed section are loaded very similarly. The only difference is that the uninitialized data section will set the IMAGE_SCN_CNT_UNINITIALIZED_DATA flag in the section header characteristics to indicate that the section is not file-backed. If this flag is present, the loader does not initialize the section with data from the file but instead zero-initializes it. The size needed for the allocated section is stored in the SizeOfRawData field like with regular file-backed sections. Adding support for the .bss section in a BOF loader involves checking for that flag in the section header and either zero-initializing the allocated section or initializing it with the data found at the PointerToRawData file offset in the header.

TrustedSec’s COFFLoader will zero-initialize any sections which have a non-zero size and a PointerToRawData field set to NULL. This means that it does have support for loading the .bss section since the .bss section’s PointerToRawData field will be set to NULL and the SizeOfRawData field will be non-zero.

bsstest.c

#include <windows.h>

#include "beacon.h"


static int bss_variable;
static float other_bss_variable;


void go(void) {
    bss_variable = 123;
    BeaconPrintf(CALLBACK_OUTPUT, "bss_variable: %d\n", bss_variable);

    other_bss_variable = 3.14;
    BeaconPrintf(CALLBACK_OUTPUT, "other_bss_variable: %0.2f\n", other_bss_variable);
}

matt@laptop ~/COFFLoader (main)> x86_64-w64-mingw32-gcc -c -o bsstest.o bsstest.c
matt@laptop ~/COFFLoader (main)> ./COFFLoader64.exe go bsstest.o
Got contents of COFF file
Running/Parsing the COFF file
bss_variable: 123
other_bss_variable: 3.14
Ran/parsed the coff
Outdata Below:

bss_variable: 123
other_bss_variable: 3.14

matt@laptop ~/COFFLoader (main)>

What may cause confusion with the .bss section are the differences between .bss defined symbols and COMMON symbols. MaskRay’s blog post “All about COMMON symbols“ does a great job explaining them and why they can cause many issues in C.

GCC 10 and Clang 11 (released around 2020) included a change where the -fno-common flag is now added by default during compilation. This will cause public uninitialized global variables to be treated as .bss defined symbols rather than COMMON symbols.

Here is an example of what COMMON symbols look like and how they differ from .bss defined symbols.

commonstest.c

#include <windows.h>

#include "beacon.h"


int common_symbol;
static int bss_symbol;


void go(void) {
    common_symbol = 123;
    BeaconPrintf(CALLBACK_OUTPUT, "common_symbol: %d\n", common_symbol);

    bss_symbol = 123;
    BeaconPrintf(CALLBACK_OUTPUT, "bss_symbol: %d\n", bss_symbol);
}

The common_symbol is a public uninitialized global variable. This is what causes COMMON symbols to appear in a compiled object file.

The -fcommon compile flag is needed when using MinGW GCC to treat common_symbol as a COMMON symbol since the -fno-common flag is included by default. The bss_symbol variable is a regular .bss defined symbol since it was declared with static storage duration. These symbols can be viewed in the COFF symbol table using llvm-readobj.

matt@laptop ~> ls
beacon.h  commonstest.c
matt@laptop ~> x86_64-w64-mingw32-gcc -fcommon -c -o commonstest.o commonstest.c
matt@laptop ~> llvm-readobj -s commonstest.o
…
 Symbol {
    Name: bss_symbol
    Value: 0
    Section: .bss (3)
    BaseType: Null (0x0)
    ComplexType: Null (0x0)
    StorageClass: Static (0x3)
    AuxSymbolCount: 0
  }
…
  Symbol {
    Name: common_symbol
    Value: 4
    Section: IMAGE_SYM_UNDEFINED (0)
    BaseType: Null (0x0)
    ComplexType: Null (0x0)
    StorageClass: External (0x2)
    AuxSymbolCount: 0
  }
…

The bss_symbol shows up as being defined in the .bss section at address 0. The common_symbol is rather different. COMMON symbols in COFFs are represented as having a section number of IMAGE_SYM_UNDEFINED and a Value that is non-zero. This is very similar to regular undefined symbols but with the only difference being that the Value field is non-zero for COMMONS. The system linker will handle resolving COMMON symbols as outlined in MaskRay’s blog post mentioned above but they ultimately will not end up defined in the .bss section until after linking.

MSVC’s defaults are different than MinGW GCC or Clang and will compile public uninitialized global variables as COMMON symbols. This is equivalent to passing the -fcommon flag like in the example above.

One way to avoid COMMON symbols when using MSVC is by making uninitialized global variables static. The drawback with this is that the symbol will be local to the translation unit it is being compiled in and cannot be referenced externally.

As far as I have discovered, the only way to create a public .bss defined symbol with MSVC is by wrapping it in a bss_seg pragma.

#include <windows.h>

#include "beacon.h"


#pragma bss_seg(push, bss, ".bss")
int bss_symbol;
#pragma bss_seg(pop, bss)


void go(void) {
    bss_symbol = 123;
    BeaconPrintf(CALLBACK_OUTPUT, "bss_symbol: %d\n", bss_symbol);
}

I can see why the confusion around COMMON symbols is the reason why BOF loaders decided to not support BOFs with uninitialized global variables. MinGW GCC and Clang changed their defaults for them after the initial BOF loaders were released which would cause COMMON symbols to show up more frequently during testing.

There is not a lot of easily accessible information online explaining COMMON symbols in-depth which makes them rather obscure. Many C development courses do not mention them at all because they are a compiler-specific “feature” not really part of the language itself. There are many pitfalls when using COMMON symbols in C and exist mainly for FORTRAN compatibility.

BOF loaders should be able to support .bss defined symbols fairly easily. As stated above, TrustedSec’s COFFLoader does support them. I personally do not expect BOF loaders to handle COMMON symbols due to the complexity but they can be avoided pretty easily in the BOF source code.

Boflink does support handling COMMON symbols like a regular linker does and will allocate them at the end of the .bss section if they do appear.

Custom Beacon API

Beacon Object Files can utilize what is known as a “Beacon API” or a set of API functions the BOF loader exposes for the BOF to interact with the loader itself.

Cobalt Strike’s Beacon API is included by default but developers can utilize a custom Beacon API instead of the default Cobalt Strike one.

The custom Beacon API is an import library that is passed in using the --custom-api command line flag.

Here is an example on how to use a custom Beacon API with Boflink.

The custom API for this example includes four functions: MyApiVersion, MyApiPrintf, MyApiAlloc and MyApiFree. A Module-Definition File can be used for creating an import library that exports these symbols.

myapi.def

LIBRARY MyApi
EXPORTS
  MyApiVersion
  MyApiPrintf
  MyApiAlloc
  MyApiFree

Using llvm-dlltool on Linux

llvm-dlltool -l libmyapi.a -d myapi.def

Using lib.exe on Windows

lib /machine:x64 /def:myapi.def /out:myapi.lib

Using MinGW dlltool

x86_64-w64-mingw32-dlltool -l libmyapi.a -d myapi.def

It is recommended to use llvm-dlltool over MinGW dlltool. The reason for this is that the import libraries that llvm-dlltool and lib.exe create are better optimized when compared to MinGW dlltool.

Here is the example source code.

myapi.h

#ifndef MYAPI_H
#define MYAPI_H

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus


#include <stdint.h>

__declspec(dllimport) int MyApiVersion(void);
__declspec(dllimport) void MyApiPrintf(const char *format, ...);
__declspec(dllimport) void *MyApiAlloc(size_t size);
__declspec(dllimport) void MyApiFree(void *ptr);


#ifdef __cplusplus
};
#endif // __cplusplus

#endif // MYAPI_H

custom-api.c

#include "myapi.h"


void go(void) {
    int version = MyApiVersion();
    MyApiPrintf("MyApiVersion: %d", version);

    int *value = MyApiAlloc(sizeof(int));
    *value = 123;
    MyApiPrintf("value: %d", *value);

    MyApiFree(value);
}

The BOF can be compiled and linked with the import library that contains the API symbols.

MinGW GCC

# llvm-dlltool is preferred over x86_64-w64-mingw32-dlltool
llvm-dlltool -l libmyapi.a -d myapi.def

# x86_64-w64-mingw32-dlltool is supported but should be used only if llvm-dlltool is not available
x86_64-w64-mingw32-dlltool -l libmyapi.a -d myapi.def

# Usage
x86_64-w64-mingw32-gcc -B ~/.local/libexec/boflink -fno-lto -nostartfiles -Wl,--custom-api=libmyapi.a -o custom-api.bof custom-api.c

Clang

llvm-dlltool -l libmyapi.a -d myapi.def

clang --ld-path=$(which boflink) --target=x86_64-windows-gnu -nostartfiles -Wl,--custom-api=libmyapi.a -o custom-api.bof custom-api.c

MSVC

lib /machine:x64 /def:myapi.def /out:myapi.lib

cl /GS- /c /Fo:custom-api.obj custom-api.c
boflink --custom-api myapi.lib -o custom-api.bof custom-api.obj

The --custom-api command flag also provides some flexibility on how Boflink finds the import library. It can either be the path to the import library on disk or the name of a link library for Boflink to search for in the list of library search paths.

If the custom API import library is a part of some packaged tool chain stored at /toolchains/myapi/lib/libmyapi.a, then it can be linked to using the following command line flags.

x86_64-w64-mingw32-gcc -B ~/.local/libexec/boflink -fno-lto -nostartfiles -Wl,--custom-api=myapi -o custom-api.bof custom-api.c -L /toolchains/myapi/lib

boflink -o custom-api.bof custom-api.o –custom-api myapi -L /toolchains/myapi/lib

Boflink will add the /toolchains/myapi/lib search path to its list of link library search paths and search for the libmyapi.a library.

Link Graph Visualization

Internally, Boflink creates a directed graph that is used for performing various linking operations. During the course of development, it became useful to visualize this graph with an external tool.

The --dump-link-graph flag will write out the state of the link graph in GraphViz DOT format to the file specified.

x86_64-w64-mingw32-gcc -B ~/.local/libexec/boflink -fno-lto -nostartfiles -Wl,--dump-link-graph=graph.dot -o example.bof example.c

clang --ld-path=$(which boflink) --target=x86_64-windows-gnu -nostartfiles -Wl,--dump-link-graph=graph.dot -o example.bof example.c

boflink --dump-link-graph graph.dot -o example.bof example.c

This will create a file named graph.dot which is a plaintext GraphViz dot file containing the link graph. The dot command line tool can be used to render this file into an SVG or PNG file so it can be examined using an image viewer or web browser.

# Installing the Graphviz dot command line tool
sudo apt install graphviz
winget install –id Graphviz.Graphviz

# Converting to an SVG
dot -Tsvg graph.dot -o graph.svg

# Converting to a PNG
dot -Tpng graph.dot -o graph.png

This feature does not add anything feature-wise to the linked BOF but may be useful as a tool for debugging.

MSVCRT Pitfalls

It is fairly common for BOF developers to include and use C standard library functions from msvcrt.dll in their BOFs. The issue with using msvcrt.dll is that Microsoft basically abandoned all support for it back in 2010 since it had many incompatibilities with C89 (yes, the C standard released in 1989) and it could not add C89 support without breaking ABI compatibility. Microsoft does not even ship an import library for it and has not for a while now.

This means that you cannot link with msvcrt.dll on Windows without creating a custom import library for it. Even if you do decide to use msvcrt.dll, the functions contained are not compatible with C89 so the C standard library functions defined in the header files Microsoft provides may not be valid for it.

On the MinGW side, MinGW’s solution for dealing with the msvcrt.dll issues is to basically not deal with it at all. If you try to link with certain functions from msvcrt.dll using MinGW, MinGW will instead statically link their own implementation instead. This is so that you do not accidentally shoot yourself in the foot trying to use some C standard library function without knowing that the implementation for it inside msvcrt.dll is completely different than the header definition for it.

The solution for this with Boflink is to use UCRT instead. UCRT is the replacement for msvcrt.dll and is installed by default starting with Windows 10. Boflink supports linking with the UCRT both on Windows with MSVC and using MinGW.

As for UCRT support with BOF loaders, I am not sure how every single BOF loader is implemented so it may vary. I do know that TrustedSec’s COFFLoader has worked when using UCRT in some of my testing.

To link with UCRT on Windows pass -lucrt as an additional link flag for finding C standard library functions.

MinGW ships a separate UCRT toolchain with UCRT support. It includes x86_64-w64-mingw32ucrt-gcc as a separate compiler instead of x86_64-w64-mingw32-gcc. Using x86_64-w64-mingw32ucrt-gcc will link with UCRT.

Linking against msvcrt.dll is highly discouraged due to the pitfalls stated above. If using UCRT is not an option, it is recommended to try and find alternative functions from shlwapi.h or strsafe.h. Another option is to use compiler intrinsic functions if the compiler includes them.

This may be rather inconvenient to many people who are used to using msvcrt.dll in their BOFs. Seeing that it is very prevalent in many open source BOFs, I did spend a lot of time figuring out how to add some support for it as a fallback. I could not figure out a good solution that would work in a non-intrusive way and since Microsoft has been trying to migrate to UCRT, supporting that is a better option.

Language Support

Boflink was developed and tested with BOFs written in C. This is because C is by far the most common language used when developing BOFs. Languages outside of C, such as C++, have not been tested at all with Boflink.

That being said, some C++ may work currently but since it has not been tested, the state of C++ support is unknown. Most of the COFF spec is implemented in Boflink but there may be some edge cases with C++ compilers that Boflink does not handle properly. On top of this, there are some language features in C++ which cannot be expressed properly in a COFF. Those features would require some form of runtime initialization to happen either during startup or with the BOF loader.

Conclusion

This project was designed with the goal to help streamline the BOF development process. There are many aspects with BOF development that are notoriously tedious and can make it somewhat more difficult. On the fly capability development has become an increasingly more demanding task. Time and research spent on further streamlining the development process is often neglected but can provide a lot of long term value.

As an aside, some people may be asking: “Isn’t this tool a little bit overkill for typical BOF development scenarios?”. Yes, I absolutely agree that this is a pretty over the top solution for the current issues BOF developers face. This project was also a personal research project for me to understand more about how linkers work. I decided to use Beacon Object Files for this since it can provide some value as a development tool and writing a linker for BOFs is a lot simpler than for full executables.

Recently, I came across a post on X by @0xTriboulet asking how to deal with large header files in Visual Studio projects https://x.com/0xTriboulet/status/1878139439714558169.

intelligence intellisense

Based on this post and the rest of the thread, I assume that they were attempting to insert the binary data from a file in their program by converting it into a large C byte array and then pasting that array into a header file.

This is a very common method of embedding binary data from a file inside a C/C++ project. The file data gets converted to hex or decimal and wrapped inside a C array.

#ifndef MYFILE_HEADER_H
#define MYFILE_HEADER_H

const unsigned char MYFILE_DATA[] = { 0x41, 0x41, 0x41, 0x41, 0x41, 0x41, ... };

#endif // MYFILE_HEADER_H

Although this does work, it can lead to some issues with code analysis tools, like auto completion, when they attempt to process this file.

An alternative method of embedding files in a C/C++ program is by skipping the source code part altogether and instead convert the needed file directly into an object file that can be linked in at build time.

TL; DR

GNU/MinGW ld can generate an object file from arbitrary binary data using the -r and -b binary options. This object file will export a few symbols named _binary_FILENAME_start, _binary_FILENAME_end, and _binary_FILENAME_size which can be used to reference the embedded data.

More information can be found in this StackOverflow thread.

A script or other tools can also be used to generate object files with other files embedded into it.

Generating COFFs with ld

This method only¹ works with GNU/MinGW ld and LLVM lld. These linkers support different targets which determine what type of object files they are capable of generating. The target formats supported by both GNU/MinGW ld and LLVM lld are listed in the --help output of each program.

# GNU ld
ld --help | grep 'supported targets'
ld: supported targets: elf64-x86-64 elf32-i386 elf32-iamcu elf32-x86-64 pei-i386 pe-x86-64 pei-x86-64 elf64-little elf64-big elf32-little elf32-big pe-bigobj-x86-64 pe-i386 pdb elf64-bpfle elf64-bpfbe srec symbolsrec verilog tekhex binary ihex plugin

# LLVM lld
ld.lld --help | grep 'supported targets'
ld.lld: supported targets: elf

The target format can be specified using the --oformat flag on the command line. These linkers also support another flag, -r, which specifies that they should generate a relocatable object file as output instead of a typical executable or shared library. The -b option is used to specify the type of input file.

Here is how a COFF can be generated using ld with the contents of an arbitrary file embedded inside it.

matt@laptop :: ~ >> cat hello.txt
Hello World
matt@laptop :: ~ >> ld -r --oformat pe-x86-64 -b binary -o hello.o hello.txt
matt@laptop :: ~ >> file hello.o
hello.o: Intel amd64 COFF object file, no relocation info, no line number info, not stripped, 1 section, symbol offset=0x4c, 3 symbols, 1st section name ".data"
matt@laptop :: ~ >>

MinGW ld can also do the same but without needing the --oformat since it produces COFFs by default.

Along with the embedded file data, the COFF will also contain a set of symbols that can be used for referencing that data. These symbols can be viewed using any generic tool that is capable of displaying the symbol table of a COFF. One such tool is rabin2.

matt@laptop :: ~ >> rabin2 -s hello.o
[Symbols]
nth paddr      vaddr      bind   type size lib name                    demangled
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x0000003c 0x00000000 GLOBAL UNK  4        _binary_hello_txt_start
0   0x00000000 0x00000000 GLOBAL UNK  4        _binary_hello_txt_size
0   0x00000048 0x0000000c GLOBAL UNK  4        _binary_hello_txt_end

The symbol names are derived from the name of the input file passed into ld.

Using ld Generated COFFs

Now in the C/C++ program, the file data can be referenced through those exported symbols.

#include <stdio.h>

extern unsigned char _binary_hello_txt_start[];
extern unsigned char _binary_hello_txt_end;
extern unsigned char _binary_hello_txt_size;

int main(void) {
    printf("Array: %p\n", _binary_hello_txt_start);
    printf("Array end: %p\n", &_binary_hello_txt_end);
    printf("Array size: %llu\n", &_binary_hello_txt_size);
    return 0;
}

There are three important things worth mentioning here:

1. The file data is not guaranteed to be NULL terminated. If the data is being used as a string, a NULL terminator should be manually inserted to ensure that it is present. ld will pad the section with NULL bytes to match the specified alignment (16 bytes) but will not add this padding if it is not needed. The NULL terminator can be added either before the input file is passed through ld or during post-processing.
2. The _binary_hello_txt_end symbol is the first byte past the end of the file data. A & is needed to get the address of it.
3. The _binary_hello_txt_size symbol is a little weird. The actual size of the file data is the address of the symbol and not the symbol itself. This is why the & is needed to get the array size. It may be easier to create a macro that derives the size of the file data based on the start and end addresses of the array.

#include <stdio.h>

extern unsigned char _binary_hello_txt_start[];
extern unsigned char _binary_hello_txt_end;

#define hello_txt_size (&_binary_hello_txt_end - _binary_hello_txt_start)

int main(void) {
    printf("Array size: %llu\n", hello_txt_size);
    return 0;
}

The object file with the embedded file data can be linked in as is without needing to add any special link flags.

x86_64-w64-mingw32-gcc -o main.exe main.c hello.o

# Or with clang
clang --target=x86_64-windows-gnu -o main.exe main.c hello.o

This method of embedding arbitrary file data into a C/C++ program is a lot nicer since it does not require any extra developer tooling and eliminates the need to generate a source file for the embedded data.

Object Post-Processing

Some post-processing may be needed in order to get the object file in a more desirable state. This can be done with objcopy or various other custom tools.

Here are some example scenarios where objcopy can be used to make these modifications.

Renaming the Exported Symbols

The auto-generated symbol names can be renamed using the --redefine-sym flag.

objcopy \
	--redefine-sym _binary_hello_txt_start=hello_data_start \
	--redefine-sym _binary_hello_txt_end=hello_data_end \
	--redefine-sym _binary_hello_txt_size=hello_data_size \
	hello.o

Removing the _size Symbol

If the *_size symbol or any other symbol is not needed, it can be removed from the COFF.

objcopy -N _binary_hello_txt_size hello.o

Adding a Trailing NULL Byte

A trailing NULL byte can be added at the end of the file data if it is being used as a string. This is done by creating a temporary file with the extracted section data, adding the trailing NULL byte to it, and then reinserting it back into the COFF.

export SECTION_TMPFILE=$(mktemp -t -p /tmp objcopy-section.XXXXX)
objcopy --dump-section .data=$SECTION_TMPFILE hello.o
printf '\0' >> $SECTION_TMPFILE
objcopy --update-section .data=$SECTION_TMPFILE hello.o
rm $SECTION_TMPFILE
unset SECTION_TMPFILE

Changing the Section of the File Data

ld by default will insert the file into the .data section. This can be changed to a different section if desired.

objcopy --rename-section .data=.rdata hello.o

The section flags will automatically be adjusted if the new section name is a standard section name. If the section flags need to be manually adjusted for custom sections, they can be specified using the --set-section-flags option or in the --rename-section option.

objcopy --rename-section .data=custom hello.o
objcopy --set-section-flags custom=alloc,load,readonly,data,contents hello.o

# Changing the flags during renaming
objcopy --rename-section .data=custom,alloc,load,readonly,data,contents hello.o

The flag values are listed under the --set-section-flags option in the objcopy man page.

Generating COFFs from Scratch

ld and objcopy provide a ton of flexibility for converting arbitrary binary data files into linkable object files. One of the disadvantages is that this file embedding workflow is not ideal for Windows environments. MSVC’s link.exe is unable to generate an object file from an arbitrary binary input file and LLVM lld only supports generating ELFs². The Windows version of LLVM lld bundled with Visual Studio also does not support the -r or -b flags.

There are many existing tools publicly available that work on Windows and can generate COFFs from an arbitrary binary file. These can be found by searching for “bin2obj” or “bin2coff” programs online.

Writing a custom tool for this can provide a lot more flexibility than what existing implementations may offer.

It may seem a little complicated at first; however, COFFs are a pretty straightforward file format and the lack of relocations makes things slightly easier.

The “Writing Beacon Object Files Without DFR” blog post starting from the “So How Does This Work?” section contains an in-depth walk through on the COFF file structure which provides some good background on this.

Looking at the COFF Generated by ld

Analyzing the COFFs generated by ld can help with understanding what is all involved to accomplish this.

This will create a basic test COFF for exploring.

echo "Hello World" > hello.txt
ld -r --oformat pe-x86-64 -b binary -o hello.o hello.txt

Here is the hex-dump of the generated COFF.

00000000: 6486 0100 0000 0000 4c00 0000 0300 0000  d.......L.......
00000010: 0000 0500 2e64 6174 6100 0000 0000 0000  .....data.......
00000020: 0000 0000 1000 0000 3c00 0000 0000 0000  ........<.......
00000030: 0000 0000 0000 0000 4000 50c0 4865 6c6c  ........@.P.Hell
00000040: 6f20 576f 726c 640a 0000 0000 0000 0000  o World.........
00000050: 0400 0000 0000 0000 0100 0000 0200 0000  ................
00000060: 0000 1c00 0000 0c00 0000 ffff 0000 0200  ................
00000070: 0000 0000 3300 0000 0c00 0000 0100 0000  ....3...........
00000080: 0200 4900 0000 5f62 696e 6172 795f 6865  ..I..._binary_he
00000090: 6c6c 6f5f 7478 745f 7374 6172 7400 5f62  llo_txt_start._b
000000a0: 696e 6172 795f 6865 6c6c 6f5f 7478 745f  inary_hello_txt_
000000b0: 7369 7a65 005f 6269 6e61 7279 5f68 656c  size._binary_hel
000000c0: 6c6f 5f74 7874 5f65 6e64 00              lo_txt_end.

It is pretty small with the majority of the file consisting of the COFF’s metadata.

Ghidra, or any other disassembler, can also help with further analyzing it.

This listing display contains the entire COFF. There is a COFF File Header, a single Section Header for the .data section and the file contents inside the .data section.

The symbol table (Window -> Symbol Table) lists all of the defined symbols.

These are the symbols that are automatically generated and exported for use inside the main program. The “Source” column in Ghidra shows them as being “Imported” but that just means they are defined with IMAGE_SYM_CLASS_EXTERNAL storage class.

The relocations (Window -> Relocation Table) window will show 0 relocations because there are no references in this COFF that reference external data or data in other sections.

This COFF information can be laid out linearly as it is in the file but with the values for each structure filled in.

/** COFF File header */
struct COFFFileHeader {
    Machine = IMAGE_FILE_MACHINE_AMD64, /* 0x8664 */
    NumberOfSections = 1,
    TimeDateStamp = 0,
    PointerToSymbolTable = 0x4c,
    NumberOfSymbols = 3,
    SizeOfOptionalHeader = 0,
    Characteristics = IMAGE_FILE_RELOCS_STRIPPED | IMAGE_FILE_LINE_NUMS_STRIPPED, /* 0x5 */
};

/** Section Table (Section Headers) */
/* Only 1 section header in the section table */
struct COFFSectionHeader {
    Name = ".data",
    VirtualSize = 0,
    VirtualAddress = 0,
    SizeOfRawData = 0x10,
    PointerToRawData = 0x3c,
    PointerToRelocations = 0,
    PointerToLineNumbers = 0,
    NumberOfRelocations = 0,
    NumberOfLineNumbers = 0,
    Characteristics = IMAGE_SCN_CNT_INITIALIZED_DATA | IMAGE_SCN_ALIGN_16BYTES | IMAGE_SCN_MEM_READ | IMAGE_SCN_MEM_WRITE, /* 0xc0500040 */
};

/** The embedded file's contents are located here after the section header and padded with NULL bytes */
"Hello World"

/** COFF Symbol Table (3 symbols) */
struct COFFSymbol {
    Name = "_binary_hello_txt_start",
    Value = 0,
    SectionNumber = 1,
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL, /* 0x0 */
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL, /* 0x2 */
    NumberOfAuxSymbols = 0,
};

struct COFFSymbol {
    Name = "_binary_hello_txt_size",
    Value = 0xc,
    SectionNumber = IMAGE_SYM_ABSOLUTE, /* -1 */
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL, /* 0x0 */
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL, /* 0x2 */
    NumberOfAuxSymbols = 0,
};

struct COFFSymbol {
    Name = "_binary_hello_txt_end",
    Value = 0xc,
    SectionNumber = 1,
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL, /* 0x0 */
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL, /* 0x2 */
    NumberOfAuxSymbols = 0,
};

/* String table */

One thing missing from this is the COFF’s string table. The string table contains the string values from the Name fields in the COFFSymbol structures. They are stored there because those strings are longer than 8 bytes. More information on how the string table is utilized can also be found in the “So How Does This Work?” section from the “Writing Beacon Object Files Without DFR” post.

In the _binary_hello_txt_size symbol, the value is set to the size of the file data and the symbol’s section value is set to IMAGE_SYM_ABSOLUTE. This is where the weirdness with that symbol mentioned above comes from and why you need to reference the symbol’s address to get the actual value. There is a way to fix that mentioned later in the “Fixing the _size Symbol” section.

The parts that will vary in this metadata are the PointerToSymbolTable field in the COFFFileHeader, the SizeOfRawData field in the COFFSectionHeader, and the Value fields in the _binary_hello_txt_size and _binary_hello_txt_end symbols. They change based on the size of the file being embedded.

There are some patterns with this data. The PointerToSymbolTable field in the COFFFileHeader structure is actually the PointerToRawData field from the COFFSectionHeader structure plus the size of the embedded file itself. The SizeOfRawData field in the COFFSectionHeader is the file size rounded up to the next multiple of the alignment specified in the Characteristics field (IMAGE_SCN_ALIGN_16BYTES 16 bytes). The section data is padded with NULL bytes at the end to reach this size. The Value fields in the _binary_hello_txt_size and _binary_hello_txt_end COFFSymbols are the same and are just the size of the file.

Ultimately, the COFF consists of the structures above laid out in the order below with the file data embedded somewhere in the center.

• COFF File Header
• Section header for the .data section
• Embedded file’s data padded with NULL bytes to reach the specified alignment
• The COFFSymbol structure array
• The string table

Fixing the _size Symbol

The way the *_size symbol is defined is a little bit inconvenient to work with when referencing it in a program. A simple way of fixing this is to append the file’s size at the end of the section and set the *_size symbol to reference that value. Another way is to create a new .rdata section with the file size and have the symbol reference that value.

Here is what the former looks like.

Current layout of the file data and symbol table.

/* The section data as a hexdump */
00000000: 4865 6c6c 6f20 576f 726c 640a 0000 0000  Hello World.....

/* The symbol table */
struct COFFSymbol {
    Name = "_binary_hello_txt_start",
    Value = 0,
    SectionNumber = 1,
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL,
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL,
    NumberOfAuxSymbols = 0,
};

struct COFFSymbol {
    Name = "_binary_hello_txt_size",
    Value = 0xc,
    SectionNumber = IMAGE_SYM_ABSOLUTE,
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL,
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL,
    NumberOfAuxSymbols = 0,
};

struct COFFSymbol {
    Name = "_binary_hello_txt_end",
    Value = 0xc,
    SectionNumber = 1,
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL,
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL,
    NumberOfAuxSymbols = 0,
};

New layout with the file size added in.

/* The section data as a hexdump */
00000000: 4865 6c6c 6f20 576f 726c 640a 0000 0000  Hello World.....
00000010: 0c00 0000 0000 0000 0000 0000 0000 0000  ................ // Size of the file (0xc) in little endian and added at the end with some NULL byte padding.

/* The symbol table */
struct COFFSymbol {
    Name = "_binary_hello_txt_start",
    Value = 0,
    SectionNumber = 1,
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL,
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL,
    NumberOfAuxSymbols = 0,
};

struct COFFSymbol {
    Name = "_binary_hello_txt_size",
    Value = 0x10, // Value adjusted to point to the inserted size value in the section
    SectionNumber = 1, // SectionNumber adjusted to reference the section with the size value
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL,
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL,
    NumberOfAuxSymbols = 0,
};

struct COFFSymbol {
    Name = "_binary_hello_txt_end",
    Value = 0xc,
    SectionNumber = 1,
    Type = IMAGE_SYM_DTYPE_NULL | IMAGE_SYM_TYPE_NULL,
    StorageClass = IMAGE_SYM_CLASS_EXTERNAL,
    NumberOfAuxSymbols = 0,
};

Now, the size of the file data can be referenced without needing to take the address of it.

#include <stdint.h>
#include <stdio.h>

extern char _binary_hello_txt_start[];
extern char _binary_hello_txt_end;
extern size_t _binary_hello_txt_size;

int main(void) {
    printf("Array size: %llu\n", _binary_hello_txt_size);
    return 0;
}

bin2coff.py

I wrote a small, self-contained python script for generating COFFs that should work on various different platforms (Linux, Windows, Mac, etc.).

https://gist.github.com/MEhrn00/9615b92d9bfd3c85d6cba69edb31387d

Generating COFFs from… yaml?

Some people might say that this method is extremely cursed and should not be a thing that actually exists. Others may marvel at its pristine beauty and grasp the true extent of its full potential.

In the LLVM toolset, there exists a set of two peculiar tools named yaml2obj and obj2yaml.

As the names may imply, these tools are capable of creating object files from a yaml file that describes its contents.

Here is what that looks like. The yaml description of the hello.o file from above can be printed out using obj2yaml.

matt@laptop :: ~ >> obj2yaml hello.o
--- !COFF
header:
  Machine:         IMAGE_FILE_MACHINE_AMD64
  Characteristics: [ IMAGE_FILE_RELOCS_STRIPPED, IMAGE_FILE_LINE_NUMS_STRIPPED ]
sections:
  - Name:            .data
    Characteristics: [ IMAGE_SCN_CNT_INITIALIZED_DATA, IMAGE_SCN_MEM_READ, IMAGE_SCN_MEM_WRITE ]
    Alignment:       16
    SectionData:     48656C6C6F20576F726C640A00000000
    SizeOfRawData:   16
symbols:
  - Name:            _binary_hello_txt_start
    Value:           0
    SectionNumber:   1
    SimpleType:      IMAGE_SYM_TYPE_NULL
    ComplexType:     IMAGE_SYM_DTYPE_NULL
    StorageClass:    IMAGE_SYM_CLASS_EXTERNAL
  - Name:            _binary_hello_txt_size
    Value:           12
    SectionNumber:   -1
    SimpleType:      IMAGE_SYM_TYPE_NULL
    ComplexType:     IMAGE_SYM_DTYPE_NULL
    StorageClass:    IMAGE_SYM_CLASS_EXTERNAL
  - Name:            _binary_hello_txt_end
    Value:           12
    SectionNumber:   1
    SimpleType:      IMAGE_SYM_TYPE_NULL
    ComplexType:     IMAGE_SYM_DTYPE_NULL
    StorageClass:    IMAGE_SYM_CLASS_EXTERNAL
...

This yaml data contains all of the information pertaining to this COFF.

A new COFF can be generated by modifying the values in this yaml file or by creating a new yaml file from scratch and then running it through yaml2obj.

For the purpose of embedding files into C/C++ programs, this is achievable with yaml2obj.

The yaml example file above can be used as a template for embedding another file into it. The section data string will need to be replaced with the hex string of the target file for embedding and the other metadata needs to be adjusted to account for the size of the file data. Then, yaml2obj can take the modified yaml file and generate a fresh object file for linking that contains the embedded file data.

This process can be scripted out using something like bash or python.

#!/bin/bash

if [ "$#" -ne 3 ]; then
    echo "usage: $0 [INPUT] [OUTPUT] [SYMBOL]"
    exit 1
fi

if [ ! -f "$1" ]; then
    echo "$1 is not a file."
    exit 1
fi

if [ -z "$3" ]; then
    echo "Symbol is empty."
    exit 1
fi

filesize=$(ls -l $1 | cut -d' ' -f5)
filehex=$(xxd -p -u -c0 $1)

sectiondata=$filehex
sectionsize=$filesize

alignment=16
remainder=$(($sectionsize % $alignment))
if [ $remainder -ne 0 ]; then
    padding=$(($alignment - $remainder))
    for _ in $(seq $padding); do
        sectiondata+="00"
    done
    sectionsize=$(($sectionsize + $padding))
fi

tmp=$(mktemp -t -p /tmp yaml2obj.XXXXX)
trap '{ rm -f -- "$tmp"; }' EXIT

cat <<EOF > $tmp
--- !COFF
header:
  Machine:         IMAGE_FILE_MACHINE_AMD64
  Characteristics: [ IMAGE_FILE_RELOCS_STRIPPED, IMAGE_FILE_LINE_NUMS_STRIPPED ]
sections:
  - Name:            .data
    Characteristics: [ IMAGE_SCN_CNT_INITIALIZED_DATA, IMAGE_SCN_MEM_READ, IMAGE_SCN_MEM_WRITE ]
    Alignment:       16
    SectionData:     $sectiondata
    SizeOfRawData:   $sectionsize
symbols:
  - Name:            _binary_${3}_start
    Value:           0
    SectionNumber:   1
    SimpleType:      IMAGE_SYM_TYPE_NULL
    ComplexType:     IMAGE_SYM_DTYPE_NULL
    StorageClass:    IMAGE_SYM_CLASS_EXTERNAL
  - Name:            _binary_${3}_size
    Value:           $filesize
    SectionNumber:   -1
    SimpleType:      IMAGE_SYM_TYPE_NULL
    ComplexType:     IMAGE_SYM_DTYPE_NULL
    StorageClass:    IMAGE_SYM_CLASS_EXTERNAL
  - Name:            _binary_${3}_end
    Value:           $filesize
    SectionNumber:   1
    SimpleType:      IMAGE_SYM_TYPE_NULL
    ComplexType:     IMAGE_SYM_DTYPE_NULL
    StorageClass:    IMAGE_SYM_CLASS_EXTERNAL
EOF

yaml2obj -o $2 $tmp
rm -f $tmp

This should generate a COFF with the data from the specified file embedded into it.

Unfortunately, yaml2obj does not ship with Visual Studio’s clang tools and is not present in the LLVM.LLVM package from winget so it may need to be compiled from source in order to use it on Windows.

Build System Integration

It’s generally not a good idea to commit binary files into version control unless the the version control system has good support for them. Git has Git LFS for this and is available on Github but it would be great to automate generating these COFFs during the main program’s build process.

Most build systems should support defining and running custom commands which makes it possible to integrate this during the build process. Here are some basic examples using make, nmake, cmake and meson with the bin2coff.py script. These examples are for a basic project with a main.c source file and a hello.txt file that needs to be embedded. The bin2coff.py script is put in a separate scripts/ directory at scripts/bin2coff.py to keep the root of the project more organized.

Makefile

CC = x86_64-w64-mingw32-gcc
PYTHON = python3
BIN2COFF = scripts/bin2coff.py


.PHONY : all clean
all : main.exe

clean:
	rm main.exe main.o hello.o

main.exe : main.o hello.o
	$(CC) $(LDFLAGS) $(TARGET_ARCH) $^ $(LDLIBS) -o $@

hello.o : hello.txt
	$(PYTHON) $(BIN2COFF) -m amd64 $< $@

NMake

PYTHON = python3
BIN2COFF = .\scripts\bin2coff.py

all : main.exe

clean:
	del /f main.exe main.obj hello.obj

main.exe : main.obj hello.obj
	$(CC) $(CFLAGS) /Fe:$@ $**

hello.obj : hello.txt
	$(PYTHON) $(BIN2COFF) $? $@

CMakeLists.txt

cmake_minimum_required(VERSION 3.18)

project(example LANGUAGES C)

find_package(Python REQUIRED COMPONENTS Interpreter)

add_custom_command(
  OUTPUT hello.o
  COMMAND
    ${Python_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/scripts/bin2coff.py
      ${CMAKE_CURRENT_SOURCE_DIR}/hello.txt
      hello.o
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/hello.txt
  COMMENT "Building hello.o from hello.txt with bin2coff.py"
  VERBATIM
)

add_custom_target(hello_gen DEPENDS hello.o)

add_library(hello OBJECT IMPORTED)
set_target_properties(hello PROPERTIES
  IMPORTED_OBJECTS
    "${CMAKE_CURRENT_BINARY_DIR}/hello.o"
)

add_executable(main main.c)
target_link_libraries(main hello)

meson.build

project('example', 'c')

python = find_program('python3', native : true,  required : true)

hello = custom_target(
  'hello',
  output : 'hello.o',
  input : 'hello.txt',
  command : [python, '@CURRENT_SOURCE_DIR@/scripts/bin2coff.py', '@INPUT@', '@OUTPUT@']
)

executable('main', 'main.c', hello)

Wrapping Up

This post provides an alternative method for embedding file data in C/C++ without needing to store it as a large byte array in the source code. GNU ld is the standard linker on most Linux systems so this process works without needing to install any extra tools. Since COFFs are a relatively straightforward file format, it makes writing a custom tool that performs the same functionality a lot simpler to create.

Beacon Object Files have become very popular for red teams to add additional capabilities on the fly without needing to include the overhead of a reflective DLL or .NET assembly. This advantage comes at the cost of Beacon Object Files being a little bit awkward to develop. One development quirk is the need to prefix imported symbols with the associated library name where the symbol can be found. This concept, known as Dynamic Function Resolution (or DFR), is how the BOF tells the BOF loader where to find external symbols.

What if I told you that you do not need to write these DFR prototypes in your code when developing BOFs?

TL; DR

objcopy supports redefining symbol names in object files using the --redefine-sym or --redefine-syms flag. This can be used to translate imported symbols from the normal system definition to the DFR format during post-processing.

The Need For DFR

An important thing to note about Beacon Object Files is that the resulting file a BOF loader loads is a generic COFF file. This may seem rather obvious to people who have written BOFs before, but it is important to note because it helps identify what exactly a BOF loader has to work with and what data it lacks.

One piece of information that a COFF contains is a symbol table. This is an array of structures listing both the symbols that the COFF defines and the external symbols that the COFF requires. Each symbol definition includes the name of the symbol as is declared in the source file itself. What the symbol table lacks is the name of the external library where the symbol can be found. The linker’s job is to take these symbols from the symbol table and search for them in a predefined set of libraries. Since BOFs do not go through a linking stage, this job is passed on to the BOF loader. Linkers will perform a brute-force style search to locate these symbols which is not the most ideal approach for a BOF loader.

This is where the DFR concept comes into play. Instead of performing this brute-force search every single time a BOF is loaded, the library names are instead integrated directly into the symbol name. The way this is done is by prefixing the symbol name with the library name and separating them with a dollar sign ($). For example, if a BOF requires the symbol CreateFileA and that symbol lives in kernel32.dll, the BOF would instead define the symbol KERNEL32$CreateFileA and the BOF loader will know to search for the CreateFileA symbol in kernel32.

DFR Issues

This method of prepending the library name along with the symbol name works and has been the pretty standard way of defining imports in BOFs but there can be some issues with this approach.

Mismatched Prototypes

Since an already declared symbol needs to be redeclared using the DFR format, this manual redeclaration could potentially not match the original one exactly due to a typo. For basic functions, this error may be easy to find but for more complicated functions, it can be a little bit more difficult to identify.

Some functions in the Windows API are known to include a rather large number of parameters. Take CreateProcessWithLogonW as an example. This is what the DFR declaration would look like in order to use this function in a BOF.

DECLSPEC_IMPORT BOOL WINAPI ADVAPI32$CreateProcessWithLogonW(
	LPCWSTR lpUsername,
	LPCWSTR lpDomain,
	LPCWSTR lpPassword,
	DWORD dwLogonFlags,
	LPCWSTR lpApplicationName,
	LPWSTR lpCommandLine,
	DWORD dwCreationFlags,
	LPVOID lpEnvironment,
	LPCWSTR lpCurrentDirectory,
	LPSTARTUPINFOW lpStartupInfo,
	LPPROCESS_INFORMATION lpProcessInformation);

If a parameter is swapped, omitted, or the type is wrong in the declaration, the function may not behave how it is expected to behave. The exact issue that occurs will depend on what part of the declaration is incorrect. In some cases, the function may work during one run but fail in another one. Like with many things related to C development, it just depends on how the computer is feeling at that moment in time if it is going to work or not ¯\_(ツ)_/¯.

Regardless of what error is returned when this type of issue occurs, this mistake can only be spotted by manually reviewing the code and double checking that the DFR prototype matches the original one exactly.

C++, the Savior

In the “Simplifying BOF Development: Debug, Test, and Save Your B(e)acon” blog post by Fortra, Henri Nurmi mentioned using the C++11 decltype specifier to help solve this issue.

This pattern is less error-prone since the new DFR symbol declaration is constructed directly from the original one.

The same CreateProcessWithLogonW prototype would look something like this using decltype.

DECLSPEC_IMPORT decltype(CreateProcessWithLogonW) ADVAPI32$CreateProcessWithLogonW;

The original function prototype does not need to be manually rewritten since it is provided by decltype.

The caveat here is that you need a C++ compiler to compile the BOF so it requires dealing with some C++ specific nuances like name mangling but it does make declaring DFR prototypes a lot easier.

Executable Generation

During the testing phases of developing a BOF, it is helpful to compile the code into an executable or integrate it into a testing framework. Adding the DFR specification to imported symbols means that they will not be resolvable by the system linker. The system linker is unaware of the DFR format and interprets the <library>$<symbol> value as the symbol name itself.

There are some workarounds for this.

Filename: examplebof.c

#include <windows.h>
#include <lmcons.h>

#include "beacon.h"

DECLSPEC_IMPORT DWORD WINAPI KERNEL32$GetCurrentProcessId(void);
DECLSPEC_IMPORT BOOL WINAPI ADVAPI32$GetUserNameA(LPSTR, LPDWORD);

void go(void) {
    DWORD pid = KERNEL32$GetCurrentProcessId();
    BeaconPrintf(CALLBACK_OUTPUT, "Current process id: %lu", pid);

    char username[UNLEN + 1] = {0};
    if (ADVAPI32$GetUserNameA(username, &(DWORD){ sizeof(username) }) == TRUE) {
        BeaconPrintf(CALLBACK_OUTPUT, "Username: %s", username);
    }
}

// Main function for building as an executable
int main() {
    go();
    return 0;
}

Attempting to compile this example BOF as an executable throws undefined reference errors when linking.

matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> x86_64-w64-mingw32-gcc -o examplebof.exe examplebof.c
/usr/lib/gcc/x86_64-w64-mingw32/14.1.1/../../../../x86_64-w64-mingw32/bin/ld: /tmp/ccQizFTo.o:examplebof.c:(.text+0x14): undefined reference to `__imp_KERNEL32$GetCurrentProcessId'
/usr/lib/gcc/x86_64-w64-mingw32/14.1.1/../../../../x86_64-w64-mingw32/bin/ld: /tmp/ccQizFTo.o:examplebof.c:(.text+0x3b): undefined reference to `__imp_BeaconPrintf'
/usr/lib/gcc/x86_64-w64-mingw32/14.1.1/../../../../x86_64-w64-mingw32/bin/ld: /tmp/ccQizFTo.o:examplebof.c:(.text+0x73): undefined reference to `__imp_ADVAPI32$GetUserNameA'
/usr/lib/gcc/x86_64-w64-mingw32/14.1.1/../../../../x86_64-w64-mingw32/bin/ld: /tmp/ccQizFTo.o:examplebof.c:(.text+0x97): undefined reference to `__imp_BeaconPrintf'
collect2: error: ld returned 1 exit status
matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example 1 >>

A common way of fixing this issue is by wrapping all of the DFR prototypes in an #ifdef macro and choosing which version of the symbol to use depending on if that macro is defined or not. The DFR symbol and the system symbol can be aliased to a common name in order to refer to the different variants based on the configuration.

Filename: examplebof.c

#include <windows.h>
#include <lmcons.h>

#include "beacon.h"

#ifdef BOF
// Use DFR if `BOF` is defined

DECLSPEC_IMPORT DWORD WINAPI KERNEL32$GetCurrentProcessId(void);
#define kernel32_GetCurrentProcessId KERNEL32$GetCurrentProcessId

DECLSPEC_IMPORT BOOL WINAPI ADVAPI32$GetUserNameA(LPSTR, LPDWORD);
#define advapi32_GetUserNameA ADVAPI32$GetUserNameA

#else // BOF
// Do not use DFR if `BOF` is not defined

#define kernel32_GetCurrentProcessId GetCurrentProcessId
#define advapi32_GetUserNameA GetUserNameA

#endif // BOF

void go(void) {
    DWORD pid = kernel32_GetCurrentProcessId();
    BeaconPrintf(CALLBACK_OUTPUT, "Current process id: %lu", pid);

    char username[UNLEN + 1] = {0};
    if (advapi32_GetUserNameA(username, &(DWORD){ sizeof(username) }) == TRUE) {
        BeaconPrintf(CALLBACK_OUTPUT, "Username: %s", username);
    }
}

#ifndef BOF
// Create a main function to wrap the BOF entrypoint
int main() {
    go();
    return 0;
}
#endif // BOF

Passing in the -DBOF flag during compilation will use the DFR import declarations and omitting that flag will use the normal system declarations. Both of the symbols are aliased with <libname>_<symbol> so that the correct symbol is used when referring to them.

# For compiling with the BOF DFR imports
x86_64-w64-mingw32-gcc -DBOF -c -o examplebof.o examplebof.c

# For compiling the executable with the normal system imports
x86_64-w64-mingw32-gcc -o examplebof.exe examplebof.c

Compiling it with a Makefile

Filename: Makefile

CC = x86_64-w64-mingw32-gcc
RM = rm -vf

sources := examplebof.c
objs := $(sources:.c=.o)

.PHONY: all clean
all : examplebof.bof.o examplebof.exe
clean:
	$(RM) examplebof.bof.o examplebof.exe $(objs)

examplebof.o : examplebof.c beacon.h
examplebof.bof.o : examplebof.c beacon.h

%.bof.o : %.c
	$(CC) -DBOF $(CFLAGS) $(TARGET_ARCH) -c $(OUTPUT_OPTION) $<

% : %.o
%.exe : %.o
	$(LINK.o) $^ $(LDLIBS) -o $@

matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> make
x86_64-w64-mingw32-gcc -DBOF   -c -o examplebof.bof.o examplebof.c
x86_64-w64-mingw32-gcc    -c -o examplebof.o examplebof.c
x86_64-w64-mingw32-gcc   examplebof.o  -o examplebof.exe
/usr/lib/gcc/x86_64-w64-mingw32/14.1.1/../../../../x86_64-w64-mingw32/bin/ld: examplebof.o:examplebof.c:(.text+0x3b): undefined reference to `__imp_BeaconPrintf'
/usr/lib/gcc/x86_64-w64-mingw32/14.1.1/../../../../x86_64-w64-mingw32/bin/ld: examplebof.o:examplebof.c:(.text+0x97): undefined reference to `__imp_BeaconPrintf'
collect2: error: ld returned 1 exit status
make: *** [Makefile:20: examplebof.exe] Error 1
matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example 2 >>

The BOF version compiles successfully; however, the executable version still yields a few undefined reference linking errors.

The linker is failing to find the Beacon API (BeaconPrintf) symbols. These symbols typically reside in a BOF loader and are resolved during the loading process so they do not live anywhere on the system for the linker to find.

A workaround for this issue is to create mock implementations of the Beacon API and link them in when compiling the executable version. The provided Visual Studio BOF template mentioned in the “Simplifying BOF Development: Debug, Test, and Save Your B(e)acon” blog post uses this strategy (Cobalt-Strike/bof-vs/BOF-template/base/mock.cpp#L391).

The mock Beacon API implementations can be ported over in a way that works with this BOF. Ideally, these would be implemented in a static library that can be reused across different projects but since BeaconPrintf is the only function needed for this project, it is fine to just include it along with the BOF.

Filename: beacon_mock.c

#include "beacon_mock.h"

#include <assert.h>
#include <stdarg.h>
#include <stdio.h>

/// BeaconPrintf implementation for printing to stdout.
/// Based off of https://github.com/Cobalt-Strike/bof-vs/blob/855a33afacd6efad3eaceebe42c5ece4a435d91d/BOF-Template/base/mock.cpp#L391 but ported to C
void BeaconPrintf(int type, const char *fmt, ...) {
	printf("[Output Callback: (0x%02x)]: ", type);
	va_list args;
	va_start(args, fmt);
	vprintf(fmt, args);
	puts("");
	assert(fflush(stdout) == 0);
	va_end(args);
}

Filename: beacon_mock.h

#ifndef BEACON_MOCK_H
#define BEACON_MOCK_H

#define CALLBACK_OUTPUT      0x0
#define CALLBACK_OUTPUT_OEM  0x1e
#define CALLBACK_OUTPUT_UTF8 0x20
#define CALLBACK_ERROR       0x0d

void BeaconPrintf(int type, const char *fmt, ...);

#endif // BEACON_MOCK_H

Filename: examplebof.c

#include <windows.h>
#include <lmcons.h>

#ifdef BOF
// Include the regular beacon.h definitions when compiling as a BOF
#include "beacon.h"

DECLSPEC_IMPORT DWORD WINAPI KERNEL32$GetCurrentProcessId(void);
#define kernel32_GetCurrentProcessId KERNEL32$GetCurrentProcessId

DECLSPEC_IMPORT BOOL WINAPI ADVAPI32$GetUserNameA(LPSTR, LPDWORD);
#define advapi32_GetUserNameA ADVAPI32$GetUserNameA

#else // BOF
// Include the mock Beacon API definitions when compiling as a standalone executable
#include "beacon_mock.h"

#define kernel32_GetCurrentProcessId GetCurrentProcessId
#define advapi32_GetUserNameA GetUserNameA

#endif // BOF

void go(void) {
    DWORD pid = kernel32_GetCurrentProcessId();
    BeaconPrintf(CALLBACK_OUTPUT, "Current process id: %lu", pid);

    char username[UNLEN + 1] = {0};
    if (advapi32_GetUserNameA(username, &(DWORD){ sizeof(username) }) == TRUE) {
        BeaconPrintf(CALLBACK_OUTPUT, "Username: %s", username);
    }
}

#ifndef BOF
// Create a main function to wrap the BOF entrypoint
int main() {
    go();
    return 0;
}
#endif // BOF

And adjusting the Makefile above to include the new mock Beacon API implementations

Filename: Makefile

CC = x86_64-w64-mingw32-gcc
RM = rm -vf

sources := examplebof.c beacon_mock.c
objs := $(sources:.c=.o)

.PHONY: all clean
all : examplebof.bof.o examplebof.exe
clean:
	$(RM) examplebof.bof.o examplebof.exe $(objs)

examplebof.exe : examplebof.o beacon_mock.o
examplebof.bof.o : examplebof.c beacon.h

examplebof.o : examplebof.c beacon_mock.h
beacon_mock.o : beacon_mock.c beacon_mock.h

%.bof.o : %.c
	$(CC) -DBOF $(CFLAGS) $(TARGET_ARCH) -c $(OUTPUT_OPTION) $<

% : %.o
%.exe : %.o
	$(LINK.o) $^ $(LDLIBS) -o $@

Compiling this as both a BOF and a standalone executable should work now since there is an implementation for BeaconPrintf present that the linker can find.

matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> ls
beacon.h  beacon_mock.c  beacon_mock.h  examplebof.c  Makefile
matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> make
x86_64-w64-mingw32-gcc -DBOF   -c -o examplebof.bof.o examplebof.c
x86_64-w64-mingw32-gcc    -c -o examplebof.o examplebof.c
x86_64-w64-mingw32-gcc    -c -o beacon_mock.o beacon_mock.c
x86_64-w64-mingw32-gcc   examplebof.o beacon_mock.o  -o examplebof.exe
matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> ls
beacon.h  beacon_mock.c  beacon_mock.h  beacon_mock.o  examplebof.bof.o  examplebof.c  examplebof.exe  examplebof.o  Makefile
matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> wine ./examplebof.exe
002c:fixme:winediag:loader_init wine-staging 9.15 is a testing version containing experimental patches.
002c:fixme:winediag:loader_init Please mention your exact version when filing bug reports on winehq.org.
[Output Callback: (0x00)]: Current process id: 32
[Output Callback: (0x00)]: Username: matt
matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >>

Symbol Redefining With Objcopy

As seen above, this method for managing DFR imports can be a little bit of a hassle. It requires various macros and other helpers in the source code causing a lot of clutter. It would be nice if there was a way to write a BOF like a normal C program but manage the DFR aspects separately outside of the source code.

This is possible using something like objcopy.

Objcopy is a tool from the GNU Binutils designed to manipulate object files. The Binutils have been around for over two decades and are pretty common on most Linux systems. Objcopy supports various different object file formats including COFFs.

One feature that objcopy includes is the ability to rename symbols using the --redefine-sym flag. This allows changing the name of a symbol in an existing object file.

Here is how this can be utilized with Beacon Object Files.

The example BOF code above can be rewritten to remove all of the DFR specifics.

Filename: examplebof.c

#include <windows.h>
#include <lmcons.h>

#include "beacon.h"

void go(void) {
    DWORD pid = GetCurrentProcessId();
    BeaconPrintf(CALLBACK_OUTPUT, "Current process id: %lu", pid);

    char username[UNLEN + 1] = {0};
    if (GetUserNameA(username, &(DWORD){ sizeof(username) }) == TRUE) {
        BeaconPrintf(CALLBACK_OUTPUT, "Username: %s", username);
    }
}

Compiling this version of the example BOF and using it with TrustedSec’s COFFLoader will fail.

PS C:\Users\User\Documents\writing-bofs-without-dfr-example> .\COFFLoader.exe go .\examplebof.bof.o
Got contents of COFF file
Running/Parsing the COFF file
Machine 0x8664
Number of sections: 7
TimeDateStamp : 0
PointerToSymbolTable : 0x2C2
NumberOfSymbols: 21
OptionalHeaderSize: 0
Characteristics: 4
...
Doing Relocations of section: 0
        VirtualAddress: 0x14
        SymbolTableIndex: 0x12
        Type: 0x4
        SymPtr: 0x1A
        SymVal: __imp_GetCurrentProcessId
        SectionNumber: 0x0
Failed to resolve symbol
Returning
Failed to run/parse the COFF file
PS C:\Users\User\Documents\writing-bofs-without-dfr-example>

COFFLoader throws an error during the processing of the __imp_GetCurrentProcessId symbol because it is unable to parse out the library name.

Using objcopy, the imported symbols in the example BOF can be rewritten to match the DFR format. This is what the BOF loader expects to see when resolving these imported symbols.

objcopy \
	--redefine-sym '__imp_GetCurrentProcessId=__imp_KERNEL32$GetCurrentProcessId' \
	--redefine-sym '__imp_GetUserNameA=__imp_ADVAPI32$GetUserNameA' \
	examplebof.bof.o examplebof-redefined.bof.o

Rabin2 can be used to verify that the symbols were renamed properly.

File: examplebof.bof.o

matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> rabin2 -s examplebof.bof.o
[Symbols]
nth paddr      vaddr      bind   type size lib name                          demangled
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x00000000 0x00000000 LOCAL  FILE 4        .file
0   0x0000012c 0x00000000 GLOBAL FUNC 4        go
0   0x0000012c 0x00000000 LOCAL  SECT 4        .text
0   0x00000000 0x000000b0 LOCAL  SECT 4        .data
0   0x00000000 0x000000c0 LOCAL  SECT 4        .bss
0   0x000001dc 0x000000d0 LOCAL  SECT 4        .rdata
0   0x0000020c 0x00000100 LOCAL  SECT 4        .xdata
0   0x0000021c 0x00000110 LOCAL  SECT 4        .pdata
0   0x00000228 0x00000120 LOCAL  UNK  4        .rdata$zzz
0   ---------- ---------- NONE   UNK  4        imp.__imp_GetCurrentProcessId
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_GetUserNameA

File: examplebof-redefined.bof.o

matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> rabin2 -s example-redefined.bof.o
[Symbols]
nth paddr      vaddr      bind   type size lib name                                   demangled
―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x00000000 0x00000000 LOCAL  FILE 4        .file
0   0x0000012c 0x00000000 GLOBAL FUNC 4        go
0   0x0000012c 0x00000000 LOCAL  SECT 4        .text
0   0x00000000 0x000000b0 LOCAL  SECT 4        .data
0   0x00000000 0x000000c0 LOCAL  SECT 4        .bss
0   0x000001dc 0x000000d0 LOCAL  SECT 4        .rdata
0   0x0000020c 0x00000100 LOCAL  SECT 4        .xdata
0   0x0000021c 0x00000110 LOCAL  SECT 4        .pdata
0   0x00000228 0x00000120 LOCAL  UNK  4        .rdata$zzz
0   ---------- ---------- NONE   UNK  4        imp.__imp_KERNEL32$GetCurrentProcessId
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_ADVAPI32$GetUserNameA

Testing the newly generated BOF with the redefined symbols now works with COFFLoader

PS C:\Users\User\Documents\writing-bofs-without-dfr-example> .\COFFLoader.exe go .\example-redefined.bof.o
Got contents of COFF file
Running/Parsing the COFF file
Machine 0x8664
Number of sections: 7
TimeDateStamp : 0
PointerToSymbolTable : 0x2C2
NumberOfSymbols: 21
OptionalHeaderSize: 0
Characteristics: 4
...
: Section: 0, Value: 0x0
        : Section: 7, Value: 0x0
        8: Section: 0, Value: 0x0
        : Section: 0, Value: 0x0
        : Section: 0, Value: 0x0
        : Section: 0, Value: 0x0
Back
Returning
Ran/parsed the coff
Outdata Below:

Current process id: 9028
Username: User

PS C:\Users\User\Documents\writing-bofs-without-dfr-example>

That command line flag is the only thing needed to get this BOF working. The source can stay how it is without needing the DFR declarations.

Having to specify the import renaming on the command line every time can become difficult to manage as more imports are added. This can be simplified by storing the name mappings inside a dedicated file.

Adding An Imports.txt

Objcopy has a --redefine-syms flag which allows specifying a file with the list of symbol redefinitions instead of needing to pass them on the command line each time. The format for this file is: the current symbol name, a space, and the new name for the symbol. These redefinitions can be listed multiple times in the file on separate lines.

Here is how to create an imports.txt file for the example BOF above.

Filename: imports.txt

__imp_GetCurrentProcessId __imp_KERNEL32$GetCurrentProcessId
__imp_GetUserNameA __imp_ADVAPI32$GetUserNameA

Rerunning objcopy with the symbols specified in the imports.txt file should redefine all of the needed BOF imports.

objcopy --redefine-syms=imports.txt example.bof.o example-redefined.bof.o

Checking the symbol table with rabin2 confirms that the new symbol names were applied correctly.

matt@laptop :: ~/Documents/dev/writing-bofs-without-dfr-example >> rabin2 -s example-redefined.bof.o
[Symbols]
nth paddr      vaddr      bind   type size lib name                                   demangled
―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
0   0x00000000 0x00000000 LOCAL  FILE 4        .file
0   0x0000012c 0x00000000 GLOBAL FUNC 4        go
0   0x0000012c 0x00000000 LOCAL  SECT 4        .text
0   0x00000000 0x000000b0 LOCAL  SECT 4        .data
0   0x00000000 0x000000c0 LOCAL  SECT 4        .bss
0   0x000001dc 0x000000d0 LOCAL  SECT 4        .rdata
0   0x0000020c 0x00000100 LOCAL  SECT 4        .xdata
0   0x0000021c 0x00000110 LOCAL  SECT 4        .pdata
0   0x00000228 0x00000120 LOCAL  UNK  4        .rdata$zzz
0   ---------- ---------- NONE   UNK  4        imp.__imp_KERNEL32$GetCurrentProcessId
0   ---------- ---------- NONE   UNK  4        imp.__imp_BeaconPrintf
0   ---------- ---------- NONE   UNK  4        imp.__imp_ADVAPI32$GetUserNameA

This provides a way of specifying the BOF imports in a separate file outside of the source code itself. The BOF can be written like any other normal C program without needing to make special BOF-specific adjustments for managing imports.

So How Does This Work?

This will do a deep dive into what exactly objcopy is doing under the hood to make this work. Objcopy is from the GNU Binutils, so that means it may not work well on non-free platforms *cough cough Windows*. LLVM has their own version of objcopy (llvm-objcopy) which does work on Windows; however, it may be nice to have a standalone tool dedicated to this. A custom tool can add a lot of flexibility or other features that cater more towards BOF development.

Before diving in, it is good to get familiar with the raw file structure of a COFF. Not just what each of the components (file header, section headers, relocations, etc.) are but also where they are located inside the raw file. Taking a hex dump of a COFF and labeling each component would look like this.

Hexdump output for examplebof.bof.o

───────────────────────────────────────────────────────────────────
00000000: 6486 0700 0000 0000 c202 0000 1500 0000  d............... COFF File Header
                   ┌───────────────────────────────────────────────
00000010: 0000 0400│2e74 6578 7400 0000 0000 0000  .....text....... COFF Section
───────────────────┘                                                Headers
00000020: 0000 0000 b000 0000 2c01 0000 6802 0000  ........,...h...
00000030: 0000 0000 0600 0000 2000 5060 2e64 6174  ........ .P`.dat
00000040: 6100 0000 0000 0000 0000 0000 0000 0000  a...............
00000050: 0000 0000 0000 0000 0000 0000 0000 0000  ................
00000060: 4000 50c0 2e62 7373 0000 0000 0000 0000  @.P..bss........
00000070: 0000 0000 0000 0000 0000 0000 0000 0000  ................
00000080: 0000 0000 0000 0000 8000 50c0 2e72 6461  ..........P..rda
00000090: 7461 0000 0000 0000 0000 0000 3000 0000  ta..........0...
000000a0: dc01 0000 0000 0000 0000 0000 0000 0000  ................
000000b0: 4000 5040 2e78 6461 7461 0000 0000 0000  @.P@.xdata......
000000c0: 0000 0000 1000 0000 0c02 0000 0000 0000  ................
000000d0: 0000 0000 0000 0000 4000 3040 2e70 6461  ........@.0@.pda
000000e0: 7461 0000 0000 0000 0000 0000 0c00 0000  ta..............
000000f0: 1c02 0000 a402 0000 0000 0000 0300 0000  ................
00000100: 4000 3040 2f34 0000 0000 0000 0000 0000  @.0@/4..........
00000110: 0000 0000 4000 0000 2802 0000 0000 0000  ....@...(.......
                             ┌─────────────────────────────────────
00000120: 0000 0000 0000 0000│4000 5040 5557 4881  ........@.P@UWH. Raw data for
─────────────────────────────┘                                      each section
00000130: ec48 0100 0048 8dac 2480 0000 0048 8b05  .H...H..$....H..
00000140: 0000 0000 ffd0 8985 bc00 0000 8b85 bc00  ................
00000150: 0000 4189 c048 8d05 0000 0000 4889 c2b9  ..A..H......H...
00000160: 0000 0000 488b 0500 0000 00ff d048 8d55  ....H........H.U
00000170: b0b8 0000 0000 b920 0000 0048 89d7 f348  ....... ...H...H
00000180: ab48 89fa 8802 4883 c201 c745 ac01 0100  .H....H....E....
00000190: 0048 8d55 ac48 8d45 b048 89c1 488b 0500  .H.U.H.E.H..H...
000001a0: 0000 00ff d083 f801 751f 488d 45b0 4989  ........u.H.E.I.
000001b0: c048 8d05 1800 0000 4889 c2b9 0000 0000  .H......H.......
000001c0: 488b 0500 0000 00ff d090 4881 c448 0100  H.........H..H..
000001d0: 005f 5dc3 9090 9090 9090 9090 4375 7272  ._].........Curr
000001e0: 656e 7420 7072 6f63 6573 7320 6964 3a20  ent process id: 
000001f0: 256c 7500 5573 6572 6e61 6d65 3a20 2573  %lu.Username: %s
00000200: 0000 0000 0000 0000 0000 0000 0111 0585  ................
00000210: 1103 0901 2900 0270 0150 0000 0000 0000  ....)..p.P......
00000220: a800 0000 0000 0000 4743 433a 2028 474e  ........GCC: (GN
00000230: 5529 2031 342e 312e 3120 3230 3234 3036  U) 14.1.1 202406
00000240: 3037 2028 4665 646f 7261 204d 696e 4757  07 (Fedora MinGW
00000250: 2031 342e 312e 312d 332e 6663 3430 2900   14.1.1-3.fc40).
                             ┌─────────────────────────────────────
00000260: 0000 0000 0000 0000│1400 0000 1200 0000  ................ Relocation data
─────────────────────────────┘
00000270: 0400 2c00 0000 0a00 0000 0400 3b00 0000  ..,.........;...
00000280: 1300 0000 0400 7300 0000 1400 0000 0400  ......s.........
00000290: 8800 0000 0a00 0000 0400 9700 0000 1300  ................
000002a0: 0000 0400 0000 0000 0400 0000 0300 0400  ................
000002b0: 0000 0400 0000 0300 0800 0000 0c00 0000  ................
              ┌────────────────────────────────────────────────────
000002c0: 0300│2e66 696c 6500 0000 0000 0000 feff  ...file......... Symbol Table
──────────────┘
000002d0: 0000 6701 6578 616d 706c 6562 6f66 2e63  ..g.examplebof.c
000002e0: 0000 0000 0000 676f 0000 0000 0000 0000  ......go........
000002f0: 0000 0100 2000 0201 0000 0000 0000 0000  .... ...........
00000300: 0000 0000 0000 0000 0000 2e74 6578 7400  ...........text.
00000310: 0000 0000 0000 0100 0000 0301 a800 0000  ................
00000320: 0600 0000 0000 0000 0000 0000 0000 2e64  ...............d
00000330: 6174 6100 0000 0000 0000 0200 0000 0301  ata.............
00000340: 0000 0000 0000 0000 0000 0000 0000 0000  ................
00000350: 0000 2e62 7373 0000 0000 0000 0000 0300  ...bss..........
00000360: 0000 0301 0000 0000 0000 0000 0000 0000  ................
00000370: 0000 0000 0000 2e72 6461 7461 0000 0000  .......rdata....
00000380: 0000 0400 0000 0301 2500 0000 0000 0000  ........%.......
00000390: 0000 0000 0000 0000 0000 2e78 6461 7461  ...........xdata
000003a0: 0000 0000 0000 0500 0000 0301 1000 0000  ................
000003b0: 0000 0000 0000 0000 0000 0000 0000 2e70  ...............p
000003c0: 6461 7461 0000 0000 0000 0600 0000 0301  data............
000003d0: 0c00 0000 0300 0000 0000 0000 0000 0000  ................
000003e0: 0000 0000 0000 0f00 0000 0000 0000 0700  ................
000003f0: 0000 0301 3800 0000 0000 0000 0000 0000  ....8...........
00000400: 0000 0000 0000 0000 0000 1a00 0000 0000  ................
00000410: 0000 0000 0000 0200 0000 0000 3400 0000  ............4...
00000420: 0000 0000 0000 0000 0200 0000 0000 4700  ..............G.
                                       ┌───────────────────────────
00000430: 0000 0000 0000 0000 0000 0200│5a00 0000  ............Z... String Table
───────────────────────────────────────┘
00000440: 2e72 6461 7461 247a 7a7a 002e 7264 6174  .rdata$zzz..rdat
00000450: 6124 7a7a 7a00 5f5f 696d 705f 4765 7443  a$zzz.__imp_GetC
00000460: 7572 7265 6e74 5072 6f63 6573 7349 6400  urrentProcessId.
00000470: 5f5f 696d 705f 4265 6163 6f6e 5072 696e  __imp_BeaconPrin
00000480: 7466 005f 5f69 6d70 5f47 6574 5573 6572  tf.__imp_GetUser
00000490: 4e61 6d65 4100                           NameA.
───────────────────────────────────────────────────────────────────

The important parts are the symbol table, section headers, and the string table. Conveniently, the string table is located at the end of the file.

How do these bits relate to each other? The symbol table and section headers contain string data which may reference the string table. Each structure will set aside 8 bytes in the name field for holding this string data.

The formats for the name fields are outlined in the Section Table (Section Headers) and the COFF Symbol Table PE format documentation.

This can be examined by looking at the entry for the .text section in the hex dump above.

                                               Name (8 bytes)
                                                 │
                   ╭───────────────────┬─────────┴────┬─────╮
00000010:          │2e74 6578 7400 0000│0000 0000     │.text│......
                   ╰───────────────────╯              ╰─────╯
00000020: 0000 0000 b000 0000 2c01 0000 6802 0000  ........,...h...
00000030: 0000 0000 0600 0000 2000 5060            ........ .P`    

Since the name for this section can fit in the 8 bytes set aside for the name field, it is embedded inline with the section metadata.

What happens if the section name is longer than 8 bytes?

That is where the string table comes into play. Instead of the name field containing the name of the section, it will contain a forward slash (/) at the start and then an ASCII number with the index into the string table where the name of the section lies.

This occurs with the last section header in the above hex dump example.

                The name field in this instance is "/4" meaning that the name
                of the section is really in the string table starting at the
                fourth index.
                                               Name (8 bytes)
                                                 │
                   ╭───────────────────┬─────────┴────┬────────╮
00000100:          │2f34 0000 0000 0000│0000 0000     │/4......│....
                   ╰───────────────────╯              ╰────────╯
00000110: 0000 0000 4000 0000 2802 0000 0000 0000  ....@...(.......
00000120: 0000 0000 0000 0000                      ........

And the value in the string table at that index is “.rdata$zzz”.

        Real name of the section
                 │
00000430:        │                      5a00 0000              Z...
         ╭───────┴───────────────────┬─────────────┬──────────╮
00000440:│2e72 6461 7461 247a 7a7a 00│2e 7264 6174 │.rdata$zzz│.rdat
         ╰───────────────────────────╯             ╰──────────╯
00000450: 6124 7a7a 7a00 5f5f 696d 705f 4765 7443  a$zzz.__imp_GetC
00000460: 7572 7265 6e74 5072 6f63 6573 7349 6400  urrentProcessId.
00000470: 5f5f 696d 705f 4265 6163 6f6e 5072 696e  __imp_BeaconPrin
00000480: 7466 005f 5f69 6d70 5f47 6574 5573 6572  tf.__imp_GetUser
00000490: 4e61 6d65 4100                           NameA.

One important thing to note is where this index is based from in the string table. The first four bytes of the string table (0x43c – 0x43f) is the size field. This is a little-endian integer (0x5a) that contains the size of the string table including the size field itself. The data for the string table starts at 0x440 with the size of that data being the value in the size field minus the size of that field (0x5a - 4 = 0x56).

The index defined in the section header is not based from the start of the string table data but rather the start of the string table including the size field.

Symbol names follow the same pattern but with one difference. The difference is outlined in the Symbol Name Representation PE format documentation.

Instead of the first byte of the name starting with a forward slash to signify that the name string is located in the string table, the first four bytes of the name field will be set to NULL and the next four bytes are the string table index. This index is a regular 4 byte, little-endian integer rather than an ASCII decimal number like in the section headers. The name index in the symbol table follows the same rule as the section header name where that index is based from the beginning of the string table starting at the size field instead of where the string data starts.

In the example hex dump, the last symbol in the symbol table contains a symbol name longer than 8 bytes.

           First four bytes are all 0
                                   │     The symbol name is in the string
                                   │     table at index 0x47
                                   │            │
                                  ╭┴────────┬───┴╮
00000420:                         │0000 0000│4700│           ....G.
                                  ╰─────────┤    │
         ╭──────────────────────────────────╯    │
         │    ╭──────────────────────────────────╯
00000430:│0000│0000 0000 0000 0000 0200            ............
         ╰────╯

The string table

00000430:                               5a00 0000               Z...
00000440: 2e72 6461 7461 247a 7a7a 002e 7264 6174   .rdata$zzz..rdat
00000450: 6124 7a7a 7a00 5f5f 696d 705f 4765 7443   a$zzz.__imp_GetC
00000460: 7572 7265 6e74 5072 6f63 6573 7349 6400   urrentProcessId.
00000470: 5f5f 696d 705f 4265 6163 6f6e 5072 696e   __imp_BeaconPrin
                 ╭────────────────────────────────╮   ┌─────────────╮
00000480: 7466 00│5f 5f69 6d70 5f47 6574 5573 6572│ tf│__imp_GetUser│
         ╭───────┘      ╭─────────┬───────────────┴┬──┘  ┌──────────┘
00000490:│4e61 6d65 4100│         │                │NameA│
         └──────────────┘         │                └─────┘
                                  │
               The name of this symbol is "__imp_GetUserNameA"

This shows how the string table is connected to the section headers and the symbol table. Now, on to how the symbol renaming works.

DIY Symbol Renaming

Due to the nature of how the section headers and symbol table interact with the string table, the action of renaming a symbol is pretty straightforward.

The first thing to do is to find the symbol table entry of the symbol which needs to be renamed. The name field will either hold the symbol name as a byte string or an index into the string table depending on if the name is longer than 8 bytes. If the current symbol name and new name it needs to be renamed to are both 8 bytes in length or less, the new name can be inserted directly into the name field replacing the old value. Nothing else in the COFF needs to be modified.

It is a lot more common for symbol names to be longer than 8 bytes which requires a little bit more work. There are a few ways that a symbol can be renamed but this will go over the “naive” way and another way by directly replacing the old string with the new one in the string table.

The Naive Way

Remember earlier in this blog post during the section explaining the COFF file layout it was mentioned that the string table is “conveniently” located at the end of the file? The reason this is convenient is because arbitrary strings can be appended to it without needing to update other parts of the COFF!

COFF metadata will occasionally contain references to other parts of the file. Inserting or removing any data in the middle of the file will cause various components to shift around. This requires going back through the COFF to make sure any old file references are updated to account for this shift. Appending data does not cause this shift so the file references will stay valid.

To rename a symbol the naive way, the new symbol name can simply be appended to the end of the string table while updating the string table size field to account for the added string. All that is left to do is change the name field in the COFF symbol table entry to reference the newly added string. The rest of the COFF can stay as is since this method does not cause any other parts of the file to shift around. The old name string can be left where it is and it will simply exist as a couple extra bytes of unused data.

This approach may not be the most ideal when a lot of symbols need to be renamed since the old symbol names will take up space.

Replacing the Current String Table Entry with the New One

Another option for renaming a symbol is by replacing the current symbol name in the string table with the new name. The only difference here is that the other string table references in the section headers and symbol table will need to be adjusted to account for any shifts. If a symbol needs to be renamed with a new name 9 bytes longer than the original one, any section headers or symbol table entries that reference strings past this string will need their indexes increased by 9 due to the size change.

Wrapping Up

The purpose of this blog post is to showcase a lesser known tool from the GNU Binutils that people may not be too familiar with. Its ability to redefine symbols inside an object file is something that can be utilized in Beacon Object File development. BOFs do not need their imports to be manually declared in DFR format inside the source code. They can be managed separately while the code focuses more on what the BOF is being developed to do. Keeping the source code more inline with how traditional C code is written allows it to better integrate with existing development tools.

Another takeaway is the concept of “decoupling” the constraints of software designed to run in atypical environments from the software itself. Keeping the software more generic makes it easier to work with when needing to test or debug it. Finding alternative ways of dealing with these constraints outside of the code, either through libraries or other tooling, means that the code can focus only on what it is being designed to do while the various environmental factors are handled elsewhere.

Using a dedicated tool for managing imported functions in Beacon Object Files is one example of how this decoupling concept can be applied.

Part one of the series discusses how this project came about and the development of it.

Project repository: https://github.com/MythicAgents/thanatos

Overview

• Thanatos Features and Functionality
  • Installing Mythic with Thanatos: Setting up Mythic and Thanatos on an Ubuntu VM
  • Building the Agent: How to build the payload
  • Using the Agent: Basic functionality
  • Unique Capabilities: Features which standout compared to other C2 agents
• Future Improvements

Thanatos Features and Functionality

If you’re new to Mythic, I highly recommend checking out the Mythic Documentation. Mythic is very unique compared to other C2 frameworks due to its modular design. Other frameworks such as Cobalt Strike or Empire include a full suite of modules including: C2 profiles/transports, stagers, payloads a UI, etc. Mythic decides to take these common features of a C2 framework and split them up into three distinct server, C2 profiles and payload types modules. Due to this design, payloads can vary from compiled .NET Windows executables to chrome web browser extensions. C2 profiles give the operator and developers flexibility on how their payloads communicate with Mythic. This allows a very high level of flexibility to tune the operation based on what the target is. The currently public C2 profiles are HTTP, DNS and websocket but profiles can be developed which utilize AWS S3 buckets, Microsoft Teams, Dropbox or various other mediums for communication.

It’s important to note this modular aspect when using Mythic since it provides a somewhat unique experience when performing red team operations.

Installing Mythic with Thanatos

Setting up a machine with Mythic and installing Thanatos is very straight forward thanks to Mythic’s use of Docker containers. Along the that, there is a convenient mythic-cli program which can be used instead of manually setting up and running all of the images.

The first thing to do is setup Linux machine and install docker. For this example I will be using Ubuntu 20.04 in a virtual machine.

Be sure you allocate enough resources to your machine. I will be using a virtual machine with 20GB of hard drive space, 8GB of ram and 2 vCPUs.

After Linux is setup, docker and docker-compose need to be installed.

sudo apt update
sudo apt install docker.io docker-compose

Ensure the docker daemon has been started and set to start on boot

sudo systemctl enable --now docker

Next, clone the Mythic repository from Github. This can be cloned to anywhere on the machine.

git clone https://github.com/its-a-feature/Mythic.git --depth 1

The --depth 1 is optional but it makes the download significantly faster.

ubuntu@mythic-server:~$ git clone https://github.com/its-a-feature/Mythic.git --depth 1
Cloning into 'Mythic'...
remote: Enumerating objects: 2245, done.
remote: Counting objects: 100% (2245/2245), done.
remote: Compressing objects: 100% (1983/1983), done.
remote: Total 2245 (delta 276), reused 2112 (delta 231), pack-reused 0
Receiving objects: 100% (2245/2245), 24.81 MiB | 17.27 MiB/s, done.
Resolving deltas: 100% (276/276), done.
ubuntu@mythic-server:~$ cd Mythic/
ubuntu@mythic-server:~/Mythic$ ls
C2_Profiles           Example_Payload_Type      install_docker_kali.sh    mythic-docker        postgres-docker  SECURITY.md
docker-compose.yml    Example_Translator        install_docker_ubuntu.sh  mythic-react-docker  rabbitmq-docker  VERSION
documentation-docker  hasura-docker             LICENSE                   nginx-docker         README.md
Example_C2_Profile    install_docker_debian.sh  mythic-cli                Payload_Types        redis-docker
ubuntu@mythic-server:~/Mythic$

The newly cloned Mythic repo contains a mythic-cli program. This program is used for managing the framework.

Configuring the server is done through a .env file located in the Mythic directory. To generate this configuration file run ./mythic-cli config

ubuntu@mythic-server:~/Mythic$ ./mythic-cli config
ALLOWED_IP_BLOCKS = 0.0.0.0/0
COMPOSE_PROJECT_NAME = mythic
DEFAULT_OPERATION_NAME = Operation Chimera
DOCUMENTATION_BIND_LOCALHOST_ONLY = true
DOCUMENTATION_HOST = mythic_documentation
DOCUMENTATION_PORT = 8090
EXCLUDED_C2_PROFILES =
EXCLUDED_PAYLOAD_TYPES =
HASURA_BIND_LOCALHOST_ONLY = true
HASURA_HOST = mythic_graphql
HASURA_PORT = 8080
HASURA_SECRET = bWeMjZIlXjbl54NWlW0GoHv2FJOnhH
JWT_SECRET = ZxkLIpPB5HbH8LNU3kvTpkxS6epnPU
MYTHIC_ADMIN_PASSWORD = 2Kszg9c5fRUDapU1TF9UxNzpfn16HA
MYTHIC_ADMIN_USER = mythic_admin
MYTHIC_DEBUG = false
MYTHIC_ENVIRONMENT = production
MYTHIC_REACT_BIND_LOCALHOST_ONLY = true
MYTHIC_REACT_HOST = mythic_react
MYTHIC_REACT_PORT = 3000
MYTHIC_SERVER_BIND_LOCALHOST_ONLY = true
MYTHIC_SERVER_DYNAMIC_PORTS = 7000-7010
MYTHIC_SERVER_HOST = mythic_server
MYTHIC_SERVER_PORT = 17443
NGINX_BIND_LOCALHOST_ONLY = false
NGINX_HOST = mythic_nginx
NGINX_PORT = 7443
NGINX_USE_SSL = true
POSTGRES_BIND_LOCALHOST_ONLY = true
POSTGRES_DB = mythic_db
POSTGRES_HOST = mythic_postgres
POSTGRES_PASSWORD = zhqoomxZd3BsI1x5tcAnLTosiJjBRG
POSTGRES_PORT = 5432
POSTGRES_USER = mythic_user
RABBITMQ_BIND_LOCALHOST_ONLY = true
RABBITMQ_HOST = mythic_rabbitmq
RABBITMQ_PASSWORD = bIoU2A9M5vZTZ8LopdYpik2pktMDiJ
RABBITMQ_PORT = 5672
RABBITMQ_USER = mythic_user
RABBITMQ_VHOST = mythic_vhost
REBUILD_ON_START = true
REDIS_BIND_LOCALHOST_ONLY = true
REDIS_HOST = mythic_redis
REDIS_PORT = 6379
SERVER_HEADER = nginx 1.2
SIEM_LOG_NAME =
WEB_KEEP_LOGS = false
WEB_LOG_SIZE = 1024000
ubuntu@mythic-server:~/Mythic$

The defaults can be kept the same; however, I am going to set a different admin password.

MYTHIC_ADMIN_PASSWORD="TestingPassword123!@#"

Since this is a test VM for a demo only reachable from my host machine, I am okay with using the default Mythic admin user and an insecure password.

After that’s done, it’s time to install the Thanatos payload and HTTP C2 profile.

sudo ./mythic-cli install github https://github.com/MythicAgents/thanatos
sudo ./mythic-cli install github https://github.com/MythicC2Profiles/http

Mythic can now be started

sudo ./mythic-cli mythic start

This can take a fair bit of time depending on your network connection. Mythic has to download all of the docker images for the server along with the docker images for the HTTP profile and Thanatos.

real    3m4.578s
user    0m2.149s
sys     0m0.422s

If everything went well, Mythic should be reachable at https://<IP address>:7443/ using a web browser.

To make sure everything was set up correctly, log in using the password you set. The username is mythic_admin unless you changed it during the configuration. Navigate to the C2 Profiles and Paylod Types page by clicking on the headphones icon in the top left corner.

Thanatos should be listed under the Payload Types and http under the C2 Profiles with a green status icon.

Note: “tetanus” was the old name for the Mythic agent. This is why the payload types entry has an agent named tetanus instead of thanatos.

Building the Agent

The build page can be reached by clicking on the Payloads icon on the top left of the web page next to the C2 Profiles and Payload Types icon. In the drop down Actions menu in the top left, click the Generate New Payload button.

This menu will prompt you to select the target OS. Thanatos only supports targeting Windows or Linux. After the target OS is selected, the build parameters configuration will be available.

1. The first build parameter is an option to configure how the agent should run. If this options is set and the payload is built for Windows, the agent will hide the console window when it is executed. For Linux, this option controls whether the agent should run in the foreground or fork and run in the background.

2. The second build parameter controls how many attempts the agent should make for the initial check in. If the agent fails to establish a connection when it is executed, it will sleep for the configured interval and try to establish another connection. The retries determine how many attempts the agent should make before it will stop. More information about it can be found in the Mythic documentation.

3. The third parameter configures the output format for the payload file. Thanatos can be built as a standalone executable, a shared library, or raw shellcode for Windows. The shared library option will build a Windows DLL when targeting Windows and an ELF shared object when targeting Linux. The raw shellcode for Windows can be used for injecting the payload through various injection techniques or for developing obfuscation wrappers. Picking the shellcode option when targeting Linux will result in the build failing!

4. The fourth parameter controls static linking for Linux payloads. Statically linking the payload will make the executable size larger; however, it will help ensure it can run on all Linux platforms. This is recommended if trying to spawn the agent on a host using a non glibc libc or on older Linux systems. This option has no effect when building payloads for Windows.

5. The fifth parameter is the payload architecture. The payload can be built to target both 32 and 64 bit x86 systems.

6. The sixth parameter is the working hours. The working hours mean that the agent will only make connections to Mythic during the configured time frame. This also includes the initial check in. If the agent was executed when not in the configured working hours period, it will not check in until the start of the working hours the next day. This option can be changed during operation of the agent using the workinghours command. The format for the working hours is HH:MM-HH:MM using 24 hour format. When operating, the agent will use the targeted system’s locally set time zone. Time zone calculations may be needed in order to compensate for time differences.

After the build parameters are set, the next menu will allow you to configure what commands to build into the agent. The agent does not support dynamic compilation of features so all commands are included.

The C2 profiles page only gives an option for HTTP. There are plans to include different C2 profiles in the future.

• Callback Host

  • Hostname or IP to connect to when beaconing back to Mythic.

• Callback Interval in seconds

  • Sleep interval for the agent in seconds. This can be changed while interacting with the agent using the sleep command.

• Callback Jitter in percent

  • Jitter to apply for the agent’s sleep interval. The agent will pick a random percentage value between 0 and the configured jitter during each sleep time. The jitter is randomly added or subtracted from the configured sleep interval during the sleep time. If the sleep interval is set for 30 seconds and the jitter value is 50%, the agent will choose a random sleep time between 15 to 45 seconds. This value can be changed during operation using the sleep command.

• Callback Port

  • Listening port of the server for http requests.

• Crypto type

  • Choose whether the C2 traffic should be AES256 encrypted or if there should be no encryption.

• GET request URI

  • The URI for performing GET requests.

• HTTP Headers

  • Addition HTTP headers for the agent.

• Kill Date

  • Kill date of the agent

• Query Path Name

  • Name of the query parameter for GET requests

• Perform Key Exchange

  • Configure whether or not the agent should perform a key exchange during the initial check in.

• Proxy Information

  • Connecting to socks proxies from the agent to Mythic is currently unimplemented so these proxy parameters can be left blank

Once the C2 profile information is set, the next page will allow you to name the payload along with setting a description for it. The description for the payload will be the initial description in the C2 callbacks page.

Once the payload creation has kicked off, it can take around 15 seconds to a few minutes for the agent to build depending on VM resources. Thanatos will do dependency caching after the initial build depending on target OS, architecture and static linking. For example, an initial x64 Windows agent build will take the pre-built dependencies and cache them. Future builds targeting Windows x64 will take significantly less time as compared to the initial build because the dependencies from the initial build are used.

The payload builder works this way to keep the initial size of the docker image smaller while also shortening consecutive build times. Not every operation is going to need the pre-build dependencies targeting 32 bit Linux; therefore, those pre-built dependencies are not going to take up unnecessary disk space.

Using the Agent

The basic agent operations are very similar to any other Mythic payload. Thanatos has a few features which are slightly different than other Mythic payloads.

During initial check in for Linux hosts, Thanatos will query information about the Linux kernel version and whether or not the agent is on an SELinux system. That information can be found by clicking on the Linux icon under the OS section in the callback page.

Here is an example of what it will show. The kernel version of the system this payload is running on is 5.16.12-200.fc35.x86_64 and it does have SELinux capabilities.

The interact row can be used to interact with the agent. The dropdown menu provides various quick interactions. Clicking on the keyboard icon will pull up the command window at the bottom of the screen.

Issuing help in the command window will show a list of all the available commands and a brief description about them. More information about the available commands can be found in the Mythic documentation.

The Mythic documentation can be reached by clicking on the question mark in the top right corner and clicking on Agent Documentation. This page is where Mythic will store the documentation about payload types and C2 profiles. The left side of the web page will have a list of all the installed agents. Clicking on Thanatos will pull up the documentation for the Thanatos payload. Clicking on the Commands menu on the left side of the web page will bring up a list of all the commands Thanatos supports. Clicking on the command will take you to that command’s documentation.

Issuing tasking can be done using the Mythic popup UI or through named parameter flags. The Mythic popup UI can be displayed by typing the command in the task Window and pressing Shift + Enter. Commands and their parameters can also be issued directly through the tasking prompt using named parameters or inline with the command.

Not every command supports entering arguments directly in the task prompt. Every command does support the Mythic UI popup by pressing Shift + Enter after typing the command in the tasking prompt. For more information about command parameter formats, refer to the documentation for the command in the Mythic documentation.

Some commands support browser scripts. Browser scripts in Mythic allow more refined ways of formatting the task output along with potentially issuing other tasking through the browser script.

In the ls example, the browser script allows for new tasking to be issued by clicking on any of the tasking buttons. More browser script support is planned for the future since it makes issuing more tasks very convenient.

Unique Capabilities

Thanatos features a few capabilities which other agents do not have. Starting with building the agent, Thanatos allows the operator a lot of flexibility on choosing how to build the agent. This flexibility includes controlling the output format, target architecture, static linking and even whether or not the agent should daemonize. The operator can also choose configuration for the C2 communications such as how many times the agent should attempt to check in if the initial check in fails and what time throughout the day the agent should make check ins to the C2.

Going into the operation of the agent, Thanatos currently has two distinct features that are somewhat unique. The first being its SSH capabilities. The agent uses the ssh2 library in order to make SSH connections. The agent features a whole suite of commands which can all be executed over SSH. These include executing shell commands, downloading and uploading files between the SSH connected machine and Mythic, displaying the contents of files, grabbing directory listings and removing files. Typing ssh into the tasking prompt for a callback and pressing Shift + Enter will display the capabilities and parameters.

The dropdown menu for the parameter group can be selected to choose what action you would like to perform over ssh.

All of the actions are documented in the Mythic documentation but I would like to highlight the List action.

The first parameter for each ssh function is to select what credentials to use. The agent will pull these credentials from the Mythic credential database. When creating a new credential for ssh, the plaintext credential type means that the supplied credential is a plain text username and password combination. A credential type of key signifies that the supplied credential is an SSH private key. The only options in the Mythic credential which need to be populated are the Account Name for the username of the account to log in as for SSH and the Credential which is either the plain text password for the user or an SSH private key.

Once the credential is selected, the use ssh agent option can be set to false. This tells Thanatos whether it should use running ssh agents on the system for authentication instead of through the Mythic credential. More information about that can be found in the documentation for the ssh-agent command.

I have another Linux machine located at 192.168.122.56 where I know the username and password for a user on that machine.

Once I submit the task, the agent will attempt to connect to that machine through SSH with the ubuntu user and grab a directory listing of the root directory.

The SSH command features a browser script which will pull the time metadata and permissions for each entry similar to the regular ls browser script. Along with that, the browser script features the same context menus as the normal ls command. Through the browser script, the operator can issue new SSH tasking to list different subdirectories or perform other actions.

Tasking issued through the browser script will use the same credentials and host information for the new task so the new task will be queued automatically without having to manually fill out the task parameters.

This provides a very convenient way to interact with other machines through SSH without having to spawn a payload on the machine.

The second notable feature is the ability to stand up TCP redirectors through the redirect command. The agent will listen for connections on a machine and relay them to another machine. This is very useful when dealing with machines that do not have direct Internet access. A redirector can be created which will redirect traffic from the machine to a server on the Internet.

The redirect capability can also bring p2p-like functionality to other agents which do not support peer-to-peer connections. The Mythic documentation for the redirect command gives an example of using the redirector to tunnel C2 traffic through the agent. This idea can also be translated to other tools and C2 agents. Empire and meterpreter can be tunneled through Thanatos to give it p2p functionality.

Since setting up redirectors requires binding to a port on the machine, it is not very OPSEC safe and may not be practical in restricted environments. This functionality was designed for lab environments which require a lot of pivoting and lateral movement. I have found when going through various red team labs that there are machines which cannot directly connect to my machine. This can make pivoting a little cumbersome by having to use something like chisel or SSH port forwarding in order to gain access to that machine. Having a tool which contains port forwarding capabilities built in (and eventually socks proxying) makes it more convenient when trying to pivot to other machines since I do not have to upload chisel binaries or rely on the pivot machine having SSH available.

Future Improvements

Future development plans and agent features are mentioned in part one of the blog post series.

Part two of the series goes over setting it up in an Ubuntu VM and its functionality.

Project repository: https://github.com/MythicAgents/thanatos

Overview

• Development

  • Background: Some background on what motivated this project and what this project is
  • Why Mythic?: Advantages of using Mythic for a C2
  • Mythic Payload Development: Development of a Mythic C2 agent
  • Challenges: Challenges faced during development

• Rust Programming Language

  • Offensive Capabilities: Ways Rust is an ideal language for offensive tooling
  • Transitioning from C/C++ to Rust: Transitioning C/C++ concepts to Rust

• Future Improvements

  • Development Plans: Future capabilities and development plans

Development

Background

Back in early 2021, I was having a discussion with Max Harley, a good friend of mine, about the Rust programming language. At that time, our knowledge of Rust was very limited but we both thought it was a really cool language and had plans of getting more familiar with it. Max decided to pitch the idea of writing a Mythic agent in Rust as a project for getting more familiar with the language. Due to the ease of cross-compiling Rust code, we also wanted to make the agent cross-platform. This did not seem like a difficult task since the Rust standard library can be compiled for both Linux and Windows without any modifications. Having a native C2 agent which could target both Linux and Windows allows a lot of flexibility due to it not requiring any runtime dependencies such as python or powershell.

So Max and I, with our very minimal knowledge of Rust, decided to start tackling this project of building a C2 agent for Mythic.

Why Mythic?

There are many C2 frameworks that already exist and include features for developing custom extensions and modules. Building custom extensions for these frameworks is great; however, I wanted to build a fully custom agent. There are not any or very few which allow developing custom fully custom agents. This was very limiting and the other option would be to develop a C2 framework from scratch for the agent. Writing a custom C2 server for the agent would mean that I would have to spend development time creating the server architecture instead of developing only the agent.

Mythic is very unique compared to other frameworks in the sense that it splits up design and functionality into three distinct parts. These parts are the server, the C2 profiles and the C2 agents. Due to this nature, profiles and agents can be developed separately from the server and then integrated into the platform. This design for a C2 framework is where Mythic really excels compared to other platforms. Developers have the freedom to create their own custom agents with unique capabilities for a central server. This allowed me to only focus on the agent aspects without needing to create my own custom framework. There are already great examples of the flexibility Mythic brings with this architecture. The MythicAgents Github organization contains a whole suite of custom agents ranging from fully featured .NET agents to Mac OS JXA agents. On top of custom C2 agents, there are examples of rather unique C2 profiles. The Orthrus agent uses Apple’s MDM to backdoor a Mac OS system and communicates using Apple Push Notifications and the Typhon agent is a malicious JAMF configuration which allows Mythic to act as a JAMF server in order to control JAMF enrolled devices. Mythic’s modularity allows for these fully custom payloads and profiles to be developed to work seamlessly with the Mythic server.

Mythic is the ideal framework for developing custom C2 tools and fits perfectly for my use case. It provides the flexibility for developing a custom agent without having to focus on the server aspects. Using Mythic for agent development is ideal when wanting to include custom payload functionality without creating my own server from scratch. Creating the server from scratch allows for flexibility on the design of the framework; however, it is not always viable to create a new framework from scratch.

Mythic Payload Development

Mythic payload type development is very well documented in the Mythic documentation. The first stage requires creating a directory structure for the agent.

.
├── agent_icons/
│   └── mypayload.svg
├── config.json
├── documentation-payload/
│   └── mypayload/
└── Payload_Type/
    └── mypayload/
        ├── agent_code/
        ├── Dockerfile
        ├── mythic/
        │   ├── agent_functions/
        │   │   ├── builder.py
        │   │   └── __init__.py
        │   ├── browser_scripts/
        │   ├── __init__.py
        │   ├── mythic_service.py
        │   ├── payload_service.sh
        │   └── rabbitmq_config.json
        └── requirements.txt

9 directories, 10 files

There are a few strict rules when it comes to file and directory names. For example: the name of the directory under Payload_Type/* has to be the name of the payload. The same goes for documentation-payload/* for documentation and agent_icons/*.svg for the icon of the agent. The example above assumes that the agent name is mypayload.

Some of the files such as the mythic_service.py and rabbitmq_config.json file need to be pre-populated according to the Mythic documentation or other payload types.

The config.json file includes configuration options for the payload.

{
    "exclude_payload_type": false,
    "exclude_c2_profiles": true,
    "exclude_documentation_payload": false,
    "exclude_documentation_c2": true,
    "exclude_documentation_wrapper": true,
    "exclude_agent_icons": false
}

Since this is only a payload type and doesn’t include any custom C2 profiles, only the exclude_payload_type, exclude_documentation_payload and exclude_agent_icons fields need to be set to false.

Mythic functions using docker containers. The Payload_Type/mypayload/Dockerfile file is used to define the docker container the payload builder will use. There are docker base images already available which include dependencies for building different types of payloads but a custom one can be defined. This docker container is used for building the payload; other functions such as C2 communication are handled in profile containers.

The Payload_Type/mypayload/mythic/agent_functions/builder.py file includes metadata about the payload along with the implementation for building each payload. The Mythic documentation for this file includes a very in-depth guide on what to include in this file in order to define your agent in Mythic along with how to compile build parameters into the payload.

I like to think of payload type development as containing “payload” code and “mythic” code. The payload code is the code for the agent itself and lives in the Payload_Type/mypayload/agent_code/ directory. The actual development of the agent and its features occur here. The other part of the agent is the mythic code which is in the Payload_Type/mypayload/mythic/agent_functions/ directory. Here is where various commands are defined for the agent. This will define the commands and their parameters along with any other pre-tasking before sending it down to the agent. The system for defining commands in Mythic provides a vast set of features for the developer. Information about adding different commands to Mythic can be found in the documentation.

HTTP is a very common C2 communication transport and is one of the easiest to implement. Mythic already includes an HTTP C2 profile which can be used with an agent for C2 communications. This is a fairly straight forward profile which uses HTTP GET/POST requests and base64 encoded JSON data. The initial check in for an agent consists of an HTTP request with the following format.

Base64( PayloadUUID + JSON({
    "action": "checkin", // required
    "ip": "127.0.0.1", // internal ip address - required
    "os": "macOS 10.15", // os version - required
    "user": "its-a-feature", // username of current user - required
    "host": "spooky.local", // hostname of the computer - required
    "pid": 4444, // pid of the current process - required
    "uuid": "payload uuid", //uuid of the payload - required

    "architecture": "x64", // platform arch - optional
    "domain": "test", // domain of the host - optional
    "integrity_level": 3, // integrity level of the process - optional
    "external_ip": "8.8.8.8", // external ip if known - optional
    "encryption_key": "base64 of key", // encryption key - optional
    "decryption_key": "base64 of key", // decryption key - optional
    "process_name": "osascript", // name of the current process - optional
    })
)

The PayloadUUID is generated for each payload at compile time. An HTTP POST request with this in the body of the request will register an initial check in with Mythic in the callbacks page. Encryption can be included in the request payload by following the format specified in the documentation.

From here, an agent can be created by periodically beaconing back to the Mythic server to get tasking and sending the results of completed tasking back.

This goes over the start of building a basic Mythic payload. Creating more advanced commands can be found through the Mythic documentation. The example does not go into depth about all of the other great capabilities included with Mythic. Mythic provides support for registering new commands with a callback. An example can be where an agent loads a DLL during runtime and commands with Mythic can be registered in order to interact with that newly loaded DLL. The Medusa agent includes this capability. Mythic also supports a structure for peer-to-peer communications between agents. An agent can communicate with other agents directly in order to pass on tasking. The Apollo and Poseidon agents support p2p functionality through SMB and/or TCP.

Challenges

There were a few issues faced when developing the agent. These issues were not necessarily design issues but were due to how the Rust programming language is designed and what capabilities I wanted to include into the agent.

The first major issue was compile times. Compiling Rust programs by themselves isn’t slow; however, the way Rust handles compiling and linking dependencies can drastically increase build times. Dependencies for a Rust project are defined in a Cargo.toml file in the root of the project directory. When the project is compiled, each dependency is pulled down and then compiled separately from the main project source and then linked together. Builds are incremental so once the dependencies are compiled in the project, each subsequent build will only build the source code for the main project and link the built dependencies. An initial build of a project may take around 40 seconds to download and compile all of the dependencies whereas subsequent builds only take around 0.3 seconds. This dependency management system works very well; however, it is per-project. If you have two Rust projects that both rely on the same library, each project will compile the library and store the built library in their project directory. On top of this, dependencies will also be built according to what target the project is building for. If a project was built for 64 bit Linux, a subsequent 32 bit Linux build will require rebuilding all of the dependencies for 32 bit.

How does this relate to Thanatos? Initially, Thanatos would not do any special dependency caching. This meant that each time a new payload was built, the dependencies for the payload were compiled each time. Build times would average around 30 seconds to a minute each build depending on system resources. To solve this issue, the payload builder will cache dependencies after the first build for the target platform. An initial build of a Linux 64 bit payload will compile all of the dependencies for 64 bit Linux and then cache them for future builds. This allows for the build times of subsequent builds to be significantly reduced. This design was used to help reduce the size of the docker image. The docker image could already include pre-built dependencies but that would mean there would need to be Windows/Linux 64 and 32 bit targets along with statically linked Linux builds. If an operation does not require Linux agents, then the libraries would take up a lot of unnecessary hard drive space.

The second issue was cross-compilation. Rust by itself has incredible cross-compilation capabilities; however, those can be affected when introducing dependencies which require C development libraries. The ssh2 library that Thanatos uses for SSH requires openssl. When compiling for Windows targets, an openssl library compatible with mingw is needed. There also needs to include both 32 bit and 64 bit builds. One of my options to fix this was by cross-compiling openssl for each platform I needed and then including that inside the docker container. It wasn’t an ideal fix for the issue but it would make the agent compile. I found out that the Fedora docker base image included all of the dependencies I needed inside the repositories so I ended up using Fedora for the docker base image.

One of the other influencers for using Fedora for the docker base image was due to Windows 32 bit builds. I was having a fair bit of difficulty getting Windows 32 bit Rust binaries built in Ubuntu docker containers which I tracked down to being an issue with the mingw32 compiler included in the Ubuntu repository. The mingw32 compiler in the Ubuntu repositories comes with an option compiled in which uses a linker not compatible with Rust’s libunwind. This was a major hindrance which meant that Thanatos could not target Windows 32 bit platforms. Building 32 bit Windows binaries would allow for injecting the payload into 32 bit processes so it would be a nice feature to include. Luckily, the mingw32 compiler in Fedora did not enable this feature and allowed building 32 bit Windows payloads.

Rust Programming Language

Offensive Capabilities

Digging more into Rust, I was blown away by the offensive capabilities it can provide. Rust can be thought of, at a high level, as a language which bridges the gap between low-level systems development through direct memory manipulation and high-level development such as manipulating JSON. Rust has the ability to work with raw pointers and manipulate memory very similar to C/C++. There may be times where a DLL needs to be loaded reflectively in either the current process or another process. Rust can parse the DLL headers and resolve all the symbols in the same way that C/C++ can. Reflectively loading a DLL means that the DLL does not touch the hard disk of the target system which can trigger AV or EDR depending on what the DLL is. Rust even supports inline assembly. This allows offensive tool developers very fine control over what executes in their program. Golang can use pointers but they don’t provide the same level of control as Rust. Golang gets around this by writing the low-level memory code in C and then using the Golang C ffi to invoke those C functions. Rust does not need to rely on C for any low-level memory management.

As mentioned, Rust is used for bridging the gap between low-level systems development and high-level development. Working with JSON Rust using the serde_json library is very similar to working with JSON in Golang. There are many different HTTP libraries available with many including async support. Using an HTTP library such as reqwest makes sending HTTP requests and returning the output as simple as

[dependencies]
reqwest = { version = "0.11", features = ["blocking"] }

fn main() {
    let data = reqwest::blocking::get("http://example.com")
        .unwrap()
        .text()
        .unwrap();

    println!("{}", data);
}

No need to initialize an HTTP handle or manually allocate memory.

Libraries not only make the development process easier but the language provides various functional features which can help reduce the amount of code needed to do various tasks. The standard library is very extensive and almost always includes some way of doing a very specific task in an elegant manner.

A few great resources on Rust being used for offensive tooling worth checking out are Black Hat Rust and Offensive Rust.

Transitioning From C/C++ to Rust

There have been many situations I have found where I can ditch C/C++ for a project and use Rust instead. Rust can do anything I need which C/C++ can do while also bringing memory safety. C and C++ have a history of being the root cause for many different memory corruption vulnerabilities that exist even today. This is partly due to the developers writing software which contains bugs and partly due to the fact that C/C++ do not prevent people from writing software which could introduce a memory corruption vulnerability.

This is why Rust is a great language for C/C++ developers who want to write secure code while keeping the same performance and low-level properties of C/C++. There are a few things that tripped me up when transitioning from C/++ to Rust.

The Rust compiler features a borrow checker which can be a little frustrating to get used to at first. The idea behind the borrow checker is to prevent pointer aliasing and shared mutability. Here are two examples to demonstrate ownership and borrowing.

fn main() {
    let a = "Hello World".to_string();
    let b = a; // 'a' variable is moved to 'b'

    println!("{}", a); // since 'a' was moved to 'b', 'a' is no longer valid
}

This example will not compile. The a variable contains a heap allocated string "Hello World". The b variable is now being assigned to the a variable and the a variable is being printed out. C/C++ will treat a and b as pointers to the same heap allocated string "Hello World". This results in a and b pointing to the same area of memory which can result in unsafe behavior. Other languages such as Golang or Python will make a copy of the string whenever it gets assigned to the b variable. Since heap allocations can be relatively expensive computationally, Rust won’t implicitly allocate memory and store a new copy of the string but instead throw a compile error.

fn main() {
    let a = "Hello World".to_string();
    let b = &a; // 'b' is now a reference to 'a'

    println!("{}", a); // Since 'b' is a reference to 'a', 'a' is still valid
}

This example does compile because the ownership of the heap allocation containing the string "Hello World" isn’t being passed to the b variable but instead, b is now borrowing the string from a. This may seem like a basic concept; however, it can become very tedious when applying it.

Lifetimes exist in C/C++ but they are more verbose in Rust. Lifetimes are the idea that when a variable refers to another piece of data, that data will exist in the program as long as any references to that variable. Lifetimes in Rust can get a little bit ugly but knowing how and when to use them can help make them easier to read.

fn main() {
    let a: String = "Hello World".to_string(); // "Hello World" is a heap allocated string
    let b: &str = a.as_str(); // refers to the heap allocated string directly

    println!("{}", b);
}

I included types for the variables to make the program logic a little easier to understand. The b variable refers to the "Hello World" string by reference. This is valid but what happens if the "Hello World" string gets deallocated?

fn main() {
    let a: String = "Hello World".to_string(); // "Hello World" is a heap allocated string
    let b: &str = a.as_str(); // refers to the heap allocated string directly

    drop(a); // Deallocate the "Hello World" string

    println!("{}", b);
}

This obviously won’t work because b is now a reference to memory which was deallocated. Lifetime issues become clearer when working with structures.

struct MyStruct {
    field1: &str
}

fn main() {
    let b = "Hello World";

    let a = MyStruct {
        field1: "Hello World",
    };

    println!("{}", a.field1);
}

This example won’t compile because it is not guaranteed that every time MyStruct is created the string field1 refers to will be valid. &str can be thought of as a string literal and not a heap allocated string. This is where a lifetime parameter is needed.

struct MyStruct<'a> {
    field1: &'a str
}

fn main() {
    let b = "Hello World";

    let a = MyStruct {
        field1: b,
    };

    println!("{}", a.field1);
}

This does compile because the 'a lifetime sends a hint to the compiler that any value which field1 refers to has to live as long as the structure itself.

Future Improvements

Development Plans

The agent is far from finished and development will continue to happen. This initial release should be thought of as a beta test for the agent to see what areas could be improved and to fix any potential bugs. The agent hasn’t been thoroughly tested so there are most-likely issues that will arise. New feature development is going to focus on areas which have a potential of affecting the overall structure of the agent. The reasoning behind this is due to the potential of having to rewrite the agent, or most of it, to include a certain feature. Rewriting the agent would not be a huge setback now; however, if miscellaneous features are added before the structure isn’t solidified, a rewrite would take a lot more time.

The three most important features which could potentially require restructuring the code base of the agent are: integration of multiple C2 profiles, socks proxying through the agent and p2p C2 profiles. Once the overall structure of the agent is completely figured out, it should make adding various commands a matter of implementing the code which accomplishes the task.