pe-signgen

Cross-version binary signatures and RVA offsets for Windows PE functions

Overview

pe-signgen is a tool for reverse engineers and security researchers that automatically generates:

Binary signatures (byte patterns with wildcards) for unexported and exported functions
RVA and file offsets for locating functions directly in binaries
Cross-build signatures that work across many Windows versions
Multiple output formats optimized for different use cases
Support for x64, ARM64, and WoW64 architectures

The core idea is to provide a systematic, robust way to access unexported functions across Windows 10/11 builds. It leverages:

Winbindex for Windows build metadata
Microsoft's public symbol servers for PDBs
Local caching for reproducible, offline-friendly workflows

⚠️ Windows version support pe-signgen supports Windows 10 and Windows 11 only. This is a deliberate design choice: Winbindex does not provide complete data for older versions.

Use Cases

Unexported Windows internals Generate signatures for functions like LdrpInitializeTls, RtlpInsertInvertedFunctionTableEntry, etc.
Game hacking / anti-cheat research Generate stable signatures that survive game updates
Security research Locate security-critical routines across Windows builds
Automation Scriptable signature and offset generation for entire sets of internal APIs

Output Formats

pe-signgen provides three distinct output formats for different use cases:

1. JSON Format

Structured data for automation, scripting, and integration with other tools.

pe-signgen --signature ntdll!NtCreateFile -o ntcreatefile.json --output-format json

Output structure:

{
  "dll_name": "ntdll",
  "function_name": "NtCreateFile",
  "architecture": "x64",
  "generated": "2024-12-11T15:30:00.123456",
  "total_builds": 1247,
  "unique_signatures": 3,
  "signature_groups": [
    {
      "matched_symbol": "NtCreateFile",
      "signature": "4C 8B DC 49 89 5B 08 49 89 6B 10 49 89 73 18 ...",
      "length": 48,
      "build_count": 845,
      "versions": [
        { "major": 10240, "minor": 16384, "build": "10240.16384" },
        { "major": 10586, "minor": 0, "build": "10586.0" }
      ]
    }
  ]
}

Notes:

major and minor are derived from the build string by splitting at the first .. Example: "10240.16384" → major = 10240, minor = 16384.
build is the original build string key used internally.

2. Binary Format (WSIG/WOFF)

Compact, runtime-ready binary formats optimized for embedded systems and low-overhead scanning.

These match the on-disk layout implemented in write_wsig() and write_woff().

WSIG Format (Windows Signature)

Magic: WSO\0 (0x57 0x53 0x4F 0x00) Current Version: 1 Purpose: Store binary signatures with wildcard masks and associated Windows build versions

File Structure (conceptual)

┌─────────────────────────────────────┐
│         Header (36 bytes)           │
├─────────────────────────────────────┤
│      DLL Name (variable)            │
├─────────────────────────────────────┤
│    Function Name (variable)         │
├─────────────────────────────────────┤
│   Signature / Mask / Build blobs    │ ← Arbitrary order, see notes
├─────────────────────────────────────┤ ← Aligned to 4 bytes
│   Groups Table (24 × N bytes)       │
└─────────────────────────────────────┘

Important layout notes (matches write_wsig)

After the header, the DLL and function names are written as UTF‑8 bytes.
For each signature group, the pattern bytes and mask bytes are written, followed by the build array for that group.
These per-group regions are not grouped globally by type: patterns, masks, and build arrays may be interleaved.
The builder aligns to 4 bytes before each build array and before the groups table. This can introduce padding.
Consumers must always follow the offsets in the header and group entries; do not rely on the conceptual diagram for physical contiguity.

// Packed as: "<4sIIIIIIII" (little-endian)

typedef struct {
    char     magic[4];   // "WSO\0" (WSIG_MAGIC)
    uint32_t version;    // FORMAT_VERSION (currently 1)
    uint32_t arch;       // Architecture code (1=x64, 2=ARM64, 3=WoW64)
    uint32_t dll_off;    // Offset to DLL name string
    uint32_t dll_len;    // Length of DLL name in bytes
    uint32_t func_off;   // Offset to function name string
    uint32_t func_len;   // Length of function name in bytes
    uint32_t group_count;// Number of signature groups
    uint32_t groups_off; // Offset to groups table
} wsig_header_t; // 36 bytes

Group Entry (24 bytes)

Each signature group represents a unique pattern that applies to one or more Windows builds.

// Packed as: "<IIIIII" (little-endian)

typedef struct {
    uint32_t sig_off;    // Offset to signature pattern bytes
    uint32_t sig_len;    // Length of signature pattern (in bytes)
    uint32_t mask_off;   // Offset to wildcard mask bytes
    uint32_t mask_len;   // Length of wildcard mask (≈ ceil(sig_len/8))
    uint32_t builds_off; // Offset to build version array
    uint32_t build_cnt;  // Number of builds using this signature
} wsig_group_t; // 24 bytes

Build Version Entry (8 bytes)

Each build entry identifies a specific Windows version that uses this signature.

typedef struct {
    uint32_t major; // e.g. 19041
    uint32_t minor; // e.g. 1234
} wsig_build_t; // 8 bytes

major and minor come from splitting the build string ("A.B" → A, B). The original build string is not stored in the binary format; if you need it, keep it externally (it is present in the JSON output).

Wildcard Mask Format

The mask is a bitmask where each bit corresponds to a byte in the signature pattern:

Bit = 1: Byte must match exactly (fixed byte)
Bit = 0: Byte is wildcarded (ignore this byte during matching)

Example:

Signature: 4C 8B DC 49 89 ?? 08 49
Mask bits: 1  1  1  1  1  0  1  1  (MSB first within each byte)
Mask byte: 0xBF (binary: 10111111)

Mask bytes are stored and interpreted in little-endian bit order within each byte (exactly as used in the C helpers and parse_signature):

uint8_t bit = (mask_bytes[byte_index >> 3] >> (byte_index & 7)) & 1u;

String Storage

DLL and function names are stored as UTF‑8, without null terminators.
Use *_len to determine the length; do not read past that.
There are no alignment requirements for the strings themselves.
Additional data regions (build arrays and the groups table) are aligned to 4‑byte boundaries; treat any padding as opaque.

WOFF Format (Windows Offset)

Magic: WOF\0 (0x57 0x4F 0x46 0x00) Current Version: 1 Purpose: Store direct RVA and file offsets for functions across Windows builds

File Structure

┌─────────────────────────────────────┐
│         Header (36 bytes)           │
├─────────────────────────────────────┤
│      DLL Name (variable)            │
├─────────────────────────────────────┤
│    Function Name (variable)         │
├─────────────────────────────────────┤
│ Matched Symbol Names (variable)     │ ← One UTF‑8 string per entry
├─────────────────────────────────────┤ ← Aligned to 4 bytes
│   Entries Table (32 × N bytes)      │
└─────────────────────────────────────┘

Layout details (matches write_woff):

After the header placeholder, the DLL and function names are written as UTF‑8 bytes.
For each build, the matched symbol name is written as a UTF‑8 string (no terminator). These form a simple string pool.
The writer then aligns to 4 bytes and writes the fixed-size entries table.
Each entry contains offsets (matched_off, matched_len) pointing into this string pool.

// Packed as: "<4sIIIIIIII" (little-endian)

typedef struct {
    char     magic[4];   // "WOF\0" (WOFF_MAGIC)
    uint32_t version;    // FORMAT_VERSION (currently 1)
    uint32_t arch;       // Architecture code (1=x64, 2=ARM64, 3=WoW64)
    uint32_t dll_off;    // Offset to DLL name string
    uint32_t dll_len;    // Length of DLL name in bytes
    uint32_t func_off;   // Offset to function name string
    uint32_t func_len;   // Length of function name in bytes
    uint32_t entry_cnt;  // Number of offset entries
    uint32_t entries_off;// Offset to entries table
} woff_header_t; // 36 bytes

Offset Entry (32 bytes)

Each entry maps a Windows build to the function's location in that build.

// Packed as: "<IIQQII" (little-endian)

typedef struct {
    uint32_t major;       // Windows major version (e.g., 19041)
    uint32_t minor;       // Windows minor version (e.g., 1234)
    uint64_t rva;         // Relative Virtual Address in the DLL
    uint64_t file_offset; // Raw file offset in the DLL on disk
    uint32_t matched_off; // Offset to matched symbol name string
    uint32_t matched_len; // Length of matched symbol name
} woff_entry_t; // 32 bytes

Usage Notes

RVA is the memory offset when the DLL is loaded at its preferred base.
File offset is the raw position in the PE file on disk.
Matched symbol may differ from the requested function (e.g., forwarded exports). The string is stored once in the string pool; matched_off/matched_len reference it.
Entries are sorted by build version (major, then minor) for efficient lookup.

Architecture Codes

Both binary formats use the same architecture encoding (via ARCH_CODE_MAP):

Code	Architecture	Description
1	x64	64-bit AMD64/Intel64
2	ARM64	64-bit ARM (AArch64)
3	WoW64	32-bit x86 on 64-bit Windows

Unknown architecture strings default to 1 (x64) internally; the CLI restricts values to the supported set.

3. C Header Format

Ready-to-compile C headers with type-safe structures and data arrays.

pe-signgen can emit two kinds of C headers:

WSIG headers – for signature and mask data (from write_wsig_header).
WOFF headers – for direct RVA/file-offset tables (from write_woff_header).

The --output-format cheader option selects C headers; combining it with --offsets switches between WSIG and WOFF variants.

WSIG C Header

pe-signgen --signature ntdll!RtlpInitializeThreadActivationContextStack \
  -o rtlp_init_actx.h --output-format cheader

Generated header structure (simplified, matches write_wsig_header):

/* Auto-generated WSIG header for ntdll ! RtlpInitializeThreadActivationContextStack ! x64. */
#ifndef WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_H
#define WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_H

#include <stdint.h>
#include <stddef.h>

#define WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_DLL_NAME  "ntdll"
#define WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_FUNCTION_NAME "RtlpInitializeThreadActivationContextStack"
#define WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_ARCH "x64"

/* Per-version build identifier. */
typedef struct {
    uint32_t major;
    uint32_t minor;
} WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_version_t;

/* Signature group entry. */
typedef struct {
    const uint8_t *pattern;
    const uint8_t *mask;
    uint32_t length;
    uint32_t build_count;
    const WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_version_t *versions;
} WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group_t;

/* One pattern/mask/versions triple per group. */
static const uint8_t WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_pattern[] = { /* ... */ };
static const uint8_t WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_mask[]    = { /* ... */ };
static const WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_version_t
    WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_versions[] = {
        { 10240u, 16384u }, /* 10240.16384 */
        /* ... */
    };

static const WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group_t
    WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_GROUPS[] = {
        {
            WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_pattern,
            WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_mask,
            (uint32_t)(sizeof(WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_pattern) /
                       sizeof(WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_pattern[0])),
            (uint32_t)(sizeof(WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_versions) /
                       sizeof(WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_versions[0])),
            WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group0_versions
        }, /* group 0 (RtlpInitializeThreadActivationContextStack) */
        /* ... */
};

static const size_t WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_GROUP_COUNT =
    sizeof(WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_GROUPS) /
    sizeof(WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_GROUPS[0]);

#endif /* WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_H */

Integration example (corrected to match the generated types):

#include "rtlp_init_actx.h"

static inline int match_byte(uint8_t want, uint8_t got,
                             const uint8_t *mbits, uint32_t i) {
    uint8_t bit = (mbits[i >> 3] >> (i & 7)) & 1u;
    return bit ? (want == got) : 1;
}

static const uint8_t *
find_signature(const uint8_t *base, size_t size,
               const uint8_t *pattern,
               const uint8_t *mbits,
               uint32_t sig_len) {
    if (!base || !pattern || !mbits || sig_len == 0)
        return NULL;
    if (size < sig_len)
        return NULL;

    // Find first non-wildcard byte as anchor
    uint32_t anchor = sig_len;
    for (uint32_t i = 0; i < sig_len; ++i) {
        if ((mbits[i >> 3] >> (i & 7)) & 1u) {
            anchor = i;
            break;
        }
    }
    if (anchor == sig_len)
        return base; // all wildcards

    const uint8_t anchor_val = pattern[anchor];
    const size_t last_pos = size - (size_t)sig_len;

    for (size_t pos = 0; pos <= last_pos; ++pos) {
        if (base[pos + anchor] != anchor_val)
            continue;

        uint32_t i = 0;
        for (; i < sig_len; ++i) {
            if (!match_byte(pattern[i], base[pos + i], mbits, i))
                break;
        }
        if (i == sig_len)
            return base + pos;
    }
    return NULL;
}

static void
fetch_signature(uint32_t major, uint32_t minor,
                const WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group_t *groups,
                size_t group_len,
                const uint8_t **signature_dest,
                const uint8_t **mask_dest,
                uint32_t *signature_len_dest) {
    *signature_dest = NULL;
    *mask_dest = NULL;
    *signature_len_dest = 0;

    const WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group_t *closest = NULL;
    uint32_t best_distance = 0xFFFFFFFFu;

    for (size_t gi = 0; gi < group_len; ++gi) {
        const WSIG_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_group_t *g = &groups[gi];
        for (uint32_t vi = 0; vi < g->build_count; ++vi) {
            uint32_t m = g->versions[vi].major;
            uint32_t n = g->versions[vi].minor;

            uint32_t distance = (m > major ? m - major : major - m) * 10000u +
                                (n > minor ? n - minor : minor - n);

            if (distance < best_distance) {
                best_distance = distance;
                closest = g;
            }

            if (m == major && n == minor) {
                *signature_dest = g->pattern;
                *mask_dest = g->mask;
                *signature_len_dest = g->length;
                return;
            }
        }
    }

    if (closest) {
        *signature_dest = closest->pattern;
        *mask_dest = closest->mask;
        *signature_len_dest = closest->length;
    }
}

You can then wire this into your own loader-specific code (e.g. using GetModuleHandleA, walking PE sections, etc.). The header intentionally only provides data; helper functions are up to the consumer.

WOFF C Header

For offset-only use cases, write_woff_header emits a small header describing a sorted table of (major, minor, rva, file_offset) entries.

Layout (matches write_woff_header):

/* Auto-generated WOFF header for ntdll ! RtlpInitializeThreadActivationContextStack ! x64. */
#ifndef WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_H
#define WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_H

#include <stdint.h>
#include <stddef.h>

#define WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_DLL_NAME  "ntdll"
#define WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_FUNCTION_NAME "RtlpInitializeThreadActivationContextStack"
#define WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_ARCH "x64"

/* Per-build offset entry. */
typedef struct {
    uint32_t major;
    uint32_t minor;
    uint64_t rva;
    uint64_t file_offset;
} WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_entry_t;

static const WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_entry_t
    WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_ENTRIES[] = {
        { 10240u, 16384u, 0x5B195ULL, 0x5A595ULL }, /* 10240.16384 (RtlpInitializeThreadActivationContextStack) */
        /* ... (sorted by major, then minor) ... */
};

static const size_t WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_ENTRY_COUNT =
    sizeof(WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_ENTRIES) /
    sizeof(WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_ENTRIES[0]);

#endif /* WOFF_NTDLL_RTLPINITIALIZETHREADACTIVATIONCONTEXTSTACK_X64_H */

This is useful when you trust the offsets themselves and do not need pattern-matching.

Installation

Prerequisites

Python 3.8+
Git
Internet connection (first run)
~10GB disk space for full cache

Install from Pip

pip install pe-signgen

Install from Source

git clone https://github.com/forentfraps/pe-signgen.git
cd pe-signgen
pip install -r requirements.txt
pip install -e .

Quick Start

Generate a Signature

pe-signgen --signature ntdll!LdrLoadDll

Generate Offsets

pe-signgen --signature kernel32!CreateFileW --offsets

Save as JSON

pe-signgen --signature ntdll!NtCreateFile -o out.json --output-format json

Command-Line Options

Basic Syntax

pe-signgen --signature DLL!FUNCTION [OPTIONS]

Architecture

--arch x64   # default
--arch arm64
--arch wow64

Version Filtering

--os-version win10       # Only Windows 10
--os-version win11       # Only Windows 11
--min-version 10.0       # Minimum version
--max-version 11.0       # Maximum version

Signature Length Control

--min-length 32          # Minimum signature length
--max-length 64          # Maximum signature length

Output Options

-o, --output PATH        # Output file path
--output-format FORMAT   # json | binary | cheader
--offsets                # Generate offsets instead of signatures

Performance

--workers 16             # Parallel workers (default: CPU count)
--no-cache               # Disable caching
--no-git-update          # Skip Winbindex updates

Verbosity

--verbose                # Detailed output
--quiet                  # Minimal output
--no-progress            # Disable progress bars

Caching

Cache Layout

~/.cache/pe-signgen/
│
├── dlls/           # Downloaded DLLs
├── pdbs/           # Downloaded PDBs
├── signatures/     # Generated signatures
└── winbindex_data/ # Winbindex metadata

Cache Control

# Disable cache for fresh generation
pe-signgen --signature ntdll!NtCreateFile --no-cache

# Clear cache
rm -rf ~/.cache/pe-signgen

# Custom cache location
export PE_SIGNGEN_CACHE=/custom/path
pe-signgen --signature ntdll!NtCreateFile

Performance

Example performance (12-core CPU, 100 Mbps):

Operation	Time
First run (no cache)	5–10 min
Cached run	< 1 sec
Per-build analysis	0.1–0.5 sec
Full run (1000 builds, 8 workers)	2–4 min

Resource requirements:

Disk: ~10 GB for full DLL/PDB cache
Memory: ~500 MB peak usage
Network: Several GB on first run

Known Limitations

Windows version coverage: Only Windows 10 and 11 (Winbindex limitation)
Build availability: Not every Win10/11 build exists in Winbindex

Development

git clone https://github.com/forentfraps/pe-signgen.git
cd pe-signgen
pip install -e ".[dev]"

# Code formatting
black pe_signgen/

# Type checking
mypy pe_signgen/

License

MIT License – see LICENSE.

Credits

Winbindex – Windows build metadata by @m417z
pefile – PE parsing library
winpdb-rs – PDB parsing Python bindings

Inspired by the need for robust, automated signature generation for internal Windows APIs.

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

pe-signgen

Most Popular

pe-signgen

Overview

Use Cases

Output Formats

1. JSON Format

2. Binary Format (WSIG/WOFF)

WSIG Format (Windows Signature)

File Structure (conceptual)

Header Layout (36 bytes)

Group Entry (24 bytes)

Build Version Entry (8 bytes)

Wildcard Mask Format

String Storage

WOFF Format (Windows Offset)

File Structure

Header Layout (36 bytes)

Offset Entry (32 bytes)

Usage Notes

Architecture Codes

3. C Header Format

WSIG C Header

WOFF C Header

Installation

Prerequisites

Install from Pip

Install from Source

Quick Start

Generate a Signature

Generate Offsets

Save as JSON

Command-Line Options

Basic Syntax

Architecture

Version Filtering

Signature Length Control

Output Options

Performance

Verbosity

Caching

Cache Layout

Cache Control

Performance

Known Limitations

Development

License

Credits

Contributing

Support