deglyph v1.3.0

A large release focused on evidence-backed analysis, a fuller TUI workbench,
portable annotation projects, on-disk caching, and a hardened I/O layer. Every
detector and scanner result now carries the evidence behind it, so a hit reads
as a candidate to confirm in disassembly rather than a verified fact.

Analysis core

• Arch-neutral operand model, per-function CFG, and unwind-backed function
  discovery (re/cfg.py, re/unwind.py).
• Pattern detectors now attach the evidence (the instructions and references)
  behind each hit; calling-convention inference carries a confidence level.
• Data cross-references: detectors and the scanner surface where a constant or
  string is read from, not just that it exists.
• Unwind starts are filtered to executable sections so seeded-start evidence
  matches what the disassembler can actually decode.

Scanner, fingerprint, and CVE

• Scanner findings are grouped into categories and carry per-finding evidence.
• Library fingerprinting reports a confidence level with backing byte
  signatures instead of a bare name match.
• CVE lookups record their provenance and run offline against a local feed.

AI assistant

• Evidence transcript for every investigation, with renames gated on a prior
  inspection so the model cannot rename a function it never looked at.
• Redacted export of the last investigation from the TUI.

TUI workbench

• Session model: filter, active tab, and selection persist and restore across
  runs.
• Data view, full command palette, keyboard-driven call-graph navigation, and a
  compare view.
• Copy address, copy the active pane, and export a per-function report.
• User-renamed functions are visually distinguished in the tree.
• Background discovery and strings scans can be cancelled from the TUI.

Export and portable projects

• deglyph export writes a versioned JSON schema of the analysis.
• Annotation projects are portable: rename and note work moves with the file,
  keyed by content hash rather than absolute path.

Performance

• On-disk analysis cache keyed by file hash, covering discovery scan targets,
  the xref index, and extracted strings.
• Optional wall-clock budget for discovery, returning uncached partial results
  when the budget is exhausted.
• Timing benchmark over the sample binaries (scripts/benchmark.py).

Hardening

• Response bodies are bounded and corrupt files are tolerated at the I/O
  boundaries, so one bad region or oversized response never aborts a scan.
• TUI tab activation is guarded against teardown after the tree unmounts.

Tests and docs

• Property tests for address translation and section reads; golden snapshots
  for scan JSON, SARIF, and the export document; fuzzing of the whole-image
  passes on an undecodable stream.
• README and the in-app help manual synced with the current CLI.

Upgrading

The GitHub Action pin in the README now points at deglyph-re/cli@v1.3.0.
Update your workflow's uses: line to match after the tag is published.

deglyph v1.2.0

• Fat (universal) Mach-O support. A multi-arch Mach-O (e.g. x86_64 + arm64e) now loads correctly. Earlier builds read only the first slice and, worse, landed in the fat header's zero padding, so disassembly came back as a wall of add byte ptr [rax], al. deglyph now parses the fat container, picks a slice, and folds each slice's file offset into every section read, which also fixes string extraction, search, and scanning on these binaries.
• Live scan badge. deglyph scan --format badge emits a shields.io endpoint object summarizing the run (clean / N errors / N warnings, colored by the worst level), ready to publish as a README badge. The GitHub Action gained a badge input that writes the file on every run, even when the gate fails.
• Whole-file content map. The TUI renders a colorized map of the entire file's regions, complementing the per-function disassembly and hexdump.

New features

Fat Mach-O slices

• load_image resolves a fat binary, chooses a slice (explicit --slice N -> requested --arch -> host arch -> first), and corrects section offsets so reads land in the chosen slice.
• CLI: --slice N selects a slice; the chosen slice and the full list are reported.
• TUI: a per-slice picker under Binary, with reload on switch.

Scan badge output

• --format badge produces a shields.io endpoint-badge JSON (schemaVersion, label, message, color).
• A clean scan reads clean in green; otherwise the message counts findings worst-first and the color follows the worst level (note = blue, warning = yellow, error = red).
• The GitHub Action's badge input writes the same file from a workflow.

TUI content map

• A whole-file region map rendered as Rich Text, alongside the existing disassembly and hexdump views.

Fixes

• Markdown scan reports use an ASCII separator, so the $GITHUB_STEP_SUMMARY append no longer mangles on Windows runners that decode it as cp1252.

Documentation and tooling

• CLAUDE.md restructured via progressive disclosure: the 18 architecture invariants, the full Common Mistakes table, and the extension how-tos moved verbatim into doc/claude/, leaving the main file at every-session essentials plus a sub-documentation table.
• New help entries for badges and the updated output formats; README and help use a logo-enhanced badge.
• The tone/style verifier (scripts/verify.py) treats doc/claude/ as developer docs, exempt from the ASCII-only rule like CLAUDE.md.
• Action usage examples pinned to v1.2.0.

Upgrading

The GitHub Action examples reference deglyph-re/cli@v1.2.0. Create and push the v1.2.0 tag for that reference to resolve.

deglyph v1.1.0

This release improves the CI scanner and wires it fully into the GitHub Action, and ships a complete, JSON-indexed help manual.

Scanner

• Credential rule now requires a value. secret/credential-keyword fires only on an actual assignment or a value-shaped token, not a bare keyword. This removes the bulk of false positives on real binaries (167 → 0 on one Qt app).
• Expanded provider-token catalog. New high-precision regexes for GitHub fine-grained tokens, GitLab PATs, Slack webhooks, Stripe, npm, SendGrid, OpenAI, and Telegram.
• PE stack-canary fix. Detection now reads the load-config security cookie, so a stripped /GS build no longer false-reports harden/no-stack-canary.
• JSON output. scan --format json emits a flat findings list with a level-count summary and a per-finding fingerprint, for jq and custom gates.
• Finding suppression. --ignore (by rule id, category/ prefix, or fingerprint: hash) and --ignore-file (default .deglyphignore) drop findings before the exit code is computed, so the report and the gate agree.

GitHub Action

• The composite action now feeds four surfaces from one scan: the job gate, the Actions run summary (always on), a code-scanning SARIF upload (upload-sarif), and the sticky PR comment.
• New ignore / ignore-file inputs, threaded into every scan step.
• The summary and SARIF-upload steps run with if: always(), so a failing gate still reports its surfaces.

Documentation

• New JSON-indexed help manual under doc/help/: help.json plus 34 categorized Markdown pages covering the interface, the analysis pipeline, the CI scanner, and the GitHub Action. The project website renders it from this source.
• Usage examples (README.md, action.yml, examples/deglyph-scan.yml) pin deglyph-re/cli@v1.1.0.

Tests

• Added scanner, hardening, and CLI-coverage cases for the new secret rules, PE canary path, JSON output, and suppression.

deglyph v1.0.0

Initial release. deglyph opens a compiled binary and helps you understand what it does, all from your terminal. It never executes the binary; it only reads and disassembles it.

Highlights

• Load any object. PE32, PE32+, ELF, Mach-O, and fat binaries. Format and architecture are detected from the file, with --fmt / --arch overrides.
• Find a function. A searchable, grouped tree of exports, symbols, imports, and the entrypoint. For stripped binaries that export nothing, functions are recovered by scanning .text for call targets and named sub_<address>.
• Read disassembly. Branch and call targets resolve to names and are clickable; the listing follows the cursor.
• Follow a wrapper to its implementation. Resolves exported-stub chains to the function that does the work.
• Walk the call graph. Recursive caller/callee trees plus a focused node navigator centered on the selected function.
• Recover structure. Heuristic detectors for immediate stores, call-argument immediates, and CRC/checksum loops (with candidate polynomial and init).
• Extract data. Image-wide strings (ASCII and UTF-16) and the data a function references, in the TUI or headless.
• Search the image. Byte patterns with ?? wildcards, strings, and immediate constants in executable code.
• Read pseudo-C. A line-by-line, x86-only heuristic reading of the assembly.
• Ask the assistant. An opt-in, agentic AI assistant over read-only tools. Use Claude with your own key or any OpenAI-compatible endpoint. Sends nothing until you ask.
• Annotate and keep it. Renames, notes, and bookmarks persist to a per-user sidecar and survive across sessions.

CI and supply chain

• deglyph scan. Headless check reporting hardening posture, embedded secrets, risky imports, library fingerprints, and build drift against a baseline. Output as text, SARIF, markdown, or a single-file HTML dashboard, with a configurable --fail-on exit gate.
• deglyph sbom. CycloneDX 1.5 and SPDX 2.3 bill of materials from the detected libraries.
• GitHub Action. A composite action wrapping deglyph scan that posts a sticky PR comment with the markdown report.

Notes

The pattern detectors and the scanner are heuristics that point at the right instructions, not proofs. Confirm a finding in the disassembly before treating it as fact.

Built on LIEF, Capstone, and Textual. Python 3.10+. GPLv3 licensed.

deglyph v0.0.2

A documentation and packaging patch release. No functional changes to the
analysis core, scanner, or TUI, existing behavior is unchanged.

Changes

• PyPI rendering — README now uses PNG images with absolute URLs so they
  render correctly on the PyPI project page.
• Action examples — the GitHub Action snippets in README.md, action.yml,
  and examples/deglyph-scan.yml are pinned to the release tag (@v0.0.2).
• Docs copy — the AI assistant documentation uses a neutral example.
• Version — bumped to 0.0.2.

Upgrade

pip install --upgrade deglyph

GitHub Action consumers should pin to the new tag:

- uses: deglyph-re/cli@v0.0.2

deglyph v0.0.1

The first public release of deglyph: a terminal reverse-engineering tool for native
binaries. It loads a PE, ELF, or Mach-O, recovers its functions even when the binary
exports nothing, and gives you annotated disassembly, recursive call graphs, a
heuristic pseudo-C view, pattern detectors for recovering structure, and an optional
AI assistant, without ever executing the binary.

Built on LIEF (container parsing),
Capstone (disassembly), and
Textual (interface). Python 3.10+. GPLv3.

Highlights

• Loads any object. PE32, PE32+, ELF, Mach-O, and fat binaries. Format and
  architecture are auto-detected; --fmt and --arch override when needed.
• Finds functions in stripped binaries. Exports, symbols, imports, and the
  entrypoint, plus sub_<address> functions recovered by scanning .text for
  call targets, so a release notepad.exe with no exports becomes hundreds of
  navigable functions.
• Annotated disassembly. Branch and call targets resolve to names and are
  clickable; the listing follows the cursor.
• Follows wrappers to implementations. Press f to resolve a thin exported
  stub to the routine that does the real work.
• Call-graph navigation. Recursive caller/callee trees (x) and a focused,
  clickable node navigator centered on the selected function (c).
• Structure recovery (heuristic). Immediate stores (mov [buf+off], imm),
  constant call arguments, and CRC/checksum loops with candidate polynomial, init
  value, and a name for well-known polynomials. The disassembly view is always one
  key away to confirm.
• Data extraction. A browsable list of every string (ASCII and UTF-16) with
  address and section, plus the strings, tables, and pointer constants a function
  references.
• Image search. Byte patterns with ?? wildcards, ASCII/UTF-16 strings, and
  immediate constants referenced anywhere in executable code.
• Pseudo-C (heuristic, x86 only). A readable, line-by-line C-like view of the
  selected function.
• AI assistant (opt-in). Press i to ask Claude about a function in plain
  language. Agentic: it calls read-only tools to locate and explain the answer and
  cites clickable addresses. Bring your own Anthropic key, or point it at any
  OpenAI-compatible endpoint (OpenAI, Azure, Groq, OpenRouter, DeepSeek, or a local
  Ollama / LM Studio). Sends nothing until you ask.
• Persistent annotations. Rename (n), note (;), and bookmark (b) by
  address, saved to a per-user sidecar so they survive across sessions; renames show
  everywhere the function appears.
• Navigation history. Browser-style back/forward over deliberate jumps ([ /
  ]), plus recent-function and chat menus.
• Theming and glyphs. Command-palette theme switcher (remembered between runs),
  --ascii for limited terminals, and --nerd for Font Awesome icons.

For CI: deglyph scan

A headless check for build pipelines that reads the binary and never runs it:

• Secrets — private keys, cloud/provider tokens, and credential-labeled strings.
• Hardening posture — ASLR/DEP/CFG, canaries, PIE, RELRO, BTI/PAC, code signing,
  across PE / ELF / Mach-O.
• Library fingerprinting — string-signature identification feeding an SBOM
  emitter (CycloneDX 1.5 / SPDX 2.3) and optional CVE lookups against osv.dev.
• Risky imports — process execution, code injection, dynamic loading, network,
  anti-debug.
• Build drift — functions and imports that appeared or vanished against a
  --baseline.

Output is human text, --sarif for GitHub code scanning, or --format markdown /
html for a PR comment or dashboard. Findings set a non-zero exit (--fail-on
chooses the gate). Ships as a composite GitHub Action that keeps a single sticky PR
comment in sync.

All detectors are heuristics, not proofs: a secret hit is a candidate, an import is a
capability not a misuse, a hardening "miss" is an absent flag, and an empty
fingerprint list means "no catalog match", never "self-contained".

Install

The launcher bootstraps an isolated virtual environment on first run; the only host
requirement is Python 3.10 or newer.

./deglyph.sh path/to/library.dll   # or ./deglyph.sh for the welcome screen

Or install as a package (the AI assistant and C++ demangling are included):

python3 -m venv .venv && . .venv/bin/activate
pip install -e .
deglyph path/to/library.dll

GitHub Action

- name: Scan with deglyph
  uses: deglyph-re/cli@v0.0.1
  with:
    path: build/app
    sarif: deglyph.sarif
    comment: "true"
    fail-on: never

Notes and limits

• deglyph never executes the binary it analyzes; it only reads and disassembles it.
• The pattern detectors, pseudo-C, and immediate search inspect x86 / x86-64
  operands. ARM and AArch64 targets still load, list functions, resolve wrappers, and
  disassemble, but those detectors report nothing until a per-architecture operand
  walk is added.
• Function discovery misses indirect and tail-call-only functions.