youssefnoob003-SindriKit/docs/tests/pe_mutator.md

PE Mutation Engine (tests/loader/pe_mutator.py)

Location: tests/loader/pe_mutator.py

Applies targeted structural modifications to valid PE files to stress-test the reflective loader parser and pipeline. Output filenames use each mutation's name field: {basename}_{name}.dll.

Mutation categories

Benign edge-cases

Structurally valid but unusual — the loader should succeed.

name	Description	What it tests
unaligned_sec	SectionAlignment / FileAlignment → 0x200	Hardcoded 0x1000 alignment assumptions
stripped_relocs	Strips .reloc, sets IMAGE_FILE_RELOCS_STRIPPED (EXE only)	Loaders that require relocations for EXEs
garbage_dos_stub	Overwrites DOS stub bytes with garbage	Linear DOS-stub reads vs e_lfanew seek
append_overlay	4 KB junk after last section	Mapping beyond declared sections
null_sec_names	Zeroes section name strings	Unsafe section name handling

Breaking stressors

Structurally corrupt — parser must reject gracefully, never crash.

name	Description	What it tests
oob_reloc_size	First reloc block SizeOfBlock = 0xFFFFFFFF	Unbounded relocation loops
massive_headers	SizeOfHeaders = 0xFFFFFFFF	Unchecked header-sized copies
truncated_sec	Section SizeOfRawData beyond file end	Section mapping bounds
int_overflow	VirtualSize / SizeOfRawData = 0xFFFFFFFF	Allocation overflow arithmetic
overlap_sections	All section file offsets collapsed to zero	File alignment normalization
corrupt_pe_sig	NT signature replaced with 0xDEADBEEF	PE signature validation
bad_e_lfanew	e_lfanew points past EOF	NT header offset bounds
zero_imgsize	SizeOfImage = 0	Allocation size validation
bad_import	Import directory RVA → unmapped region	Import RVA bounds
bad_export	Export directory RVA → unmapped region (DLL only)	Export RVA bounds
huge_sections	NumberOfSections = 0xFFFF	Section table overflow
unterminated_imports	Import descriptor terminator overwritten	Import loop termination
massive_exports	NumberOfFunctions / NumberOfNames = 0xFFFFFFFF (DLL only)	Export iteration bounds
oob_entry_point	Entry RVA past SizeOfImage	Entry point validation

API

Mutation dataclass

Field	Type	Description
name	str	Short identifier (used in output filenames)
description	str	Human-readable label
apply	Callable	(src, dst) -> None mutation function
expect_loadable	bool	True = loader must succeed; False = must reject
applies_to	str	"both", "exe", or "dll"

mutate_pe(src_path, mutation, output_dir) -> str

Applies the mutation and writes {name}_{mutation.name}{ext} under output_dir. Raises MutationError on failure.

Dependency

Requires pefile for structured edits:

pip install pefile

Raw byte mutations (garbage_dos_stub, corrupt_pe_sig, bad_e_lfanew, huge_sections) operate on the byte buffer directly.

Related documentation

• Test runner — --mutate flag
• Test payloads