# OFFX-MCP

**Offensive Execution MCP Server** — A [Model Context Protocol](https://modelcontextprotocol.io/) 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

```bash
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

```bash
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:

```json
{
  "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`](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`:

```python
# 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.