Quokka

image generated by DALL-E

---

Table of Contents

• Introduction
• Installation
• Usage
• Building
• Documentation
• FAQ

Introduction

Quokka is a binary exporter: from the disassembly of a program, it generates an export file that can be used without the disassembler. It currently supports IDA Pro and Ghidra as disassembly backends.

The main objective of Quokka is to enable to completely manipulate the binary without ever opening a disassembler after the initial export. Moreover, it abstracts the disassembler's API to expose a clean interface to the users.

Quokka is heavily inspired by BinExport, the binary exporter used by BinDiff.

Architecture

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

Installation

Python plugin

The plugin is built in the CI and available in the registry.

It should be possible to install directly from PIP using this kind of commmand:

$ pip install quokka-project

IDA Plugin

Note: The IDA plugin is not needed to read a Quokka generated file. It is only used to generate them.

Quokka is currently compatible with IDA 7.3+

The plugin is built on the CI and available in the Release tab.

To download the plugin, get the file named quokka_plugin**.so.

Ghidra Extension

Quokka also supports exporting from Ghidra (>= 12.0.3) via a dedicated extension. It produces the same .quokka protobuf files that the Python library can load.

For build instructions, installation, and usage details see the Ghidra extension README.

Usage

Exporting via GUI

The first manual way to export a binary is to use the plugin inside IDA Pro. The default shortcut inside IDA is Alt+A. It opens the following dialog:

Modes available are:

• LIGHT: Exports data up to basic blocks start/stop (instructions are disassembled by bindings)
• NORMAL: Exports data and instructions address (instruction content and operands are retrieved by bindings)
• FULL: Exports data, instructions and operands (self-contained mode, do not require disassembling in binding)

Exporting in headless

IDA

!!! note

This requires a working IDA installation.

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

All available options are described in the Usage.

Note: idat is used instead of ida to increase the export speed as graphical interface is not needed.

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

See the Ghidra extension README for more details.

Exporting in CLI

Quokka provides a CLI utility tool to automatically export a single file or all executable files of a given directory in parallel. An example to automate the export using 8 threads:

$ quokka-cli -t 8 dir/

It also accepts various arguments:

• --ida-path to provide the path to IDA Pro (directory or binary)
• --decompiled to enable decompiled code export
• --verbose to enable verbose logging

Loading an export file

import quokka

# Directly from the binary (requires the IDA plugin to be installed)
ls = quokka.Program.from_binary("/bin/ls")

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

Building

The process for building depends on which version of the IDA SDK you are using. These two modes are also referred as the new mode and the old mode.

IDA < 9.2 (The old way)

Since the IDA SDK is still proprietary code, you have to fetch it yourself and provide its path to cmake through the option -DIdaSdk_ROOT_DIR:STRING=path/to/sdk

NOTE: This will also work on newer versions but it requires more steps from the users as they will have to download the sdk themselves.

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

IDA >= 9.2 (The new way)

Ida SDK has been finally open sourced so there is no need anymore to download it separately.

You can use the cmake option -DIDA_VERSION=<major>.<minor> to automatically sync it from 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 --target quokka_plugin -- -j

Install

To install the plugin:

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

In any case, the plugin will also be in build/quokka-install. You can copy it to IDA's user plugin directory.

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

For more detailed information about building, see Building

Documentation

Documentation is available online at documentation

FAQ

You can see a list of questions here FAQ

Exporting modes

Quokka offers two modes to export the disassembly analysis: the light mode and the self contained mode.

The light mode focuses on exporting only essential information, producing fast and lightweight files. In this mode no information at instruction level or below is exported, so the capstone engine will be used at runtime to obtain the instructions' disassembly.

The self contained mode instead exports the full disassembly, exactly how the backend disassembler shows it. This will produce heavier files but it doesn't require depending on third party disassemblers at runtime.

It's important to note that both modes offer the same API in the python bindings.

Warning

From the self contained mode it is still possible to obtain the capstone instruction object but beware that the capstone disassembly might be different than the one exported by quokka (instructions might be splitted, merged, not supported, have different mnemonics, etc.). In general different binary analysis platforms produce different disassembly, keep this in mind when mixing capstone with the self contained mode.

For a complete overview of the difference between the two modes look at the table below:

	Light Mode	Self contained Mode
Functions	✅	✅
Basic Blocks	✅	✅
Instructions	❌	✅
Operands	❌	✅
Data References	✅	✅
Cross References	✅	✅
Sections/Layout	✅	✅
Decompilation	✅¹	✅¹
CFG drawing coordinates	✅¹²	✅¹²

^{¹ Optionally enabled}

^{² Currently not supported}