v0.7.7 — CLR Header & .NET Metadata Foundations

[malx-labs]

v0.7.7 — CLR Header & .NET Metadata Foundations

Summary

v0.7.7 extends IOCX’s static PE engine with full CLR header parsing and foundational .NET metadata extraction.
This release introduces support for IMAGE_COR20_HEADER, validation of core metadata streams, and deterministic extraction of high‑value .NET attributes. It also adds adversarial fixtures covering malformed CLR headers, corrupted metadata streams, and deceptive hybrid binaries.

The goal is to give IOCX first‑class awareness of managed code, enabling correct handling of .NET binaries, improving structural heuristics, and ensuring deterministic behaviour across malformed or partially‑valid CLR metadata — while preserving IOCX’s static‑only design.

---

Scope

v0.7.7 focuses on:

• CLR header parsing
• .NET metadata stream validation
• extraction of core .NET metadata fields
• managed/unmanaged boundary heuristics
• adversarial CLR/metadata fixtures
• deterministic reason codes for malformed CLR structures

No IL parsing, decompilation, or dynamic analysis is introduced.

---

Goals

Extend IOCX’s static PE engine with:

• IMAGE_COR20_HEADER parsing
• metadata stream validation (#~, #Strings, #Blob, #GUID, #US)
• core .NET metadata extraction
• deterministic handling of malformed CLR headers
• conservative heuristics for managed/unmanaged boundaries

All behaviour must remain reproducible and JSON‑safe.

---

Feature Requirements

1. CLR Header Parsing (IMAGE_COR20_HEADER)

Support extraction and validation of:

• CLR header RVA + size
• MajorRuntimeVersion / MinorRuntimeVersion
• Metadata RVA + size
• Flags
• EntryPointToken / EntryPointRVA
• Strong‑name signature RVA + size
• Managed resources RVA + size

Expected behaviour:
Invalid CLR headers produce structured, non‑fatal errors; snapshot‑stable output.

---

2. Metadata Stream Validation

Validate presence, structure, and boundaries of:

• #~ (compressed metadata tables)
• #Strings
• #Blob
• #GUID
• #US (user strings)

Expected behaviour:
Invalid or truncated streams never crash the parser; metadata extraction remains deterministic.

---

3. Core .NET Metadata Extraction

Extract high‑value metadata fields:

• runtime version
• metadata stream sizes
• strong‑name signature size
• managed entrypoint token
• IL‑only flag
• 32BITREQUIRED flag

Expected behaviour:
Metadata is stable and JSON‑safe; invalid fields handled conservatively.

---

4. Managed/Unmanaged Boundary Heuristics

Add deterministic heuristics for:

• CLR header present but metadata streams missing
• metadata streams present but CLR header missing
• hybrid binaries with partial CLR structures
• impossible CLR header sizes

Expected behaviour:
Heuristics must not misfire; reason codes must be deterministic and snapshot‑verified.

---

5. Adversarial CLR Fixtures

Add adversarial samples covering:

• truncated CLR headers
• invalid metadata stream offsets
• corrupted stream headers
• zero‑length metadata tables
• malformed strong‑name signatures
• deceptive “fake .NET” binaries

Expected behaviour:
Parser remains stable; output remains JSON‑safe; no nondeterministic behaviour.

---

6. Reason‑Code Expansion for CLR/.NET Issues

Add new deterministic reason codes:

• malformed_clr_header
• invalid_metadata_rva
• truncated_metadata_stream
• invalid_entrypoint_token
• missing_required_stream
• impossible_clr_size

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

---

Output Requirements

All new metadata must produce:

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

Parser errors must be:

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

---

Integration Requirements

• add CLR fixtures under tests/contract/fixtures/layer2_clr/
• add malformed CLR/metadata fixtures under layer3_adversarial/
• add snapshot tests for all new metadata
• no new extractors
• no dynamic analysis
• no heavy dependencies

---

Non‑Goals (Strict)

v0.7.7 must not introduce:

• IL parsing
• IL disassembly
• decompilation
• JIT simulation
• dynamic execution
• unpacking or emulation
• behavioural tracing
• ML/AI models
• sandboxing
• network access

---

Testing Requirements

Tests must verify:

• correct parsing of CLR headers
• correct validation of metadata streams
• deterministic extraction of .NET metadata
• stable behaviour on malformed CLR structures
• no false positives on native binaries
• no crashes or nondeterministic output

---

Acceptance Criteria

• CLR header parsing implemented
• Metadata stream validation implemented
• Core .NET metadata extraction implemented
• Managed/unmanaged boundary heuristics implemented
• Adversarial CLR fixtures added
• Reason‑code expansion completed
• Deterministic snapshot tests added
• Parser remains stable and JSON‑safe
• No dynamic analysis introduced