Documentation

install it, run it, keep the project

Start with /bin/ls. The first command identifies the file. The second saves a SQLite project you can search, annotate, reopen, undo, and export.

10 minutes

run one binary

Use uvx, inspect /bin/ls, and leave no checkout behind.

daily work

make a .glaurung project

Run kickoff, then search functions, inspect xrefs, and record your names and notes.

reference

40 command pages

Open the command index for syntax, examples, and side effects.

Try it

one command, no checkout

The first run builds the Rust extension. uv keeps that build for next time.

one command

$ uvx --from git+https://github.com/mjbommar/glaurung.git \
    glaurung kickoff /bin/ls

On Linux, /bin/ls is usually an ELF binary. On macOS it is Mach-O. Replace it with any binary you are allowed to inspect.

Install

put glaurung on your PATH

uv gives the command its own environment and keeps it out of your project packages.

persistent tool install

$ uv tool install git+https://github.com/mjbommar/glaurung.git
$ glaurung --version
glaurung 0.1.0

$ glaurung triage /bin/ls
$ glaurung kickoff /bin/ls --db ls.glaurung

First project

triage, kickoff, inspect

# Fast identification: format, architecture, hardening, strings.
$ glaurung triage /bin/ls

# Deeper analysis saved to a project file.
$ glaurung kickoff /bin/ls --db ls.glaurung

# Control flow and pseudocode for the entry point.
$ glaurung cfg /bin/ls
$ glaurung decompile /bin/ls --style c

# Machine-readable output for a script or pipeline.
$ glaurung triage /bin/ls --json

triage reads headers, strings, hardening flags, and entropy. kickoff runs function discovery, cross-references, stack analysis, and type recovery. Add --db or the project is temporary.

Hack on it

build from a checkout

The repository has a locked environment and sample binaries. uv sync builds the extension.

$ git clone https://github.com/mjbommar/glaurung.git
$ cd glaurung
$ uv sync --locked --dev
$ uv run glaurung --version
$ uv run glaurung kickoff \
    samples/binaries/platforms/linux/amd64/export/native/gcc/O2/hello-gcc-O2

Python

use the Python module

The module returns the same objects used by the command line.

temporary Python environment

$ uv run --with 'glaurung @ git+https://github.com/mjbommar/glaurung.git' python

>>> import glaurung as g
>>> art = g.triage.analyze_path("/bin/ls")
>>> v = art.verdicts[0]
>>> print(v.format, v.arch, v.bits)
ELF x86_64 64

Projects

open the project again

journal and undo take the project file first. Commands that read bytes also need the binary.

# Read the journal and undo log in the saved project.
$ glaurung journal ls.glaurung list --binary /bin/ls
$ glaurung undo ls.glaurung --list --binary /bin/ls

# Continue in the interactive shell.
$ glaurung repl /bin/ls --db ls.glaurung

pick the page that matches the job

reference

command index

Every top-level command, grouped by inspection, project work, annotation, recovery, formats, Windows, and LLM use.

support

formats and processors

Check file and processor support before using the decompiler on a new target.

measure C

C source analysis

Measure complexity, compare reports, and replace common pyjoern graph calls with the file-based Python API.

engine repository

long tutorials

The source repository has walkthroughs for native C, stripped Go, Java, PE files, packed binaries, patching, and agent workflows.

Source, issues, and the full tutorial: github.com/mjbommar/glaurung.