offsec-mcp
<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.**
[](https://github.com/nadirzhon/offsec-mcp/actions/workflows/ci.yml)



</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.
TDQS
Scored across 10 tools
Most tools have clearly distinct targets: DNS, WHOIS, subdomain enumeration, CVE search/detail, JS analysis, HTTP probing, header auditing, and port scanning. The main potential confusion is between cve_search and cve_lookup, and between http_probe and security_headers, but descriptions make the boundaries reasonably clear.
The set mixes conventions: noun_verb forms like dns_lookup, cve_search, and port_scan alongside verb_noun analyze_js, bare nouns like whois and security_headers, and the less predictable recon_subdomains. The names are readable, but there is no single consistent pattern.
Ten tools is well-scoped for an offensive-security reconnaissance server. Each tool maps to a distinct phase or resource, and none appears redundant or trivial.
The surface covers a solid recon workflow: subdomain discovery, DNS, WHOIS, CVE research, JavaScript analysis, HTTP probing, security-header auditing, and port scanning, plus scope status. Minor gaps exist, such as URL/content discovery or broader vulnerability scanning, but core workflows are represented.