Red Harness

An evidence-bound static reverse-engineering harness for binaries you own or are authorized to test.

It is an MCP server (rh mcp, stdio) with 14 tools: static analysis through an IDA or Ghidra engine (functions, strings, xrefs, decompile, disassemble, raw byte and raw string reading), controlled execution in Windows Sandbox when the scope manifest allows it, a sandboxed compute tool for the model's own Python, and fix verification. Every claim a model records has to cite evidence ids, quotes and addresses; a claim verifier (version 17) checks them against the evidence ledger and rejects or downgrades claims it cannot support. Behavior claims are proven only by a controlled run, not by a value appearing in code. Whatever was not examined is reported as unknown, never as "clean".

Design notes are in docs/design/, the tool surface is in docs/usage-mcp.md and docs/tool-design.md, and the privacy rules for tracked files are in docs/privacy-guard.md. Third-party attributions: NOTICE.

Editions

This repository is the Core edition (Apache-2.0). Pro is a separate commercial edition. The MCP tool surface (14 tools) is the same in both; Pro adds capabilities behind the same tools and a few extra commands.

In the Core build the Pro-only entry points answer in a fixed way: run_controlled with observe returns DYNAMIC_BACKEND_UNAVAILABLE ("premium feature not included in this build"), the Pro CLI commands print a premium notice and exit with status 2, and the driver facts in target_open are {"available": false, "note": "premium feature not included in this build"}. To ask about Pro: contact: see repository profile.

Related MCP server: Antardrishti

Requirements

• Windows 10 or 11, 64-bit (developed and tested on Windows 10 Pro). The server, the engines and every static tool run on any edition.

• Python 3.12 (py -3.12). The only runtime dependency is the mcp SDK, pinned and installed by pip.

• One analysis engine: Ghidra (free) or IDA Pro (see "Engines"). No MCP tool works without an engine, because target_open opens the target through it.

• Windows Sandbox, only for the two tools that run code (run_controlled and compute). Windows Sandbox is part of Windows 10/11 Pro, Enterprise and Education (not Home); it needs hardware virtualization enabled in the firmware and the optional Windows feature "Windows Sandbox" switched on (restart required). Without it those two tools return SANDBOX_UNAVAILABLE and everything else keeps working. The sandbox gets 2048 MB of memory by default (RH_SANDBOX_MEMORY_MB, 512 to 16384).

  • compute also needs a pinned embeddable CPython, installed once: rh compute-runtime prints the download address and the expected SHA-256, then rh compute-runtime install python-3.12.10-embed-amd64.zip.

• Memory: the Ghidra engine runs a JVM with a 4 GB heap (6 GB job limit); the IDA engine is limited to 6 GB as well.

Engines

Every MCP tool needs an analysis engine; choose one with rh mcp --engine ghidra or rh mcp --engine ida. Without the flag the server starts the IDA engine. A requested engine that is not usable stops the server with the reason on stderr and in the error answer to the client's initialize request; there is no silent fallback to the other engine.

Ghidra (free).

1. Ghidra 12.1.3 (the version this project is tested with): download the zip from https://github.com/NationalSecurityAgency/ghidra/releases and extract it anywhere.

2. A JDK 21 (for example Eclipse Temurin 21), with java on PATH or JAVA_HOME set. Check with java -version in a new terminal.

3. Tell the server where Ghidra is: set RH_GHIDRA_DIR (or GHIDRA_INSTALL_DIR) to the extracted folder, the one that contains support\analyzeHeadless.bat. Without either variable the server looks for ghidra_* on your Desktop, for ghidra* in your user folder and in %ProgramFiles%, and for C:\ghidra* (newest name first).

4. Start the server with rh mcp --engine ghidra. The first open of a target runs Ghidra's full analysis once (minutes for a large binary; about two and a half minutes for a 200 KB system program on a desktop PC); the result is cached under the data root and later opens and queries reuse it.

IDA. IDA 9.x with a licence that includes idalib (IDA's headless library): the Pro editions. IDA Home and Classroom are listed by Hex-Rays as shipping idalib since 9.4; not yet tested by us. The Python package idapro that talks to it is deliberately not a dependency of this project (its publisher on PyPI is unverified); install it from the wheel in your IDA installation into the same virtual environment as redharness:

.venv\Scripts\pip install "<IDA>\idalib\python\idapro-0.0.9-py3-none-any.whl"

<IDA> is for example C:\Program Files\IDA Professional 9.4. Use the exact file name you find in that folder (dir "<IDA>\idalib\python"); pip does not accept a * wildcard there. Do not run py-activate-idalib.py. The IDA folder is found automatically under %ProgramFiles%\IDA Professional* or from RH_IDA_DIR / IDADIR. The engine runs IDA in a separate Python process; if that Python is not the one with idapro, set RH_IDA_PYTHON to it. Without idapro, target_open fails with TOOL_MISSING and a message that says exactly this.

What works without any engine: none of the 14 MCP tools. The standalone scripts in scripts/ need no engine and execute nothing (see "Standalone static CLIs"), and so does rh compute-runtime.

Quickstart

This walk-through uses Ghidra and runs the same calls a model makes, from a small Python client that ships with the project. Use a program you built or are authorized to analyze; below it is C:\path\to\target.exe.

py -3.12 -m venv .venv
.venv\Scripts\pip install -e .
set RH_GHIDRA_DIR=C:\path\to\ghidra_12.1.3_PUBLIC

(set is for cmd.exe; in PowerShell use $env:RH_GHIDRA_DIR = "C:\path\to\ghidra_12.1.3_PUBLIC". Skip it if Ghidra sits in one of the folders listed under "Engines".)

1. SHA-256 of the target, lowercase (the manifest rejects upper case):

   powershell -NoProfile -Command "(Get-FileHash 'C:\path\to\target.exe' -Algorithm SHA256).Hash.ToLower()"

2. Write the scope manifest scope.json next to it. The hash binds the manifest to this exact file; basis is owner or authorized-test; allowed_operations lists what the session may do (static is the minimum; run_controlled and compute must be added explicitly); an optional "expires": "2027-12-31" limits its lifetime.

   {
     "schema": "rh.scope/1",
     "target_sha256": "<the lowercase hash from step 1>",
     "authorization": {
       "declared_by": "Your Name / Your Company",
       "basis": "owner",
       "statement": "This binary belongs to us; static analysis is authorized."
     },
     "allowed_operations": ["static"]
   }

3. Run the client (first open: Ghidra analyses the target once):

   .venv\Scripts\python scripts\quickstart_client.py C:\path\to\target.exe scope.json --engine ghidra

   It starts rh mcp --engine ghidra, lists the tools and makes five calls: target_open(target_path, manifest_path), strings(limit=20, detail="full"), claim_add(kind="observation", text, evidence_ids, atoms) quoting the first string it got back, coverage() and report_build(). It ends with the path of the Markdown report, under <data root>\jobs\<job id>\report\. A model client makes exactly these calls with the arguments named above; the claim_add atoms are {"type":"quote","evidence_id":"ev_...","text":"<string>"} and {"type":"address","evidence_id":"ev_...","value":"0x..."}.

Connect an MCP client

Use absolute paths. The server needs the engine settings in its environment.

Claude Code: copy .mcp.json.example to .mcp.json in your project folder, replace the placeholder paths, start Claude Code and approve the red-harness server with /mcp.

{
  "mcpServers": {
    "red-harness": {
      "type": "stdio",
      "command": "C:\\path\\to\\red-harness\\.venv\\Scripts\\rh.exe",
      "args": ["mcp", "--engine", "ghidra"],
      "env": {"RH_GHIDRA_DIR": "C:\\path\\to\\ghidra_12.1.3_PUBLIC", "RH_DATA_ROOT": "C:\\path\\to\\RedHarnessData"}
    }
  }
}

OpenAI Codex CLI (~/.codex/config.toml):

[mcp_servers.red-harness]
command = 'C:\path\to\red-harness\.venv\Scripts\rh.exe'
args = ["mcp", "--engine", "ghidra"]
env = { RH_GHIDRA_DIR = 'C:\path\to\ghidra_12.1.3_PUBLIC', RH_DATA_ROOT = 'C:\path\to\RedHarnessData' }

Any other stdio MCP client: run the command C:\path\to\red-harness\.venv\Scripts\rh.exe with the arguments mcp --engine ghidra and the environment variables above. The protocol runs over the process's stdin and stdout (one JSON-RPC message per line), so nothing else may write to stdout. scripts/quickstart_client.py is a complete example client built on the official mcp SDK. The server side was verified with that SDK client; the client entries above follow those clients' documented formats.

If a client only says "connection closed", start the same command in a terminal: the reason is printed on stderr.

Development and tests

Install with the test extra and run the default suite (no engine and no Windows Sandbox needed):

py -3.12 -m venv .venv
.venv\Scripts\pip install -e .[dev]
.venv\Scripts\python -m pytest -m "not heavy"

• heavy tests need a real Ghidra/IDA or Windows Sandbox; they are not part of the default run.

• Unit tests point RH_DATA_ROOT at a temp directory; RedHarnessData or any other directory need not exist beforehand.

• Real Windows Sandbox tests run only with RH_ALLOW_REAL_SANDBOX=1 (otherwise skipped).

• Engine paths and the idapro install are described under "Engines" above and in docs/usage-mcp.md.

Standalone static CLIs

Read-only helper in scripts/ that needs no engine, no Windows Sandbox and executes nothing: file_strings.py (it prints its usage in its module docstring).

Scope

Use it only on targets you own or are explicitly authorized to test. The scope manifest is required, binds the target SHA-256 and lists the effects (for example run_controlled, compute) a session may use.