# CyberMCP — a free, open-source pentesting & bug bounty MCP server for AI agents

CyberMCP turns any AI agent (Claude, OpenCode, Cursor, Cline, RooCode, Continue, etc.) into a capable **authorized** pentest/bug-bounty assistant. It enforces engagement scope, keeps a full audit trail, and provides safe, detection-first recon + vulnerability checks, plus reporting.

> [!IMPORTANT]
> **Authorized testing only.** Use CyberMCP only on targets you have explicit, written permission to test. All network tools enforce per-engagement scope. See [Scoping, Ethics & Authorized Testing](cyber_mcp/knowledge/scoping_ethics.md).

## Features

- **Scope-first safety** — `scope.yaml` per engagement (domains/CIDRs, wildcards, out-of-scope, rate/concurrency). Every network action is guard-checked.
- **Full audit trail** — append-only `audit.jsonl` for every action, tool run, finding and scope bypass (if any).
- **Recon** — DNS lookup, subdomain enum (crt.sh + DNS wordlist), async TCP port scan, HTTP probing, WAF hints.
- **Web analysis** — flexible HTTP client, content discovery, parameter discovery, tech fingerprinting, security headers, TLS inspection, CORS.
- **Vuln detection (safe)** — exposed `.git/.env/backups`, open redirect, SQLi error-based, reflected XSS, LFI, sensitive paths, auth gaps.
- **Payload & wordlist generation** — context-aware payloads tailored to detected tech/DB; mines live pages to build custom wordlists; merge/dedup.
- **Orchestration pipelines** — `full_recon_pipeline`, `web_assessment_pipeline`, `vuln_scan_pipeline` stage results and can auto-record findings.
- **Crypto & secrets** — JWT decode + weak-secret detection, hash identification, encoding/decoding toolbox.
- **External CLI wrappers** — nmap/nuclei/ffuf/sqlmap/subfinder/httpx (auto-detected, scope-checked, time-limited, pure-Python fallbacks exist).
- **Findings & reporting** — add/update/list/findings; export JSON; generate professional **Markdown + HTML** pentest reports.
- **Embedded knowledge** — OWASP Top 10 2021, methodology, web cheatsheet, reporting standards, tool cheatsheets, scoping/ethics.
- **MCP prompts** — reusable workflows (`full_recon`, `web_assessment`, `vulnerability_validation`, `report_writer`).

## Quick Start

### 1) Install

**From PyPI (once published):**
```bash
uvx cyber-mcp
```

**From source (works today):**
```bash
git clone https://github.com/Dacraezy1/CyberMCP
cd CyberMCP
pip install .
cyber-mcp
```

### 2) Configure with an MCP client (examples)

#### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "cyber-mcp": {
      "command": "uvx",
      "args": ["cyber-mcp"]
    }
  }
}
```

#### Cursor (`mcp.json`)
```json
{
  "mcpServers": {
    "cyber-mcp": {
      "command": "uvx",
      "args": ["cyber-mcp"]
    }
  }
}
```

#### OpenCode / Cline / RooCode
Use `command: uvx`, `args: ["cyber-mcp"]`.

### 3) Use in an agent (typical flow)

1. **Engage**: `init_engagement(name="demo", in_scope_domains=["example.com"], rules="Authorized test only.")`
2. **Recon**: `full_recon_pipeline(target="example.com")`
3. **Assess**: `web_assessment_pipeline(url="https://example.com")`
4. **Review**: `list_findings()`
5. **Report**: `generate_report(fmt="both")`

All actions are scope-enforced and audited.

## Development

### Clone & run in dev mode

```bash
git clone https://github.com/Dacraezy1/CyberMCP
cd CyberMCP
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
cyber-mcp
```

### Tests

```bash
pytest -v
```

## Safety Notes

- **Detection-first**: built-in checks are non-destructive (error-based signatures, reflection canaries, metadata reads). They don't exploit, modify data, or exfiltrate bulk secrets.
- **Scope is king**: if a target isn't in your engagement scope, tools refuse it. Private/reserved IPs are blocked by default.
- **External tools**: wrappers add timeouts, scope checks and restricted flags. Increase risk only with written authorization.
- **Auditability**: every action goes to `engagements/<name>/audit.jsonl`. Keep it intact for post-test review.
- **No warranty**: provided as-is, for **authorized security testing** only. Users are responsible for compliance with applicable laws and program rules.

## License

[MIT License](LICENSE)

## Contributing

Contributions welcome. Please:
- Keep changes consistent with existing style and architecture (scope guard + audit first).
- Add/extend tests for new tools.
- Document new tools/prompts in README and knowledge.
- Maintain safety: scope checks on all network tools.