Metadata-Version: 2.4
Name: quokka-project
Version: 0.6.2
Summary: Quokka: A Fast and Accurate Binary Exporter
Author-email: Quarkslab <diffing@quarkslab.com>
License: Apache Software License (Apache License, Version 2)
Project-URL: Homepage, https://github.com/quarkslab/quokka/
Project-URL: Repository, https://github.com/quarkslab/quokka/
Project-URL: Documentation, https://quarkslab.github.io/quokka/
Project-URL: Bug Tracker, https://github.com/quarkslab/quokka/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: capstone>=4.0.2
Requires-Dist: networkx>=2.4
Requires-Dist: protobuf>=3.12.2
Requires-Dist: python-magic; os_name != "nt"
Requires-Dist: python-magic-bin; os_name == "nt"
Requires-Dist: click
Requires-Dist: idascript>=0.4.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: coverage[toml]; extra == "test"
Requires-Dist: pypcode>=2.0.0; extra == "test"
Provides-Extra: pypcode
Requires-Dist: pypcode>=2.0.0; extra == "pypcode"
Provides-Extra: doc
Requires-Dist: mkdocs; extra == "doc"
Requires-Dist: mkdocs-material; extra == "doc"
Requires-Dist: mkdocstrings; extra == "doc"
Requires-Dist: mkdocstrings-python; extra == "doc"
Requires-Dist: mkdocs-literate-nav; extra == "doc"
Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == "doc"
Requires-Dist: mkdocs-gen-files; extra == "doc"
Requires-Dist: mkdocs-simple-hooks; extra == "doc"
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: flake8-black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: mypy-protobuf; extra == "dev"
Requires-Dist: nox; extra == "dev"
Requires-Dist: pypcode>=2.0.0; extra == "dev"
Dynamic: license-file

# Quokka

<p align="center">
	<img src="https://raw.githubusercontent.com/quarkslab/quokka/main/docs/img/logo.png"  width="256" height="256">
</p>

image generated by [DALL-E](https://labs.openai.com/s/3k4LtWP564OYrVCIeoGmefMB)


---

Table of Contents
=================

* [Introduction](#introduction)
* [Installation](#installation)
* [Usage](#usage)
* [Building](#building)
* [Documentation](#documentation)
* [FAQ](#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.

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

Quokka is heavily inspired by [BinExport](https://github.com/google/binexport),
the binary exporter used by BinDiff.

## Installation

### Python plugin

The plugin is built in the CI and available in the
[registry](https://github.com/quarkslab/quokka/packages).

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

```commandline
$ 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](https://github.com/quarkslab/quokka/releases/new) tab.

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

## Usage

### Export a file

!!! note

    This requires a working IDA installation.


- Either using command line:
```commandline
$ idat64 -OQuokkaAuto:true -A /path/to/hello.i64
```

Note: We are using `idat64` and not `ida64` to increase the export speed
because we don't need the graphical interface.

- Using the plugin shortcut inside IDA: (by default) Alt+A

### Export a file in batch

One can write its own bash script run multiple `idat64` in parallel. However,
Quokka provides an utility tool to automatically export all executable files
of a given directory in parallel. An example to automate the export using 8 threads:

```commandline
$ quokka-cli -t 8 dir/
```


### Load an export file

```python
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.

```console
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](https://github.com/HexRaysSA/ida-sdk) 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.

```console
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:

```console
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.

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

For more detailed information about building, see [Building](docs/installation.md#ida-plugin)

## Documentation
Documentation is available online at
[documentation](https://quarkslab.github.io/quokka/)

## FAQ
You can see a list of questions here [FAQ](docs/FAQ.md)
