OFFX-MCP

Offensive Execution MCP Server — A Model Context Protocol server that bridges AI agents (Claude, Kilo, Antigravity, etc.) to a Docker-isolated Kali Linux environment over SSH, with built-in OPSEC enforcement and multi-agent coordination.

---

Overview

OFFX-MCP exposes 29 security tools as MCP tools. All commands execute inside a Docker container on a remote VPS — nothing runs on the host machine. Before every command, the server performs an OPSEC preflight check to verify the egress IP matches your VPN exit node.

┌─────────────────────┐       SSH (stdio)      ┌──────────────────────┐
│  AI Agent           │ ─────────────────────▶ │  mcp_bridge.py       │
│  (Claude / Kilo)    │                         │  (Windows host)      │
└─────────────────────┘                         └──────────┬───────────┘
                                                           │ docker exec
                                                           ▼
                                                ┌──────────────────────┐
                                                │  offx_mcp/main.py    │
                                                │  (Kali Docker)       │
                                                │                      │
                                                │  ┌────────────────┐  │
                                                │  │ OPSEC preflight│  │
                                                │  │ (VPN check)    │  │
                                                │  └────────────────┘  │
                                                │  ┌────────────────┐  │
                                                │  │ nmap / nuclei  │  │
                                                │  │ httpx / hydra  │  │
                                                │  │ sqlmap / ffuf  │  │
                                                │  │ CVE Intel      │  │
                                                │  │ Shared State   │  │
                                                │  └────────────────┘  │
                                                └──────────────────────┘

---

Features

• 29 MCP tools across 4 categories: admin, active scanning, passive intel, multi-agent coordination
• OPSEC enforcement — every command is gated by an egress IP check; fails immediately if VPN is down
• Async job system — long-running scans run as background jobs; poll with job_status
• Shared SQLite state — multiple agents can share findings, claim tasks, and exchange messages without conflicts
• Full audit trail — every tool call writes a JSONL event + markdown timeline per run
• CVE Intelligence — lookup, search, and enrich CVEs from NVD, CIRCL, MITRE, EPSS, CISA KEV, SearchSploit, GitHub, and Nuclei Templates

---

Requirements

• Python 3.11+ on the host (Windows or Linux)
• Docker with a Kali Linux container on your VPS
• VPN configured on the VPS with nftables firewall rules
• SSH key-based access to the VPS

Python Dependencies

pip install -r requirements.txt

Package	Purpose
mcp>=1.0.0	MCP server framework (FastMCP)
paramiko>=3.0.0	SSH bridge
requests>=2.31.0	CVE intel HTTP calls

---

Setup

1. Configure environment variables

cp .env.example .env
# Edit .env with your values

The critical variables are:

Variable	Description
OFFX_SSH_HOST	Your VPS IP or hostname
OFFX_SSH_KEY	Path to your SSH private key
OFFX_SSH_USER	SSH username (default: ubuntu)
OFFX_EXPECTED_EGRESS_IP	Your VPN exit IP — all traffic must leave through this
OFFX_FORBIDDEN_EGRESS_IP	Your VPS raw IP — must never be the egress

2. Configure your MCP client

Copy .mcp.json.example to .mcp.json (or your client's config file) and fill in your paths:

{
  "mcpServers": {
    "offx-remote": {
      "type": "stdio",
      "command": "python",
      "args": ["C:\\path\\to\\OFFX-MCP\\mcp_bridge.py"],
      "env": {
        "OFFX_SSH_HOST": "YOUR_VPS_IP",
        "OFFX_SSH_KEY": "C:\\Users\\YOU\\.offx\\ssh_key",
        "OFFX_EXPECTED_EGRESS_IP": "YOUR_VPN_EXIT_IP",
        "OFFX_FORBIDDEN_EGRESS_IP": "YOUR_VPS_RAW_IP"
      }
    }
  }
}

3. Verify connectivity

Once your MCP client connects, call:

health_check()

It will return the current egress IP, binary availability, and VPN/firewall status.

---

Project Structure

OFFX-MCP/
├── mcp_bridge.py          # SSH bridge — runs on Windows host
├── offx_mcp/              # MCP server — runs inside Docker
│   ├── main.py            # FastMCP server + all 29 tool definitions
│   ├── opsec.py           # OPSEC preflight + execution engine
│   ├── config.py          # Settings from environment variables
│   ├── jobs.py            # Async job manager (ThreadPoolExecutor)
│   ├── intel.py           # CVE/exploit intelligence service
│   ├── shared_state.py    # SQLite multi-agent coordination store
│   ├── audit.py           # Audit trail (JSONL + Markdown timeline)
│   ├── syncer.py          # Wiki/Git knowledge sync
│   └── utils.py           # Shared helpers
├── .env.example           # Environment variable template
├── .mcp.json.example      # MCP client config template
├── .gitignore             # Excludes secrets, keys, loot, logs
├── requirements.txt       # Python dependencies
└── docs/
    └── tools_reference.md # Full tool reference with parameters

---

Tool Categories

🟢 Admin

health_check · vpn_status · execute_command · job_status · job_cancel

🔴 Active Scanning

nmap_scan · nmap_advanced_scan · httpx_probe · netexec_scan · feroxbuster_scan · ffuf_scan · katana_crawl · hydra_attack · sqlmap_scan · smbmap_scan · nuclei_scan · web_evidence_screenshotter

🟡 Passive Intel

cve_lookup · cve_search · cve_enrich · exploit_search · package_vuln_lookup

🔵 Multi-Agent Coordination

shared_state_overview · publish_shared_intel · query_shared_intel · claim_shared_task · heartbeat_shared_task · complete_shared_task · list_shared_tasks · upsert_agent_presence · list_agent_presence · post_agent_message · fetch_agent_messages · ack_agent_message · wiki_git_syncer

See docs/tools_reference.md for full parameter documentation.

---

OPSEC Model

Every tool call that executes a command performs two checks:

1. Preflight — before execution: egress IP, route table, nftables presence, host snapshot freshness
2. Postflight — after execution: re-checks egress IP to detect VPN drops mid-command

If either check fails, the call returns {"ok": false, "error": {"code": "opsec_failed", ...}} and no command is executed.

The host OPSEC snapshot (intel/host_opsec_snapshot.json) is written by a watchdog script on the VPS and must be refreshed every ≤10 minutes. Required services and nftables tables are validated against it.

---

Async Jobs

Scan tools default to mode="async". The tool returns immediately with a job_id:

# Submit
result = nmap_scan(target="10.0.0.1", mode="async")
job_id = result["job_id"]

# Poll
status = job_status(job_id=job_id, include_result=True)

# Cancel
job_cancel(job_id=job_id)

Jobs run in a ThreadPoolExecutor with OFFX_JOB_WORKERS threads (default: 5). In-progress processes are tracked and can be SIGTERM'd via job_cancel.

---

License

MIT

---

Security Notice

This tool is intended for authorized security assessments on systems you own or have explicit written permission to test. Unauthorized use against systems you do not own is illegal. The authors are not responsible for misuse.