Adversarial REA: Evidence-First Binary Triage

Local native telemetry, bounded MCP tools, and unverified review candidates.

Start with what the binary says. Mark everything else as a question.

MCP Guide · Tool Catalog · Showcases

Quick start · How Adversarial REA works · What you can analyze · Swarm roles · Showcases · Exploit chains · FAQ · Documentation

node bin/cli.js analyze ./target.elf --no-chain

Need a first-pass review of a native binary without source code? Connect your MCP client to Adversarial REA or use adv-rea from a terminal. It extracts bounded symbols, strings, sections, and mitigation signals from local files, then offers follow-up questions rather than claiming that a risky import proves a bug.

Use it to narrow manual review: identify suspicious imports, inspect observed call instructions, and distinguish unknown mitigations from observed absences. Native ELF and Mach-O extraction use host tools; PE headers and mitigation flags can be previewed without host PE tools. Packages, archives, WebAssembly, firmware images, text, and JavaScript receive bounded metadata inspection, not deep code or exploit analysis.

Quick start

Adversarial REA requires Node.js >= 22.0.0, npm, and standard host binary utilities (objdump, nm, strings, file; plus otool on macOS).

git clone https://github.com/Cultistsid/adversarial-rea-mcp.git
cd adversarial-rea
npm install

Set up your MCP client

Add adversarial-rea to your MCP client configuration (mcp.json):

{
  "mcpServers": {
    "adversarial-rea": {
      "command": "node",
      "args": ["/absolute/path/to/adversarial-rea/src/mcp/main.js"],
      "env": {}
    }
  }
}

Restart your MCP client after saving. All 12 inspection tools register over stdio JSON-RPC 2.0 and require zero external API keys.

Ask your agent

Run analyze_binary and trace_calls on ./target.elf. Compare import observations
with actual call instructions; do not claim an input flow or bug from either.

Replace ./target.elf with a native ELF or Mach-O file. For a script or container, use inspect_carrier instead. PE code extraction depends on your host objdump/nm build.

Use the terminal

Run local inspection without a key; the separate candidate-triage commands use a remote reasoning service and require its API key.

# Offline metadata for APK/IPA/JAR/ASAR, Wasm, JS/text, PE, firmware, or .app bundles
node bin/cli.js inspect ./package.apk --limit 50

# Reproduce a declarative fixture flow in memory, not a native program
node bin/cli.js inspect test/fixtures/flow-direct.flow.json --flow-fixture

# Offline call sites on native files, or byte-verified gadget candidates on ELF64 x86_64
node bin/cli.js inspect ./target.elf --calls --gadgets

# Candidate analysis on a native ELF file
node bin/cli.js analyze ./target.elf --agents 8 --trace-calls --no-chain --output results.json

# Deploy a targeted agent swarm with custom mission and offensive roles
node bin/cli.js swarm ./target.elf \
  --mission "Review possible heap corruption and address leaks" \
  --roles mem-corrupt,mitigation-bypass

# Triage selected CWE patterns (candidate findings only)
node bin/cli.js hunt ./target.elf --patterns UNCHECKED_BOUNDS,FORMAT_STRING --critical-only

# Attack surface enumeration only (vectors, trust boundaries, primitives)
node bin/cli.js surface ./libtarget.so --type elf

To install the adv-rea command globally for regular terminal use:

npm install --global .
adv-rea --help

Related MCP server: BinSight

How Adversarial REA works

The native analyzer reads a regular file (up to 64 MiB), identifies its magic bytes, and invokes local tools with argument arrays, timeouts, and output limits. The separate carrier inspector reads bounded headers and indexes without unpacking or executing content. A separate fixture evaluator follows explicit single-argument steps and repeats a deterministic in-memory sink observation; it does not run binaries. Extraction failures remain visible; unknown mitigation status is not converted to "off." Optional reasoning only receives a bounded structural summary, never extracted secret-like string values by default.

1. Local telemetry (BinaryAnalyzer, CarrierInspector) — Native metadata or metadata-only previews for other file formats; carrier previews do not imply code parsing.

2. Instruction evidence (CallSiteExtractor, GadgetCandidateFinder) — Opt-in direct call instructions with target hashes and versioned evidence IDs; selected ELF64 x86_64 gadget candidates are checked against executable file bytes. Neither proves reachable input flow or exploitability.

3. Review hypotheses (AttackSurfaceEnumerator, VulnHunter) — Suggests possible vectors and CWE follow-up checks. Triage scores and remote answers remain unverified.

4. Evidence gate (ExploitChainBuilder) — Requires independently verified native flow, stage references, and an observed native trigger trace. Those native flow/trigger producers are not implemented; fixture-only records are excluded, so ordinary analyses return no validated exploit chain.

What you can analyze

The file signature decides the native format; --type only asserts an expected native format. Use inspect_carrier or adv-rea inspect for metadata-only carriers; the native analyze_binary tool still rejects them.

Large files (over 64 MiB) and non-regular files are rejected; flow fixtures have a separate 16 KiB / 32-step limit. Each native subprocess has a 15-second timeout and a 2 MiB output cap; truncated or unavailable evidence is not treated as proof of safety. For an MCP client that should see only one directory, set ADV_REA_ALLOWED_ROOTS=/absolute/path/to/targets in its server environment. Without it, any readable local regular file can be submitted for inspection.

MCP Tool Catalog

Every tool exposed by src/mcp/main.js runs locally with zero network dependencies:

Responses are capped at 64 KiB. get_strings intentionally requires reveal_sensitive: true to show potentially sensitive string categories; handle that output locally.

Platform-Normalized Mitigation Scoring

check_security reports null when any required check is unknown. Where checks succeed, RELRO is ELF-only and excluded from the Mach-O denominator.

Agent swarm roles

Eight specialist roles are available for adv-rea swarm; adv-rea analyze selects triage patterns rather than deploying all eight. A role's output is a review hypothesis, not proof.

Vulnerability Patterns (CWE Coverage)

The --critical-only CLI flag filters the pattern's triage priority, not a verified finding's severity.

Showcases

The visual panels are illustrative, not generated results. No addresses, chain scores, or exploit stages in the artwork correspond to a validated fixture.

Native ELF import triage (available)

Run analyze_binary and find_dangerous_patterns to identify printf/strcpy imports for review, then trace_calls to locate decoded calls. Verify the controlled data flow and trigger separately; even an observed call does not prove a bug.

Electron IPC boundary mapping (planned)

inspect_carrier lists bounded ASAR file entries. IPC brokers, renderer messages, and sandbox boundaries still require dedicated parsing and observed evidence.

Firmware header preview

inspect_carrier reports ELF magic markers and limited plausible header fields in a raw image. Even a plausible header does not prove an embedded executable or extract firmware; analyze independently extracted native files separately.

Exploit chain templates

Six chain definitions exist for future evidence-backed work. Only four have draft scaffold templates; PRIV_ESC_WINDOWS and AUTH_BYPASS are explicitly unsupported. Local call-site and constrained gadget evidence are available, but no implemented producer establishes end-to-end native input flow or an observed native trigger. Synthetic fixture replay does not satisfy that requirement. The generator returns a blocked result when evidence or required facts are missing; it does not export a runnable exploit.

import { AdversarialREA } from 'adversarial-rea';

const rea = new AdversarialREA({
  maxAgents: 8,
  aggressiveMode: true,
  parallelAnalysis: true,
  timeout: 300000
});

const analysis = await rea.analyzeTarget('./target.elf', {
  type: 'elf',
  buildChains: true
});

console.log('Candidate triage score:', analysis.attackSurface.candidate_score);
console.log('Review candidates:', analysis.candidates.length);
console.log('Verified vulnerabilities:', analysis.vulnerabilities.length);

FAQ

Any client or agent runtime that supports local MCP servers over stdio JSON-RPC 2.0. Point the client at node /absolute/path/to/adversarial-rea/src/mcp/main.js in mcp.json.

No. The MCP server (src/mcp/main.js) executes local binary inspection tools (objdump, nm, strings, otool, file) directly on disk and requires zero API keys or network access. API credentials are only used when running standalone multi-agent LLM swarms via the adv-rea CLI or AdversarialREA SDK class.

No. Core binary extraction needs compatible host utilities (objdump, nm, strings, file, and otool on macOS). The analyzer detects rizin and radare2 but does not use them for deep decompilation.

The binary stays local. CLI reasoning sends bounded metadata (format, sizes, import names, mitigation signals, and string category counts) to the configured endpoint; no extracted string values are included by default. A user can explicitly request raw sensitive strings through the local MCP get_strings tool with reveal_sensitive: true.

Run the unit and live-binary integration suites with:

npm test                   # deterministic unit tests (zero network calls)
npm run test:integration   # Live binary & stdio MCP JSON-RPC integration tests
npm run test:all           # Full suite

Documentation

• MCP Server Usage Guide: registration, tool parameters, example prompts, and extraction-to-findings workflow.

• Agent Skill Specification: offensive methodology, surface scoring formula, and JSON reporting schema.

• MCP Server Manifest: machine-readable capability and tool declarations.

Star history

License

MIT