クイックスタート¶

5分以内に Kagura で保護されたバイナリを作ります。

1. プラグインを入手¶

プリビルトリリースソースからビルド

プラグインのバイナリはリリースごとに GitHub Releases で配布しています。

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

各アーカイブの中身:

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

ソースからビルドを参照。

2. 単一ファイルを難読化¶

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

3. 推奨: JSON 設定を使う¶

実プロジェクトでは、すべてのパス設定を1つの JSON ファイルにまとめます。

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

DSL の全仕様は設定を参照。

4. `opt` を使った IR レベル運用¶

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. 関数単位の制御¶

// この関数にだけ強制的にパスを適用
__attribute__((annotate("kagura_fla")))
void critical_function(void) { /* ... */ }

// この関数だけパスを無効化
__attribute__((annotate("kagura_nofla")))
void performance_sensitive(void) { /* ... */ }

// VM パスで仮想化
__attribute__((annotate("kagura_vm")))
int verify_license(const char *key) { /* ... */ }

6. ランタイムをリンク (必要なら)¶

一部のパス (str-aes, vm, anti-debug, tamper, pac, ci) は libkagura_runtime.a のリンクが必要です:

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

シンボル対応表はランタイムライブラリを参照。