VMWhere

Author: expend20

CLAUDE.md

@@ -4,19 +4,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project
 
-Python port of Pluto LLVM obfuscation passes using llvm-nanobind bindings. Six passes transform LLVM IR to obfuscate code: Substitution, MBA Obfuscation, Bogus Control Flow, Flattening, Global Encryption, and Indirect Call.
+Python port of Pluto, Polaris, and VMwhere LLVM obfuscation passes using llvm-nanobind bindings. Passes transform LLVM IR to obfuscate code. See README.md for the full pass list.
 
 ## Commands
 
+**Always use `uv` to run tests** — never use the system Python directly. The system Python may have a different llvm-nanobind build with incompatible API (e.g. `is_terminator` vs `is_terminator_inst`). Only `uv run` uses the correct project venv.
+
+llvm-nanobind requires LLVM dev headers to build. Set `CMAKE_PREFIX_PATH` to your LLVM installation if `uv sync` fails to find LLVM (CI does this automatically).
+
 ```bash
-# Run all tests
-python -m uv run pytest tests/ -v
+# Run all tests (always use this form)
+CMAKE_PREFIX_PATH="C:\llvm\clang+llvm-21.1.0-x86_64-pc-windows-msvc" python -m uv run pytest tests/ -v
 
 # Run a single test file
-python -m uv run pytest tests/test_substitution.py -v
+CMAKE_PREFIX_PATH="C:\llvm\clang+llvm-21.1.0-x86_64-pc-windows-msvc" python -m uv run pytest tests/test_substitution.py -v
 
 # Run a single test by name
-python -m uv run pytest tests/test_substitution.py -k "test_add_substitution" -v
+CMAKE_PREFIX_PATH="C:\llvm\clang+llvm-21.1.0-x86_64-pc-windows-msvc" python -m uv run pytest tests/test_substitution.py -k "test_add_substitution" -v
 
 # Run UI (requires llvm-nanobind built)
 python -m uv run python -m shifting_codes.ui.app
@@ -42,14 +46,14 @@ pipeline.add(SubstitutionPass(rng=CryptoRandom(seed=42)))
 pipeline.run(mod, ctx)
 ```
 
-**FunctionPasses:** Substitution, MBAObfuscation, BogusControlFlow, Flattening
-**ModulePasses:** GlobalEncryption, IndirectCall
+**FunctionPasses:** Substitution, MBAObfuscation, BogusControlFlow, Flattening, IndirectBranch, AliasAccess, AntiDisassembly
+**ModulePasses:** GlobalEncryption, IndirectCall, CustomCC, MergeFunction, StringEncryption
 
 ### Utilities (`src/shifting_codes/utils/`)
 
 - **`crypto.py`** — `CryptoRandom`: wraps `secrets` (production) or `random.Random(seed)` (testing). All passes accept an `rng` parameter for determinism.
 - **`mba.py`** — Z3-based MBA coefficient generation with result caching. Generates linear (15 truth tables) and univariate polynomial expressions.
-- **`ir_helpers.py`** — PHI/register demotion to stack (`demote_phi_to_stack`, `demote_regs_to_stack`), used by Flattening pass.
+- **`ir_helpers.py`** — PHI/register demotion to stack (`demote_phi_to_stack`, `demote_regs_to_stack`), shared encryption utilities (`build_decrypt_function`, `encrypt_bytes`).
 
 ### XTEA (`src/shifting_codes/xtea/`)
 
@@ -61,6 +65,16 @@ Reference XTEA cipher implementation (pure Python) plus an LLVM IR builder that
 - `rng`: Seeded `CryptoRandom(seed=42)` for deterministic tests
 - Helper functions: `make_add_function()`, `make_arith_function()`, `make_branch_function()`, `make_loop_function()`
 
+## Maintenance Rules
+
+- **Keep README.md up to date.** When adding new passes, changing pass behavior, or making other significant changes, update the README pass tables, usage examples, and any other affected sections. The README is the public-facing documentation and must accurately reflect the current state of the project.
+
+## Testing Policy
+
+- **All tests pass on CI. There are no pre-existing test failures.** If tests fail after your changes, your changes broke them — investigate and fix. Never assume failures are pre-existing.
+- **Always run tests via `uv run`**, not the system Python. The system Python has a different llvm-nanobind with incompatible API names.
+- Test helper imports use `from conftest import ...` (not `from tests.conftest import ...`).
+
 ## llvm-nanobind API Pitfalls
 
 - `ctx.types.ptr`, `ctx.types.i32`, `ctx.types.void` are **properties** (not methods)

README.md

@@ -1,6 +1,6 @@
 # Shifting Codes
 
-Python port of [Pluto](https://github.com/bluesadi/Pluto) and [Polaris](https://github.com/za233/Polaris-Obfuscator/) LLVM obfuscation passes using [llvm-nanobind](https://github.com/LLVMParty/llvm-nanobind) bindings, with a PyQt6 visualization UI.
+Python port of [Pluto](https://github.com/bluesadi/Pluto), [Polaris](https://github.com/za233/Polaris-Obfuscator/), and [VMwhere](https://github.com/MrRoy09/VMwhere) LLVM obfuscation passes using [llvm-nanobind](https://github.com/LLVMParty/llvm-nanobind) bindings, with a PyQt6 visualization UI.
 
 ![](assets/UI-showcase.gif)
 
@@ -32,6 +32,13 @@ Upgraded versions of four Pluto passes plus four new passes:
 | **Custom CC** | Module | Randomly assigns non-standard calling conventions to internal functions |
 | **Merge Function** | Module | Merges multiple functions into a single switch-based dispatcher |
 
+### [VMwhere](https://github.com/MrRoy09/VMwhere) (2 passes)
+
+| Pass | Type | Description |
+|------|------|-------------|
+| **String Encryption** | Module | XOR-encrypts string constant globals (`[N x i8]`) with per-function stack-local decryption at runtime |
+| **Anti-Disassembly** | Function | Injects crafted x86 inline assembly that desynchronizes linear-sweep disassemblers (IDA, Ghidra, objdump) |
+
 ## Prerequisites
 
 - **Python 3.12+**
@@ -119,6 +126,23 @@ pipeline.add(MergeFunctionPass(rng=rng))
 pipeline.run(mod, ctx)
 ```
 
+VMwhere passes:
+
+```python
+from shifting_codes.passes import PassPipeline
+from shifting_codes.passes.string_encryption import StringEncryptionPass
+from shifting_codes.passes.anti_disassembly import AntiDisassemblyPass
+from shifting_codes.utils.crypto import CryptoRandom
+
+rng = CryptoRandom(seed=42)
+
+pipeline = PassPipeline()
+pipeline.add(StringEncryptionPass(rng=rng))
+pipeline.add(AntiDisassemblyPass(rng=rng, density=0.3))  # density: 0.0-1.0
+
+pipeline.run(mod, ctx)
+```
+
 Passes are registered via `@PassRegistry.register` and can be looked up by name:
 
 ```python

src/shifting_codes/passes/anti_disassembly.py

@@ -0,0 +1,105 @@
+"""Anti-Disassembly Pass — injects junk bytes via inline assembly.
+
+Crafted x86 byte sequences exploit linear-sweep disassembler weaknesses.
+They look like multi-byte instructions but include a hidden short jump
+that skips junk bytes. The CPU executes correctly but disassemblers
+(IDA, Ghidra, objdump) get desynchronized.
+
+Only active when the module target triple contains "x86" or "x86_64".
+"""
+
+from __future__ import annotations
+
+import llvm
+
+from shifting_codes.passes import PassRegistry
+from shifting_codes.passes.base import FunctionPass, PassInfo
+from shifting_codes.utils.crypto import CryptoRandom
+
+
+@PassRegistry.register
+class AntiDisassemblyPass(FunctionPass):
+
+    def __init__(self, rng: CryptoRandom | None = None, density: float = 0.3):
+        self.rng = rng or CryptoRandom()
+        self.density = max(0.0, min(1.0, density))
+
+    @classmethod
+    def info(cls) -> PassInfo:
+        return PassInfo(
+            name="anti_disassembly",
+            description="[VMwhere] Inject anti-disassembly junk bytes (x86 only)",
+        )
+
+    def _make_asm_string(self) -> str:
+        """Build an anti-disassembly byte pattern.
+
+        Pattern: 0x48 0xB8 <r1> <r2> <r3> 0xEB 0x08 0xFF 0xFF 0x48 0x31 0xC0 0xEB 0xF7 0xE8
+
+        The 0x48 0xB8 prefix makes disassemblers think it's a 10-byte
+        movabs rax, imm64. The 0xEB 0x08 is a short jump +8 that skips
+        the junk bytes. Random bytes add variation.
+        """
+        r1 = self.rng.get_range(256)
+        r2 = self.rng.get_range(256)
+        r3 = self.rng.get_range(256)
+        return (
+            f".byte 0x48, 0xB8, {r1:#04x}, {r2:#04x}, {r3:#04x}, "
+            f"0xEB, 0x08, 0xFF, 0xFF, 0x48, 0x31, 0xC0, 0xEB, 0xF7, 0xE8"
+        )
+
+    def run_on_function(self, func: llvm.Function, ctx: llvm.Context) -> bool:
+        # Check target triple — only inject on x86
+        mod = func.module
+        triple = mod.target_triple.lower() if mod.target_triple else ""
+        if "x86" not in triple and "i386" not in triple and "i686" not in triple:
+            return False
+
+        # void() function type for the inline asm calls
+        void_fn_ty = ctx.types.function(ctx.types.void, [])
+        changed = False
+
+        for bb in func.basic_blocks:
+            instructions = list(bb.instructions)
+            if not instructions:
+                continue
+
+            # Find first non-PHI instruction as insertion point
+            first_non_phi = None
+            non_phi_insts = []
+            for inst in instructions:
+                if inst.opcode == llvm.Opcode.PHI:
+                    continue
+                if first_non_phi is None:
+                    first_non_phi = inst
+                non_phi_insts.append(inst)
+
+            if first_non_phi is None:
+                continue
+
+            # Always inject at block start (before first non-PHI)
+            asm_str = self._make_asm_string()
+            asm_val = llvm.get_inline_asm(
+                void_fn_ty, asm_str, "~{eax}", True, False,
+                llvm.InlineAsmDialect.ATT, False)
+            with bb.create_builder() as b:
+                b.position_before(first_non_phi)
+                b.call(void_fn_ty, asm_val, [], "")
+            changed = True
+
+            # Randomly inject before other non-PHI, non-terminator instructions
+            for inst in non_phi_insts:
+                if inst == first_non_phi:
+                    continue
+                if inst.is_terminator:
+                    continue
+                if self.rng.get_range(1000) < int(self.density * 1000):
+                    asm_str = self._make_asm_string()
+                    asm_val = llvm.get_inline_asm(
+                        void_fn_ty, asm_str, "~{eax}", True, False,
+                        llvm.InlineAsmDialect.ATT, False)
+                    with bb.create_builder() as b:
+                        b.position_before(inst)
+                        b.call(void_fn_ty, asm_val, [], "")
+
+        return changed

src/shifting_codes/passes/global_encryption.py

@@ -14,8 +14,9 @@
 from shifting_codes.passes import PassRegistry
 from shifting_codes.passes.base import ModulePass, PassInfo
 from shifting_codes.utils.crypto import CryptoRandom
-
-KEY_LEN = 4
+from shifting_codes.utils.ir_helpers import (
+    KEY_LEN, build_decrypt_function, encrypt_bytes,
+)
 
 
 def _type_byte_size(ty: llvm.Type) -> int | None:
@@ -29,66 +30,6 @@ def _type_byte_size(ty: llvm.Type) -> int | None:
     return None
 
 
-def _encrypt_bytes(orig_val: int, byte_size: int, key: int,
-                   byte_offset: int = 0) -> int:
-    """XOR integer value byte-by-byte with 4-byte key (cyclic)."""
-    key_bytes = (key & 0xFFFFFFFF).to_bytes(4, 'little')
-    val_bytes = bytearray(orig_val.to_bytes(byte_size, 'little', signed=False))
-    for i in range(byte_size):
-        val_bytes[i] ^= key_bytes[(byte_offset + i) % KEY_LEN]
-    return int.from_bytes(val_bytes, 'little')
-
-
-def _build_decrypt_function(mod: llvm.Module, ctx: llvm.Context) -> llvm.Function:
-    """Build: void @__obfu_globalenc_dec(ptr %data, ptr %key, i64 %len, i64 %keyLen)
-
-    Loop body: data[i] ^= key[i % keyLen]
-    """
-    i8 = ctx.types.i8
-    i64 = ctx.types.i64
-    ptr = ctx.types.ptr
-    fn_ty = ctx.types.function(ctx.types.void, [ptr, ptr, i64, i64])
-    func = mod.add_function("__obfu_globalenc_dec", fn_ty)
-    func.linkage = llvm.Linkage.Private
-
-    entry_bb = func.append_basic_block("entry")
-    cmp_bb = func.append_basic_block("cmp")
-    body_bb = func.append_basic_block("body")
-    end_bb = func.append_basic_block("end")
-
-    data = func.get_param(0)
-    key = func.get_param(1)
-    length = func.get_param(2)
-    key_len = func.get_param(3)
-
-    with entry_bb.create_builder() as b:
-        i_ptr = b.alloca(i64, name="i")
-        b.store(i64.constant(0), i_ptr)
-        b.br(cmp_bb)
-
-    with cmp_bb.create_builder() as b:
-        iv = b.load(i64, i_ptr, "iv")
-        cond = b.icmp(llvm.IntPredicate.SLT, iv, length, "cmp")
-        b.cond_br(cond, body_bb, end_bb)
-
-    with body_bb.create_builder() as b:
-        iv = b.load(i64, i_ptr, "iv")
-        key_idx = b.srem(iv, key_len, "kidx")
-        key_ptr = b.gep(i8, key, [key_idx], "kptr")
-        key_byte = b.load(i8, key_ptr, "kbyte")
-        data_ptr = b.gep(i8, data, [iv], "dptr")
-        data_byte = b.load(i8, data_ptr, "dbyte")
-        dec = b.xor(key_byte, data_byte, "dec")
-        b.store(dec, data_ptr)
-        b.store(b.add(iv, i64.constant(1), "inc"), i_ptr)
-        b.br(cmp_bb)
-
-    with end_bb.create_builder() as b:
-        b.ret_void()
-
-    return func
-
-
 def _is_encryptable_global(gv) -> bool:
     """Check if a value is a global variable suitable for encryption."""
     if not hasattr(gv, 'global_value_type'):
@@ -154,7 +95,7 @@ def run_on_module(self, mod: llvm.Module, ctx: llvm.Context) -> bool:
             return False
 
         # Phase 2: Build shared decrypt helper
-        decrypt_func = _build_decrypt_function(mod, ctx)
+        decrypt_func = build_decrypt_function(mod, ctx)
 
         i32 = ctx.types.i32
         i64 = ctx.types.i64
@@ -188,7 +129,7 @@ def run_on_module(self, mod: llvm.Module, ctx: llvm.Context) -> bool:
             try:
                 if vtype.kind == llvm.TypeKind.Integer:
                     orig_val = init.const_zext_value
-                    enc_val = _encrypt_bytes(orig_val, byte_size, key)
+                    enc_val = encrypt_bytes(orig_val, byte_size, key)
                     gv.initializer = vtype.constant(enc_val)
                 elif vtype.kind == llvm.TypeKind.Array:
                     elem_type = vtype.element_type
@@ -199,7 +140,7 @@ def run_on_module(self, mod: llvm.Module, ctx: llvm.Context) -> bool:
                     for j in range(elem_count):
                         elem = init.get_aggregate_element(j)
                         orig_val = elem.const_zext_value
-                        enc_val = _encrypt_bytes(orig_val, elem_size, key,
+                        enc_val = encrypt_bytes(orig_val, elem_size, key,
                                                  byte_offset)
                         enc_elements.append(enc_val)
                         byte_offset += elem_size