Originally posted on 2024-04-25

I’ve now tried 010 Editor, ImHex, and fq.

010 Editor and ImHex’s development workflows didn’t work for me.

fq was better, and actually really great for certain things, but I wanted something I could generate code with. So here I am.

Installation

On MacOS:

brew install kaitai-struct-compiler
sudo gem install kaitai-struct-visualizer

The Ruby gem installation time is punishing and silent but it seems to work even on MacOS’s old version of Ruby which is ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin23] as of this writing.

Now you’ll have two three tools installed:

kaitai-struct-compiler - to compile .ksy files to your language of choice
ksv - to visualize a file using the format defined in a .ksy file
ksdump - to dump an entire file using the format defined in a .ksy file

Testing

Try a sample file first before using the tools. Make small changes and test incrementally. As with all other binary file definition systems I’ve tried the errors can be a bit confusing. Let’s try the GIF format example from the Kaitai site:

meta:
  id: gif
  file-extension: gif
  endian: le
seq:
  - id: header
    type: header
  - id: logical_screen
    type: logical_screen
types:
  header:
    seq:
      - id: magic
        contents: 'GIF'
      - id: version
        size: 3
  logical_screen:
    seq:
      - id: image_width
        type: u2
      - id: image_height
        type: u2
      - id: flags
        type: u1
      - id: bg_color_index
        type: u1
      - id: pixel_aspect_ratio
        type: u1

Assuming your .gif file is called pronounced-like-the-peanut-butter.gif these three commands should work:

ksv -i gif.ksy pronounced-like-the-peanut-butter.gif

Visualizer (really useful for drilling down into files)

ksdump -f json pronounced-like-the-peanut-butter.gif gif.ksy

Dump to JSON

kaitai-struct-compiler -t go gif.ksy

Compile to Golang

UNFINISHED: Installing and working with Kaitai Struct

Installation

Testing