r2morph

Metamorphic mutation engine with structured validation and reporting

Overview

r2morph is a metamorphic mutation engine that applies tracked binary transformations with validation, rollback, and machine-readable reports. The 0.4.0-alpha.3 support contract is intentionally narrow: Linux ELF x86-64 is the official target. Other formats and architectures remain preview or experimental.

Key Features

Installation

Prerequisites

• Python 3.12 or 3.13
• radare2 installed

Install radare2

git clone https://github.com/radareorg/radare2
cd radare2
sys/install.sh

Install r2morph

pip install r2morph                  # Basic
pip install "r2morph[enhanced]"      # + angr, lief, z3
pip install "r2morph[all]"           # + frida, hypothesis

Development Install

git clone https://github.com/seifreed/r2morph.git
cd r2morph
python -m pip install --editable ".[dev]"

The CI dependency manifest remains available for reproducing the extended analysis environment: python -m pip install -r requirements.txt followed by python -m pip install --editable ..

Support Matrix

Formats

Architectures

The machine-readable contract is docs/support-matrix.json. The reproducible GCC/Clang corpus and its build manifest live in the public r2morph-corpus repository.

Instruction Equivalence Rules

• x86/x86_64: 100+ rules in x86_rules.yaml - bidirectional groups covering zero registers, self-moves, flag-preserving patterns, XOR/SUB equivalence
• ARM32: 10+ groups in arm_rules.yaml - zero, increment, decrement, self-move, shift, negate, double, compare for r0-r11
• ARM64: Register classes defined in arm64_rules.yaml

Mutation Passes

Stable (tested, production-ready)

Experimental (working, limited testing)

Validation

Quick Start

# Mutate with stable passes
r2morph mutate input.elf -o output.elf -m nop -m substitute -m register

# SARIF report for CI/CD
r2morph mutate input.elf -o output.elf --format sarif --report mutations.sarif

# Reproducible run
r2morph mutate input.elf -o output.elf --seed 1337

# Runtime validation
r2morph validate original.elf mutated.elf --corpus fixtures/dataset/runtime_corpus.json

# CI gate: fail if severity below threshold
r2morph mutate input.elf -o output.elf --report report.json --min-severity bounded-only

# Display and filter reports
r2morph report report.json --only-pass nop --summary-only
r2morph report report.json --format sarif -o report.sarif

CLI Reference

Commands

Report Filters

SARIF 2.1.0 Integration

Reports in SARIF format include:

• MITRE ATT&CK taxonomy - T1027 (Obfuscated Files), T1027.001 (Binary Padding), T1027.002 (Software Packing)
• Partial fingerprints (SHA256) for deduplication across CI runs
• Code flows showing mutation chains per function
• Related locations linking mutations to validation failures
• Disassembly snippets in the rendered field alongside hex bytes
• Fix suggestions with byte-level replacements

Compatible with GitHub Code Scanning, Azure DevOps, SonarQube, and any SARIF 2.1.0 consumer.

Python API

from r2morph import MorphEngine
from r2morph.mutations import NopInsertionPass, InstructionSubstitutionPass, RegisterSubstitutionPass

with MorphEngine() as engine:
    engine.load_binary("input.elf").analyze()

    engine.add_mutation(NopInsertionPass())
    engine.add_mutation(InstructionSubstitutionPass())
    engine.add_mutation(RegisterSubstitutionPass())

    result = engine.run(validation_mode="structural", report_path="report.json")
    engine.save("output.elf")

print(f"Applied {result['total_mutations']} mutations")

Detection & Analysis

Devirtualization (Experimental)

Instrumentation (Experimental)

Frida integration for dynamic analysis: process spawning, script injection, API call logging, anti-analysis detection. Requires frida package.

Report Schema

JSON reports follow a documented schema at r2morph/reporting/report_schema.json. Each report includes:

• metadata: tool version, timestamp, duration, platform
• input/output: binary path, architecture, format, function count
• passes: per-pass mutation counts, timing, diff summaries
• mutations: flat list with address, bytes, disassembly, function, section
• validation: mode, results, symbolic coverage
• gate_evaluation: severity gate outcomes for CI
• summary: aggregated statistics

Requirements

• Python 3.10+
• radare2
• Optional: lief (PE/Mach-O/section creation), angr (symbolic validation), frida (instrumentation), z3-solver (MBA simplification)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support the Project

If you find r2morph useful, consider supporting its development:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Attribution Required:

• Author: Marc Rivero | @seifreed
• Repository: github.com/seifreed/r2morph

_{Made with dedication for the reverse engineering community}