Skip to content

Binary Ninja Plugin

Use Metalware/Havoc debugging inside Binary Ninja with a full sidebar workflow: session control, MMIO stream editing, CPU state inspection, breakpoints/watchpoints, coverage overlays, taint overlays, and symbolic state fetches.

Install Quick Start Analysis Features

Install

  1. Copy or symlink plugin directory to Binary Ninja plugins path:
  2. Linux: ~/.binaryninja/plugins/havoc
  3. macOS: ~/Library/Application Support/Binary Ninja/plugins/havoc
  4. Windows: %APPDATA%\Binary Ninja\plugins\havoc
  5. Restart Binary Ninja.
  6. Open View > Sidebar and select Metalware Debugger if not already visible.

Requirements

  • Binary Ninja plugin API python3
  • Minimum Binary Ninja version 4000
  • Python dependency: requests
  • Plugin metadata version: 1.0.0

Quick Start

  1. Click the bottom status indicator (🔴 Metalware) or use sidebar connection flow.
  2. Enter server URL and API key.
  3. On success, status changes to connected and session controls are enabled.
  1. Enter Run ID.
  2. Pick testcase from searchable combo box.
  3. Click Connect in sidebar session row to load streams.

Use toolbar controls: - restart - continue - reverse/forward step by block - reverse/forward step by instruction

CPU panel updates registers, stack, PC navigation, and stream cursors.

Main Features

MMIO Streams

  • Stream table with Address, Symbol, Cursor, Size.
  • Editable hex detail grid with ASCII view.
  • Double-click stream rows for bulk edit dialog.
  • Fork, Trim, Save, and Refresh actions.
  • Unsaved-change tracking with modified stream indicators.

Save/Trim constraints

Save and Trim are enabled for forked inputs (forked_*) workflows.

CPU State and Memory

  • Editable register grid (writes via write_reg).
  • Stack view (reads from SP, resolves symbols when possible).
  • Editable memory hex view (writes via write_mem).
  • PC marker highlighting and auto-navigation to current PC.

Reverse stepping guard

After register or memory writes, reverse stepping controls are disabled until restart/rewind to avoid inconsistent reverse state.

Breakpoints and Watchpoints

  • Breakpoint list with add/remove/refresh.
  • Watchpoint list with add/remove/refresh (read / write).
  • Symbol-aware display when symbols are resolvable in current BinaryView.

Analysis Features

Coverage

  • Run-level or testcase-level instruction coverage load.
  • Highlights covered instructions in BinaryView.
  • Current PC and taint highlights take precedence.
  • Export CSV report with per-function coverage stats.

Taint

  • Asynchronous taint analysis request (get_tainted_instructions).
  • Highlights tainted instructions (purple).
  • Preserves/merges with coverage and PC highlighting rules.

Symbolic Tracking

  • Asynchronous symbolic-state fetch (get_symbolic_state).
  • Displays symbolic register expressions and icount context.

Session Persistence and Settings

Plugin stores local settings in:

.metalware_settings.json

Saved values include: - URL - API key - last run ID - last testcase

API Commands Used

Key debug commands used through <server>/api/.../debug-session/.../command:

  • control: step_block, reverse_step_block, step_instruction, reverse_step_instruction, step_mmio, continue, rewind
  • state/data: state, list_regs, read_reg, write_reg, read_mem, write_mem
  • break/watch: add_breakpoint, remove_breakpoint, list_breakpoints, add_watchpoint, remove_watchpoint, list_watchpoints
  • MMIO/input: get_input, write_input, fork_input
  • analysis: get_tainted_instructions, get_symbolic_state

Troubleshooting

No testcase list after entering Run ID

Verify run ID exists and server is reachable with your API key, then click session refresh (↻).

Coverage or taint controls fail

Ensure a debug session is active for the selected run/testcase first.

Connect dialog keeps failing

Validate URL format, API key, and that server /api/analyses is reachable from the Binary Ninja host.

License

Apache 2.0