A Rust disassembler for raw machine code, object-backed binaries, symbol-scoped inspection, and conservative semantic analysis.

Built for low-friction terminal workflows, deterministic verification, and evidence-backed output rather than decompiler theater.

assembler is a command-line disassembly frontend implemented in Rust.

It:

• decodes raw opcode streams and object-backed executable code through Capstone
• resolves section and symbol context through object
• renders normalized assembly in either terminal-friendly pretty mode or grep-friendly plain mode
• emits structured JSON for automation and CI usage
• optionally runs a conservative semantic analyzer for x86 and x86_64 disassembly

It is intentionally not a decompiler, source reconstructor, symbolic executor, or exploitability oracle.

• Deterministic decoding surface: explicit architecture selection when metadata is insufficient; no silent guessing for ARM/Thumb raw modes
• Symbol-first workflow: real binary and object-file inspection with symbol and section filtering instead of only byte-stream demos
• Terminal-safe output: hostile strings are escaped before rendering, and non-interactive output defaults to a stable plain-text layout
• Conservative analysis: findings are derived from operand semantics, memory addressing, and control-flow evidence—not from mnemonic names or imported APIs
• Regression-proof development: fixture binaries use exact global_asm! symbols so verification is not hostage to compiler codegen drift

• Build and installation
• Command model
• Common workflows
• Output formats
• Semantic analysis
• Deterministic fixture corpus
• Reverse-engineering example
• Architecture support and limits
• Safety and robustness
• Verification
• Project layout
• Implementation stack

cargo build --release

cargo install --path .

• Rust toolchain (edition 2024)
• a C compiler only if you want to build the optional demo target in examples/password-login/

assembler [FILE] [OPTIONS]
assembler --raw-hex <HEX> --arch <ARCH> [OPTIONS]

The CLI operates in two disjoint input modes:

Raw-byte mode requires --arch because there is no container metadata to infer decode mode safely.

• --symbol, --section, and --all-sections are file-mode only
• --base-address is only meaningful for raw-byte decoding
• --syntax att only affects x86 and x86_64 output
• ARM object files require explicit --arch arm or --arch thumb

cargo run -- --help

cargo run -- --raw-hex "55 48 89 e5 5d c3" --arch x86-64

cargo run -- ./target/debug/assembler --symbol main

cargo run -- ./target/debug/assembler --section .text --section .init

cargo run -- --raw-hex "55 48 89 e5 5d c3" --arch x86-64 --render pretty --color never

cargo run -- --raw-hex "55 48 89 e5 5d c3" --arch x86-64 --render plain --color always

cargo run -- ./target/debug/assembler --symbol main --analyze --output json

cargo run -- ./target/debug/assembler --symbol main --analyze --analyze-exit-code

The text renderer has two layouts:

Color behavior:

--output json emits a stable structured document:

{
  "disassembly": {
    "target": "...",
    "architecture": "X86_64",
    "metadata": [["format", "Elf"], ...],
    "sections": [...]
  },
  "analysis": {
    "architecture": "X86_64",
    "findings": [...],
    "notes": [...]
  }
}

analysis is omitted when --analyze is not requested.

--analyze runs a post-decoding pass that consumes Capstone detail-mode output and reasons over:

• typed operands
• access direction
• stack-relative memory addressing
• frame setup patterns
• basic-block control flow and loop back-edges

It does not inspect rendered text for keywords and does not claim exploitability from disassembly alone.

CLI
  → DisasmRequest
  → Capstone decode (detail mode)
  → DisassemblyReport
  → analyze()
  → AnalysisReport
  → text or JSON render

• frame reconstruction scans prologue instructions until the first backward branch or call, which handles delayed setups better than a fixed instruction window
• CFG construction builds basic blocks and back-edge relationships instead of relying on flat backward-jump heuristics alone
• bound matching only promotes a loop bound into a finding when the compared register is the one actually driving the memory write progression
• finding deduplication keys on (kind, address, section, rationale) so distinct evidence at one address is preserved
• bounded-loop suppression prevents strongly bounded local loops from being reported as suspicious when the proven bound fits the inferred local capacity

• no decompilation
• no source reconstruction
• no symbolic execution
• no imported-API danger lists turned into fake findings
• no exploitability claims beyond observed disassembly evidence

fixtures/ is a dedicated workspace member that builds a separate verification binary containing exact global_asm! symbols.

This is a major part of the project’s engineering discipline: analyzer and renderer regressions are validated against precise assembly programs, not compiler-accidental Rust or C code generation.

• positive x86_64 fixtures for every current analyzer finding class
• negative x86_64 fixtures for false-positive resistance
• AArch64 fixtures for renderer and unsupported-analysis verification
• linker-retained symbols through extern "C" declarations plus #[used] retention tables

cargo build -p fixtures
cargo test --test fixtures

# inspect one positive fixture manually
cargo run -- ./target/debug/fixtures --symbol fixture_stack_local_unbounded_loop --analyze --output json

• symbol names use the fixture_ prefix
• local labels use .L_<fixture_name>_<label>
• every fixture symbol has an explicit .size directive for reliable symbol-scoped disassembly
• fixture code lives only in fixtures/, never in production src/
• fixture verification is Linux/ELF-oriented; AArch64 fixtures are cross-built and disassembled, not executed on the host

examples/password-login/ contains a small C target compiled to preserve readable machine code.

gcc -O0 -g -fno-inline -fno-builtin -no-pie \
  -o examples/password-login/secret_login \
  examples/password-login/secret_login.c

cargo run -- examples/password-login/secret_login --symbol check_password --render pretty --color never

cargo run -- examples/password-login/secret_login --symbol check_password --analyze --render plain --color never

This function is intentionally a negative analysis case: it reveals a secret through immediate byte comparisons, but it does not perform the stack-local copy or repeated write behavior required for a memory-safety finding.

See examples/password-login/README.md for the full walkthrough.

Important limits:

• raw-byte mode requires --arch
• ARM object files are not silently guessed as ARM vs Thumb
• big-endian object files are explicitly rejected
• semantic analysis currently targets x86 and x86_64 only

• terminal-hostile strings are escaped before rendering
• pretty output preserves full instruction text without clipping operands or labels
• raw hex input is capped at 8192 decoded bytes
• input files must be regular files and are capped at 128 MiB
• raw mode rejects file-only flags such as --symbol, --section, and --all-sections
• Thumb symbol addresses are normalized so label mapping and slicing remain stable on real ELF symbols
• fixture verification uses explicit symbol retention and nm checks instead of assuming the linker kept test-only targets

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo build -p fixtures
cargo test
cargo test --test fixtures
bash scripts/smoke.sh

CI additionally performs:

• x86_64 fixture symbol verification with nm
• AArch64 cross-build verification with aarch64-linux-gnu-gcc
• AArch64 fixture symbol verification with aarch64-linux-gnu-nm

src/
  main.rs            entry point and output dispatch
  cli.rs             CLI model and argument parsing
  types.rs           shared request/report/instruction data model
  disasm.rs          Capstone integration, object parsing, symbol resolution
  render.rs          text rendering, ANSI styling, operand token classification
  analysis.rs        semantic analyzer, CFG construction, finding model

fixtures/
  src/main.rs        symbol retention tables and fixture module wiring
  src/x86_64.rs      exact x86_64 analyzer fixtures
  src/aarch64.rs     exact AArch64 renderer fixtures

tests/
  cli.rs             CLI integration tests
  fixtures.rs        fixture-driven analyzer regression tests

scripts/
  smoke.sh           quick end-to-end verification

examples/
  password-login/    reverse-engineering demo target

assembler is optimized for the real work of low-level inspection:

• point it at bytes or a binary
• narrow to the symbol or section you care about
• get stable, scriptable disassembly output
• optionally attach conservative semantic findings
• verify the whole stack against deterministic assembly fixtures

If you want a terminal-native disassembler with explicit architecture handling, disciplined output, and analyzer behavior that is tested against exact machine code instead of wishful abstractions, this repository is built for that workflow.