v0.7.6 — Remaining PE Directories & Structural Completion

[malx-labs]

v0.7.6 — Remaining PE Directories & Structural Completion

Summary

v0.7.6 completes IOCX’s static PE directory coverage by implementing the remaining structural directories: Relocations, Certificate Table, Debug Directory, Delay‑Load Imports, and TLS Directory.
This release focuses on structural correctness, directory‑level invariants, and deterministic parsing across malformed, truncated, or contradictory metadata.

The goal is to bring IOCX’s static PE engine to full directory completeness, enabling richer metadata, stronger invariants, and improved correctness — while preserving IOCX’s static‑only, deterministic design.

---

Scope

v0.7.6 includes:

• relocation table parsing
• certificate table parsing
• debug directory parsing
• delay‑load import parsing (deferred from v0.7.4)
• TLS directory parsing (deferred from v0.7.4)
• extended directory‑invariant validation
• structured metadata for all new directories
• deterministic reason‑code expansion

No dynamic analysis, unpacking, or behavioural logic is introduced.

---

Goals

Extend IOCX’s static PE engine with:

• Relocation block parsing
• Certificate table extraction
• Debug directory extraction
• Delay‑load import parsing
• TLS directory parsing
• structured metadata for relocations, signatures, debug info, TLS callbacks, and delay‑load imports
• deterministic reason codes for malformed directories

All behaviour must remain reproducible, conservative, and JSON‑safe.

---

Feature Requirements

1. Relocation Table Parsing

Implement support for IMAGE_BASE_RELOCATION:

• parse relocation blocks
• validate block sizes
• validate relocation entry RVAs
• detect truncated or malformed blocks
• extract relocation types (e.g., HIGHLOW, DIR64)

Expected behaviour:
Malformed blocks produce structured, non‑fatal errors; snapshot‑stable output.

---

2. Certificate Table Parsing

Implement support for WIN_CERTIFICATE:

• parse certificate table
• validate certificate size
• validate certificate offset (must lie outside the image)
• extract certificate metadata (revision, type, length)
• detect truncated or malformed certificate blobs

Expected behaviour:
Malformed certificates never crash parsing; metadata remains JSON‑safe.

---

3. Debug Directory Parsing

Implement support for IMAGE_DEBUG_DIRECTORY:

• parse debug directory entries
• validate entry RVAs
• extract PDB path (CodeView)
• extract debug type (CodeView, Misc, etc.)
• detect truncated or malformed entries

Expected behaviour:
Malformed entries produce structured errors; PDB extraction is deterministic.

---

4. Delay‑Load Import Parsing (Deferred from v0.7.4)

Implement support for IMAGE_DELAY_IMPORT_DESCRIPTOR:

• parse delay‑load descriptors
• validate INT/IAT RVAs
• validate DLL name RVA
• extract delayed import names
• detect malformed or truncated descriptors

Expected behaviour:
Parser remains stable; malformed descriptors produce deterministic reason codes.

---

5. TLS Directory Parsing (Deferred from v0.7.4)

Implement support for IMAGE_TLS_DIRECTORY:

• parse TLS callbacks
• validate callback array RVAs
• validate raw data start/end
• handle zero‑length TLS regions
• detect malformed or looping callback arrays

Expected behaviour:
Invalid TLS structures produce structured, non‑fatal errors; no false positives.

---

6. Extended Directory‑Invariant Validation

Add deterministic checks for:

• relocation directory RVAs mapping to valid sections
• certificate table offset not overlapping the image
• debug directory entries mapping to valid regions
• delay‑load import RVAs mapping to valid sections
• TLS callback arrays mapping to valid sections
• directory sizes not exceeding section boundaries

Expected behaviour:
Invalid directories produce structured, non‑fatal errors; heuristics remain conservative.

---

7. Metadata Enrichment for New Directories

Expose structured metadata:

• relocation block counts
• relocation entry counts
• certificate metadata (revision, type, length)
• debug directory metadata (type, timestamp, characteristics)
• delay‑load import metadata (DLL name, INT/IAT sizes)
• TLS metadata (callback count, raw data range)

Expected behaviour:
Metadata is stable, JSON‑safe, and conservatively extracted.

---

8. Reason‑Code Expansion

Add new deterministic reason codes for:

• malformed relocation blocks
• invalid relocation entry RVAs
• malformed certificate table
• certificate offset inside image
• malformed debug directory entries
• invalid debug entry RVAs
• malformed delay‑load descriptors
• invalid TLS callback RVAs
• truncated TLS directory

Expected behaviour:
Codes are lowercase, snake_case, non‑overlapping, and snapshot‑stable.

---

Output Requirements

All new directory data must produce:

• deterministic JSON output
• structured Detection objects where applicable
• stable snapshot results

Parser errors must be:

• structured
• non‑fatal
• deterministic
• JSON‑safe

---

Integration Requirements

• add relocation, certificate, debug, TLS, and delay‑load fixtures under layer2_directories/
• add malformed directory samples under layer3_adversarial/
• add snapshot tests for all new metadata
• no new extractors
• no dynamic analysis
• no heavy dependencies

---

Non‑Goals (Strict)

v0.7.6 must not introduce:

• dynamic execution
• unpacking or emulation
• behavioural tracing
• ML/AI models
• sandboxing
• network access
• disassembly or CFG reconstruction
• .NET metadata parsing (reserved for v0.8.x)

---

Testing Requirements

Tests must verify:

• correct parsing of relocations
• correct parsing of certificate tables
• correct parsing of debug directories
• correct parsing of delay‑load imports
• correct parsing of TLS directories
• deterministic behaviour on malformed directories
• stable metadata extraction
• no false positives on normal system binaries
• no crashes or nondeterministic output

---

Acceptance Criteria

• Relocation table parsing implemented
• Certificate table parsing implemented
• Debug directory parsing implemented
• Delay‑load import parsing implemented
• TLS directory parsing implemented
• Directory invariant validation extended
• Metadata enrichment implemented
• Reason‑code expansion completed
• Deterministic snapshot tests added
• Parser remains stable and JSON‑safe
• No dynamic analysis introduced