Adversarial REA: Offensive Binary Exploitation Harness

One MCP server and multi-agent swarm engine for attack surface mapping, vulnerability hunting, and exploit chain synthesis.

Drop a binary in. Extract ground-truth telemetry. Weaponize findings into multi-stage chains.

MCP Guide · Tool Catalog · Showcases

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

npx adv-rea analyze ./target.elf --agents 8

[!IMPORTANT] Get Adversarial REA from Cultistsid/adversarial-rea. All binary telemetry extraction (objdump, nm, strings, otool, file) runs locally on your machine against real on-disk binaries—never fabricated or hallucinated.

Need to tear apart a native binary, driver, mobile package, or firmware image without source code? Connect your MCP client to Adversarial REA or launch adv-rea straight from your terminal. It inspects the binary on disk, extracts real symbols, sections, classified strings, and exploit mitigations, and deploys an 8-role parallel swarm to hunt vulnerabilities and assemble multi-stage exploit chains.

Adversarial REA bridges deterministic binary inspection (objdump, nm, strings, otool, file) with multi-agent offensive workflows across ELF, Mach-O, PE, Android APK, iOS IPA, Electron ASAR, WebAssembly, and raw firmware targets. Every reported finding includes its CWE classification, trigger conditions, mitigation posture, and exploitation feasibility score.

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.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 8 binary inspection tools register over stdio JSON-RPC 2.0 and require zero external API keys.

Ask your agent

Run analyze_binary and find_dangerous_patterns on ./target.elf, disassemble any
function that references strcpy or system, and rank the most feasible RCE chain.

Replace ./target.elf with any local ELF, Mach-O, PE, or firmware binary you want to tear down.

Use the terminal

Run the full 3-phase offensive pipeline (Recon → Hunt → Chain) directly from your shell:

# Full analysis pipeline — 8 parallel agents, PE target
npx adv-rea analyze ./target.exe --agents 8 --type pe --output results.json

# Deploy a targeted agent swarm with custom mission and offensive roles
npx adv-rea swarm ./target.elf \
  --mission "Find heap corruption and ASLR leak primitives" \
  --roles mem-corrupt,mitigation-bypass

# Vulnerability hunt — surface critical CWE patterns only
npx adv-rea hunt ./target.apk --critical-only

# Attack surface enumeration only (vectors, trust boundaries, primitives)
npx adv-rea surface ./libtarget.so --type elf-shared

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

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

How Adversarial REA works

Your MCP client or CLI invocation calls Adversarial REA to extract ground-truth binary structure first, then layers parallel offensive reasoning over those extracted facts. Every claim is anchored to real symbol offsets, section flags, string literals, and mitigation headers.

1. Deterministic Telemetry (BinaryAnalyzer) — Executes objdump, nm, strings, otool, and file to collect imports, exports, function symbols, section permissions, categorized strings, and platform-normalized mitigation scores.
2. Attack Surface Enumeration (AttackSurfaceEnumerator) — Deploys parallel tasks to map entry vectors (network listeners, file parsers, IPC handlers), trust boundaries (user↔kernel, renderer↔broker, pre-auth↔post-auth), and exploitation primitives.
3. Parallel Swarm Hunting (AgentSwarm + VulnHunter) — Matches 19 CWE patterns against extracted imports/strings and dispatches up to 8 concurrent specialist roles via p-limit.
4. Exploit Chain Synthesis (ExploitChainBuilder) — Matches discovered vulnerabilities against 6 multi-stage exploitation templates, scores stage coverage, and generates PoC skeletons.

What you can analyze

Adversarial REA auto-detects target formats by extension or accepts an explicit --type override:

MCP Tool Catalog

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

Platform-Normalized Mitigation Scoring

check_security normalizes security scores to 100 per binary format. Because RELRO is an ELF-specific concept, it is excluded from the Mach-O denominator—so a fully hardened macOS binary scores 100/100 rather than being capped at 85.

Agent swarm roles

Eight specialist roles execute in parallel during adv-rea analyze and adv-rea swarm:

Vulnerability Patterns (CWE Coverage)

Showcases

1. Linux ELF: Format string leak to 5-stage ROP chain

Inspect an unstripped ELF service binary with analyze_binary, flag an uncontrolled printf (CWE-134) alongside a stack strcpy (CWE-120), and automatically assemble the CODE_EXEC_LINUX template (info_leak → memory_corruption → control_flow_hijack → rop_chain → shellcode_exec).

2. Desktop / Electron: IPC broker boundary breakout

Enumerate renderer-to-broker trust boundaries with adv-rea surface, deploy the input-inject and protocol-abuse swarm roles to audit message deserialization handlers, and score SANDBOX_ESCAPE chains.

3. Embedded Firmware: Hardcoded crypto & command injection triage

Extract crypto_material and credential_related strings from a raw .bin image via get_strings, cross-reference popen/system symbol imports with get_symbols, and isolate unauthenticated root command execution sinks.

Exploit chain templates

ExploitChainBuilder matches discovered vulnerabilities and primitives against 6 built-in exploitation templates and ranks feasible chains by stage completeness:

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('Attack Surface Score:', analysis.attackSurface.score);
console.log('Vulnerabilities:', analysis.vulnerabilities.length);
console.log('Top Exploit Chain:', analysis.exploitChains[0]);

FAQ

npm test                   # 61 deterministic unit tests (zero network calls)
npm run test:integration   # Live binary & stdio MCP JSON-RPC integration tests
npm run test:all           # Full 71-test verification 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