Module 6: Beacon User Data (BUD)

The contract between loader and Beacon — pre-resolved syscalls, RTL functions, and full memory layout awareness delivered through a single structured data block.

1. What Is BUD?

BUD (Beacon User Data) is the mechanism by which a UDRL (User-Defined Reflective Loader) communicates loader-resolved data to the Beacon payload after loading it into memory. It is not a Cobalt Strike "feature" in the UI sense — it is a structured binary contract between the loader and Beacon's internal runtime.

The concept was introduced with the original UDRL feature in Cobalt Strike 4.4, but it was significantly expanded in CS 4.11 to support a much richer set of pre-resolved data. Crystal-Loaders targets the 4.11 BUD specification.

C#define DLL_BEACON_USER_DATA  0x0d   // fdwReason = 13

// The loader calls Beacon's DllMain with:
DllMain(hInstance, DLL_BEACON_USER_DATA, (LPVOID)&userData);

Once Beacon has the USER_DATA pointer, it uses the pre-resolved data for four critical capabilities:

2. The USER_DATA Structure

The top-level structure that ties everything together. Every field is a pointer to a sub-structure (or a fixed-size buffer), and Beacon validates the version field before touching anything else.

Ctypedef struct {
    unsigned int        version;          // CS version: 0x041100 = 4.11
    PSYSCALL_API        syscalls;         // Pre-resolved syscall entries (36 Nt*)
    char                custom[BEACON_USER_DATA_CUSTOM_SIZE]; // User-defined field
    PRTL_API            rtls;             // Pre-resolved RTL functions
    PALLOCATED_MEMORY   allocatedMemory;  // Memory region tracking
} USER_DATA;

3. SYSCALL_API — The Syscall Table

The SYSCALL_API structure is the largest component of BUD. It contains 36 entries, one for each Nt* function that Beacon may need to call during its lifecycle. Each entry is a SYSCALL_API_ENTRY with three fields:

Ctypedef struct {
    PVOID fnAddr;     // Address of the Nt* function in ntdll.dll
    PVOID jmpAddr;    // Address of a syscall;ret gadget in ntdll for indirect execution
    DWORD sysnum;     // The System Service Number (SSN) for this syscall
} SYSCALL_API_ENTRY;

The full SYSCALL_API structure contains 36 named entries. Crystal-Loaders resolves all of them during the loading process using LibGate:

Ctypedef struct {
    SYSCALL_API_ENTRY ntAllocateVirtualMemory;
    SYSCALL_API_ENTRY ntProtectVirtualMemory;
    SYSCALL_API_ENTRY ntFreeVirtualMemory;
    SYSCALL_API_ENTRY ntGetContextThread;
    SYSCALL_API_ENTRY ntSetContextThread;
    SYSCALL_API_ENTRY ntResumeThread;
    SYSCALL_API_ENTRY ntCreateThreadEx;
    SYSCALL_API_ENTRY ntOpenProcess;
    SYSCALL_API_ENTRY ntOpenThread;
    SYSCALL_API_ENTRY ntClose;
    SYSCALL_API_ENTRY ntCreateSection;
    SYSCALL_API_ENTRY ntMapViewOfSection;
    SYSCALL_API_ENTRY ntUnmapViewOfSection;
    SYSCALL_API_ENTRY ntQueryVirtualMemory;
    SYSCALL_API_ENTRY ntDuplicateObject;
    SYSCALL_API_ENTRY ntReadVirtualMemory;
    SYSCALL_API_ENTRY ntWriteVirtualMemory;
    SYSCALL_API_ENTRY ntReadFile;
    SYSCALL_API_ENTRY ntWriteFile;
    SYSCALL_API_ENTRY ntCreateFile;
    SYSCALL_API_ENTRY ntQueueApcThread;
    SYSCALL_API_ENTRY ntCreateProcess;
    SYSCALL_API_ENTRY ntOpenProcessToken;
    SYSCALL_API_ENTRY ntTestAlert;
    SYSCALL_API_ENTRY ntSuspendProcess;
    SYSCALL_API_ENTRY ntResumeProcess;
    SYSCALL_API_ENTRY ntQuerySystemInformation;
    SYSCALL_API_ENTRY ntQueryDirectoryFile;
    SYSCALL_API_ENTRY ntSetInformationProcess;
    SYSCALL_API_ENTRY ntSetInformationThread;
    SYSCALL_API_ENTRY ntQueryInformationProcess;
    SYSCALL_API_ENTRY ntQueryInformationThread;
    SYSCALL_API_ENTRY ntOpenSection;
    SYSCALL_API_ENTRY ntAdjustPrivilegesToken;
    SYSCALL_API_ENTRY ntDeviceIoControlFile;
    SYSCALL_API_ENTRY ntWaitForMultipleObjects;
} SYSCALL_API;

Complete Syscall Reference Table

All 36 Nt* functions in the SYSCALL_API, listed in source order:

4. RTL_API — Runtime Library Functions

Not everything Beacon needs is a syscall. Three runtime library values are resolved by the loader and passed separately in the RTL_API structure:

Ctypedef struct {
    PVOID rtlDosPathNameToNtPathNameUWithStatusAddr;
    PVOID rtlFreeHeapAddr;
    PVOID rtlGetProcessHeapAddr;
} RTL_API, *PRTL_API;

ResolveRtlFunctions Implementation

The loader resolves these three values during initialization, before the BUD handoff:

Cvoid ResolveRtlFunctions(PRTL_API rtls)
{
    // Find ntdll base address via PEB walking + hash comparison
    PVOID ntdll = findModuleByHash(NTDLL_HASH);

    // Resolve the RTL functions from ntdll's export table
    rtls->rtlDosPathNameToNtPathNameUWithStatusAddr = findFunctionByHash(
        ntdll, RTL_DOSPATHNAME_HASH);
    rtls->rtlFreeHeapAddr = findFunctionByHash(
        ntdll, RTL_FREEHEAP_HASH);
    rtls->rtlGetProcessHeapAddr = findFunctionByHash(
        ntdll, RTL_GETPROCESSHEAP_HASH);
}

5. ALLOCATED_MEMORY — Memory Region Tracking

This is the most complex component of BUD, and arguably the most important. The ALLOCATED_MEMORY structure gives Beacon a complete map of every memory region the loader allocated, with section-level granularity. This map is critical for sleep masking — without it, the sleep mask would have no way to know which regions to encrypt, what permissions to change, or how to restore them after waking up.

Ctypedef struct {
    ALLOCATED_MEMORY_REGION AllocatedMemoryRegions[6];  // Up to 6 tracked regions
} ALLOCATED_MEMORY;

Each region represents a single top-level memory allocation (e.g., the Beacon DLL image, the sleep mask code, a BOF buffer). Within each region, up to 8 sections describe the internal layout:

Ctypedef struct {
    ALLOCATED_MEMORY_PURPOSE                 Purpose;
    PVOID                                    AllocationBase;
    SIZE_T                                   RegionSize;
    DWORD                                    Type;          // MEM_COMMIT, MEM_RESERVE, etc.
    ALLOCATED_MEMORY_SECTION                 Sections[8];   // Up to 8 sections per region
    ALLOCATED_MEMORY_CLEANUP_INFORMATION     CleanupInformation;
} ALLOCATED_MEMORY_REGION;

Ctypedef struct {
    ALLOCATED_MEMORY_LABEL  Label;           // TEXT, RDATA, DATA, PDATA, RELOC, etc.
    PVOID                   BaseAddress;
    SIZE_T                  VirtualSize;
    DWORD                   CurrentProtect;
    DWORD                   PreviousProtect;
    BOOL                    MaskSection;     // TRUE = encrypt this section during sleep
} ALLOCATED_MEMORY_SECTION;

The CleanupInformation field in each region tells Beacon how to clean up the allocation on exit. It contains the allocation method, a cleanup flag, and method-specific additional information:

Ctypedef struct {
    BOOL                                             Cleanup;
    ALLOCATED_MEMORY_ALLOCATION_METHOD               AllocationMethod;
    ALLOCATED_MEMORY_ADDITIONAL_CLEANUP_INFORMATION   AdditionalCleanupInformation;
} ALLOCATED_MEMORY_CLEANUP_INFORMATION;

The AdditionalCleanupInformation is a union that carries method-specific data needed for correct deallocation:

Ctypedef union {
    HEAPALLOC_INFO    HeapAllocInfo;    // HeapHandle, DestroyHeap
    MODULESTOMP_INFO  ModuleStompInfo;  // ModuleHandle
} ALLOCATED_MEMORY_ADDITIONAL_CLEANUP_INFORMATION;

typedef struct {
    PVOID HeapHandle;   // Handle to the heap this region was allocated from
    BOOL  DestroyHeap;  // TRUE if the heap itself should be destroyed on cleanup
} HEAPALLOC_INFO;

typedef struct {
    PVOID ModuleHandle; // Handle to the stomped module
} MODULESTOMP_INFO;

6. Enums Explained

Three enum types provide semantic meaning to the raw integer values stored in the ALLOCATED_MEMORY structures. Understanding these is essential for interpreting the memory map correctly.

ALLOCATED_MEMORY_PURPOSE

Cenum ALLOCATED_MEMORY_PURPOSE {
    PURPOSE_EMPTY           = 0,   // Slot is unused
    PURPOSE_GENERIC_BUFFER  = 1,   // General-purpose buffer (loader scratch space)
    PURPOSE_BEACON_MEMORY   = 2,   // The Beacon DLL image
    PURPOSE_SLEEPMASK_MEMORY = 3,  // The sleep mask code
    PURPOSE_BOF_MEMORY      = 4    // A loaded BOF (Beacon Object File)
};

ALLOCATED_MEMORY_LABEL

Cenum ALLOCATED_MEMORY_LABEL {
    LABEL_EMPTY     = 0,   // Slot is unused / not assigned
    LABEL_BUFFER    = 1,   // Generic buffer (non-PE data)
    LABEL_PEHEADER  = 2,   // PE/COFF headers
    LABEL_TEXT      = 3,   // .text section (executable code)
    LABEL_RDATA     = 4,   // .rdata section (read-only data, vtables, strings)
    LABEL_DATA      = 5,   // .data section (writable initialized data)
    LABEL_PDATA     = 6,   // .pdata section (exception handler tables)
    LABEL_RELOC     = 7,   // .reloc section (base relocation fixups)

    LABEL_USER_DEFINED = 1000  // Starting value for user-defined labels
};

The label tells the sleep mask (and Beacon) what kind of data lives in each section. This matters because different sections need different permission transitions during sleep:

ALLOCATED_MEMORY_ALLOCATION_METHOD

Cenum ALLOCATED_MEMORY_ALLOCATION_METHOD {
    METHOD_UNKNOWN       = 0,   // Unknown or unset allocation method
    METHOD_VIRTUALALLOC  = 1,   // Allocated via VirtualAlloc / NtAllocateVirtualMemory
    METHOD_HEAPALLOC     = 2,   // Allocated via HeapAlloc / RtlAllocateHeap
    METHOD_MODULESTOMP   = 3,   // Overwrote an existing mapped module (module stomping)
    METHOD_NTMAPVIEW     = 4,   // Mapped via NtMapViewOfSection

    METHOD_USER_DEFINED  = 1000 // Starting value for user-defined methods
};

7. Why BUD Matters for Sleep Masking

Sleep masking is the technique where Beacon encrypts its own memory during sleep intervals to avoid detection by memory scanners. Without BUD, the sleep mask would need to hardcode memory addresses, discover regions through heuristic scanning, or use a simplified single-region approach. BUD gives the sleep mask a complete, loader-provided map of every region and every section within those regions.

The sleep mask also benefits from the pre-resolved SYSCALL_API in BUD. During the sleep cycle, it needs to call NtProtectVirtualMemory (to change permissions) and NtWaitForSingleObject (to sleep). If it had to resolve these itself, it would need its own PEB walking and export table parsing code — duplicating work the loader already did. With BUD, the sleep mask just reads the pre-resolved entries.

8. The FixSectionPermissions Function

This function is the bridge between the PE loading logic (LibTCG) and the BUD memory tracking system. After the loader copies Beacon's PE sections into memory, FixSectionPermissions sets the correct per-section memory protections and populates the ALLOCATED_MEMORY_REGION structure for BUD.

Cvoid FixSectionPermissions(PDLLDATA dlldata, PBYTE dst, PALLOCATED_MEMORY_REGION region)
{
    // Set the region-level metadata
    region->AllocationBase = dst;
    region->RegionSize     = SizeOfDLL(dlldata);
    region->Type           = MEM_COMMIT;

    // Iterate each PE section and apply granular protections
    PIMAGE_SECTION_HEADER sectionHdr = IMAGE_FIRST_SECTION(dlldata->NtHeaders);
    for (WORD i = 0; i < dlldata->NtHeaders->FileHeader.NumberOfSections; i++)
    {
        DWORD protect = PAGE_READONLY;  // Default: read-only

        // Determine the appropriate protection from section characteristics
        // NOTE: Simplified for clarity. The actual source has 7 cascading
        // conditions handling PAGE_WRITECOPY, PAGE_READONLY, PAGE_READWRITE,
        // PAGE_EXECUTE, PAGE_EXECUTE_WRITECOPY, PAGE_EXECUTE_READ, and
        // PAGE_EXECUTE_READWRITE based on the full set of characteristic flags.
        if (sectionHdr->Characteristics & IMAGE_SCN_MEM_EXECUTE)
            protect = PAGE_EXECUTE_READ;     // .text: RX
        else if (sectionHdr->Characteristics & IMAGE_SCN_MEM_WRITE)
            protect = PAGE_READWRITE;        // .data: RW

        // Apply the protection
        DWORD oldProtect;
        KERNEL32$VirtualProtect(
            dst + sectionHdr->VirtualAddress,  // Section base address
            sectionHdr->SizeOfRawData,         // Section size
            protect,                           // New protection
            &oldProtect                        // Previous protection (saved)
        );

        // Track the section metadata in the BUD region
        region->Sections[i].Label           = GetLabelFromSectionHeader(sectionHdr->Name);
        region->Sections[i].BaseAddress     = dst + sectionHdr->VirtualAddress;
        region->Sections[i].VirtualSize     = sectionHdr->SizeOfRawData;
        region->Sections[i].CurrentProtect  = protect;
        region->Sections[i].PreviousProtect = oldProtect;
        region->Sections[i].MaskSection     = TRUE;  // All Beacon sections are maskable

        sectionHdr++;
    }
}

The GetLabelFromSectionHeader helper function converts PE section names (like .text, .rdata) into the corresponding ALLOCATED_MEMORY_LABEL enum values. This abstraction allows the sleep mask to reason about section types without parsing PE section name strings.

9. Module Summary