glaurung

Quick start

run Glaurung on /bin/ls

Glaurung isn't on PyPI yet. uvx can build it from Git and run it without leaving a checkout behind.

One command

run it without installing it

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

Commands

triage, analyze, graph, decompile

# 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 the headers, strings, hardening flags, and entropy. kickoff runs the larger analysis pipeline. Add --db to keep the names, types, comments, and cross-references in a SQLite file.

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

Repository

more commands and test binaries

repository

docs/

CLI reference, architecture notes, Windows work, design documents, and a longer tutorial.

repository

tests/decompiler_fixtures/

Source fixtures, baselines, and the harness that recompiles and runs recovered C.

license

Apache-2.0

Use it, fork it, break it, and send patches.

Source, issues, and command reference: github.com/mjbommar/glaurung.