BOF Development Kit
Write, build, test, and load custom Beacon Object Files
Write custom BOFs that run on Krait’s agent using the same Beacon API as Cobalt Strike. The SDK lives at tools/bof-sdk/ in the Krait release package.
Quick Start
# 1. Copy template
cp tools/bof-sdk/bof_template.c my_bof.c
# 2. Edit — implement go() with Beacon API calls
# 3. Build
cd tools/bof-sdk && ./build_bof.sh ../my_bof.c
# 4. Test locally (Linux)
./test_harness my_bof.so
# 5. Load on target agent
bof load my_bof.x64.o --args zi hello 42
SDK Contents
| File | Purpose |
|---|---|
beacon.h | Beacon API declarations (CS-compatible) |
bofdefs.h | DFR macros + common Windows API imports |
bof_pack.h | Argument packing format documentation |
bof_template.c | Skeleton BOF with go() entry point |
build_bof.sh | Cross-platform build script |
Makefile | Make targets for Windows/Linux/macOS |
test_harness.c | Standalone BOF test runner |
Beacon API Reference
Output
| Function | Description |
|---|---|
BeaconPrintf(type, fmt, ...) | Formatted output (like printf) |
BeaconOutput(type, data, len) | Raw data output |
Output types: CALLBACK_OUTPUT (0x0), CALLBACK_OUTPUT_OEM (0x1e), CALLBACK_OUTPUT_UTF8 (0x20), CALLBACK_ERROR (0x0d).
Data Parsing (Input Arguments)
| Function | Description |
|---|---|
BeaconDataParse(parser, buffer, size) | Initialize parser on args buffer |
BeaconDataInt(parser) | Extract int32 |
BeaconDataShort(parser) | Extract int16 |
BeaconDataLength(parser) | Remaining bytes |
BeaconDataExtract(parser, &size) | Extract byte blob |
Format Buffer (Output Building)
| Function | Description |
|---|---|
BeaconFormatAlloc(format, maxsz) | Allocate format buffer |
BeaconFormatAppend(format, text, len) | Append raw bytes |
BeaconFormatPrintf(format, fmt, ...) | Append formatted string |
BeaconFormatInt(format, value) | Append int32 |
BeaconFormatToString(format, &size) | Get final buffer |
BeaconFormatFree(format) | Free buffer |
Token / Identity
| Function | Description |
|---|---|
BeaconUseToken(token) | Impersonate token |
BeaconRevertToken() | Revert to self |
BeaconIsAdmin() | Check admin rights |
Process Injection
| Function | Description |
|---|---|
BeaconGetSpawnTo(x86, buffer, length) | Get sacrificial process path |
BeaconSpawnTemporaryProcess(...) | Spawn sacrificial process |
BeaconInjectProcess(hProc, pid, ...) | Inject into existing process |
BeaconInjectTemporaryProcess(...) | Inject into spawned process |
BeaconCleanupProcess(pInfo) | Clean up process handles |
Utility
| Function | Description |
|---|---|
toWideChar(src, dst, max) | ANSI to wide char conversion |
BeaconPipeReaderStart/Wait/Cleanup | Read from pipe in background thread |
BeaconKeylogStart/Stop/Dump | Keylogger control |
Argument Packing Format
The bof load command packs arguments using the same format as Cobalt Strike’s bof_pack:
| Char | Type | Description |
|---|---|---|
z | string | UTF-8 null-terminated string |
Z | wstring | UTF-16LE null-terminated wide string |
i | int32 | 32-bit integer (little-endian) |
s | int16 | 16-bit integer (little-endian) |
b | binary | Raw byte blob with length prefix |
Example: bof load whoami.x64.o --args zi username 1 passes a string and an int.
In your BOF, parse with:
void go(char *args, int len) {
datap parser;
BeaconDataParse(&parser, args, len);
char *username = BeaconDataExtract(&parser, NULL);
int flag = BeaconDataInt(&parser);
}
Dynamic Function Resolution (DFR)
Windows BOFs must use the DLL$Function convention to call Windows APIs. This avoids import table entries that would break COFF loading.
#include "bofdefs.h"
void go(char *args, int len) {
// Use KERNEL32$GetComputerNameA instead of GetComputerNameA
char name[MAX_COMPUTERNAME_LENGTH + 1];
DWORD size = sizeof(name);
KERNEL32$GetComputerNameA(name, &size);
BeaconPrintf(CALLBACK_OUTPUT, "Host: %s\n", name);
// Memory allocation via intAlloc / intFree macros
char *buf = intAlloc(4096);
// ... use buf ...
intFree(buf);
}
Common DFR declarations are pre-defined in bofdefs.h: KERNEL32, ADVAPI32, NTDLL, NETAPI32, DBGHELP, MSVCRT.
For APIs not in bofdefs.h, declare them yourself:
DECLSPEC_IMPORT BOOL WINAPI WTSAPI32$WTSEnumerateSessionsA(HANDLE, DWORD, DWORD, PVOID, DWORD *);
Loading Custom BOFs
CLI
# No arguments
bof load /path/to/recon.x64.o
# With typed arguments
bof load /path/to/lateral.x64.o --args Zi target.domain.local 445
# Raw hex-encoded packed args
bof load /path/to/custom.x64.o --raw 0400000068656c6c6f00
# Custom display name
bof load /path/to/tool.x64.o --name my-recon-tool
Web UI
The Command Browser page includes a Custom BOF Upload widget. Select a target agent, drag-and-drop or browse for your .o/.so file, fill in the format string and arguments, and click Execute.
Build Flags
Windows (COFF)
x86_64-w64-mingw32-gcc -c -Os -masm=intel -fno-stack-protector \
-fno-ident -fpack-struct=8 -falign-functions=1 -ffunction-sections \
-falign-jumps=1 -falign-labels=1 -mno-stack-arg-probe -w -fPIC \
-DBOF -I. -o bof.x64.o bof.c
Linux (Shared Object)
gcc -shared -fPIC -Os -o bof.so bof.c
macOS (Object File)
clang -c -Os -fPIC -target arm64-apple-macos -o bof.macos.o bof.c
Cobalt Strike Compatibility
Krait’s Beacon API uses the same function signatures as Cobalt Strike. Most public CS BOFs compile and run unmodified:
Works out of the box:
- TrustedSec Situational Awareness BOFs
- bof-collection
- CS-Remote-OPs-BOF
- Most single-file BOFs using standard Beacon API
Krait-specific extensions:
BeaconPipeReaderStart/Wait/Cleanup— background pipe readingBeaconKeylogStart/Stop/Dump— keylogger controlBeaconSpawnTemporaryProcess— sacrificial process spawning
Known differences:
- Krait’s COFF loader supports x64 only (no x86 BOFs on Windows)
- Linux and macOS BOFs use shared objects (
.so), not COFF BeaconGetSpawnToreturns Krait’s configured spawn process (default:dllhost.exe)
Common Patterns
Error Handling
void go(char *args, int len) {
HANDLE h = KERNEL32$CreateFileW(path, ...);
if (h == INVALID_HANDLE_VALUE) {
BeaconPrintf(CALLBACK_ERROR, "CreateFile failed: %d",
KERNEL32$GetLastError());
return;
}
// ... work ...
KERNEL32$CloseHandle(h);
}
Privilege Check
void go(char *args, int len) {
if (!BeaconIsAdmin()) {
BeaconPrintf(CALLBACK_ERROR, "Requires admin");
return;
}
// ... privileged operations ...
}
Format Buffer for Tabular Output
void go(char *args, int len) {
formatp fmt;
BeaconFormatAlloc(&fmt, 8192);
BeaconFormatPrintf(&fmt, "%-20s %-10s %s\n", "Name", "PID", "User");
// ... append rows ...
int size;
char *out = BeaconFormatToString(&fmt, &size);
BeaconOutput(CALLBACK_OUTPUT, out, size);
BeaconFormatFree(&fmt);
}