Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
51 lines (37 loc) · 4.72 KB

ARCHITECTURE.md

File metadata and controls

51 lines (37 loc) · 4.72 KB
Raw

LLVM Binary Obfuscator: Architecture Overview

This document distills the large set of historical design notes into a single, contributor‑friendly reference. It focuses on the current, production ready toolchain that powers the CLI and API entry points in cmd/llvm-obfuscator.

Layered Defense Model

Layer Purpose Implemented By
0. Compiler Hardening Aggressive clang/lld flags (-flto, -fvisibility=hidden, speculative hardening, etc.) core/obfuscator.py (shared base flags)
1. Symbol Obfuscation Cryptographic renaming of exported symbols (SHA256/BLAKE2b) MLIR pass, symbol map utilities, bundled plugins
2. String & Constant Protection XOR string encryption, fake loops, numeric constant rewriting MLIR passes (string-encrypt, constant-obfuscate) + Python helpers
3. Control Flow Obfuscation OLLVM/Linear-MBA/anti-debug transforms Bundled LLVM plugins + runtime helpers
4. Packing (Optional) UPX compression to shrink and further obfuscate binaries core/upx_packer.py

Each layer is orchestrated by the CLI (cli/obfuscate.py) and API server (api/server.py). Users can toggle layers through CLI flags or API payloads; the orchestrator stitches together compiler invocations, plugin loading, MLIR passes, UPX packing, and report generation.

Major Components

  • CLI / API – Front-ends located in cmd/llvm-obfuscator/cli and cmd/llvm-obfuscator/api. They share the same core/ engine and expose identical options (CLI via Typer, API via FastAPI + WebSocket progress updates).
  • Core Orchestrator – core/obfuscator.py coordinates compilation, pass selection, metrics collection, and reporting. It also wires in helpers for fake loops, indirect call obfuscation, entropy calculations, remarks parsing, and UPX packaging.
  • MLIR Library (mlir-obs/) – C++ pass plugin that implements string-encrypt, symbol-obfuscate, constant-obfuscate, and crypto-hash. The CLI loads the shared object/dylib/dll dynamically and injects the passes with -mllvm flags.
  • Bundled LLVM Plugins (cmd/llvm-obfuscator/plugins/) – Prebuilt OLLVM style passes (flattening, bogus control flow, substitution, linear‑MBA). Platform specific bundles ship for macOS/Linux and can be swapped out for custom builds.
  • Phoronix + Metrics (cmd/llvm-obfuscator/phoronix/) – Self‑contained harness for running the Phoronix Test Suite on baseline vs. obfuscated binaries. Metrics are consumed by core/report_converter.py to compute the “overall protection index”.
  • Advanced Pipelines (binary_obfuscation_pipeline/) – Experimental Windows + McSema lifting workflow. It comprises multiple Docker services (MinGW builder, headless Ghidra lifter, McSema converter, OLLVM stage) but is fully optional for typical contributors.

Directory Map for Contributors

  • cmd/llvm-obfuscator/core/ – Python orchestration logic. Start here when fixing pass scheduling, reporting, configuration, or metrics.
  • cmd/llvm-obfuscator/modules/ – Optional subsystems (VM transforms, MBA helpers, etc.).
  • mlir-obs/ – MLIR pass source plus helper scripts for building/testing locally.
  • binary_obfuscation_pipeline/ – Research sandbox for the Windows lifting flow (see docs/PIPELINES.md).
  • obfuscation_test_suite/ – Python framework that powers the “security analysis” section of reports.
  • phoronix/ – CI harness and documentation for running heavy benchmarks and collecting metrics.

Reports & Metrics

Reports are plain JSON + Markdown generated by core/reporter.py and core/report_converter.py. They capture:

  1. Compilation metadata (flags, passes, versions).
  2. Symbol & function reductions, entropy shifts, string analysis, and binary size changes.
  3. Optional Phoronix results (performance overhead, instruction counts).
  4. Optional Jotai benchmark coverage and notes on skipped cases.

Use python -m cmd.llvm-obfuscator.cli.obfuscate analyze <binary> to create a standalone report, or python -m cmd.llvm-obfuscator.cli.obfuscate compile ... --report-formats json,md to bundle metrics with the obfuscated binary.

Keeping Architecture Healthy

  • Prefer extending core/config.py to add new flags so both CLI and API inherit the behavior automatically.
  • If you need additional MLIR or LLVM passes, keep the pass registration logic in mlir-obs/include/Obfuscator/Passes.h and document the CLI flag mapping in core/config.py.
  • When touching bundled plugins, update cmd/llvm-obfuscator/plugins/README (future work) and regenerate checksums so release automation can detect drift.
  • Every new feature should flow through the reporting pipeline—expose metrics via core/report_converter.py so users can validate the protection delta.