← Documentation / Development

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

FilePurpose
beacon.hBeacon API declarations (CS-compatible)
bofdefs.hDFR macros + common Windows API imports
bof_pack.hArgument packing format documentation
bof_template.cSkeleton BOF with go() entry point
build_bof.shCross-platform build script
MakefileMake targets for Windows/Linux/macOS
test_harness.cStandalone BOF test runner

Beacon API Reference

Output

FunctionDescription
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)

FunctionDescription
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)

FunctionDescription
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

FunctionDescription
BeaconUseToken(token)Impersonate token
BeaconRevertToken()Revert to self
BeaconIsAdmin()Check admin rights

Process Injection

FunctionDescription
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

FunctionDescription
toWideChar(src, dst, max)ANSI to wide char conversion
BeaconPipeReaderStart/Wait/CleanupRead from pipe in background thread
BeaconKeylogStart/Stop/DumpKeylogger control

Argument Packing Format

The bof load command packs arguments using the same format as Cobalt Strike’s bof_pack:

CharTypeDescription
zstringUTF-8 null-terminated string
ZwstringUTF-16LE null-terminated wide string
iint3232-bit integer (little-endian)
sint1616-bit integer (little-endian)
bbinaryRaw 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 reading
  • BeaconKeylogStart/Stop/Dump — keylogger control
  • BeaconSpawnTemporaryProcess — 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
  • BeaconGetSpawnTo returns 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);
}