Skip to content

Quick Start

Get a Kagura-protected binary in under five minutes.

1. Get the plugin

Pre-built plugin binaries are published per release on the GitHub Releases page.

kagura-<version>-macos-arm64-llvm21.tar.gz
kagura-<version>-macos-arm64-llvm22.tar.gz
kagura-<version>-linux-x86_64-llvm19.tar.gz
kagura-<version>-linux-x86_64-llvm21.tar.gz
kagura-<version>-linux-x86_64-llvm22.tar.gz

Each archive contains:

  • plugin/KaguraObfuscator.{dylib,so}
  • runtime/libkagura_runtime.a
  • include/kagura/*.h

See Build from Source.

2. Obfuscate a single file

clang -fpass-plugin=path/to/KaguraObfuscator.dylib \
      -mllvm -kagura-str \
      -mllvm -kagura-fla \
      -mllvm -kagura-bcf \
      -mllvm -kagura-bcf-prob=50 \
      -O1 your_file.c -o your_file

For real projects, use a single JSON file to control every pass.

kagura.json
{
  "profile": "BALANCED",
  "passes": {
    "str":   true,
    "fla":   true,
    "bcf":   true,
    "honey": true,
    "mvo":   false
  },
  "tuning": {
    "bcf_prob": 40,
    "seed":     12345
  }
}

clang -fpass-plugin=path/to/KaguraObfuscator.dylib \
      -mllvm -kagura-config=kagura.json \
      -O1 your_file.c -o your_file

See Configuration for the full DSL.

4. IR-level use with opt

clang -O1 -emit-llvm -c your_file.c -o your_file.bc

opt --load-pass-plugin=path/to/KaguraObfuscator.dylib \
    -passes="kagura-str,function(kagura-fla,kagura-bcf,kagura-sub)" \
    your_file.bc -o your_file.opt.bc

clang your_file.opt.bc -o your_file

5. Per-function control

// Force-enable a pass for this function
__attribute__((annotate("kagura_fla")))
void critical_function(void) { /* ... */ }

// Force-disable a pass for this function
__attribute__((annotate("kagura_nofla")))
void performance_sensitive(void) { /* ... */ }

// Virtualize with the VM pass
__attribute__((annotate("kagura_vm")))
int verify_license(const char *key) { /* ... */ }

Some passes (str-aes, vm, anti-debug, tamper, pac, ci) require linking libkagura_runtime.a:

clang your_file.c path/to/libkagura_runtime.a -o your_file

See the Runtime Library page for the symbol matrix.

Next steps