RE-harness

RE-harness is a Windows PE static-analysis harness implemented as an OpenCode plugin. The V5 profile provides a model with structured, read-only IDA/IDASQL tools and never executes the selected sample.

Requirements

• macOS or Linux (x86_64 or arm64) with Python 3.12;
• IDA Professional 9.3 with Hex-Rays;
• IDASQL 0.0.18.1;
• OpenCode;
• CMake, Ninja, and a C++20 compiler for the bundled NeverD/LLVM fallback;
• Node.js 22 or newer for the TypeScript plugin regression test.

IDA, Hex-Rays, IDASQL, and OpenCode are not distributed with this project.

Installation

git clone --recurse-submodules https://github.com/thatskriptkid/re-harness.git
cd re-harness
python3.12 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/re-harness init-config

The local config/ directory is ignored by Git. init-config copies safe templates from config.example/ without overwriting existing settings. Then configure your endpoint, model ID, artifact root, and allowed sample directories in config/providers.yaml and config/settings.yaml. API keys belong only in the ignored .env file.

On Debian or Ubuntu, the native components require at least build-essential, clang, lld, cmake, ninja-build, git, zlib1g-dev, pkg-config, and jq. Install Python 3.12 and Node.js 22 from a source appropriate for your distribution. NeverD uses a pinned LLVM project and is not compatible with an arbitrary system LLVM; LLVM 14, for example, is insufficient. GCC 12 and GCC 13 builds have been verified on Linux.

OpenCode can be installed into a user-owned prefix without sudo:

npm install -g --prefix "$HOME/.local" opencode-ai
export PATH="$HOME/.local/bin:$PATH"

The harness looks for idasql and idat in PATH, beside each other, in the standard IDA 9.3 locations on macOS and Linux, and in ~/.local/bin. For a custom installation, set the paths explicitly:

export RE_HARNESS_IDASQL=/opt/ida-9.3/idasql
export RE_HARNESS_IDAT=/opt/ida-9.3/idat

v5 doctor does not start IDA. On a host without IDA it reports an honest exists: false result with the reason instead of returning a placeholder macOS path.

Verified Linux matrix

Environment	Host or guest	Verified coverage
Proxmox VM	Ubuntu 24.04.4 LTS, x86_64, 8 CPU / 8 GiB	Clean Python and Node installation, OpenCode 1.18.18, NeverD/LLVM, X86/X86-32 lifting, and the complete CFF regression and equivalence suite
Apple Container	Debian 12, Linux arm64, 6 CPU / 8 GiB	Clean Python and Node installation, native ARM64 NeverD/LLVM and CFF, cross-target X86 ELF, and Windows x64 COFF equivalence

Both Linux environments were tested without IDA or IDASQL. Installation, imports, the CLI, OpenCode configuration, tests, and native components work, while v5 doctor clearly reports the missing commercial dependencies. Real PE analysis still requires the Linux versions of IDA 9.3, Hex-Rays, and IDASQL.

Running

.venv/bin/re-harness v5 doctor
.venv/bin/re-harness v5 launch /path/to/sample.exe

v5 launch selects a PE, prepares an IDA database, generates a project-local opencode.json, and opens OpenCode with the re-static-v5-ida agent. Only the IDA tools belonging to this profile are exposed in OpenCode. Change the model in config/providers.yaml; the next launch regenerates opencode.json.

For a crackme, switch the agent and opening prompt so the model hunts flags instead of writing a malware behavior report. Analysis stays read-only: no execution, debugger, or patching.

.venv/bin/re-harness v5 launch --mode crackme /path/to/crackme.exe
.venv/bin/re-harness v5 batch-opencode --mode crackme /path/to/crackmes \
  --duration-hours 4 --case-timeout-minutes 20 --max-samples 10

For an isolated comparison with the upstream ida-pro-mcp, use the separate profile:

.venv/bin/re-harness ida-mcp launch /path/to/sample.exe

v5 launch excludes the MCP server and its tool schemas from the context. ida-mcp launch enables idalib-mcp --stdio, selects the separate re-static-ida-mcp agent, and prevents it from using V5 tools.

A long-running batch preserves raw OpenCode events, the session export, the conversation, final response, facade and backend events, the FLIRT manifest, and complete local artifacts:

.venv/bin/re-harness v5 batch-opencode /path/to/corpus \
  --duration-hours 12 --case-timeout-minutes 5 --max-samples 500 \
  --max-file-size-mb 30

Validation

.venv/bin/ruff check .
.venv/bin/pytest -q tests
(cd .opencode && node --experimental-strip-types --test ../tests/opencode_v5_plugin.test.ts)

flirtdb is a separate signature submodule and is never modified by the harness. If the repository was cloned without --recurse-submodules, run:

git submodule update --init --recursive

License and samples

RE-harness is distributed under AGPL-3.0-only. The modified NeverD source is in third_party/NeverD; its upstream license, pinned commit, and integration notes are preserved next to the code. See THIRD_PARTY_NOTICES.md for details.

Malware, crackmes, IDA databases, dumps, and analysis results are not included in the repository. Use only samples that you are legally authorized to analyze.