init

Author: expend20

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+.venv/
+.pytest_cache/
+*.o
+*.dll
+*.so
+*.pyd

NANOBIND_ISSUES.md

@@ -0,0 +1,136 @@
+# llvm-nanobind Issues & Gotchas
+
+Issues encountered while porting Pluto obfuscation passes to Python using llvm-nanobind.
+
+## API Surprises
+
+### `ctx.types.ptr` is a property, not a method
+```python
+# WRONG — TypeError: 'llvm.Type' object is not callable
+ptr_ty = ctx.types.ptr()
+
+# CORRECT
+ptr_ty = ctx.types.ptr
+```
+Other type accessors like `ctx.types.i32`, `ctx.types.void` are also properties.
+Only `ctx.types.function(ret, args)` and `ctx.types.array(elem, count)` are methods.
+
+### `ctx.create_module()` returns `ModuleManager`, not `Module`
+Must use as a context manager to get the actual `Module`:
+```python
+# WRONG — returns ModuleManager, has no add_function/add_global/etc.
+mod = ctx.create_module("test")
+
+# CORRECT
+with ctx.create_module("test") as mod:
+    mod.add_function(...)
+```
+
+### `mod.target_triple`, not `mod.triple`
+```python
+# WRONG
+mod.triple = "x86_64-pc-windows-msvc"
+
+# CORRECT
+mod.target_triple = "x86_64-pc-windows-msvc"
+```
+
+### `llvm.create_target_machine()` is a module-level function
+```python
+# WRONG — Target has no create_target_machine method
+tm = target.create_target_machine(triple, cpu, features)
+
+# CORRECT
+tm = llvm.create_target_machine(target, triple, cpu, features)
+```
+
+### `inst.block` for parent block, not `inst.parent`
+```python
+bb = inst.block  # correct
+```
+
+### `gv.global_value_type` for content type
+`gv.type` returns the pointer type. Use `gv.global_value_type` for the actual stored type.
+
+## Call Instruction Limitations
+
+### No setter for call callee
+There is no `set_called_operand()` or `set_callee()` on call instructions.
+`called_value` is read-only. To change a call's target, rebuild the call:
+
+```python
+# Build new indirect call and replace the old one
+with bb.create_builder() as builder:
+    builder.position_before(call_inst)
+    loaded = builder.load(ptr_ty, gv, "fn.ptr")
+    new_call = builder.call(func_ty, loaded, args, "result")
+call_inst.replace_all_uses_with(new_call)
+call_inst.erase_from_parent()
+```
+
+### Two overloads for `builder.call()`
+```python
+# Direct call (infers function type from Function object)
+builder.call(func, args, name)
+
+# Indirect call (explicit function type, callee can be any value/pointer)
+builder.call(func_ty, loaded_ptr, args, name)
+```
+Passing a loaded pointer to the 2-arg form causes `LLVMAssertionError`.
+
+## Segfaults & Crashes
+
+### ConstantDataArray element access crashes
+Accessing elements of array initializers via `init.get_operand(i)` on arrays created
+with `const_array` causes a segfault. No workaround found — we removed array encryption
+from the GlobalEncryption pass entirely.
+
+### `func.dll_storage_class` required for Windows DLL exports
+Functions emitted to object files for Windows DLLs must have:
+```python
+func.dll_storage_class = llvm.DLLExport
+```
+Otherwise the symbol won't be exported and `ctypes.CDLL` can't find it.
+
+## Missing APIs
+
+### No `splitBasicBlock()`
+Cannot split a basic block at an arbitrary instruction. The Bogus Control Flow pass
+had to be redesigned to work without block splitting — it inserts opaque predicates
+before existing terminators instead of cloning block contents.
+
+## Initialization
+
+### Must initialize ASM printers for `emit_to_file()`
+```python
+llvm.initialize_all_targets()
+llvm.initialize_all_target_mcs()
+llvm.initialize_all_target_infos()
+llvm.initialize_all_asm_printers()  # without this: "can't emit a file of this type"
+```
+
+## Integer Constant Overflow
+
+### Constants must fit the type's bit width
+`vtype.constant(value)` raises `TypeError` if `value` exceeds the type's range.
+When generating random keys for XOR encryption, mask to the bit width:
+```python
+bit_width = vtype.int_width
+mask = (1 << bit_width) - 1
+key = rng.get_uint64() & mask
+```
+
+## PHI Node Maintenance
+
+### New predecessors require PHI incoming entries
+When adding a new block that branches to an existing block containing PHI nodes,
+you must add incoming values for the new predecessor:
+```python
+for inst in target_bb.instructions:
+    if inst.opcode == llvm.Opcode.PHI:
+        inst.add_incoming(inst.type.undef(), new_bb)
+    else:
+        break
+```
+Without this, the module verifier fails with:
+`PHINode should have one entry for each predecessor of its parent basic block!`

pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "shifting-codes"
+version = "0.1.0"
+description = "LLVM obfuscation passes ported from Pluto to Python, with PyQt6 visualization"
+requires-python = ">=3.12"
+dependencies = [
+    "z3-solver>=4.12",
+    "PyQt6>=6.6",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shifting_codes"]
+
+[tool.uv.sources]
+llvm-nanobind = { path = "../llvm-nanobind", editable = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "../llvm-nanobind/build"]

src/shifting_codes/__init__.py

@@ -0,0 +1,3 @@
+"""Shifting Codes - LLVM obfuscation passes ported from Pluto to Python."""
+
+__version__ = "0.1.0"

src/shifting_codes/passes/__init__.py

@@ -0,0 +1,48 @@
+"""Pass registry and pipeline for obfuscation passes."""
+
+from __future__ import annotations
+
+import llvm
+
+from shifting_codes.passes.base import FunctionPass, ModulePass, PassInfo
+
+
+class PassRegistry:
+    """Registry of available obfuscation passes."""
+
+    _passes: dict[str, type[FunctionPass | ModulePass]] = {}
+
+    @classmethod
+    def register(cls, pass_cls: type[FunctionPass | ModulePass]) -> type:
+        info = pass_cls.info()
+        cls._passes[info.name] = pass_cls
+        return pass_cls
+
+    @classmethod
+    def get(cls, name: str) -> type[FunctionPass | ModulePass] | None:
+        return cls._passes.get(name)
+
+    @classmethod
+    def all_passes(cls) -> dict[str, type[FunctionPass | ModulePass]]:
+        return dict(cls._passes)
+
+
+class PassPipeline:
+    """Ordered pipeline of obfuscation passes."""
+
+    def __init__(self, passes: list[FunctionPass | ModulePass] | None = None):
+        self.passes: list[FunctionPass | ModulePass] = passes or []
+
+    def add(self, p: FunctionPass | ModulePass) -> None:
+        self.passes.append(p)
+
+    def run(self, mod: llvm.Module, ctx: llvm.Context) -> bool:
+        changed = False
+        for p in self.passes:
+            if isinstance(p, ModulePass):
+                changed |= p.run_on_module(mod, ctx)
+            elif isinstance(p, FunctionPass):
+                for func in mod.functions:
+                    if not func.is_declaration:
+                        changed |= p.run_on_function(func, ctx)
+        return changed

src/shifting_codes/passes/base.py

@@ -0,0 +1,43 @@
+"""Base classes for obfuscation passes."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import llvm
+
+
+@dataclass(frozen=True)
+class PassInfo:
+    name: str
+    description: str
+    is_module_pass: bool = False
+
+
+class FunctionPass(ABC):
+    """Abstract base class for function-level obfuscation passes."""
+
+    @abstractmethod
+    def run_on_function(self, func: llvm.Function, ctx: llvm.Context) -> bool:
+        """Run the pass on a single function. Returns True if the function was modified."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def info(cls) -> PassInfo:
+        """Return metadata about this pass."""
+        ...
+
+
+class ModulePass(ABC):
+    """Abstract base class for module-level obfuscation passes."""
+
+    @abstractmethod
+    def run_on_module(self, mod: llvm.Module, ctx: llvm.Context) -> bool:
+        """Run the pass on the entire module. Returns True if the module was modified."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def info(cls) -> PassInfo:
+        """Return metadata about this pass."""
+        ...

src/shifting_codes/passes/bogus_control_flow.py

@@ -0,0 +1,106 @@
+"""Bogus Control Flow Pass — port of Pluto BogusControlFlowPass.cpp.
+
+Inserts opaque predicates (always-true conditions) before unconditional
+branches, adding dead code paths to confuse static analysis.
+"""
+
+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 BogusControlFlowPass(FunctionPass):
+
+    def __init__(self, rng: CryptoRandom | None = None):
+        self.rng = rng or CryptoRandom()
+        self._bcf_counter = 0
+
+    @classmethod
+    def info(cls) -> PassInfo:
+        return PassInfo(
+            name="bogus_control_flow",
+            description="Insert opaque predicates and bogus branches",
+        )
+
+    def run_on_function(self, func: llvm.Function, ctx: llvm.Context) -> bool:
+        mod = func.module
+        i32 = ctx.types.i32
+        changed = False
+
+        # Collect blocks with unconditional branches to transform
+        blocks_to_transform = []
+        for bb in func.basic_blocks:
+            term = bb.terminator
+            if term is None:
+                continue
+            if term.opcode == llvm.Opcode.Br:
+                succs = list(term.successors)
+                if len(succs) == 1:
+                    blocks_to_transform.append(bb)
+
+        for bb in blocks_to_transform:
+            term = bb.terminator
+            succs = list(term.successors)
+            if len(succs) != 1:
+                continue
+            real_target = succs[0]
+
+            self._bcf_counter += 1
+            tag = self._bcf_counter
+
+            # Create global variables for the opaque predicate
+            x_gv = mod.add_global(i32, f"__bcf_x_{tag}")
+            x_gv.initializer = i32.constant(0)
+            x_gv.linkage = llvm.Linkage.Private
+
+            y_gv = mod.add_global(i32, f"__bcf_y_{tag}")
+            y_gv.initializer = i32.constant(0)
+            y_gv.linkage = llvm.Linkage.Private
+
+            # Create bogus block that branches back to the real target
+            bogus_bb = func.append_basic_block(f"bcf.bogus.{tag}")
+            with bogus_bb.create_builder() as builder:
+                builder.br(real_target)
+
+            # Fix PHI nodes in real_target: add incoming from bogus_bb
+            # The bogus block is unreachable, so we use undef values
+            for inst in real_target.instructions:
+                if inst.opcode == llvm.Opcode.PHI:
+                    inst.add_incoming(inst.type.undef(), bogus_bb)
+                else:
+                    break  # PHIs are always at the start of a block
+
+            # Insert opaque predicate before the terminator:
+            #   (y < 10) || (x * (x + 1) % 2 == 0)  — always true
+            with bb.create_builder() as builder:
+                builder.position_before(term)
+
+                x_val = builder.load(i32, x_gv, "bcf.x")
+                y_val = builder.load(i32, y_gv, "bcf.y")
+
+                # cond1: y < 10
+                cond1 = builder.icmp(
+                    llvm.IntPredicate.SLT, y_val, i32.constant(10), "bcf.cmp1"
+                )
+
+                # cond2: x * (x + 1) % 2 == 0  (always true: product of consecutive ints is even)
+                xp1 = builder.add(x_val, i32.constant(1), "bcf.xp1")
+                xmul = builder.mul(x_val, xp1, "bcf.xmul")
+                xmod = builder.urem(xmul, i32.constant(2), "bcf.xmod")
+                cond2 = builder.icmp(
+                    llvm.IntPredicate.EQ, xmod, i32.constant(0), "bcf.cmp2"
+                )
+
+                bogus_cond = builder.or_(cond1, cond2, "bcf.cond")
+                builder.cond_br(bogus_cond, real_target, bogus_bb)
+
+            # Remove original unconditional branch
+            term.erase_from_parent()
+            changed = True
+
+        return changed