# m3rcer/irvana architecture

> Architecture diagram of the GitHub repository m3rcer/irvana, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m3rcer/irvana
- Repository: https://github.com/m3rcer/irvana

## Overview

##### Project Type and Purpose
- IRvana is a command‐line, multi‐module framework for automating cross‐language LLVM IR generation, applying OLLVM obfuscation, and running IR in memory via various JIT interpreters.
- Primary use cases:
- IR generation pipelines for C, C++, Rust, and Nim
- IR obfuscation via OLLVM passes
- In‐memory IR execution (lli, MCJIT, ORCJIT)
- Malware development POCs (encrypted IR payload, remote IR staging)

##### High‐Level Architecture Layers
A. Environment & Toolchain Layer (Bottom)
- Windows SDK & MSVC runtime (detected by detect_sdk.bat → vs_env.mk)
- LLVM‐18.1.5 distribution (clang, clang++, llvm‐link, opt, lli, etc.)
- Nim 1.6.6 standalone compiler
- Rust nightly‐2024‐06‐26 toolchain
- Build tools: GNU Make, CMake, Visual Studio
B. IR Generation Layer
- IRgen orchestrator (IRvana.cpp / IRvana.sln)
- Per‐language modules under IRgen/ (c, cxx, nim, rust) each with:
– detect_sdk.bat & vs_env.mk → environment config
– Makefile.ir.mk → invokes frontend compiler (clang/clang‐cl, rustc, nim)
– src/ → user source
– ir_bin/ → outputs (*.ll or *.bc)
C. IR Transformation & Obfuscation Layer
- LLVM‐link & opt to combine IR modules
- OLLVM plugin (OLLVM/ollvm-pass) loaded by opt:
– Control‐flow flattening, string encryption, indirect branch/call, etc.
- Final IR output (final-obf.ll or final-obf.bc)
D. Execution & Interpreter Layer (Top)
- Built‐in interpreter: `lli` (LLVM toolchain)
- Custom C++ interpreters:
– MCJIT (Interpreters/cxx - MCJIT)
– ORCJIT (Interpreters/cxx - ORC JIT)
- Rust interpreter (Interpreters/Rust - MCJIT via Inkwell)
- Maldev POCs:
– IREncryption (AES decrypt IR in memory)
– RemoteLoad (HTTP‐fetch obfuscated IR, decrypt, JIT‐execute)

##### Data Flow & Component Interactions
1. User writes source in IRgen/*/src
2. `IRvana.exe` (or Makefile) triggers detect_sdk.bat → populates vs_env.mk
3. Makefile.ir.mk calls compiler with flags:
clang/clang‐cl -S -emit-llvm → .ll
rustc --emit=llvm-ir → .ll
nim c --cc:clang --opt:size → .ll
4. LLVM‐link merges per‐file IR → single IR module
5. opt loads OLLVM DLL → applies obfuscation passes
6. opt outputs final-obf.ll (text) or bitcode
7. Final IR can be:
- Saved to disk (ir_bin)
- Piped to `lli` for immediate execution
- Loaded by custom MCJIT/ORCJIT interpreters
- Embedded in Maldev executables (encrypted or remote)
8. In Maldev/RemoteLoad, HTTP client fetches encrypted IR → decrypt → feed to MCJIT/ORCJIT

##### Architectural Patterns & Principles
- Layered pipeline: clear separation of concerns (environment setup → IRgen → IR transform → execution)
- Plugin architecture: OLLVM as a dynamically‐loaded opt pass
- Cross‐language polymorphism: unified IR output consumed by same tool/exec layers
- Extensible modules: per‐language IRgen and interpreter backends as interchangeable components
- Reuse of open‐source tooling (LLVM, Make, CMake, rustc, nim)

##### In‐Depth IR Generation Details
- detect_sdk.bat → reads Windows SDK & MSVC paths → writes vs_env.mk
- Makefile.ir.mk invokes:
clang-cl –nologo –O2 –emit-llvm –S –o $(IR_BIN)/final.ll $(SRC)
- llvm-link $(IR_BIN)/*.bc –o merged.bc
- opt -load DLL -flatten -indirect-branch … –o final-obf.ll
- Optionally call llc to compile to native code or feed to JIT APIs
- For Rust, specify `cargo +nightly llvm-ir` or `rustc --emit=llvm-bc`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment & Toolchain Layer
    subgraph "Environment & Toolchain Layer"
        direction TB
        SDK["Windows SDK & MSVC runtime"]:::toolchain
        LLVM["LLVM 18.1.5"]:::toolchain
        NimComp["Nim 1.6.6"]:::toolchain
        RustTC["Rust nightly-2024-06-26"]:::toolchain
        BuildTools["GNU Make / CMake / VS"]:::toolchain
    end

    %% IR Generation Layer
    subgraph "IR Generation Layer"
        direction TB
        Orchestrator["IRvana Orchestrator\n(IRvana.cpp / .sln / .vcxproj)"]:::irgen
        subgraph "C Module"
            direction TB
            C_Detect["detect_sdk.bat"]:::irgen
            C_Env["vs_env.mk"]:::data
            C_Make["Makefile.ir.mk"]:::irgen
            C_Src["src/"]:::irgen
        end
        subgraph "C++ Module"
            direction TB
            CXX_Detect["detect_sdk.bat"]:::irgen
            CXX_Env["vs_env.mk"]:::data
            CXX_Make["Makefile.ir.mk"]:::irgen
            CXX_Src["src/"]:::irgen
        end
        subgraph "Nim Module"
            direction TB
            Nim_Detect["detect_sdk.bat"]:::irgen
            Nim_Env["vs_env.mk"]:::data
            Nim_Make["Makefile.ir.mk"]:::irgen
            Nim_Src["src/"]:::irgen
        end
        subgraph "Rust Module"
            direction TB
            Rust_Detect["detect_sdk.bat"]:::irgen
            Rust_Env["vs_env.mk"]:::data
            Rust_Cargo["Cargo.toml"]:::irgen
            Rust_Make["Makefile.ir.mk"]:::irgen
            Rust_Src["src/"]:::irgen
        end
    end

    %% IR Transformation & Obfuscation Layer
    subgraph "IR Transformation & Obfuscation Layer"
        direction TB
        Linker["llvm-link"]:::transform
        Opt["opt\n--load OLLVM"]:::transform
        OLLVMPlugin["OLLVM Plugin\n(obfuscation passes)"]:::transform
        FinalIR["final-obf.ll / .bc"]:::data
    end

    %% Execution & Interpreter Layer
    subgraph "Execution & Interpreter Layer"
        direction TB
        LLI["lli"]:::interp
        MCJIT_CXX["C++ MCJIT"]:::interp
        ORCJIT_CXX["C++ ORC JIT"]:::interp
        MCJIT_Rust["Rust MCJIT\n(via Inkwell)"]:::interp
        subgraph "Maldev POCs"
            direction TB
            IREncrypt["IREncryption"]:::maldev
            RemoteLoad["RemoteLoad"]:::maldev
            HTTP["HTTP Server"]:::maldev
        end
    end

    %% Flows
    SDK -->|setup via detect_sdk.bat| C_Detect
    SDK -->|setup via detect_sdk.bat| CXX_Detect
    SDK -->|setup via detect_sdk.bat| Nim_Detect
    SDK -->|setup via detect_sdk.bat| Rust_Detect
    C_Detect -->|writes| C_Env
    CXX_Detect -->|writes| CXX_Env
    Nim_Detect -->|writes| Nim_Env
    Rust_Detect -->|writes| Rust_Env

    Orchestrator --> C_Make
    Orchestrator --> CXX_Make
    Orchestrator --> Nim_Make
    Orchestrator --> Rust_Make

    C_Make -->|emit-llvm| C_Src
    CXX_Make -->|emit-llvm| CXX_Src
    Nim_Make -->|emit-llvm| Nim_Src
    Rust_Make -->|emit-llvm| Rust_Src

    C_Src -->|.ll/.bc| Linker
    CXX_Src -->|.ll/.bc| Linker
    Nim_Src -->|.ll/.bc| Linker
    Rust_Src -->|.ll/.bc| Linker

    Linker -->|merged.bc| Opt
    Opt -->|opt --load| OLLVMPlugin
    OLLVMPlugin -->|obfuscated IR| FinalIR

    FinalIR -->|pipe| LLI
    FinalIR -->|JIT API| MCJIT_CXX
    FinalIR -->|JIT API| ORCJIT_CXX
    FinalIR -->|JIT API| MCJIT_Rust

    FinalIR -->|encrypt & embed| IREncrypt
    HTTP -->|fetch| RemoteLoad
    RemoteLoad -->|decrypt| FinalIR
    RemoteLoad -->|JIT| MCJIT_CXX

    %% Click Events
    click Orchestrator "https://github.com/m3rcer/irvana/blob/main/IRvana.cpp"
    click Orchestrator "https://github.com/m3rcer/irvana/blob/main/IRvana.sln"
    click Orchestrator "https://github.com/m3rcer/irvana/blob/main/IRvana.vcxproj"
    click C_Make "https://github.com/m3rcer/irvana/blob/main/IRgen/c/Makefile.ir.mk"
    click C_Detect "https://github.com/m3rcer/irvana/blob/main/IRgen/c/detect_sdk.bat"
    click C_Src "https://github.com/m3rcer/irvana/tree/main/IRgen/c/src/"
    click CXX_Make "https://github.com/m3rcer/irvana/blob/main/IRgen/cxx/Makefile.ir.mk"
    click CXX_Detect "https://github.com/m3rcer/irvana/blob/main/IRgen/cxx/detect_sdk.bat"
    click CXX_Src "https://github.com/m3rcer/irvana/tree/main/IRgen/cxx/src/"
    click Nim_Make "https://github.com/m3rcer/irvana/blob/main/IRgen/nim/Makefile.ir.mk"
    click Nim_Detect "https://github.com/m3rcer/irvana/blob/main/IRgen/nim/detect_sdk.bat"
    click Nim_Src "https://github.com/m3rcer/irvana/tree/main/IRgen/nim/src/"
    click Rust_Make "https://github.com/m3rcer/irvana/blob/main/IRgen/rust/Makefile.ir.mk"
    click Rust_Detect "https://github.com/m3rcer/irvana/blob/main/IRgen/rust/detect_sdk.bat"
    click Rust_Cargo "https://github.com/m3rcer/irvana/blob/main/IRgen/rust/Cargo.toml"
    click Rust_Src "https://github.com/m3rcer/irvana/tree/main/IRgen/rust/src/"
    click OLLVMPlugin "https://github.com/m3rcer/irvana/blob/main/OLLLVM/ollvm-pass/CMakeLists.txt"
    click OLLVMPlugin "https://github.com/m3rcer/irvana/tree/main/OLLLVM/ollvm-pass/obfuscation/"
    click LLI "https://github.com/m3rcer/irvana/blob/main/Interpreters/lli - ORC JIT/lli.cpp"
    click LLI "https://github.com/m3rcer/irvana/blob/main/Interpreters/lli - ORC JIT/CMakeLists.txt"
    click MCJIT_CXX "https://github.com/m3rcer/irvana/blob/main/Interpreters/cxx - MCJIT/main.cpp"
    click MCJIT_CXX "https://github.com/m3rcer/irvana/blob/main/Interpreters/cxx - MCJIT/CMakeLists.txt"
    click ORCJIT_CXX "https://github.com/m3rcer/irvana/blob/main/Interpreters/cxx - ORC JIT/main.cpp"
    click ORCJIT_CXX "https://github.com/m3rcer/irvana/blob/main/Interpreters/cxx - ORC JIT/CMakeLists.txt"
    click MCJIT_Rust "https://github.com/m3rcer/irvana/blob/main/Interpreters/Rust - MCJIT/src/main.rs"
    click MCJIT_Rust "https://github.com/m3rcer/irvana/blob/main/Interpreters/Rust - MCJIT/Cargo.toml"
    click IREncrypt "https://github.com/m3rcer/irvana/blob/main/Maldev/IREncryption/main.cpp"
    click IREncrypt "https://github.com/m3rcer/irvana/blob/main/Maldev/IREncryption/encryptIR.py"
    click IREncrypt "https://github.com/m3rcer/irvana/blob/main/Maldev/IREncryption/CMakeLists.txt"
    click RemoteLoad "https://github.com/m3rcer/irvana/blob/main/Maldev/RemoteLoad/main.cpp"
    click RemoteLoad "https://github.com/m3rcer/irvana/blob/main/Maldev/RemoteLoad/CMakeLists.txt"

    %% Styles
    classDef toolchain fill:#D0E6FF,stroke:#0366d6,stroke-width:1px
    classDef irgen fill:#D6F5D6,stroke:#2e8b57,stroke-width:1px
    classDef transform fill:#FFE5B4,stroke:#f28c00,stroke-width:1px
    classDef interp fill:#E0BBE4,stroke:#9b59b6,stroke-width:1px
    classDef maldev fill:#F5B7B1,stroke:#c0392b,stroke-width:1px
    classDef data fill:#FFFFFF,stroke:#999,stroke-dasharray: 2 2,stroke-width:1px
```
