Skip to content

installation.md

Latest commit

 

History

History
233 lines (159 loc) · 6.04 KB

installation.md

File metadata and controls

233 lines (159 loc) · 6.04 KB
Raw

Installation

Python Bindings

System requirements

  • Python >= 3.8

!!! note While the IDA plugin requires Linux, the Python bindings work on all major platforms (Linux, macOS, Windows).

Installation

Using PIP

$ pip install quokka-project

Using the sources

To have the latest version, you can directly download the source from GitHub and install it locally.

$ git clone git@github.com:quarkslab/quokka.git
$ cd quokka
$ python -m venv .quokka-env
$ source .quokka-env/bin/activate
(.quokka-env) $ pip install .

!!! note The previous snippet creates a virtualenv, which is a good practice to manage Python dependencies.

Using a CI wheel

CI wheels are available directly on the CI

Final checks

To check the installation worked, run the following commands:

$ source .quokka-env/bin/activate
(.quokka-env) $ python -c 'import quokka; print(quokka.__version__)'

IDA Plugin

!!! warning The plugin support for Windows is experimental.

From the CI

The plugin is built on the CI and available in the Releases.

To download the plugin, get the file named quokka_plugin.so (or the quokka-ida<version>.zip archive matching your IDA version).

On IDA 9.2+ you can also install it through the Hex-Rays plugin manager:

user@host:~$ hcli plugin install quokka

Building

Requirements

  • CMake (at least 3.13)
  • A reasonably modern compiler supporting at least C++20
  • IDA SDK (version 9.1 or higher)
  • IDA (9.1 or higher)

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 \
                          -S . \
                          -DIdaSdk_ROOT_DIR:STRING=path/to/ida_sdk \
                          -DCMAKE_BUILD_TYPE:STRING=Release

IDA >= 9.2 (The new way)

The IDA SDK has been 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 \
                          -S . \
                          -DIDA_VERSION=9.2 \
                          -DCMAKE_BUILD_TYPE:STRING=Release

Finalize the build

If the first step succeeded, you can now do the actual building.

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

Installing the plugin

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

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_plugin.so $HOME/.idapro/plugins/

Build on Windows

!!! warning This is only experimental.

Requirements

This procedure has only been tested with using a Windows Dev Machine:

Optional:

Steps

  1. Configure the plugin

    PS C:\Users\User\quokka> cmake -B build -S . -DIdaSdk_ROOT_DIR=third_party/idasdk80 -A x64

  2. Perform the build

    PS C:\Users\User\quokka> cmake --build build --target quokka_plugin --config Release

  3. Cross your fingers and hope.

    Quokka for Windows is experimental and not tested. There are known issues with older Visual Studio versions and Ninja. Feel free to report any bug.

Ghidra Extension

Requirements

  • JDK 21+
  • Gradle >= 8.5 (a Gradle wrapper is included, so no system-wide install is needed)
  • Ghidra >= 12.0.3

Building

export GHIDRA_INSTALL_DIR=/path/to/ghidra
cd ghidra_extension
rm -rf dist/
./gradlew buildExtension

The extension ZIP is generated in dist/ (e.g. ghidra_12.0.3_PUBLIC_QuokkaExporter.zip).

Installing

  1. Open Ghidra
  2. File > Install Extensions
  3. Add the ZIP file from dist/
  4. Restart Ghidra

Alternatively, unzip the extension directly into the Ghidra extensions directory:

unzip -o ghidra_extension/dist/ghidra_*_QuokkaExporter.zip \
  -d "$GHIDRA_INSTALL_DIR/Ghidra/Extensions/"

!!! tip The scripts/fetch_ghidra.sh script can download the correct Ghidra release matching the version pinned in the repository:

```bash
export GHIDRA_INSTALL_DIR="$(scripts/fetch_ghidra.sh)"
```

BinaryNinja Extension

Requirements

  • Binary Ninja with its bundled Python 3 environment
  • protobuf available in Binary Ninja's Python interpreter (the plugin manager installs it automatically from plugin.json; for manual installs run pip install 'protobuf' with Binary Ninja's Python)

Installation

Clone the repository and symlink the extension into the Binary Ninja user plugin directory:

$ git clone git@github.com:quarkslab/quokka.git
$ cd quokka
$ python binaryninja_extension/install_dev.py

Alternatively, copy the binaryninja_extension/ directory into the Binary Ninja user plugin folder manually.

!!! note The generated protobuf module (bn_quokka/quokka_pb2.py) is committed to the repository, so no generation step is needed to install. After changing proto/quokka.proto, regenerate it as described in the extension README.