# 🧪 Bug Bounty Assistant MCP

An MCP (Model Context Protocol) server that gives an LLM a toolkit of **passive and low-impact active reconnaissance** tools for authorized bug bounty and security assessment work. The LLM decides which tools to call based on the target and context, then synthesizes findings into a structured report.

> ⚠️ **Authorized use only.** This tool is intended strictly for testing assets you own or have **explicit written authorization** to test (e.g. a program listed on HackerOne/Bugcrowd/Intigriti with the target in scope). Running these tools against systems without permission may violate laws such as the CFAA (US), Computer Misuse Act (UK), or equivalent legislation elsewhere. Always check the program's scope and rules of engagement before scanning.

---

## Features

The server currently exposes the following tools to the calling LLM:

| Tool | Description |
|---|---|
| `get_dns_records` | Resolves A/AAAA/MX/TXT/NS/CNAME/SOA records for a domain |
| `find_subdomains` | Enumerates subdomains via certificate transparency logs (crt.sh), passive DNS sources, and optional wordlist brute force |
| `check_security_headers` | Audits HTTP response headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, etc.) |
| `analyze_cookies` | Inspects cookies for `Secure`, `HttpOnly`, `SameSite` flags and flags risky configurations |
| `ssl_scan` | Checks TLS/SSL certificate validity, chain, protocol versions, and cipher suites |
| `discover_robots` | Fetches and parses `robots.txt` for disallowed paths that may hint at sensitive areas |
| `discover_sitemap` | Fetches and parses `sitemap.xml` for enumerable site structure |
| `detect_technologies` | Fingerprints frameworks, CMS, JS libraries, and server software (Wappalyzer-style detection) |
| `find_interesting_endpoints` | Crawls linked resources and JS files for endpoints, API routes, and parameters worth manual review |
| `take_screenshot` | Captures a visual snapshot of a page for quick triage of many hosts |
| `generate_report` | Aggregates all tool outputs into a structured Markdown/JSON recon report |

### Suggested additional tools (roadmap)

These extend the recon surface while staying passive/low-impact:

| Tool | Description |
|---|---|
| `whois_lookup` | WHOIS/RDAP data — registrar, creation date, org, nameservers |
| `check_cors_config` | Tests for permissive/misconfigured CORS policies (reflected origin, wildcard + credentials) |
| `check_open_redirect` | Passive checks for common open-redirect parameter patterns |
| `wayback_urls` | Pulls historical URLs from the Wayback Machine / `web.archive.org` CDX API for old, forgotten, or removed endpoints |
| `github_dork_search` | Searches GitHub for leaked secrets, API keys, or internal references tied to the target domain/org |
| `js_secret_scanner` | Downloads and greps JS bundles for hardcoded API keys, tokens, internal hostnames |
| `check_cname_takeover` | Flags dangling CNAMEs pointing to unclaimed cloud resources (S3, Heroku, GitHub Pages, etc.) |
| `port_scan_passive` | Uses Shodan/Censys APIs (not direct scanning) to see already-indexed open ports/services |
| `check_jwt_config` | Decodes and analyzes JWTs found in requests for weak algorithms (`alg: none`) or missing expiry |
| `rate_limit_probe` | Sends a small number of requests to see if basic rate limiting exists (low volume, non-disruptive) |
| `check_email_security` | Validates SPF/DKIM/DMARC records for the domain |
| `favicon_hash` | Computes favicon hash (`mmh3`) for Shodan-style fingerprinting of related infrastructure |
| `directory_wordlist_scan` | Optional, opt-in, rate-limited content discovery against a small curated wordlist |
| `check_graphql_introspection` | Tests if GraphQL introspection is exposed on discovered API endpoints |
| `subdomain_takeover_scan` | Combines `find_subdomains` + `check_cname_takeover` for a full sweep |
| `diff_scan` | Compares current recon results to a previous run and highlights what changed (new subdomains, new headers, cert renewal, etc.) |

---

## Architecture

```
┌─────────────┐        MCP (stdio/HTTP)        ┌──────────────────────┐
│   LLM Host   │ ──────────────────────────────▶│  Bug Bounty MCP      │
│ (Claude, etc)│ ◀──────────────────────────────│  Server              │
└─────────────┘        tool calls/results        └──────────┬───────────┘
                                                              │
                                        ┌─────────────────────┼─────────────────────┐
                                        ▼                     ▼                     ▼
                                 DNS / crt.sh          HTTP(S) client         Headless browser
                                 resolvers             (headers, ssl,        (screenshot,
                                                        robots, sitemap)      JS rendering)
```

- **Transport:** stdio (default) or Streamable HTTP, per the MCP spec
- **Language:** TypeScript (Node.js ≥ 18)
- **HTTP client:** `undici` / `axios`
- **Headless browser:** `playwright` (for `take_screenshot`, JS-rendered `find_interesting_endpoints`)
- **DNS:** Node's built-in `dns/promises`, plus crt.sh queries for subdomain enumeration
- **Report output:** Markdown by default, optional JSON

---

## Project structure

```
bug-bounty-mcp/
├── src/
│   ├── index.ts                # MCP server entrypoint, tool registration
│   ├── tools/
│   │   ├── dns.ts
│   │   ├── subdomains.ts
│   │   ├── headers.ts
│   │   ├── cookies.ts
│   │   ├── ssl.ts
│   │   ├── robots.ts
│   │   ├── sitemap.ts
│   │   ├── technologies.ts
│   │   ├── endpoints.ts
│   │   ├── screenshot.ts
│   │   └── report.ts
│   ├── lib/
│   │   ├── http-client.ts      # shared fetch wrapper, timeouts, retries
│   │   ├── rate-limiter.ts     # global politeness/rate-limit control
│   │   ├── scope-guard.ts      # validates target is in an allow-listed scope
│   │   └── logger.ts
│   └── types.ts
├── tests/
├── .env.example
├── package.json
├── tsconfig.json
└── README.md
```

---

## Installation

### Prerequisites
- Node.js ≥ 18
- npm or pnpm
- (Optional) Playwright browsers for screenshots: `npx playwright install chromium`

### Setup

```bash
git clone https://github.com/<your-username>/bug-bounty-mcp.git
cd bug-bounty-mcp
npm install
cp .env.example .env
npm run build
```

### Run the server

```bash
npm start
# or in dev mode with hot reload
npm run dev
```

### Register with an MCP host (e.g. Claude Desktop / Claude Code)

Add to your MCP config (`claude_desktop_config.json` or equivalent):

```json
{
  "mcpServers": {
    "bug-bounty-assistant": {
      "command": "node",
      "args": ["/absolute/path/to/bug-bounty-mcp/dist/index.js"]
    }
  }
}
```

---

## Configuration

Set these in `.env`:

```bash
# Comma-separated list of domains this server is allowed to scan.
# scope-guard.ts refuses to run tools against anything not listed here.
ALLOWED_SCOPE=example.com,*.example.com

# Requests per second ceiling applied globally (politeness)
MAX_REQUESTS_PER_SECOND=2

# Timeout (ms) for outbound HTTP requests
HTTP_TIMEOUT_MS=10000

# Optional API keys for enrichment tools
SHODAN_API_KEY=
CENSYS_API_ID=
CENSYS_API_SECRET=
GITHUB_TOKEN=
```

**Scope guard:** every tool call passes the target through `scope-guard.ts`, which checks it against `ALLOWED_SCOPE` and refuses to run if the target isn't explicitly listed. This is the main safety rail — update it per-engagement before you start testing.

---

## Example usage

> User: "Analyze example.com for bug bounty recon."

The LLM will typically:
1. Call `get_dns_records` and `find_subdomains` to map infrastructure
2. Call `check_security_headers`, `analyze_cookies`, and `ssl_scan` on discovered hosts
3. Call `discover_robots` / `discover_sitemap` for structure hints
4. Call `detect_technologies` to fingerprint the stack
5. Call `find_interesting_endpoints` to surface API routes worth manual review
6. Call `take_screenshot` for visual triage across many hosts
7. Call `generate_report` to produce a single Markdown summary with findings, severity notes, and suggested next manual steps

Sample report output:

```markdown
# Recon Report — example.com
Generated: 2026-07-10

## DNS
- A: 93.184.216.34
- MX: none found
- NS: a.iana-servers.net, b.iana-servers.net

## Subdomains (4 found)
- www.example.com
- dev.example.com  ⚠ exposed, no auth wall detected
- api.example.com
- mail.example.com

## Security Headers — www.example.com
- CSP: ❌ missing
- HSTS: ✅ present (max-age=63072000)
- X-Frame-Options: ❌ missing

## Recommendations
- Investigate dev.example.com — appears to be a non-production environment reachable externally
- Add CSP and X-Frame-Options headers on the main site
```

---

## Roadmap

- [ ] Add `wayback_urls`, `github_dork_search`, `check_cname_takeover`
- [ ] Add per-tool caching to avoid re-hitting the same host repeatedly in one session
- [ ] Add a `diff_scan` tool to compare against a prior report
- [ ] Support authenticated scans (session cookie/header injection) for logged-in recon
- [ ] Add Slack/Discord webhook output for `generate_report`
- [ ] Docker image for one-command deployment

---

## Contributing

1. Fork the repo and create a feature branch
2. Add or update tools under `src/tools/`
3. Add tests under `tests/`
4. Run `npm run lint && npm test` before opening a PR

---

## Legal

This project performs reconnaissance only — no exploitation, no automated attack payloads, no denial-of-service behavior. It is the user's sole responsibility to:
- Confirm the target is in scope for a bug bounty program or that they have explicit authorization to test it
- Comply with the program's rules of engagement (rate limits, prohibited techniques, disclosure process)
- Comply with local law

The maintainers accept no liability for misuse.

## License

MIT