Initial commit

Author: expend20

CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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.
+
+## Commands
+
+```bash
+# Run all tests
+python -m uv run pytest tests/ -v
+
+# Run a single test file
+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
+
+# Run UI (requires llvm-nanobind built)
+python -m uv run python -m shifting_codes.ui.app
+```
+
+## Dependencies
+
+- **llvm-nanobind**: Local editable dependency at `../llvm-nanobind/build/` (must be built separately before tests/UI work)
+- **z3-solver**: Constraint solving for MBA coefficient generation
+- **PyQt6**: GUI framework (UI not yet tested)
+- Python 3.12+ required, managed with UV + hatchling build backend
+
+## Architecture
+
+### Pass System
+
+All passes inherit from `FunctionPass` or `ModulePass` (in `src/shifting_codes/passes/base.py`) and are auto-registered via `@PassRegistry.register` decorator. Each pass implements `run_on_function(func, ctx)` or `run_on_module(mod, ctx)` returning a bool indicating modification.
+
+Passes are composed via `PassPipeline` (in `src/shifting_codes/passes/__init__.py`):
+```python
+pipeline = PassPipeline()
+pipeline.add(SubstitutionPass(rng=CryptoRandom(seed=42)))
+pipeline.run(mod, ctx)
+```
+
+**FunctionPasses:** Substitution, MBAObfuscation, BogusControlFlow, Flattening
+**ModulePasses:** GlobalEncryption, IndirectCall
+
+### 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.
+
+### XTEA (`src/shifting_codes/xtea/`)
+
+Reference XTEA cipher implementation (pure Python) plus an LLVM IR builder that constructs the same cipher using the nanobind Builder API. Used for end-to-end testing: build IR → apply all passes → compile → execute via ctypes → verify against reference.
+
+### Test Fixtures (`tests/conftest.py`)
+
+- `ctx`: Fresh LLVM context per test
+- `rng`: Seeded `CryptoRandom(seed=42)` for deterministic tests
+- Helper functions: `make_add_function()`, `make_arith_function()`, `make_branch_function()`, `make_loop_function()`
+
+## llvm-nanobind API Pitfalls
+
+- `ctx.types.ptr`, `ctx.types.i32`, `ctx.types.void` are **properties** (not methods)
+- `ctx.create_module("name")` returns a context manager: `with ctx.create_module("name") as mod:`
+- `inst.block` for parent block (not `.parent`)
+- `gv.global_value_type` for content type (not `gv.type` which returns pointer type)
+- `call_inst.called_value` is read-only — to change call target, rebuild the call instruction
+- `builder.call(func, args, name)` for direct calls; `builder.call(func_ty, ptr, args, name)` for indirect calls
+- `mod.target_triple = "..."` (not `mod.triple`)
+- `func.dll_storage_class = llvm.DLLExport` required for Windows DLL exports
+- Integer constants must be masked to bit width: `key & ((1 << vtype.int_width) - 1)`
+- ConstantDataArray element access via `get_operand()` crashes — avoid array encryption
+- PHI nodes need `inst.add_incoming(value, pred_bb)` when new predecessors are added
+- Z3 non-determinism: bound coefficients (`-10 <= X[i] <= 10`) and set `smt.random_seed`

NANOBIND_ISSUES.md

@@ -0,0 +1,117 @@
+# Shifting Codes
+
+Python port of [Pluto](https://github.com/bluesadi/Pluto) LLVM obfuscation passes using [llvm-nanobind](https://github.com/nicovank/llvm-nanobind) bindings, with a PyQt6 visualization UI.
+
+![](assets/UI-showcase.gif)
+
+## Passes
+
+Six obfuscation passes are available:
+
+| Pass | Type | Description |
+|------|------|-------------|
+| **Substitution** | Function | Replaces arithmetic operations with equivalent but obscure sequences |
+| **MBA Obfuscation** | Function | Applies Mixed Boolean-Arithmetic transformations using Z3-generated coefficients |
+| **Bogus Control Flow** | Function | Inserts opaque predicates and dead code paths |
+| **Flattening** | Function | Transforms control flow into a switch-based dispatch loop |
+| **Global Encryption** | Module | XOR-encrypts global variable initializers with runtime decryption stubs |
+| **Indirect Call** | Module | Replaces direct function calls with indirect calls through function pointers |
+
+## Prerequisites
+
+- **Python 3.12+**
+- **[UV](https://docs.astral.sh/uv/)** package manager
+- **llvm-nanobind** — must be cloned and built separately (see below)
+
+## Installation
+
+1. **Install UV** (if not already installed):
+
+   ```bash
+   pip install uv
+   ```
+
+2. **Clone and build llvm-nanobind** as a sibling directory:
+
+   ```bash
+   git clone https://github.com/LLVMParty/llvm-nanobind ../llvm-nanobind
+   cd ../llvm-nanobind
+   # Follow llvm-nanobind's build instructions to produce the build/ directory
+   cd -
+   ```
+
+   The project expects the built package at `../llvm-nanobind/build/`.
+
+3. **Install the project**:
+
+   ```bash
+   uv sync
+   ```
+
+## Usage
+
+```python
+import llvm
+from shifting_codes.passes import PassPipeline
+from shifting_codes.passes.substitution import SubstitutionPass
+from shifting_codes.passes.mba_obfuscation import MBAObfuscationPass
+from shifting_codes.passes.bogus_control_flow import BogusControlFlowPass
+from shifting_codes.passes.flattening import FlatteningPass
+from shifting_codes.passes.global_encryption import GlobalEncryptionPass
+from shifting_codes.passes.indirect_call import IndirectCallPass
+from shifting_codes.utils.crypto import CryptoRandom
+
+rng = CryptoRandom(seed=42)
+
+pipeline = PassPipeline()
+pipeline.add(SubstitutionPass(rng=rng))
+pipeline.add(MBAObfuscationPass(rng=rng))
+pipeline.add(BogusControlFlowPass(rng=rng))
+pipeline.add(FlatteningPass(rng=rng))
+pipeline.add(GlobalEncryptionPass(rng=rng))
+pipeline.add(IndirectCallPass(rng=rng))
+
+# Apply to a module
+pipeline.run(mod, ctx)
+```
+
+Passes are registered via `@PassRegistry.register` and can be looked up by name:
+
+```python
+from shifting_codes.passes import PassRegistry
+
+cls = PassRegistry.get("substitution")
+all_passes = PassRegistry.all_passes()
+```
+
+## Running Tests
+
+```bash
+# All tests
+python -m uv run pytest tests/ -v
+
+# Single test file
+python -m uv run pytest tests/test_substitution.py -v
+
+# Single test by name
+python -m uv run pytest tests/test_substitution.py -k "test_add_substitution" -v
+```
+
+## UI
+
+Launch the PyQt6 visualization GUI:
+
+```bash
+python -m uv run python -m shifting_codes.ui.app
+```
+
+## Project Structure
+
+```
+src/shifting_codes/
+  passes/          # Obfuscation passes (base classes, registry, pipeline)
+  utils/           # Shared utilities (crypto RNG, MBA solver, IR helpers)
+  xtea/            # XTEA cipher — pure Python reference + LLVM IR builder
+  ui/              # PyQt6 GUI for visualizing pass transformations
+tests/             # pytest test suite
+```

README.md

@@ -6,6 +6,12 @@
 
 from shifting_codes.passes.base import FunctionPass, ModulePass, PassInfo
 
+# Enum attribute kind IDs (stable within an LLVM version).
+# optnone: tells the optimizer to skip this function entirely.
+# noinline: required alongside optnone (LLVM verifier rejects optnone without it).
+_ATTR_NOINLINE = 32
+_ATTR_OPTNONE = 49
+
 
 class PassRegistry:
     """Registry of available obfuscation passes."""
@@ -36,13 +42,45 @@ def __init__(self, passes: list[FunctionPass | ModulePass] | None = None):
     def add(self, p: FunctionPass | ModulePass) -> None:
         self.passes.append(p)
 
-    def run(self, mod: llvm.Module, ctx: llvm.Context) -> bool:
+    def run(
+        self,
+        mod: llvm.Module,
+        ctx: llvm.Context,
+        selected_functions: set[str] | None = None,
+    ) -> bool:
+        """Run all passes on the module.
+
+        Args:
+            mod: The LLVM module to transform.
+            ctx: The LLVM context.
+            selected_functions: If None, all functions receive FunctionPasses.
+                If a set, only named functions receive FunctionPasses.
+                ModulePasses always apply to the entire module regardless.
+        """
         changed = False
+        obfuscated_functions: set[str] = set()
         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)
+                    if func.is_declaration:
+                        continue
+                    if selected_functions is not None and func.name not in selected_functions:
+                        continue
+                    if p.run_on_function(func, ctx):
+                        changed = True
+                        obfuscated_functions.add(func.name)
+
+        # Stamp obfuscated functions with optnone + noinline so that
+        # downstream compilers (e.g. clang -O2) cannot strip obfuscation.
+        if obfuscated_functions:
+            optnone = ctx.create_enum_attribute(_ATTR_OPTNONE, 0)
+            noinline = ctx.create_enum_attribute(_ATTR_NOINLINE, 0)
+            fn_idx = llvm.AttributeFunctionIndex
+            for func in mod.functions:
+                if func.name in obfuscated_functions:
+                    func.add_attribute(fn_idx, optnone)
+                    func.add_attribute(fn_idx, noinline)
+
         return changed