risc-y business vm

Author: expend20

.claude/skills/write-article/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: write-article
+description: Write a technical article about a ShiftingCodes pass or related topic
+---
+
+Write a technical article about $ARGUMENTS and save it to `articles/` with a descriptive kebab-case filename.
+
+## Workflow
+
+### 1. Read before writing
+- Read the actual pass implementation(s) the article covers — never describe what code does from memory
+- Read the test files and `tests/conftest.py` helper functions to understand what "before" IR looks like
+- If the article covers IR examples, trace the exact instruction sequences the pass emits
+
+### 2. Frontmatter
+Every article starts with:
+```yaml
+---
+title: "Title Here"
+date: "YYYY-MM-DD"
+description: "One sentence describing what the article covers and why it matters"
+tags: ["relevant", "tags", "here"]
+---
+```
+
+### 3. Structure
+1. **Hook** — one paragraph on the real-world problem (reverse engineering, protection, etc.)
+2. **What is X** — introduce the upstream project(s) with accurate history and maintenance status
+3. **The problem** — why the original doesn't work today (version freeze, API churn, etc.)
+4. **The solution** — introduce ShiftingCodes and llvm-nanobind; credit authors specifically
+5. **Before/after IR** — concrete examples grounded in actual pass output
+6. **How to use** — setup, Python driver script, selective obfuscation, UI
+7. **Credits** — name individuals, not just projects
+
+### 4. IR example rules
+- Add this note at the top of the before/after section:
+  > *IR samples are lightly simplified for readability — actual output uses random constants and generated names — but the instruction sequences and structure match the Python implementation exactly.*
+- **Before IR**: must match what the `conftest.py` helper functions actually build
+- **After IR**: must reflect the real algorithm — read the pass source, trace the instruction sequence
+- Use `<placeholder>` for random constants (e.g. `<a>`, `<m>`, `<loop_state>`) rather than inventing specific numbers
+- Show real variable names from the pass (`bcf.var`, `cff.state`, `sub.ar`, etc.)
+- Comments in IR should explain the invariant, not just label blocks
+- If a block is dead/unreachable, say so explicitly in a comment
+
+### 5. Tone and accuracy
+- No superlatives ("brilliant", "amazing") — describe what things do, not how impressive they are
+- State clearly when upstream projects are unmaintained/archived
+- Legal disclaimer (end of article):
+  > *[Project] is provided for legitimate use cases including software protection, security research, CTF challenge authoring, and compiler education. The authors make no representations regarding fitness for any particular purpose and accept no liability for any misuse or damages arising from the use of this software. Use is entirely at your own risk and responsibility.*
+- Credit individual contributors by name with GitHub links (e.g. mrexodia for llvm-nanobind)
+- Tease future articles for related projects rather than covering them inline
+
+### 6. Scope discipline
+- Be precise about what the article covers — if it's about Pluto, don't claim 17 passes when Pluto has 6
+- Don't mention Polaris techniques as Pluto techniques
+- If an IR example uses a Polaris-era algorithm, describe the algorithm accurately, not the simpler Pluto version
+
+### 7. Verification checklist before finishing
+- [ ] All URLs match the canonical list in CLAUDE.md
+- [ ] Each "before" IR matches what conftest helpers actually build
+- [ ] Each "after" IR matches the actual pass algorithm (read the source)
+- [ ] Pass count / feature claims are accurate
+- [ ] Maintenance status of upstream projects is stated correctly
+- [ ] Article scoped to what it claims to cover
+- [ ] Frontmatter complete with today's date
+- [ ] Saved to `articles/<descriptive-kebab-name>.md`

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/riscy-business"]
+	path = vendor/riscy-business
+	url = https://github.com/expend20/riscy-business

CLAUDE.md

@@ -89,3 +89,13 @@ Reference XTEA cipher implementation (pure Python) plus an LLVM IR builder that
 - 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`
+
+## Canonical URLs
+
+Do not hallucinate these — use exactly as written:
+
+- **ShiftingCodes**: https://github.com/expend20/shifting-codes-python-port
+- **Pluto**: https://github.com/bluesadi/Pluto
+- **Polaris-Obfuscator** (by za233, NOT bluesadi): https://github.com/za233/Polaris-Obfuscator
+- **llvm-nanobind** (NOT github.com/llvm-nanobind/...): https://github.com/LLVMParty/llvm-nanobind
+- **RISC-Y Business VM**: https://github.com/thesecretclub/riscy-business

README.md

@@ -39,6 +39,12 @@ Upgraded versions of four Pluto passes plus four new passes:
 | **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) |
 
+### [riscy-business](https://github.com/expend20/riscy-business) (1 pass)
+
+| Pass | Type | Description |
+|------|------|-------------|
+| **Virtualization** | Module | Translates functions to RISC-V inspired bytecode and replaces them with an embedded interpreter (Phase 1: integer arithmetic) |
+
 ## Prerequisites
 
 - **Python 3.12+**
@@ -143,6 +149,21 @@ pipeline.add(AntiDisassemblyPass(rng=rng, density=0.3))  # density: 0.0-1.0
 pipeline.run(mod, ctx)
 ```
 
+Virtualization pass (riscy-business):
+
+```python
+from shifting_codes.passes import PassPipeline
+from shifting_codes.passes.virtualization import VirtualizationPass
+from shifting_codes.utils.crypto import CryptoRandom
+
+rng = CryptoRandom(seed=42)
+
+pipeline = PassPipeline()
+pipeline.add(VirtualizationPass(rng=rng))
+
+pipeline.run(mod, ctx)
+```
+
 Passes are registered via `@PassRegistry.register` and can be looked up by name:
 
 ```python
@@ -177,9 +198,12 @@ python -m uv run python -m shifting_codes.ui.app
 
 ```
 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
+  passes/            # Obfuscation passes (base classes, registry, pipeline)
+  utils/             # Shared utilities (crypto RNG, MBA solver, IR helpers)
+  riscybusiness_vm/  # RISC-V VM: ISA definition, bytecode compiler, interpreter builder
+  xtea/              # XTEA cipher — pure Python reference + LLVM IR builder
+  ui/                # PyQt6 GUI for visualizing pass transformations
+vendor/
+  riscy-business/    # Git submodule — RISC-V VM reference (opcodes, encryption, shuffling)
+tests/               # pytest test suite
 ```