If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/orhun/binsider shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 17 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live orhun/binsider repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/orhun/binsider.

What it runs against: a local clone of orhun/binsider — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in orhun/binsider | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of orhun/binsider. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/orhun/binsider.git
#   cd binsider
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of orhun/binsider and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "orhun/binsider(\\.git)?\\b" \\
  && ok "origin remote is orhun/binsider" \\
  || miss "origin remote is not orhun/binsider (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/elf/mod.rs" \\
  && ok "src/elf/mod.rs" \\
  || miss "missing critical file: src/elf/mod.rs"
test -f "src/tui/mod.rs" \\
  && ok "src/tui/mod.rs" \\
  || miss "missing critical file: src/tui/mod.rs"
test -f "src/app.rs" \\
  && ok "src/app.rs" \\
  || miss "missing critical file: src/app.rs"
test -f "src/args.rs" \\
  && ok "src/args.rs" \\
  || miss "missing critical file: src/args.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/orhun/binsider"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Binsider is a Rust-based terminal user interface (TUI) tool for static and dynamic analysis of ELF binaries, enabling reverse engineers to inspect binary headers, symbols, relocations, dynamic linking information, strings, and perform hexdumps all within an interactive ratatui-powered interface. It combines the elf crate for ELF parsing with lurk-cli for dynamic tracing and ptrace-based system call interception. Modular structure: src/main.rs and src/app.rs form the CLI and TUI entry points; src/elf/ (header.rs, dynamic.rs, symbols.rs, relocations.rs, notes.rs) contains ELF parsing logic; src/tui/ (mod.rs, command.rs, event.rs) handles the interactive terminal UI; src/tracer.rs wraps ptrace-based dynamic analysis. The prelude.rs centralizes common imports, and error.rs provides unified error handling via thiserror.

Security researchers, reverse engineers, and systems programmers who need to analyze compiled ELF binaries (Linux executables, shared libraries) without dropping into GDB or objdump—particularly those who prefer interactive terminal UIs over command-line flags and want to explore binary structure, linked libraries, and runtime behavior in one tool.

Actively maintained and production-ready: currently at v0.3.2 with dual MIT/Apache-2.0 licensing, full CI/CD pipelines (ci.yml, cd.yml, docker.yml), comprehensive GitHub workflows including dependabot automation, and a published website at binsider.dev. The Rust edition 2021 requirement (1.88.0 MSRV) and release process via cliff.toml indicates professional release management.

Low-to-moderate risk: the project has a single primary maintainer (orhun) visible in CODEOWNERS, but is actively developed with Docker, Nix, and multi-platform support. Dependency count is moderate (~20 direct deps) with reputable crates (ratatui, clap, elf, nix for ptrace). The dynamic-analysis feature gates the optional lurk-cli dependency, reducing risk for users who don't need runtime tracing. No explicit test directory visible in file listing suggests unit test coverage may be minimal.

Active development on release automation (RELEASE.md exists), website deployment (website.yml CI), and dependency updates via Dependabot (dependabot.yml). The project maintains a CHANGELOG.md and uses git-cliff (cliff.toml) for changelog generation, indicating frequent tagged releases. Recent additions likely include the lurk-cli integration for dynamic analysis (feature in Cargo.toml) and the Astro-based website at binsider.dev.

Clone and build: git clone https://github.com/orhun/binsider && cd binsider && cargo build --release. Install directly: cargo install binsider. Run on a binary: binsider /path/to/elf/binary to launch the interactive TUI.

Daily commands: Development: cargo run -- /path/to/binary (launches TUI on a binary file). Release build: cargo build --release produces optimized binary (LTO enabled, stripped). With dynamic analysis: cargo run --features dynamic-analysis -- /path/to/binary. Docker: docker build -t binsider . && docker run -it binsider /bin/bash.

• src/main.rs — Entry point for the CLI application; orchestrates argument parsing, file loading, and TUI initialization.
• src/elf/mod.rs — Core ELF binary parsing and analysis module; abstracts the elf crate and provides the primary analysis interface.
• src/tui/mod.rs — TUI application framework using ratatui; manages event loop, state, and rendering pipeline for interactive analysis.
• src/app.rs — Application state machine and command handler; coordinates data flow between file analysis and UI updates.
• src/args.rs — CLI argument definitions using clap; defines all user-facing options and modes (static/dynamic analysis, output formats).
• Cargo.toml — Project metadata and dependency declarations; defines the dynamic-analysis feature flag and core ratatui/elf dependencies.

Add a new ELF section analyzer

1. Create a new module under src/elf/ (e.g., src/elf/my_section.rs) following the pattern of symbols.rs or dynamic.rs. (src/elf/my_section.rs)
2. Implement parsing logic using the elf crate's APIs; define structs matching ELF spec. (src/elf/my_section.rs)
3. Add a pub fn parse_my_section() entry point and export from mod.rs. (src/elf/mod.rs)
4. Call the parser from the main ELF analysis function (likely in src/elf/mod.rs's main struct). (src/elf/mod.rs)
5. Add a UI panel in src/tui/ui.rs to display the results; add state tracking in src/tui/state.rs. (src/tui/ui.rs)

Add a new TUI view/tab

1. Add a new variant to the view enum in src/tui/state.rs (e.g., MyNewView). (src/tui/state.rs)
2. Implement rendering logic in src/tui/ui.rs as a new function following existing patterns. (src/tui/ui.rs)
3. Add event handling (keyboard shortcuts) in src/tui/command.rs to switch to and navigate the new view. (src/tui/command.rs)
4. Update src/tui/event.rs if you need new custom event types for the view. (src/tui/event.rs)
5. Test navigation and rendering by running cargo run and verifying in the TUI. (src/main.rs)

Enable or extend dynamic analysis

1. Enable the dynamic-analysis feature in Cargo.toml (enabled by default via lurk-cli). (Cargo.toml)
2. Enhance src/tracer.rs with additional syscall filters, aggregation, or output formatting. (src/tracer.rs)
3. Add a UI panel in src/tui/ui.rs to display dynamic analysis results (syscall timeline, counts, etc.). (src/tui/ui.rs)
4. Update src/app.rs to trigger dynamic analysis when a flag is passed or view is selected. (src/app.rs)

Add a new CLI output format (JSON, CSV, etc.)

1. Add a new OutputFormat variant to src/args.rs (e.g., Json, Csv) using clap enum derivation. (src/args.rs)
2. In src/main.rs, add a match arm to handle the new format after analysis completes. (src/main.rs)
3. Create serialization logic (or use serde) to transform analysis results into the target format. (src/app.rs)
4. Print the formatted output to stdout or write to a file as specified by the user. (src/main.rs)

• Rust + ratatui — Memory-safe, high-performance TUI framework for interactive binary analysis without GC overhead or segfaults.
• elf crate — Leverages existing, battle-tested ELF parsing to avoid reinventing binary format handling and spec compliance.
• clap (CLI args) — Declarative, type-safe argument parsing with automatic help text generation and environment variable support.
• lurk-cli (optional dynamic analysis) — Reuses existing syscall tracing tool to provide runtime behavior insights without writing a custom tracer.
• thiserror — Reduces boilerplate in error type definitions while maintaining idiomatic Rust error handling.

• Single-threaded TUI with blocking I/O

  • Why: Simplifies state management and eliminates concurrency bugs; acceptable because ELF parsing is CPU-bound and fast.
  • Consequence: Large binaries (>100MB) may briefly freeze the UI during parsing; acceptable for typical reverse-engineering workloads.

• Dynamic analysis as optional feature (not always enabled)

  • Why: Reduces binary size and compile time for users who only need static analysis; decouples tracer complexity.
  • Consequence: Users must opt-in to dynamic analysis; adds cognitive load for feature discovery.

• TUI-first, output-later design (no streaming JSON during interactive session)

  • Why: Keeps TUI code focused on rendering; defers structured output to CLI mode.
  • Consequence: Users cannot currently export filtered TUI results; must re-run CLI in non-interactive mode to get JSON.

• undefined

  • Why: undefined
  • Consequence: undefined

Ptrace requirement: dynamic analysis (lurk-cli feature) requires ptrace capability, typically needing elevated privileges or CAP_SYS_PTRACE on Linux. Arch-specific issues: the nix crate's ptrace bindings are Linux-specific; macOS/Windows support may be limited. String extraction: rust-strings crate performs heuristic-based string detection; not guaranteed to find all ASCII/Unicode strings depending on compiler optimizations. Terminal detection: termbg.rs detects background color to auto-select logo (dark/light); may fail on unsupported terminals. No stdlib vendoring: Cargo.lock is committed but Cargo.toml lacks workspace or patch sections; upgrades are edge-driven by Dependabot.

• ELF (Executable and Linkable Format) — Binsider's entire purpose is parsing and visualizing ELF binary structure; understanding ELF headers, sections, segments, symbols, and relocations is fundamental to using and extending this tool
• Ptrace (Process Tracing) — The dynamic-analysis feature uses nix::ptrace to intercept syscalls and inspect process state at runtime; critical for understanding how Binsider monitors binary execution
• Position-Independent Code (PIE) & ASLR — Modern ELF binaries use PIE and Address Space Layout Randomization; Binsider's analysis must handle relocations and symbol resolution differently for PIE vs. static binaries
• Dynamic Symbol Resolution & Relocations — src/elf/relocations.rs and src/elf/dynamic.rs parse GOT (Global Offset Table) and PLT (Procedure Linkage Table) entries; critical for understanding how binaries resolve external symbols at load time
• TUI Event Loop Pattern — Binsider uses ratatui's event-driven architecture (src/tui/event.rs, src/tui/command.rs); understanding crossterm events, terminal drawing cycles, and state mutations is essential for UI modifications
• String Heuristics & Encoding Detection — The rust-strings dependency uses entropy-based heuristics to extract printable strings from binary; Binsider's string inspection feature relies on these heuristics to find hardcoded data
• Dependency Tree Walking (lddtree) — Binsider uses lddtree to recursively resolve shared library dependencies and display the full linking tree; understanding how glibc ld.so resolves library paths is useful for analyzing binary dependencies

• radare/radare2 — Comprehensive reverse engineering framework with binary analysis, disassembly, and debugging; Binsider targets TUI-focused interactive analysis as a lighter alternative
• WerWolv/ImHex — Hex editor and binary analysis tool with plugin system; overlaps on binary inspection but ImHex emphasizes hex viewing and memory patching over ELF metadata
• sharkdp/hexyl — Terminal-based hex viewer in Rust; Binsider uses heh crate for hexdumps and complements hexyl by adding ELF structure analysis
• strace/strace — System call tracer; Binsider's dynamic analysis (lurk-cli + nix ptrace) provides similar tracing but integrated into interactive TUI rather than CLI-only output
• ratatui-org/ratatui — Direct dependency providing TUI framework; understanding ratatui's event loop and widget composition is essential for modifying Binsider's UI

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for ELF parsing across different binary types

The repo has minimal test coverage (only tests/app.rs). The src/elf/ module handles critical parsing logic (header.rs, dynamic.rs, symbols.rs, relocations.rs, notes.rs) but lacks dedicated unit/integration tests. Adding tests for different ELF types (static/dynamic binaries, stripped/unstripped, different architectures) would catch regressions and improve maintainability for contributors working on binary analysis.

• [ ] Create tests/elf_parsing.rs with test fixtures (small ELF binaries in tests/fixtures/)
• [ ] Add tests for src/elf/header.rs parsing (magic number validation, architecture detection)
• [ ] Add tests for src/elf/symbols.rs symbol table extraction with stripped vs unstripped binaries
• [ ] Add tests for src/elf/dynamic.rs dynamic linking information parsing
• [ ] Document test setup in CONTRIBUTING.md

Add GitHub Actions workflow for security vulnerability scanning

The repo has deny.toml configured (dependency auditing) but no corresponding GitHub Actions workflow to enforce it in CI. Currently .github/workflows/ has ci.yml, cd.yml, docker.yml, flake-update.yml, and website.yml, but no security scanning. With a sensitive domain like binary analysis, automated vulnerability detection is high-value for both contributors and users.

• [ ] Create .github/workflows/security.yml with cargo-audit step using deny.toml
• [ ] Add cargo-deny check step to validate Cargo.lock against deny.toml rules
• [ ] Include SBOM generation (cargo-sbom) for supply chain transparency
• [ ] Add step to report security findings and fail on high-severity issues
• [ ] Document security workflow in CONTRIBUTING.md

Refactor TUI module into sub-modules for better separation of concerns

The src/tui/ module has grown to include ui.rs (rendering), state.rs (state management), command.rs (input handling), event.rs (event loop), and widgets/ subdirectory. The main src/tui/mod.rs likely orchestrates all these. Splitting into clearer sub-modules would reduce cognitive load for contributors adding new TUI features and improve code discoverability.

• [ ] Create src/tui/render.rs and move rendering logic from ui.rs (widget composition, layout)
• [ ] Create src/tui/input.rs to consolidate command.rs and input handling from event.rs
• [ ] Create src/tui/viewport.rs to manage navigation/focus state separate from general state.rs
• [ ] Update src/tui/mod.rs exports and document the module architecture in ARCHITECTURE.md
• [ ] Add examples/tui_custom_widget.rs demonstrating how to add new TUI components

• Add unit tests for src/elf/header.rs and src/elf/symbols.rs parsing—currently no visible test/ directory; these modules deserialize binary data and lack test coverage for edge cases (malformed ELF headers, symbol table boundaries).
• Expand examples/demo.rs with additional ELF analysis scenarios (e.g., parsing a static binary, a stripped binary, a PIE executable)—currently single demo; would help contributors understand ELF feature variety.
• Document the TUI keybindings and command flow in CONTRIBUTING.md—src/tui/command.rs has command handling but no contributor guide explains the event loop or how to add new navigation commands.

• Medium · Permissive ptrace Permissions via nix Crate — Cargo.toml (nix dependency with ptrace/signal features). The codebase uses the 'nix' crate with 'ptrace' and 'signal' features enabled for dynamic binary analysis. This allows the application to attach to and trace other processes. While necessary for the tool's functionality, it requires careful handling to prevent privilege escalation or unauthorized process inspection. Fix: Ensure ptrace operations are properly sandboxed, validate user permissions before allowing process tracing, document security implications in user documentation, and consider running with minimal necessary privileges.
• Medium · Unsafe Binary File Parsing — src/elf/mod.rs, src/elf/header.rs, src/elf/symbols.rs, src/elf/dynamic.rs, src/elf/relocations.rs, src/elf/notes.rs. The application parses untrusted ELF binaries using the 'elf' crate (0.8.0). Malformed or malicious ELF files could potentially trigger parsing vulnerabilities, buffer overflows, or denial of service attacks. Fix: Implement comprehensive input validation before processing ELF files, set resource limits for parsing operations, keep the 'elf' dependency updated, and consider fuzzing the parser with malformed binaries.
• Low · Outdated Rust Version — Cargo.toml (rust-version = "1.88.0"). The MSRV (Minimum Supported Rust Version) is set to 1.88.0, which is very recent. While this ensures modern language features, it may limit distribution and user adoption. The Docker build uses Rust 1.88-slim-bullseye, which is appropriate. Fix: Consider evaluating if a slightly older MSRV would be acceptable to reach more users without compromising security features. Regularly update the MSRV as new stable versions are released.
• Low · Missing Input Sanitization in TUI Components — src/tui/ui.rs, src/tui/widgets/. The TUI components (ratatui, tui-input, tui-popup) process user input and display binary file contents. While TUI applications have lower XSS risk than web apps, malicious binary content with special characters could potentially cause rendering issues or terminal escape sequence injection. Fix: Sanitize all binary content before display, filter control characters and ANSI escape sequences in user-facing output, and validate file content before rendering.
• Low · Unrestricted Web Browser Launch — Cargo.toml (webbrowser = "1.0.6"). The 'webbrowser' crate is used to open URLs (likely for documentation/links). This could potentially be exploited if user input influences the URLs being opened. Fix: Whitelist allowed URLs and domains before passing to the webbrowser crate, validate and sanitize any user-provided URLs, and log all external URL launches for audit trails.
• Low · System Information Disclosure — Cargo.toml (sysinfo with user feature). The 'sysinfo' crate is included with user feature enabled, which exposes system information like running processes, CPU, memory, and user accounts. Fix: Restrict access to system information based on user privileges, clearly document in the tool what system information is collected and displayed, and consider making this feature optional.
• Low · Missing Security Headers and Hardening Documentation — SECURITY.md. While SECURITY.md exists, it only specifies supported versions for the 0.1.x branch (which is outdated). The current version is 0.3.2. Security advisory procedures are documented but version support matrix is incomplete. Fix: Update SECURITY.md to reflect current version support (0.3.x), specify security update timelines, document known security limitations of the tool, and establish a clear vulnerability disclosure process with SLA.
• Info · Docker Configuration Best Practices — Dockerfile. The Dockerfile uses good security practices (non-root user 1000:1000, minimal base image), but could be enhanced further with additional hardening measures. Fix: Consider using distroless or alpine base images for smaller attack surface, add explicit USER directive earlier in build

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.