feat: upgrade to v0.5 - introduce x64 architecture support, type annotations, and robust NOP generation

[anonymouschichvy]

Description

Overview

This pull request upgrades the metamorphic engine to version 0.5. The codebase has been extensively refactored to support both 32-bit (x86) and 64-bit (x64) executables with type-safe handlers, modernized packaging, safer inputs/parsing, and significantly improved NOP generation mechanics. In addition, the documentation has been updated with detailed instructions and a detection comparison catalog.

---

🛠️ Key Changes

1. Handler Redesign & Static Typing

• New 64-Bit & 32-Bit Instruction Handler: Replaced the legacy x86handler.py with x64handler.py.
• Type Annotations: Added comprehensive type annotations (typing.Dict, List, Tuple, etc.) to the X64Handler class.
• Modernized Syntax: Converted legacy % string formatting to modern Python f-strings.
• Opcode Normalization: Added normalize_opcode to parse and standardize whitespaces, commas, and casing variations in disassembler outputs.

2. Advanced & Safe NOP Generation

• Address-Aware Relocation: Changed X64Handler.get_nops signature from (self, size, prev_ins_size=0) to (self, size: int, addr: int = 0) to support absolute instruction addresses, ensuring jumps are resolved correctly at patch time.
• Multi-Byte Long NOPs: Implemented multi-byte NOP instructions (e.g., nop dword ptr [rax] for 64-bit, nop dword ptr [eax] for 32-bit) which perform no operation and guarantee EFLAGS/RFLAGS stability.
• Instruction Substitution Variety: Added new size-constrained templates like xchg ax, ax, xor reg, 0; nop, and add reg, 0 to increase metamorphic entropy without affecting register states.

3. Radare2 Parser & CLI Enhancements

• Safe Metadata Queries: Refactored r2parser.py to parse binary JSON metadata safely using .get() rather than unsafe direct lookups, raising descriptive exceptions if architecture or bit details are missing.
• Error Logging: Wrapped function disassembly calls in try-except blocks to prevent parser crashes on corrupted functions while reporting details.
• Early Fail Validation: Updated init.py to verify if the input binary path exists using os.path.exists() before launching radare2.

4. Packaging & Documentation Overhaul

• Version Bump: Bumped version to 0.5 and moved from deprecated distutils to setuptools in setup.py.
• New Documentation: Created a highly detailed README.md that outlines the metamorphic mechanisms, a complete catalog of supported mutation patterns and NOP sequences, and a VirusTotal detection comparison.
• Asset Clean-up: Reorganized screenshots from screens/ into a structured /docs directory.

---

🧪 Verification Plan

Automated Verification

• Verify package installation and CLI entrypoint setup using pip install -e ..
• Run metame on 32-bit and 64-bit ELF/PE binaries to ensure successful mutation patches.

Manual Verification

• Test input path validation by running metame -i non_existent.exe -o output.exe and verifying that the [ERROR] Input file does not exist message is displayed cleanly.
• Verify that disassembled outputs and multi-byte NOPs are properly generated by examining the modified binaries in a debugger/disassembler.