<div align="center">

# offsec-mcp

**Offensive-security tooling for AI agents — over the Model Context Protocol.**

Give Claude, Cursor, or any MCP client the ability to run reconnaissance, pull CVE
intelligence, analyze JavaScript, and scan ports — **only against targets you're authorized to test.**

[![CI](https://github.com/nadirzhon/offsec-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nadirzhon/offsec-mcp/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-server-8A63D2)
![License](https://img.shields.io/badge/License-MIT-green)

</div>

---

## Why

Pentesters and bug-bounty hunters live in a dozen CLI tools. AI agents are great at
*orchestrating* multi-step work — but they can't touch those tools. **offsec-mcp** bridges
the gap: it exposes a focused set of security capabilities as MCP tools, so you can just ask —

> *"Enumerate subdomains of `example.com`, check which are live, and tell me if any run
> software with a critical CVE."*

— and the agent chains `recon_subdomains` → `http_probe` → `cve_search` for you.

Built on battle-tested logic from [reconwave](https://github.com/nadirzhon/reconwave),
[cve-forge](https://github.com/nadirzhon/cve-forge), and [jsintel](https://github.com/nadirzhon/jsintel).

## Guardrails first

This is a **dual-use** tool, so authorization is enforced in code, not left to good intentions:

- **Passive OSINT** (CT logs, DNS, RDAP, NVD, analyzing pasted JS) runs freely — it never touches the target.
- **Active tools** (`port_scan`, `http_probe`, `security_headers`) refuse to run unless the
  target is in your configured **authorization scope**. No scope → no active probing.
- Discovered secrets are **redacted** in output, never returned in full.

See [SECURITY.md](SECURITY.md) for the responsible-use policy.

## Tools

| Tool | Type | What it does |
|------|------|--------------|
| `recon_subdomains` | passive | Sub-domain enumeration from Certificate Transparency (crt.sh) |
| `dns_lookup` | passive | A/AAAA/MX/NS/TXT/CNAME via DNS-over-HTTPS |
| `whois` | passive | Registration data via RDAP (registrar, dates, nameservers) |
| `cve_search` | passive | Search NVD by keyword, filter by CVSS |
| `cve_lookup` | passive | Full details + references for a CVE id |
| `analyze_js` | passive\* | Extract secrets, endpoints & params from JS |
| `http_probe` | **active** | Status, headers & tech fingerprint of a URL |
| `security_headers` | **active** | Audit security headers, grade A–F |
| `port_scan` | **active** | Async TCP-connect scan of common/custom ports |
| `scope_status` | — | Report whether an authorization scope is set |

<sub>\* `analyze_js` is passive on pasted content; fetching a URL requires scope.</sub>

## Install

Run instantly with [`uv`](https://docs.astral.sh/uv/) — no clone needed:

```bash
uvx offsec-mcp        # runs the server (stdio) — or: pip install offsec-mcp
```

Or install from source:

```bash
git clone https://github.com/nadirzhon/offsec-mcp
cd offsec-mcp
uv pip install -e ".[dev]"
```

## Configure your MCP client

### Claude Desktop / Claude Code

Add to your MCP config (see [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)):

```json
{
  "mcpServers": {
    "offsec": {
      "command": "uvx",
      "args": ["offsec-mcp"],
      "env": {
        "OFFSEC_SCOPE": "example.com,*.staging.example.com,10.0.0.0/24"
      }
    }
  }
}
```

### Authorization scope

Active tools only run against hosts you list. Two ways to set it:

```bash
# inline — domains, wildcards, and CIDRs
export OFFSEC_SCOPE="example.com,*.staging.example.com,10.0.0.0/24"

# or a file, one entry per line (# comments allowed)
export OFFSEC_SCOPE_FILE="./scope.txt"
```

For a fully-owned lab you control, `OFFSEC_ALLOW_ANY=1` disables the guard. `NVD_API_KEY`
(optional) raises NVD rate limits.

## Example session

```
You:   Find subdomains of example.com and check the main site's security headers.

Agent: → recon_subdomains("example.com")      → 143 subdomains from CT logs
       → security_headers("https://example.com")
       → Grade C (60): missing CSP, Permissions-Policy.
         www, api, staging, dev.example.com are live.
```

See [`examples/sample_output.md`](examples/sample_output.md) for real tool output.

## Development

```bash
uv pip install -e ".[dev]"
pytest            # scope guard + tool logic
ruff check .
```

## Part of an AI × Security toolkit

- **offsec-mcp** — MCP server giving AI agents offensive-security tools (recon, CVE, JS analysis) · *(this repo)*
- [specter](https://github.com/nadirzhon/specter) — autonomous AI recon agent that drives those tools end-to-end
- [vigil](https://github.com/nadirzhon/vigil) — AI security review for every pull request
- [mcpscan](https://github.com/nadirzhon/mcpscan) — security scanner for MCP servers (tool poisoning, injection surfaces)
- [State of MCP Security](https://github.com/nadirzhon/state-of-mcp-security) — research: 87% of scanned MCP servers expose a medium+ hardening issue

## License

MIT — see [LICENSE](LICENSE). Published for **authorized security testing, research, and
education only.** You are responsible for having explicit permission to test any target.