0xMohammedHassan/morphkatz

What it is

MorphKatz ships as a single static morphkatz.exe (no runtime dependencies) for Windows 10+/Server 2019+, x64. Beyond the summary's mechanism description, the page exposes the actual command surface an engineer would drive — the flags that turn "rewrite gadgets by hand" into repeatable measurement.

How it works

Zydis recursive-descent disassembly recovers the CFG (including jump tables; data-in-code is never decoded), rewrites flow through a typed ir::Instruction IR carrying full operand metadata, and per-basic-block EFLAGS liveness (AF/CF/OF/PF/SF/ZF) guarantees rewrites don't corrupt flag state. Rewrite rules live as hot-swappable YAML under rules/x64/, each with a cited Intel SDM equivalence proof. Output is verified by re-disassembly (default) or optional Unicorn basic-block emulation. NOP padding uses 1–9-byte multi-byte NOP rotation from the Intel Optimization Reference Manual.

What to do

Blue-team coverage measurement — generate variants and get per-rule trigger percentages:

morphkatz --variants 50 --target your-yara/*.yar

Find which bytes drove a Defender detection:

morphkatz scan --bisect

Auto-bisect Defender anchors via MpCmdRun and feed them into the rewrite priority queue:

morphkatz --target-defender

Reproducible output for a write-up (byte-for-byte identical on any machine, xoshiro256** RNG):

morphkatz --seed N

Other flags: --data-morph on (XOR-encodes signature-bearing bytes in .rdata/.data, decoded at runtime by a polymorphic stub with an anti-emulation gate), --verify unicorn. Reports emit as JSON/HTML with per-offset before/after diffs and rule IDs.

Build: no .sln/.vcxproj are committed — they're CMake-generated. Needs VS 2022 17.8+ with MSVC v143, CMake 3.27+, and vcpkg. Set VCPKG_ROOT after bootstrapping, then use .\Open-in-VS.cmd (presets vs2022-x64, vs2022-x64-asan; -Fresh clears cache, -NoOpen configures only for CI). Set morphkatz as startup project.

Caveats

The page states hard scope limits worth noting before you plan around it:

• ML/behavioral detections (anything ending !ml) evaluate global behavior and will not budge — out of scope by design.
• It refuses to ship "pop-malware-of-the-month" rule packs; only author-audited rules with cited equivalence proofs are included. It deliberately does not target the current-malware list (see RESPONSIBLE_USE.md).
• Red-team use is framed strictly around a documented rules-of-engagement paper trail, not live-malware obfuscation.

flowchart TD
    A[PE / shellcode input] --> B{Detection class?}
    B -->|byte-pattern: YARA/Defender/Sigma/Elastic| C[Morph → byte-different, semantically identical]
    B -->|!ml behavioral| D[Out of scope — won't budge]
    C --> E{Verify}
    E -->|re-disasm default| F[Output + JSON/HTML diff]
    E -->|--verify unicorn| F