Hansken Kaitai Plugin Template for Python

This repository contains a template for a Hansken Kaitai plugin written in Python. Kaitai enables to read binary data structures from all sorts of files or network streams. The Kaitai plugin for Hansken, enables to parse a file using a Kaitai struct and write the parse result as a JSON. The template contains the general structure of a Kaitai plugin, including the required build steps.

• To get started developing Hansken Extraction Plugins, read the Getting Started Documentation.
• It is strongly recommended to take note of the Hansken Extraction Plugins for plugin developers documentation.
• For more information on the supported formats by Kaitai, go to https://formats.kaitai.io/.
• An example implementation of a Hansken Kaitai plugin is found in the extraction plugin examples repository.

To transform this template into an implementation, we suggest to conduct the following steps:

• Clone the template plugin to get started on implementing your Kaitai plugin for Hansken
• Go to the kaitai_structs_formats Github to download a Kaitai token. This is the .ksy file you need in the next step.
• Place the *.ksy file of interest in the structs directory
• Update the plugin info in plugin.py, such as:
  • the version of your plugin, author info, and your organisation
  • the matcher on the $data.fileType property of your interest in plugin.py with a suitable HQL-Lite statement (see also "how to write a good matcher" in the documentation).
• (optional) Add additional dependencies for your plugin to requirements.in if necessary
  • If you added additional dependencies, regenerate requirements.txt by calling tox -e upgrade
• (optional) Add any system dependencies to the Dockerfile
• (recommended) Create test input data in the folder testdata/input (refer to the"Test Framework" section of the SDK manual for more details on how to define test data)
  • (Re)generate your expected test result data with tox -e regenerate
  • Verify your expected test result data in testdata/result
• Update this README.md
• Publish your plugin to the Hansken community

TIP!
If you want to run the plugin from your IDE, you can add the .ksy file and the manually compiled .py files to the structs folder.

WARNING!
Successful implementations of this template have only been tested on small object trees and small byte arrays. Stability and performance for large object trees and byte arrays is not guaranteed.

Tox commands that may be useful:

• tox: runs your tests
• tox -e integration-test: runs your tests against the packaged version of your plugin (requires Docker)
• tox -e regenerate: regenerates the expected test results (use after you update your plugin)
• tox -e upgrade: regenerates requirements.txt from requirements.in
• tox -e package: creates a extraction plugin OCI/Docker image that can be published to Hansken (requires Docker)

Note: see the readme text in the Dockerfile if you need to set proxies or private Python package registries for building a plugin.