Quokka

图像由 DALL-E 生成

---

目录

• 简介
• 安装
• 使用
• 构建
• 文档
• 常见问题

简介

Quokka 是一个二进制导出器：它从程序的反汇编结果生成一个导出文件，无需反汇编器即可使用。目前它支持 IDA Pro、Ghidra 和 Binary Ninja 作为反汇编后端。

Quokka 的主要目标是让用户能够在初始导出之后，无需再打开反汇编器即可完全操控二进制文件。此外，它抽象了反汇编器的 API，向用户提供简洁的接口。

Quokka 深受 BinExport 的启发，BinExport 是 BinDiff 所使用的二进制导出器。

架构

     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 中构建，并可在 registry 中获取。

应该可以通过以下命令直接从 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 中有详细说明。

注意：使用 idat 而非 ida 是为了提高导出速度，因为不需要图形界面。

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 界面内使用导出命令。

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

更多详情请参阅 BinaryNinja 扩展 README。

通过 CLI 导出

Quokka 提供了一个 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：选择导出模式（light 或 full）
• --decompiled：启用反编译代码导出（仅限 IDA）
• -v, --verbose：启用详细日志记录

加载导出文件

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 版本。这两种模式也被称为新模式和旧模式。

IDA >= 9.2（新方式）

Ida SDK 终于开源了，因此不再需要单独下载它。

您可以使用 cmake 选项 -DIDA_VERSION=<major>.<minor> 从 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/

关于构建的更详细信息，请参阅 构建。

文档

文档可在 文档 在线获取。

常见问题

您可以在此查看问题列表：FAQ。

导出模式

注意： 目前仅实现了 LIGHT 模式。FULL（自包含）模式已规划但尚未可用。

Quokka 提供两种导出反汇编分析结果的模式：轻量模式和自包含模式。

轻量模式专注于仅导出必要信息，生成快速且轻量的文件。在该模式下，不会导出指令级或更细粒度的信息，因此在运行时将使用 capstone 引擎来获取指令的反汇编结果。

自包含模式则导出完整的反汇编结果，与后端反汇编器显示的内容完全一致。这会产生更大的文件，但在运行时无需依赖第三方反汇编器。

需要注意的是，两种模式在 Python 绑定中提供相同的 API。

[!WARNING] 在自包含模式下仍然可以获得 capstone 指令对象， 但请注意，capstone 的反汇编结果可能与 quokka 导出的结果不同 （指令可能被拆分、合并、不受支持，或具有不同的助记符等）。 一般来说，不同的二进制分析平台会产生不同的反汇编结果，在将 capstone 与自包含模式混合使用时请牢记这一点。

要全面了解两种模式之间的差异，请看下表：

	轻量模式	自包含模式
函数	✅	✅
基本块	✅	✅
指令	❌	✅
操作数	❌	✅
数据引用	✅	✅
交叉引用	✅	✅
节/布局	✅	✅
反编译	✅¹	✅¹
CFG 绘制坐标	✅¹²	✅¹²

^{¹ 可选启用}

^{² 目前不支持}