Skip to main content
Glama
binharness
by dougchansan

binharness

A binary-analysis toolkit focused on Nintendo Switch NSO/NRO modules, with raw-byte inspection for other files, packaged three ways:

  • Codex plugin (hex-viewer): an interactive hex viewer for compatible Codex clients, plus analysis tools.

  • MCP server: the full toolset: view_binary and the analysis tools. The interactive viewer needs a client that supports MCP Apps; other clients can use the text tools.

  • deepseek-bin: a standalone CLI agent that uses the same tools with DeepSeek models.

Hex Viewer showing a file with a search hit and the byte inspector

What it can do

Tool

What it does

view_binary

Interactive hex + ASCII viewer (Codex UI): go to offset, hex/text search, byte inspector

verify_nso

Recompute SHA-256 over decompressed NSO segments and compare enabled header digests; report absent digest flags separately

file_info

Identify format signatures; summarize NSO/NRO segments and symbols, NPDM declarations, or NSP/XCI container entries

disassemble

AArch64 disassembly with branch/data-reference annotations; x86-64 instruction disassembly is also available with arch: "x86-64"

list_functions

Estimate function boundaries from AArch64 call targets, relocations, init arrays and prologues

call_graph

Display detected direct AArch64 calls as a depth-limited tree; inferred boundaries and indirect calls can leave gaps

scan_syscalls

Find svc #n encodings in the text segment and label known Horizon syscall numbers; presence does not establish execution

label_syscalls

Label detected small functions with a single known syscall as candidate wrappers, and annotate SVC sites

find_services

Find known-looking Switch IPC service strings and detected references to them; references do not prove service use or ownership

label_services

Add use_<service> labels to eligible unnamed functions referencing one detected service, and annotate the strings

label_from_strings

Infer labels from diagnostic strings, such as the synthetic "FixtureWorker::Run is called", when exactly one detected unnamed function references the string

parse_npdm

Read the program id, service declarations and syscall allowlist from NPDM ACI0; does not verify ACID signatures or actual runtime activity

find_rtti

Find candidate Itanium C++ RTTI names, vtables and method-slot counts from available metadata and relocations

label_rtti

Save inferred vtable labels and <Class>::vf<n> labels for detected method targets; these are not recovered original method names

export_symbols

Export collected labels/comments as Ghidra Java/Python scripts, an IDA Python script, or JSON

find_xrefs

Detect supported AArch64 calls, branches and data references to an address

find_string_refs

Find matching strings and supported AArch64 references to them

list_symbols

Demangled dynsym symbols and your saved labels

search_bytes

Hex patterns with ?? wildcards, or "text"

decode_struct

Decode memory with a C-like layout: u32 magic; f32 pos[3]; char name[16]; ptr next

read_binary_chunk

Hexdump by file offset or virtual address

binary_strings

strings -t x on a segment, with regex filter

compare_files

Byte-level diff of two files

annotate / get_annotations

Labels, comments and notes, saved per build id in ~/.binharness/ and shown in later disassembly

extract_image

Write the decompressed NSO/NRO image + JSON symbol map for Ghidra/IDA

decompress

Decompress a Zstandard (.zs), Yaz0, gzip or zlib file (writes the output or previews it)

parse_byml

Parse BYML/BGYML (Nintendo binary YAML) to JSON; auto-decompresses a Zstd/Yaz0-wrapped input

parse_bntx

List the textures in a BNTX container (name, format, dimensions, mips) — structure only, no pixel decode

parse_bfres

Summarize a BFRES resource: version, name, model/skeleton blocks, embedded BNTX — structure only

Asset support: decompress and parse_byml are validated; parse_bntx/parse_bfres read the container structure (contents listing), not full texture/model decode, and haven't yet been run against a large corpus of real files.

Hand-off to Ghidra/IDA

extract_image and export_symbols are tool names, not shell executables. Ask your MCP client to call them with these arguments, replacing the paths:

{"name":"extract_image","arguments":{"path":"/path/to/main","out":"/path/to/out.bin"}}
{"name":"export_symbols","arguments":{"path":"/path/to/main","out":"/path/to/out","format":"both"}}

For the out prefix above, the export formats produce:

format

Output files

both (default)

out_ghidra.java, out.ghidra.py, out.ida.py

ghidra

out_ghidra.java, out.ghidra.py

ida

out.ida.py

json

out.names.json

The Java filename and public class name use the sanitized basename of the out prefix plus _ghidra; the output directory is preserved. For Ghidra, use the Java GhidraScript route to avoid a Python integration dependency. The .ghidra.py alternative needs a compatible Ghidra Python integration configured in your installation.

Load out.bin as a flat AArch64 binary at the base recorded in out.bin.json (default 0x7100000000), then run out_ghidra.java in Ghidra or out.ida.py in IDA. Review labels and import warnings in the destination tool. Function boundaries and labels are analysis hypotheses; indirect calls, missing relocations, optimized code and absent RTTI can reduce coverage.

Format support and limits

Level

Formats and behavior

Structured executable analysis

NSO with built-in LZ4 and optional externally decompressed ZBIC segments; NRO; available segment/symbol metadata and Switch AArch64 analysis heuristics

Structured container/metadata reads

NSP/PFS0, XCI/HFS0 directory entries; NPDM ACI0 program/service/kernel declarations

Identification plus raw-byte tools

ELF, Mach-O, PE, image/archive formats, SQLite, wasm, Nintendo asset signatures, and GameCube/Wii file/image signatures; detection does not imply a format-specific loader, extractor or decoder

Non-NSO/NRO inputs are treated as flat byte images for disassembly. ELF/Mach-O/PE sections and their load addresses are not mapped automatically. AArch64 reference/function analysis does not extend to x86-64 merely by selecting that disassembler. NSO/NRO addresses default to 0x7100000000; override with base when needed.

NPDM results describe ACI0 declarations. The parser does not verify the ACID signature or establish effective authorization after loader/platform checks. An allowed service or syscall need not be used, and a referenced service string does not identify its provider.

NSO hashes and optional ZBIC

verify_nso computes SHA-256 over each decompressed NSO text/rodata/data segment and compares it with header offsets 0xA0, 0xC0, and 0xE0 only when its hash-enable bit is set. A missing flag means not present, never verified. file_info reports these states, and extract_image blocks a declared mismatch unless ignore_hash_mismatch: true is explicitly supplied. These checks establish consistency with the NSO's own digest fields—not authenticity or permission to share input data.

NSO bit 7 selects ZBIC, a Switch 22.0+ modified Zstandard/BIC compression method. Binharness uses a deliberately optional, user-installed executable, not an embedded decoder: build alula/beetool separately and set BINHARNESS_BEETOOL to the absolute path of its hactool executable before starting your MCP server or CLI. For example:

export BINHARNESS_BEETOOL=/absolute/path/to/beetool/hactool
npm test

The executable is invoked strictly as -t nso0 --uncompressed=<temporary-output> <temporary-input>, with a temporary HOME/config directory to prevent hactool's default key-file search. The NSO is local, the helper's output is checked for matching metadata and segment hashes, and temporary files are erased. No helper, console keys, decrypted games, or third-party compression source is bundled, installed, downloaded, or published by binharness. An unconfigured ZBIC input raises a clear error instead of being misinterpreted as LZ4.

The tests use an independent synthetic byte/hash oracle and a mock helper to check the ZBIC handoff, not ZBIC codec correctness. When beetool is installed, setting BINHARNESS_BEETOOL also enables an actual differential NSO/LZ4 comparison in npm test; testing genuine ZBIC frames requires separately sourced, authorized inputs. See provenance.

Encrypted NCA files can be identified and inspected as raw bytes, but this toolkit does not decrypt them, acquire console keys or extract files from encrypted NCAs. Supply an NSO/NRO you are authorized to analyze. See provenance and distribution boundaries.

Related MCP server: Jukeyman Unleashed

Requirements and MCP setup

The code targets Node.js 18+ and has no npm dependencies. Disassembly requires an LLVM-compatible executable named objdump on the process PATH, supporting --triple, --no-show-raw-insn and --print-imm-hex. GNU objdump is not a drop-in replacement for these arguments. If your installation names the LLVM binary llvm-objdump, expose it as objdump with an executable wrapper or symlink; a shell alias does not affect Node's spawnSync. Symbol and RTTI demangling also need c++filt with -n and -t support. Raw hex inspection does not need these executables.

For a checkout, configure your MCP client's stdio server command as:

command: node
args: ["/absolute/path/to/binharness/plugins/hex-viewer/server.mjs"]

package.json defines binharness-mcp and deepseek-bin executables for a packaged install. This is not a claim that the package is currently published on npm; the checkout/local-node command above is the documented setup. server.json is draft registry publication metadata, without a verified registry launch recipe. The repository also contains a Codex marketplace manifest at .agents/plugins/marketplace.json and the hex-viewer plugin under plugins/hex-viewer; use the installation flow supported by your Codex version. Client configuration keys and installation commands vary by client/version.

Once connected, try "Show my synthetic fixture in the hex viewer" or "Find references to the fixture's greeting string".

deepseek-bin (DeepSeek CLI agent)

git clone https://github.com/dougchansan/binharness
cd binharness
node tests/make-fixture.mjs
export DEEPSEEK_API_KEY=your-api-key
node harness/deepseek-bin.mjs tests/fixture.nso

This starts an interactive session with streaming output and a tool-call trace. It sends prompts and selected tool results to the configured model API; the default endpoint is https://api.deepseek.com. One-shot mode using the synthetic fixture:

node harness/deepseek-bin.mjs -p "Explain the fixture's greeting-string references and cite the addresses" tests/fixture.nso

Recon. Run local metadata and naming passes before the model's analysis:

node harness/deepseek-bin.mjs --recon -p "What does this synthetic module do?" tests/fixture.nso

Recon runs file_info, label_rtti, label_syscalls, label_services, label_from_strings and a named list_functions summary. It also runs parse_npdm when the input filename is main and a sibling main.npdm exists. These passes make no model request themselves; their summaries enter the next API request and contribute to its input tokens. Saved labels persist, and their coverage depends on the input.

The current --recon file filter selects NSO and ELF signatures, not NRO. Use /recon <file> in the REPL for an NRO. ELF is treated as raw bytes rather than a mapped ELF image, so the advanced passes may fail or produce misleading results on it; NSO/NRO are the intended targets for these passes.

Option

-m <model> / --pro

Configured model; this code defaults to deepseek-flash, and --pro selects deepseek-v4-pro. Availability depends on the endpoint

-e none|low|high|max

Thinking effort (none disables thinking)

--show-thinking

Stream the model's reasoning

--max-steps N

Tool rounds per task (default 60)

--base-url <url>

Model API base URL; also configurable with DEEPSEEK_BASE_URL

-y

Allow extract_image to write files without asking

REPL commands: /help, /recon <file>, /model, /effort, /add <file>, /files, /cost, /save notes.md, /reset, /exit. Ctrl-C interrupts the current turn. The CLI's confirmation currently covers extract_image only; annotation/label tools, export_symbols and /save can write without that prompt.

Usage and estimates. Tool results sent to the model are capped at 16,000 characters per call, and the prompt asks for targeted reads. The conversation history is resent with each request. Cache use and billing depend on the provider; neither cache coverage nor savings is guaranteed. /cost uses provider-reported token counts and the hardcoded PRICES table in harness/deepseek-bin.mjs; its dollar amount is an estimate, not a current price quote or spending limit. Unknown models fall back to the built-in default model's rates.

Data flow and generated outputs

The standalone agent includes requested disassembly, strings, byte excerpts, paths and annotations in model requests as they enter the conversation. Using a local binary does not keep those extracts local. A custom API endpoint receives the same request content; choose a provider and inputs appropriate for the rights and confidentiality requirements of your work. The MCP server itself runs local tools, while the connected client's data-handling policy determines where its tool results go.

Annotations are stored under ~/.binharness/. Session JSONL logs contain prompts, model replies and tool-call metadata; /save also exports the conversation's tool results. extract_image writes the input's decompressed bytes. Model-generated C/C++, annotations and export scripts can contain information derived from the input; generating them does not establish independent provenance or redistribution rights. Review outputs before publishing. See PROVENANCE.md and the distribution audit.

Layout

.agents/plugins/marketplace.json     Codex marketplace "dougchansan"
plugins/hex-viewer/
  .codex-plugin/plugin.json          plugin manifest
  .mcp.json, server.mjs              stdio MCP server + view_binary UI wiring
  lib/bintools.mjs                   format handling, LZ4, tool dispatch, objdump wrapper
  lib/core.mjs, lib/re.mjs           reference decoding and analysis heuristics
  assets/app.html                    hex viewer UI (MCP App)
  skills/hex-viewer/SKILL.md         tells Codex when/how to use the tools
harness/deepseek-bin.mjs             DeepSeek agent
harness/fw-index.mjs                local module-directory index and declaration reports
tests/                               synthetic NSO fixture, mock DeepSeek API, test suite

Validation and distribution audit

Run the synthetic test suite and distribution checks from a checkout:

npm test
npm run audit:dist
npm run audit:history

The audit commands check the surfaces documented in docs/distribution-audit.md. They help detect packaging mistakes; they do not prove ownership, establish input provenance or grant permission to redistribute an artifact.

License

MIT for the repository's own code. Input binaries and generated artifacts remain subject to their applicable rights; see PROVENANCE.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to import binaries into Ghidra, trigger analysis, browse functions, symbols, strings, and imports, and read decompiled C code and disassembly via MCP tools.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to take software apart over MCP — native binaries, Go/Rust/.NET assemblies, WASM and EVM bytecode, Android and Flutter apps, firmware, databases, crashes and network captures — returning findings backed by code, references and explicit unknowns. Drives deep-analysis engines such as Hopper, Ghidra, IDA, JADX and Frida entirely locally, letting agents explain behavior or rebuild a feature in your own project.
      371,123 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Gives MCP clients such as Claude Code and OpenCode a static-analysis toolbox for binaries, executables, DLLs, shared objects, and web-app code, covering file identification and hashing, string extraction, PE/ELF/Mach-O/WASM parsing, disassembly, Ghidra decompilation, YARA scanning, and JavaScript deobfuscation. All inspection is read-only and never executes the target.
      16
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to locally analyze and reverse engineer binaries through a compact 12-tool MCP interface for triage, function discovery, disassembly/decompilation, cross-references, strings/imports, call graphs, memory reads, annotations, and binary diffs.
      1
      MIT