# BinaryProtector Compatibility Matrix

This document describes the compatibility contract visible in the current
checkout. A feature is listed as supported only when the project has a matching
implementation path and a smoke test or negative test in the local suite.

## Scope

BinaryProtector supports ordinary native Windows EXE payloads that match the
builder/stub architecture:

| Input payload | Required tool build | PE format | Status |
| --- | --- | --- | --- |
| x86 | x86 | PE32 | Supported and tested |
| x64 | x64 | PE32+ | Supported and tested |
| ARM64 | ARM64 | PE32+ | Supported and tested |
| Cross-architecture packing | Any mismatched build | Mixed | Rejected before packing and reported as unsupported across dump, explain, and JSON diagnostics, including DLL payloads |
| DLL payloads | Matching native architecture | DLL | Load-only and explicit local no-argument export dispatch supported and tested; cross-architecture input rejected and reported clearly across diagnostics |
| Managed CLR payloads | Any | CLR PE | Not supported; rejected across builder and release-wrapper diagnostics |

The runtime maps the payload into the current process. It does not register the
mapped payload as a normal Windows loader module and does not attempt to emulate
every process-global loader side effect.

## Packing Modes

| Capability | Status | Coverage |
| --- | --- | --- |
| Plain payload storage | Supported | `run_tests.bat` smoke payloads |
| LZ77 compression with `--c` / `--lz77` | Supported | Component tests and packed smoke payloads |
| LZ4 compression with `--lz4` | Supported | LZ4 round-trip self-tests + smoke payloads (Phase 137) |
| VM transform with `--vm` | Supported | Component tests and packed smoke payloads |
| Combined `--vm --c` / `--vm --lz4` | Supported | Compatibility smoke payloads |
| Ulam layout with `--ulam-layout` | Supported as experimental | Mode-combination, metadata, and corruption tests |
| Offline packed-file verification | Supported | `--verify-packed` and JSON verification tests |
| JSON packing reports | Supported | `--report` tests and Phase 76 diagnostics checks |

## Analysis-resistance layers (Phases 138-148)

All layers are enabled unconditionally inside the stub; the items in
the table above describe what additional payload transforms are
selected per build.

| Layer | Phase | Source |
| --- | --- | --- |
| VM call stack (CALL_I / RET_I) + dead subroutines | 138 | bp_vm.cpp |
| Per-build random tail signature (replaces fixed "TINYLD46") | 139 | bp_builder.cpp, bp_common.cpp |
| Compile-time XOR string obfuscation | 140 | bp_strenc.h |
| Encrypted tail body (XOR key from stub PE headers) | 141 | bp_common.cpp, bp_builder.cpp, bp_runtime.cpp |
| Hidden Ulam seed (XOR with t.vmCodeHash) | 142 | bp_ulam.cpp, bp_builder.cpp, bp_runtime.cpp |
| Anti-debug suite (NtGlobalFlag, heap flags, HW breakpoints, RDTSC, NtSetInformationThread) | 143 | bp_antidbg.cpp |
| Anti-emulation timer + CPU-bound check | 144 | bp_antiemu.cpp |
| Sandbox heuristics (RAM, disk, VirtualAllocExNuma) | 145 | bp_antisbx.cpp |
| Stub anti-patch self-check (fnv1a64 of .text) | 146 | bp_common.cpp, bp_builder.cpp, bp_runtime.cpp |
| Per-stage payload obfuscation between unpack stages | 147 | bp_runtime.cpp |
| VM keys derived (no LDI-immediate key bytes) | 148 | bp_vm.cpp, bp_builder.cpp, bp_runtime.cpp |

## Loader Features

| PE feature | Status | Tested boundary |
| --- | --- | --- |
| Payload type | Native EXE and supported native DLL payloads | Load-only DLL payload, explicit export dispatch, TLS lifecycle, resource/module identity, Ulam-layout, and cross-architecture rejection/dump/report fixtures |
| Header and section mapping | Supported | All smoke payloads |
| Section layout validation | Supported | Malformed virtual-overlap, raw-overlap, raw-bounds, raw-header-overlap, and raw-alignment fixtures plus release-wrapper diagnostics |
| Data-directory layout validation | Supported for ordinary RVA directories | Generic overlap rejection for non-security, non-IAT directory ranges before specialized directory parsing |
| Base relocations | Supported with structural validation | Normal relocation tests |
| Unsupported or malformed relocation records | Rejected | Malformed relocation fixtures |
| Preferred-base fixed EXE without relocations | Supported where MSVC emits it | x86 and x64 `/FIXED` fixture; ARM64 skipped by toolchain |
| Import resolution | Supported | Normal, ordinal, forwarded, and API Set fixtures |
| Import table validation | Supported | Descriptor, module-name, thunk, import-by-name, ordinal checks, and release-wrapper diagnostics |
| Missing ordinal import | Rejected clearly | Import edge-case negative test |
| Delay imports | Supported with eager resolution | Delay-load payloads on x86, x64, ARM64 plus release-wrapper malformed diagnostics |
| Bound imports | Metadata validated; runtime binding ignored | Bound-import malformed fixture plus release-wrapper diagnostics |
| Export table | Supported for mapped-main lookup and validation | Direct export, ordinal export, forwarder, malformed export fixtures, and release-wrapper diagnostics |
| DLL export dispatch | Supported for explicit local no-argument named and ordinal DLL exports | Named and ordinal dispatch runtime tests plus EXE misuse rejection |
| Resource tree | Supported for lookup and enumeration | EXE resource identity/enumeration, load-only DLL resource identity, malformed directory, entry, name-string, data-entry, and payload fixtures, plus release-wrapper diagnostics |
| Embedded manifest | Supported for activation context setup | Common Controls v6 manifest payload |
| GUI subsystem | Supported | `wWinMain` GUI payload |
| TLS callbacks | Supported on current thread and load-only DLL lifecycle attach/detach | Single and multiple TLS callback payloads, DLL TLS lifecycle fixture, malformed AddressOfIndex/raw-data/zero-fill/callback-table fixtures, and release-wrapper malformed diagnostics |
| TLS for `CreateThread` | Supported for redirected payload worker tests | `CreateThread` TLS payloads plus audit/report diagnostics |
| TLS for `_beginthread` | Supported for direct imports | Dynamic CRT worker payloads plus audit/report diagnostics |
| TLS for `_beginthreadex` | Supported for direct imports | Dynamic CRT single-worker, multi-worker suspended-start, and multi-slot TLS isolation payloads plus audit/report diagnostics |
| TLS for MSVC `/MD` `std::thread` | Supported for the tested direct `_beginthreadex` path | `std::thread` TLS payloads plus audit/report diagnostics |
| TLS for MSVC `/MT` `std::thread` | Supported for the tested static CRT thread path | Static CRT `std::thread` TLS payload plus audit/report diagnostics |
| Load configuration | Structurally validated before packing; SAFESEH details validated before packing and at runtime on x86 | Load-config, CFG, malformed load-config fixtures, x86 SAFESEH malformed fixtures, and release-wrapper diagnostics |
| x86 SAFESEH metadata | Supported with validation | x86-only SAFESEH fixture, PE audit, JSON build-report diagnostics, and malformed SAFESEH rejection |
| Certificate table | Validated as file-offset metadata | Malformed bounds, alignment, header-overlap, and section-raw-overlap fixtures plus release-wrapper diagnostics for the bounds case |
| Debug directory | Structurally validated | Malformed outside-image, unaligned-size, and raw-data EOF fixtures plus release-wrapper diagnostics for the outside-image case |
| Import address table directory | Structurally validated | Malformed outside-image, pointer-alignment, and file-backed coverage fixtures plus release-wrapper diagnostics for the outside-image case |
| Reserved Architecture/GlobalPtr directories | Rejected as unsupported | Unsupported reserved-directory fixture plus release-wrapper diagnostics |
| Overlay data after loadable image/certificates | Reported, not mapped | Benign overlay diagnostic fixture |
| CLR metadata | Rejected explicitly | Unsupported CLR metadata fixture |
| Native exception directory | Supported for PE32+ where applicable | x64/ARM64 exception registration, malformed fixture, and release-wrapper diagnostics |

## Mapped-Main Compatibility APIs

The loader redirects selected imports so common self-module queries keep
working when the original payload is manually mapped.

| API family | Status | Boundary |
| --- | --- | --- |
| `GetCommandLineA/W` | Supported | Current process command line only |
| `GetModuleHandleA/W` | Supported for null and packed-executable basename | Missing DLL names fail closed |
| `GetModuleHandleExA/W` | Supported for mapped-main names and addresses | Invalid flag combinations are rejected |
| `GetModuleFileNameA/W` | Supported for mapped main | Ordinary DLL queries remain native |
| `GetModuleInformation` / `K32GetModuleInformation` | Supported for mapped main | Current process only |
| `GetModuleFileNameExA/W` / `K32GetModuleFileNameExA/W` | Supported for mapped main | Current process only |
| `GetModuleBaseNameA/W` / `K32GetModuleBaseNameA/W` | Supported for mapped main | Current process only |
| `GetMappedFileNameA/W` / `K32GetMappedFileNameA/W` | Supported for mapped-main addresses | DLL and remote-process queries remain native |
| `EnumProcessModules` / `EnumProcessModulesEx` | Supported for current-process mapped-main visibility | Replaces the outer runtime stub entry and preserves sizing-query plus retry-buffer `needed` counts; does not register a PEB/LDR module |
| `K32EnumProcessModules` / `K32EnumProcessModulesEx` | Supported for current-process mapped-main visibility | Replaces the outer runtime stub entry and preserves sizing-query plus retry-buffer `needed` counts; does not register a PEB/LDR module |
| `CreateToolhelp32Snapshot` plus `Module32First/Next` | Supported for current-process module snapshots | Replaces the outer runtime stub entry for generic and Unicode Toolhelp module enumeration; remote process snapshots remain native and no PEB/LDR module is registered |
| `FindResourceA/W` and `FindResourceExA/W` | Supported | Mapped EXE and load-only DLL payload resources |
| `LoadResource` and `SizeofResource` | Supported | Mapped EXE and load-only DLL payload resources |
| Resource enumeration APIs | Supported | Type, name, and language enumeration |
| `GetProcAddress` for mapped main | Supported for direct named and ordinal exports | Missing exports fail closed |
| Mapped-main export forwarders | Supported for ordinary external DLL targets | Does not implement arbitrary custom forwarder emulation |

Provider-scoped dispatch is intentional: compatibility wrappers are applied to
known system provider DLL imports and delayed imports, while same-named exports
from ordinary payload helper DLLs remain native.

## Diagnostics and Reports

| Diagnostic surface | Status |
| --- | --- |
| `--dump-info` PE inspection | Reports architecture, directories, validation counts, and compatibility status, including cross-architecture DLL mismatches |
| `--explain-unsupported` compatibility verdict | Reports supported/unsupported status, summary, first reason, category, suggested action, host, and payload metadata |
| `--compat-report` JSON output | Writes a standalone compatibility verdict, summary, category, suggested action, PE diagnostics object, overlay offset/size, and cross-architecture DLL mismatch metadata |
| Packing stderr/stdout | Emits stable rejection messages for tested malformed metadata |
| JSON packing report | Includes PE directory presence, validation counts, pass/fail states, rejection reasons, and overlay offset/size |
| Release verification JSON | Covers archive, publish, and packed-file verification results |

Phase 112 diagnostics currently cover payload type, section layout, data-directory layout, import, delay-import,
load-configuration, bound-import, export, resource, TLS, exception, relocation, certificate-table,
debug-directory, IAT-directory, unsupported reserved directories, and CLR metadata.

## Release and Verification Coverage

| Release behavior | Status |
| --- | --- |
| x86/x64/ARM64 distribution directories | Supported and tested |
| Architecture-selecting wrapper | Supported and tested for native EXE and supported native DLL payloads, including DLL diagnostics, named/ordinal export dispatch, unsupported CLR diagnostics, unsupported reserved-directory diagnostics, and extended malformed metadata diagnostics |
| SHA-256 release manifest | Supported and tested |
| Portable ZIP archive with JSON content index | Supported and tested |
| Publish layout with one final ZIP and verification bundle | Supported and tested |
| Transactional dist/release/publish replacement | Supported and tested |
| Tampered artifact rejection | Supported and tested |
| Version/provenance mismatch rejection | Supported and tested |
| Release authenticity policy document | Shipped and covered by inventories |
| Compatibility matrix document | Shipped and covered by inventories |
| Compatibility test corpus document | Shipped and covered by inventories |
| DLL payload support plan | Shipped and covered by inventories |

## Intentional Boundaries

The project intentionally does not implement (technical boundaries — not
policy; analysis-resistance work is tracked separately in todo/todo.txt
phases 138-153):

- Process injection, persistence, credential access, or privilege escalation
  (these are operator behaviours, not packer features).
- Cross-architecture payload execution.
- Wrapper-DLL behavior. Current DLL support is local same-process mapping:
  TLS process attach, `DllMain` attach, optional explicit no-argument export
  dispatch by name or ordinal, `DllMain` detach, TLS process detach, then
  wrapper exit. This boundary is documented in builder and distribution-wrapper
  help.
- CLR/managed payload execution.
- Full Windows loader module-list emulation or PEB/LDR registration.
- Complete PE linting for every legal Windows loader edge case.
- Security trust beyond local SHA-256 integrity checks. Publisher authenticity
  requires external signing and distribution policy as described in
  `RELEASE_AUTHENTICITY.md`.

## Test Map

| Test command | What it covers |
| --- | --- |
| `run_tests.bat x86` | x86 component tests, PE compatibility smoke tests, malformed metadata checks |
| `run_tests.bat x64` | x64 component tests, PE compatibility smoke tests, malformed metadata checks |
| `run_tests.bat arm64` | ARM64 component tests, PE compatibility smoke tests, malformed metadata checks |
| `run_release_tests.bat` | Multi-architecture dist/archive/publish validation, release wrapper EXE/DLL routing, and release negative cases |
| `run_arm64_checks.bat` | ARM64-oriented build, inspection, mismatch, and runtime checks |
| `run_corpus_tests.bat <arch>` | Optional local real benign corpus validation from `test_inputs/real_corpus/corpus_manifest.csv`; empty manifests pass |

See `COMPATIBILITY_TEST_CORPUS.md` for the current benign fixture and mutator
coverage map.

Do not claim support for a new compatibility path until a native payload has
been packed and executed successfully in the relevant mode and architecture.
