Morok is a modular C++23 LLVM New-PM IR obfuscator. It loads as a pass plugin inside clang or opt, rewrites LLVM IR, and emits a behaviourally identical program with fewer static landmarks, more hostile control/data flow, and layered runtime self-protection.

The project is deliberately test-first. Pure arithmetic and encoding primitives live below LLVM and are exercised by exhaustive/property unit tests. The LLVM passes are tested as IR emitters and then as a whole pipeline by compiling and running real C/C++ programs clean vs obfuscated.

Morok can do things an LLVM pass can produce:

• Rewrite integer, floating, pointer, stack, PHI, branch, call, string, constant, vtable, and VM bytecode IR.
• Emit constructors, helper functions, helper threads, inline assembly, signal/exception handlers, direct syscalls, and platform-specific runtime probes into the target binary.
• Generate per-build and per-callsite diversity from a deterministic seed.
• Emit retained post-link manifests for later patchers where final native bytes are needed.

Morok cannot do things that require external infrastructure:

• It cannot sign Mach-O or PE files, provision entitlements, enable HVCI/PPL, or turn on compiler/linker features such as CFG/XFG/CET/PAC/BTI/RELRO.
• It cannot provide TPM/SGX/TrustZone/SEV/Secure-Enclave remote roots of trust.
• It cannot make a hostile kernel or hypervisor trustworthy. It raises cost and creates tamper-sensitive dependencies inside userland code.

The implementable protection backlog is tracked in docs/insurance-tasks.md. Algorithm and pass details live in docs/algorithms.md and docs/hardness.md.

Morok is layered so each level depends strictly downward:

morok::core       Pure algorithms: PRNGs, Feistel, GF(2^8), XOR sharing,
                  MBA/substitution identities, MQ/T-function/Knuth helpers.
                  No LLVM, no I/O.

morok::config     Presets, TOML loading, policy resolution, pass options.
                  No LLVM; demangling is injected.

morok::ir         LLVM helper layer: annotations, symbol cloaking, IR random
                  adapters, shared emit utilities.

morok::passes     New-PM pass implementations plus testable free functions.

libMorok          Loadable New-PM pass plugin and whole-pipeline scheduler.

Tracked top-level paths:

include/morok/{core,config,ir,passes,pipeline}/   public headers
src/{core,config,ir,passes,pipeline}/             implementations
tests/{unit,ir,e2e}/                              unit, IR, and e2e gates
programs/                                         local stress corpus, when present
third_party/{doctest,tomlplusplus}/               vendored header-only deps
cmake/Morok{LLVM,Test,Warnings}.cmake             build policy modules
docs/algorithms.md                                pass and scheduler reference
docs/hardness.md                                  primitive hardness notes
docs/insurance-tasks.md                           implementable protection checklist
cross_build.sh                                    Linux/macOS cross-build helper
run_tests.sh                                      authoritative local test entrypoint

• CMake 3.28 or newer.
• Ninja.
• A C++23 compiler.
• LLVM 18 or newer with the New-PM plugin API Morok targets.

This tree currently validates a forked/custom LLVM plugin API: <llvm/Plugins/PassPlugin.h> with LLVM_PLUGIN_API_VERSION == 2. The CMake probe in cmake/MorokLLVM.cmake fails loudly if the host LLVM cannot load the plugin ABI that Morok was compiled against.

Build:

cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DLLVM_DIR="$LLVM_PREFIX/lib/cmake/llvm"
cmake --build build
ctest --test-dir build -j

Useful CMake options:

MOROK_BUILD_TESTS=ON       build tests
MOROK_BUILD_PLUGIN=ON      build libMorok
MOROK_WERROR=OFF           treat warnings as errors when ON
MOROK_SANITIZE=OFF         ASan/UBSan for pure layers/tests when ON

Use the top-level script unless you are intentionally narrowing the loop:

./run_tests.sh            # incremental configure/build + entire ctest suite
./run_tests.sh --clean    # remove build/ and configure from scratch
./run_tests.sh -R passes  # ctest name regex
./run_tests.sh -L ir      # ctest label: core/config/ir/e2e/programs/max/unit/aggregate

The full gate covers:

On Apple hosts the e2e suite exercises the full high/max presets and VM-specific runtime gate. On non-Apple hosts, e2e uses the portable max configuration where backend/runtime porting is still incomplete; the IR tests still exercise the platform-specific emitters in-process.

Whole pipeline from clang:

clang -O2 -fpass-plugin=build/src/pipeline/libMorok.dylib \
  -mllvm -morok \
  -mllvm -morok-preset=high \
  -mllvm -morok-seed=1234 \
  prog.c -o prog

Whole pipeline from opt:

opt -load-pass-plugin build/src/pipeline/libMorok.dylib \
  -passes=morok prog.ll -o out.bc

One standalone pass:

opt -load-pass-plugin build/src/pipeline/libMorok.dylib \
  -passes=morok-strenc prog.ll -o out.bc

Configuration can be supplied by flag or environment:

clang -O2 -fpass-plugin=build/src/pipeline/libMorok.dylib \
  -mllvm -morok \
  -mllvm -morok-config=morok.toml \
  -mllvm -morok-seed=0xC0FFEE \
  prog.c -o prog

MOROK_CONFIG=morok.toml clang -O2 -fpass-plugin=... -mllvm -morok prog.c -o prog

Cross-build helper:

./cross_build.sh --source programs/cf_license_crackme.c --out-dir build/cross
./cross_build.sh --linux-only --source boo.c --out-dir build/cross
./cross_build.sh --macos-arches "arm64 x86_64" --preset max

For static Linux outputs, cross_build.sh derives a temporary config that disables function_call_obfuscate: a fully static binary has no dynamic loader, so a dlsym(RTLD_DEFAULT, ...) fallback cannot resolve imports at runtime and adds no useful hiding surface.

Config layering is intentionally simple:

1. [global].preset loads low, mid, high, or max.
2. [passes.*] sections override only fields they mention.
3. Ordered [[policy]] rules can apply another preset and/or pass overrides to matching module/function regexes.
4. -mllvm -morok-seed=N overrides the config seed for deterministic builds.

Example:

[global]
preset = "high"
seed = 0xDEADBEEF1337
demangle_names = true

[passes.string_encryption]
enabled = true
probability = 100
skip_content = ["Usage:"]

[passes.function_call_obfuscate]
enabled = true

[passes.windows_process_mitigations]
enabled = true

[[policy]]
function = "^main$"
passes.bcf.enabled = false
passes.substitution.enabled = false

[[policy]]
function = "license|verify|decrypt"
passes.mba.enabled = true
passes.external_opaque_predicates.enabled = true

Source annotations are copied from Clang's llvm.global.annotations into Morok metadata before scheduling:

__attribute__((annotate("sub")))    static int force_sub(int x) { return x + 1; }
__attribute__((annotate("nosub")))  static int skip_sub(int x)  { return x + 1; }
__attribute__((annotate("sensitive"))) static int hot_secret(int x) { return x * 7; }

Per-function annotation keys are the scheduler tags, such as sub, mba, split, bcf, optamp, threshold, aliasop, extop, decoy, nistate, entfla, csm, fla, stateop, ifsm, phitangle, typepun, stackcoalesce, stackdelta, ptrlaunder, dfi, tablearith, uniform, vobf, pathexplode, mq, tracekey, dispatchless, microstress, selfcheck, mutualguard, shamir, constenc, and indibran. Prefix any key with no to force it off for that function.

The scheduler enforces instruction, block, function, module, byte, table, route, callsite, clone, and payload caps. If a function or module grows beyond the budget, later growth passes are skipped rather than allowing exponential IR growth.

The whole-pipeline morok pass is ordered to preserve semantics and maximize composition:

VM(user code)
-> hash-gated VM self-decrypt
-> anti-hook / anti-class-dump / Windows substrate and Windows probes
-> anti-debug / timing / trap / page-fault / cache / microarchitectural probes
-> decoy strings
-> string encryption
-> function-call obfuscation
-> vtable integrity
-> per-function structural, scalar, CFG, data-flow, integrity, and literal passes
-> VM/hardening for generated protection helpers
-> nanomites
-> adversarial self-tuning / merge / function wrappers
-> per-build polymorphism
-> misleading metadata
-> generated-symbol privacy cleanup

The precise maintained order is documented in docs/algorithms.md.

Each pass can be run standalone with -passes=morok-* or through the scheduler with a TOML section. Some final hygiene transforms, such as misleading metadata and private-linkage cleanup for generated morok.* helpers, are scheduler-only.

String encryption intentionally excludes generated morok.decoy.str.* globals. Those decoys must remain visible to cheap triage tools such as strings; real user strings are encrypted, length-padded where safe, and materialized lazily.

The scheduler runs a second, restricted VM/hardening stage over allowlisted generated protection helpers so anti-debug, anti-hook, decryptor, and integrity logic is not left as a simple native plaintext island.

The Windows passes are opt-in module passes. They share the Windows PE foundation helpers instead of hardcoding duplicate offsets or import paths.

• Linux x86_64: Morok uses inline syscall for sensitive anti-debug/anti-hook operations where syscall numbers/layouts are known. Static Linux cross-builds disable FCO automatically unless you provide an explicit config that says otherwise.
• macOS x86_64/arm64: anti-debugging uses Darwin syscalls or Mach APIs as appropriate; FCO's 64-bit macOS path parses Mach-O exports by hash and avoids plaintext dlsym for supported symbols.
• Windows x86_64: Windows-specific passes emit PE/PEB/TEB/export/syscall/VEH helpers into Windows-targeted IR. Behavioural e2e plugin loading is skipped on Windows hosts; coverage comes from core/config/IR tests and targeted object smokes.
• Unsupported triples keep conservative fallbacks or no-op for passes that need platform-specific context layouts.

The current string/import strategy is designed against simple static decoders:

• Real private byte-array strings do not share a global decryptor. Safe C-string uses get per-use stack materialization; unsupported uses get one private constructor per string.
• Each string has independent key material, keystream variant, ADD/XOR combine, and odd multiplier, all perturbed through volatile runtime state.
• Linux/macOS FCO does not need to emit symbol names for supported 64-bit targets; it carries hashes and resolves exports manually.
• Per-callsite cached function pointers are encoded with volatile seed/key material and exist as raw pointers only immediately before the indirect call.
• Decoy strings are retained and plaintext by design, so strings should find bait while real user strings remain hidden.

For a narrow pass edit, use the smallest focused tests first:

cmake --build build --target morok_ir_tests morok_config_tests morok_plugin
./build/tests/ir/morok_ir_tests
./build/tests/unit/config/morok_config_tests

Before merging or pushing a completed feature, run:

./run_tests.sh
git diff --check

When touching platform runtime emitters, add a targeted object/binary smoke that proves the relevant names are absent from strings and that the emitted object contains the expected constructor/helper shape.

MIT. See LICENSE.