TLS Callbacks

Thread Local Storage callbacks execute before the process entry point and on every thread create/destroy event — a stealth execution vector that many debuggers and sandboxes miss

What TLS Is For

Thread Local Storage (TLS) is a mechanism that gives each thread its own private instance of a variable. When you declare a global variable with the __declspec(thread) modifier in C/C++, each thread that reads or writes the variable gets its own copy — changes in one thread don't affect other threads.

The PE format supports TLS through the .tls section and the TLS data directory. The TLS directory serves two purposes:

1. Static TLS data: Template values for thread-local variables. When a new thread starts, the loader copies this template to create the thread's private storage.
2. TLS callbacks: Functions that the loader calls before the process entry point, and again when any thread is created or destroyed.

From a malware perspective, only the callbacks matter. Static TLS data is a standard C++ feature; TLS callbacks are the stealth execution mechanism.

TLS Directory Structure

The TLS directory is pointed to by Data Directory entry 9 (IMAGE_DIRECTORY_ENTRY_TLS). The structure differs slightly between 32-bit and 64-bit PE:

  TLS Callback Execution Timeline
  ──────────────────────────────────────────────────────────────────
  Process Created
       │
       ▼
  Loader maps image into memory
       │
       ▼
  Loader processes imports (resolves IAT)
       │
       ▼
  ┌─────────────────────────────────────────────────────────────┐
  │  TLS CALLBACKS EXECUTE HERE (before entry point!)          │
  │  For each address in TLS.AddressOfCallBacks[]:             │
  │    callback(DllBase, DLL_PROCESS_ATTACH, NULL)             │
  └─────────────────────────────────────────────────────────────┘
       │
       ▼
  Entry point (AddressOfEntryPoint) executes — "main()"
       │
       ▼
  Thread created by process:
  ┌─────────────────────────────────────────────────────────────┐
  │  TLS CALLBACKS EXECUTE AGAIN for DLL_THREAD_ATTACH         │
  └─────────────────────────────────────────────────────────────┘
       │
       ▼
  Thread exits:
  ┌─────────────────────────────────────────────────────────────┐
  │  TLS CALLBACKS EXECUTE AGAIN for DLL_THREAD_DETACH         │
  └─────────────────────────────────────────────────────────────┘
       │
       ▼
  Process exits: DLL_PROCESS_DETACH callbacks

  

Callback Invocation

TLS callback functions have the same signature as DllMain:

void NTAPI TlsCallback(
    PVOID DllHandle,   // base address of the module being loaded
    DWORD Reason,      // DLL_PROCESS_ATTACH=1, DLL_THREAD_ATTACH=2
                       // DLL_THREAD_DETACH=3, DLL_PROCESS_DETACH=0
    PVOID Reserved
);
// AddressOfCallBacks points to: { &TlsCallback1, &TlsCallback2, ..., NULL }
// Null pointer terminates the array

The loader iterates the callback array and calls each with DLL_PROCESS_ATTACH before the entry point. For an EXE, this happens in the context of the initial thread. For a DLL loaded with LoadLibrary, TLS callbacks also fire — but only if the DLL has a TLS directory.

Writing a TLS Callback

// MSVC: declare a TLS callback that runs before main()
// The #pragma data_seg trick puts the callback pointer in the right section

#include <windows.h>
#pragma comment(linker, "/INCLUDE:_tls_used")  // x86
// For x64: #pragma comment(linker, "/INCLUDE:_tls_used")

void NTAPI my_tls_callback(PVOID, DWORD reason, PVOID) {
    if (reason == DLL_PROCESS_ATTACH) {
        MessageBoxA(NULL, "TLS callback fires before main!", "TLS", MB_OK);
    }
}

// Register the callback in the .CRT$XLx section
#pragma data_seg(".CRT$XLB")
PIMAGE_TLS_CALLBACK _tls_cb[] = { my_tls_callback, NULL };
#pragma data_seg()

int main() {
    MessageBoxA(NULL, "Entry point", "main", MB_OK);
    return 0;
    // "TLS callback fires before main!" appears first
}

Anti-Debug via TLS

TLS callbacks run before most debuggers attach their breakpoints. The most common pattern is an anti-debug check in the TLS callback:

void NTAPI AntiDebugTLS(PVOID, DWORD reason, PVOID) {
    if (reason != DLL_PROCESS_ATTACH) return;

    // Check 1: IsDebuggerPresent (PEB.BeingDebugged flag)
    if (IsDebuggerPresent()) {
        TerminateProcess(GetCurrentProcess(), 0);
    }

    // Check 2: NtGlobalFlag in PEB (set to 0x70 when debugged)
    DWORD flags = *(DWORD*)((BYTE*)__readgsqword(0x60) + 0xBC); // PEB+0xBC
    if (flags & 0x70) {
        TerminateProcess(GetCurrentProcess(), 0);
    }

    // Check 3: Timing check — debugger slows execution
    DWORD start = GetTickCount();
    volatile DWORD x = 0;
    for (volatile int i = 0; i < 1000000; i++) x += i;
    if (GetTickCount() - start > 500) {
        TerminateProcess(GetCurrentProcess(), 0);
    }
}

Malware Execution via TLS

Beyond anti-debug checks, malware uses TLS callbacks as the primary execution point, setting AddressOfEntryPoint = 0 to confuse analysis. An analyst looking at "the entry point" sees nothing — the real code is in the TLS callback array. Techniques:

Detecting TLS Abuse

import pefile

def audit_tls(filepath):
    pe = pefile.PE(filepath)
    if not hasattr(pe, 'DIRECTORY_ENTRY_TLS'):
        print("No TLS directory")
        pe.close(); return

    tls = pe.DIRECTORY_ENTRY_TLS.struct
    callbacks_va = tls.AddressOfCallBacks
    print(f"TLS directory found")
    print(f"  AddressOfCallBacks VA: {hex(callbacks_va)}")

    ep = pe.OPTIONAL_HEADER.AddressOfEntryPoint
    image_base = pe.OPTIONAL_HEADER.ImageBase
    if ep == 0:
        print("  WARNING: AddressOfEntryPoint = 0 — TLS may be sole execution point")

    # Walk the callback array
    if callbacks_va:
        ptr_size = 8 if pe.PE_TYPE == pefile.OPTIONAL_HEADER_MAGIC_PE_PLUS else 4
        offset = callbacks_va - image_base
        idx = 0
        while True:
            cb_data = pe.get_data(offset + idx * ptr_size, ptr_size)
            cb_va = int.from_bytes(cb_data, "little")
            if cb_va == 0: break
            cb_rva = cb_va - image_base
            print(f"  TLS Callback[{idx}]: VA={hex(cb_va)}  RVA={hex(cb_rva)}")
            # Cross-check: which section does this callback live in?
            for section in pe.sections:
                sec_start = section.VirtualAddress
                sec_end = sec_start + section.VirtualSize
                if sec_start <= cb_rva < sec_end:
                    name = section.Name.decode("utf-8", errors="replace").strip("\x00")
                    print(f"    Lives in section: {name}")
            idx += 1
        print(f"  Total TLS callbacks: {idx}")
    pe.close()

Q & A