Quokka

画像は DALL-E によって生成されました

目次

• はじめに
• インストール
• 使い方
• ビルド
• ドキュメント
• FAQ

はじめに

Quokka はバイナリエクスポーターです。プログラムの逆アセンブル結果から、逆アセンブラなしで使用できるエクスポートファイルを生成します。現在は逆アセンブリバックエンドとして IDA Pro、Ghidra、Binary Ninja をサポートしています。

Quokka の主な目的は、最初のエクスポート後に逆アセンブラを開くことなく、バイナリを完全に操作できるようにすることです。さらに、逆アセンブラの API を抽象化し、ユーザーにクリーンなインターフェースを提供します。

Quokka は、BinDiff が使用するバイナリエクスポーターである BinExport から大きな影響を受けています。

アーキテクチャ

     IDA Pro               Ghidra               Binary Ninja
        │                      │                      │
IDA Plugin (C++)    Ghidra Plugin (Java)   BinaryNinja Plugin (Python)
        │                      │                      │
        └────────────── quokka.proto ─────────────────┘
                     (protobuf schema)
                              │
                        .quokka files
                              │
              Python bindings (quokka.Program)
              ├── Capstone backend (primary)
              └── Pypcode backend (optional)

インストール

Python プラグイン

このプラグインは CI でビルドされ、レジストリ で入手できます。

次のようなコマンドで PIP から直接インストールできるはずです:

$ pip install quokka-project

IDA プラグイン

注: Quokka が生成したファイルを読むために IDA プラグインは必要ありません。これはファイルを生成するためだけに使用されます。

Quokka は IDA 9.1+ と互換性があります。

IDA プラグインマネージャ経由 (IDA 9.2+)

Quokka は Hex-Rays プラグインリポジトリに公開されており、hcli でインストールできます:

user@host:~$ hcli plugin install quokka

手動インストール

プラグインは CI でもビルドされ、Releases タブで入手できます。

プラグインをダウンロードするには、quokka_plugin.so という名前のファイル（またはお使いの IDA バージョン用の quokka-ida<version>.zip アーカイブ）を取得し、IDA の plugins ディレクトリにコピーしてください。

Ghidra 拡張機能

Quokka は、専用の拡張機能を介した Ghidra (>= 12.0.3) からのエクスポートもサポートしています。Python ライブラリが読み込めるのと同じ .quokka protobuf ファイルを生成します。

ビルド手順、インストール、使用方法の詳細については、Ghidra 拡張機能 README を参照してください。

BinaryNinja 拡張機能

Quokka は、Python プラグインを介した Binary Ninja からのエクスポートもサポートしています。Python ライブラリが読み込めるのと同じ .quokka protobuf ファイルを生成します。

インストールと使用方法の詳細については、BinaryNinja 拡張機能 README を参照してください。

使い方

GUI でのエクスポート

バイナリを手動でエクスポートする最初の方法は、IDA Pro 内でプラグインを使用することです。IDA 内のデフォルトのショートカットは Alt+A です。次のダイアログが開きます:

利用可能なモードは次のとおりです:

• LIGHT: ブロックレベルのデータのみをエクスポートします (命令は元のバイナリのバイトから実行時に Capstone によってデコードされます)
• FULL: 命令とオペランドをエクスポートします (自己完結モード。逆アセンブルに元のバイナリを必要としません)

注: FULL モードはまだ実装されていません。現在機能しているのは LIGHT モードのみです。

ヘッドレスでのエクスポート

IDA

注: これには動作する IDA のインストールが必要です。

$ idat -OQuokkaAuto:true -OQuokkaDecompiled:true -A /path/to/hello.i64

利用可能なすべてのオプションは、Usage に記載されています。

注: グラフィカルインターフェースが不要なため、エクスポート速度を上げるために ida の代わりに idat が使用されます。

Ghidra

$ analyzeHeadless /tmp/proj Test \
    -import /path/to/binary \
    -scriptPath ghidra_extension/src/script/ghidra_scripts \
    -postScript QuokkaExportHeadless.java \
    --out=/path/to/output.quokka --mode=LIGHT

詳細については、Ghidra 拡張機能 README を参照してください。

Binary Ninja

注: Binary Ninja API のヘッドレス使用には商用ライセンスが必要です。ライセンスがない場合は、Binary Ninja UI 内でエクスポートコマンドを使用してください。

$ python binaryninja_extension/export_headless.py /path/to/binary \
    -o /path/to/output.quokka --mode LIGHT

詳細については、BinaryNinja 拡張機能 README を参照してください。

CLI でのエクスポート

Quokka は、1つ以上のファイルやディレクトリ（各ディレクトリ内のすべての実行可能ファイル）を並列で自動エクスポートする CLI ユーティリティツールを提供します。IDA Pro と Ghidra の両方のバックエンドをサポートしています:

$ quokka-cli --backend ghidra -t 8 dir/
$ quokka-cli --backend ida --ida-path /opt/ida -t 8 dir/
$ quokka-cli -t 8 dir/                          # auto-detect backend
$ quokka-cli -o "%p/exports/%f.quokka" binary   # custom output directory
$ quokka-cli -b ida -o %F_ida.quokka -t 4 dir/  # Using relative path
$ quokka-cli -t 8 dir1/ dir2/ binary1 binary2   # multiple inputs

デフォルトでは、.quokka ファイルは入力バイナリの隣に配置されます（例: /usr/bin/ls は /usr/bin/ls.quokka を生成します）。-o を使用すると、リテラルパスまたはファイルごとに展開されるテンプレートでこれを上書きできます（%f = ファイル名の部分、%F = ファイル名、%p = 親ディレクトリ、%P = フルパス、%e = 拡張子、%% = リテラル %）。

すべてのオプションについては quokka-cli --help を実行してください。主なフラグは次のとおりです:

• -b, --backend: 逆アセンブラバックエンドを選択します (ida、ghidra、または auto)
• -i, --ida-path: IDA インストールディレクトリへのパスを指定します (idat を含むフォルダ)
• --ghidra-path: Ghidra インストールディレクトリを指定します (GHIDRA_INSTALL_DIR を上書き)
• -o, --output: 出力パスまたはテンプレートを設定します (デフォルト: %F.quokka)
• -m, --mode: エクスポートモードを選択します ( または )

エクスポートファイルの読み込み

import quokka
from quokka.types import Disassembler

# Directly from the binary (auto-detects available backend)
prog = quokka.Program.from_binary("/bin/ls")

# Explicitly choose a backend
prog = quokka.Program.from_binary("/bin/ls", disassembler=Disassembler.GHIDRA)
prog = quokka.Program.from_binary("/bin/ls", disassembler=Disassembler.IDA)

# From the exported file
prog = quokka.Program("ls.quokka",  # the exported file
                      "/bin/ls")    # the original binary

型の編集と追加

# Add new types from C declarations
prog.add_type("struct context { int id; char name[64]; };")
prog.add_type("enum status { OK=0, ERROR=1 };")

# Save the .quokka file
prog.write()

# Or apply changes (including new types) back to the IDA database
prog.commit(database_file="ls.i64", overwrite=True)

関数の名前変更、プロトタイプの設定などの詳細については、完全な 編集ドキュメント を参照してください。

ビルド

ビルドのプロセスは、使用している IDA SDK のバージョンによって異なります。これらの2つのモードは、新しいモード と 古いモード とも呼ばれます。

IDA >= 9.2 (新しい方法)

IDA SDK がついにオープンソース化されたため、個別にダウンロードする必要はなくなりました。

-DIDA_VERSION=<major>.<minor> という cmake オプションを使用すると、github から自動的に同期できます。

user@host:~/quokka$ cmake -B build \ # Where to build
                          -S . \ # Where are the sources
                          -DIDA_VERSION=9.2 \ # IDA SDK version
                          -DCMAKE_BUILD_TYPE:STRING=Release \ # Build Type

user@host:~/quokka$ cmake --build build -- -j

IDA < 9.2 (古い方法)

IDA SDK はまだプロプライエタリなコードであるため、自分で取得し、-DIdaSdk_ROOT_DIR:STRING=path/to/sdk オプションで cmake にそのパスを指定する必要があります。

注: これは新しいバージョンでも機能しますが、ユーザーが自分で SDK をダウンロードする必要があるため、より多くの手順が必要です。

user@host:~/quokka$ cmake -B build \ # Where to build
                          -S . \ # Where are the sources
                          -DIdaSdk_ROOT_DIR:STRING=path/to/ida_sdk \ # Path to IDA SDK 
                          -DCMAKE_BUILD_TYPE:STRING=Release \ # Build Type

user@host:~/quokka$ cmake --build build --target quokka_plugin -- -j

インストール

プラグインをインストールするには:

user@host:~/quokka$ cmake --install build

いずれの場合も、プラグインは build/quokka-install にあります。それを IDA のユーザープラグインディレクトリにコピーできます。

user@host:~/quokka$ cp build/quokka-install/quokka_plugin.so $HOME/.idapro/plugins/

ビルドの詳細については、Building を参照してください。

ドキュメント

ドキュメントは documentation でオンライン公開されています。

FAQ

よくある質問の一覧はこちら FAQ で確認できます。

エクスポートモード

注: 現在実装されているのは LIGHT モードのみです。FULL (自己完結) モードは計画されていますが、まだ機能していません。

Quokka は、逆アセンブリ解析をエクスポートするための2つのモードを提供します: ライトモード と 自己完結モード です。

ライトモード は、必須情報のみをエクスポートすることに重点を置き、高速で軽量なファイルを生成します。このモードでは、命令レベル以下の情報はエクスポートされないため、命令の逆アセンブリを取得するために実行時に capstone エンジンが使用されます。

一方、自己完結モード は、バックエンドの逆アセンブラが表示するのとまったく同じ完全な逆アセンブリをエクスポートします。これによりファイルサイズは大きくなりますが、実行時にサードパーティの逆アセンブラに依存する必要はありません。

両方のモードが Python バインディングで同じ API を提供することに注意することが重要です。

[!WARNING] 自己完結モード から capstone 命令オブジェクトを取得することは可能ですが、capstone の逆アセンブリは quokka がエクスポートしたものと異なる場合があることに注意してください（命令が分割、統合、未サポート、異なるニーモニックを持つなどがあるため）。 一般に、異なるバイナリ解析プラットフォームは異なる逆アセンブリを生成します。capstone と自己完結モードを併用するときは、この点に留意してください。

2つのモードの違いの完全な概要については、以下の表を参照してください:

^{¹ オプションで有効化}

^{² 現在は未サポート}