Content
# Xuanmu-BugBounty-mcp
> **Xuanmu Security Team · guaidao2 Development**
>
> Independent and self-contained SRC vulnerability mining MCP toolkit - zero external scanner dependencies, ready to use out of the box
---
## Quick Installation
```bash
git clone https://github.com/guaidao2/Xuanmu-Bugbounty-mcp.git
cd Xuanmu-BugBounty-mcp
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
# Start
xuanmu-bb
# Or: python "absolute path/src/xuanmu_bb/server.py"
```
---
## MCP Configuration
```json
{
"mcpServers": {
"Xuanmu-BugBounty-mcp": {
"command": "xuanmu-bb"
}
}
}
```
---
## Core Features
### Structured Output
All vulnerability detection tools return a unified JSON format, which can be directly parsed by LLM:
```json
{
"tool": "bb_sqli",
"target": "https://example.com",
"status": "confirmed",
"summary": "3 suspicious points found (2 CRITICAL, 1 HIGH), 2 of which have been confirmed",
"findings": [{
"param": "id", "payload": "' AND SLEEP(3) --",
"type": "time_based", "severity": "CRITICAL",
"evidence": "Time-based blind injection: response delay 3.2s",
"verified": true,
"verified_by": "Secondary confirmation: sleep(5) delay 5.1s"
}],
"waf": {"detected": true, "name": "Cloudflare"},
"metadata": {"duration_ms": 8234, "requests_sent": 45}
}
```
### Secondary Confirmation of Detection Results
| Vulnerability Type | Initial Detection | Secondary Confirmation Method |
|---------|---------|-------------|
| SQLi Time-Based Blind Injection | SLEEP(3) delay | Retry SLEEP(5) verification |
| SQLi Boolean-Based Blind Injection | 1=1 vs 1=2 difference | Switch to 2=2 vs 2=1 verification |
| XSS | Unencoded payload reflection | Cross-validation with different vectors (<img> -> <svg>) |
| SSTI | 7\*7 -> 49 | Verify 8\*8 -> 64 |
| CMDI | ping -c 3 delay | Retry ping -c 5 |
| SSRF/LFI | Response contains system files | Automatic confirmation; change address and retry if size changes |
Confirmed findings are marked with `verified: true`, and severity is upgraded to CRITICAL.
### Custom Payload
All vulnerability detection tools support the `custom_payloads` parameter, which is merged with built-in payloads for execution:
```bash
bb_sqli url="..." custom_payloads="' OR 1=1 -- ,1' AND SLEEP(10) -- "
bb_xss url="..." custom_payloads="<script>alert(document.cookie)</script>,<img src=x onerror=alert(1)>"
```
### Enhanced Fingerprinting
Integrates **Wappalyzer + EHole + FingerprintHub** projects:
| Detection Source | Quantity | Method |
|-------|------|------|
| FingerprintHub Full | **2,224 entries** | Keyword AND + 33 favicon hashes + scoring |
| Enhanced Fingerprint Library | 79 entries | Multi-signal scoring + keyword AND + implicit derivation |
| Wappalyzer | Runtime | Library detection |
| Favicon Hash | Runtime | MMH3 32-bit calculation (Shodan/EHole compatible) |
| Meta Generator | Runtime | HTML meta tag extraction CMS+version |
**Covers 27 technical categories**: CMS, OA/office, ERP/finance, framework/language, web server, CDN/proxy, WAF/security, database, network device, monitoring/log, mail system, VPN/remote, bastion machine, DevOps, video surveillance, NAS/IoT, cloud service, etc.
**Implicit technology derivation**: WordPress -> PHP + MySQL, Django -> Python, Spring Boot -> Java, Element UI -> Vue.js ...
Output is grouped by technical category, with WAF detection and subsequent testing suggestions.
```bash
bb_fingerprint url="https://example.com"
```
---
## All 39 Tools
> The following tools involving HTTP requests all support general authentication parameters: `auth_token` (Bearer Token), `cookie`, `proxy`, `timeout`.
> Vulnerability detection tools additionally support: `waf_mode`, `method` (GET/POST), `body`, `custom_payloads`.
### Reconnaissance Module
| Tool | Function | Unique Parameters |
|------|------|---------|
| `bb_ping` | Live detection — TCP + HTTP dual detection | target |
| `bb_port_scan` | Port scanning — Top100/custom range | target, ports, concurrent |
| `bb_subdomain` | Subdomain enumeration — DNS batch resolution | domain, wordlist, concurrent |
| `bb_fingerprint` | **Enhanced fingerprinting** — 2300+ fingerprints/27 categories/favicon hashes | url |
| `bb_dir_scan` | Directory brute-forcing — built-in 150+ sensitive paths | url, wordlist, status_filter, concurrent |
### Vulnerability Detection Module
| Tool | Function | Unique Parameters |
|------|------|---------|
| `bb_sqli` | SQL injection — error/boolean/time-based blind injection + secondary confirmation | url, params, custom_payloads |
| `bb_nosqli` | NoSQL injection — MongoDB \$ne/\$gt/\$regex | url, params |
| `bb_xss` | XSS detection — reflective/multi-context + cross-validation | url, params, custom_payloads |
| `bb_ssti` | SSTI template injection — multi-engine + numerical confirmation | url, params, custom_payloads |
| `bb_cmdi` | Command injection — time-based blind injection + output echo + confirmation | url, params, custom_payloads |
| `bb_ssrf` | SSRF detection — intranet/cloud metadata/OOB + confirmation | url, params, custom_payloads |
| `bb_cors` | CORS cross-domain — 12 origin tests | url |
| `bb_open_redirect` | Open redirect — parameter scanning + jump test | url, params |
| `bb_file_upload` | File upload bypass — multi-extension/MIME/truncation | url |
| `bb_csrf` | CSRF detection — Token/SameSite/Referer analysis | url |
| `bb_xxe` | XXE detection — classic/blind/SVG/XInclude | url, body, content_type |
| `bb_lfi` | Path traversal — ../traversal/PHP filter + confirmation | url, params, custom_payloads |
| `bb_host_inject` | Host header injection — 9 attack scenarios | url |
| `bb_takeover` | Subdomain takeover — CNAME+50+ cloud service matching | domain |
| `bb_race` | Race condition — concurrent request + response difference analysis | url, method, data, concurrent |
### Authentication Security Module
| Tool | Function | Unique Parameters |
|------|------|---------|
| `bb_jwt_decode` | JWT decoding — parse Header/Payload | token |
| `bb_jwt_analyze` | JWT security analysis — vulnerability detection + attack suggestions | token |
| `bb_jwt_crack` | JWT key brute-forcing — HMAC dictionary attack | token, wordlist |
| `bb_jwt_attack` | JWT attack — None/KID injection/algorithm confusion | token, mode, payload_override, public_key |
| `bb_graphql` | GraphQL scanning — Introspection/batch/recursive | url |
### Information Extraction Module
| Tool | Function | Unique Parameters |
|------|------|---------|
| `bb_extract` | URL/Endpoint extraction — HTML+JS analysis | url, depth |
| `bb_secrets` | Sensitive information detection — 20 regular patterns | url, check_js |
| `bb_headers` | Security header audit — 8 item scoring + repair suggestions | url |
| `bb_param_discover` | Parameter automatic discovery — form/query/JSON/JS | url, depth |
| `bb_js_analyze` | JS deep analysis — API route/Sourcemap/hardcoded/WebSocket | url |
### Tool Module
| Tool | Function | Unique Parameters |
|------|------|---------|
| `bb_send` | Manual HTTP packet sending — JSON/form/multipart/file upload | url, method, headers, body, content_type, files, follow_redirects |
| `bb_payload` | Payload factory — 9 types of vulnerabilities x 6 encoding | vuln_type, encode, count |
| `bb_oob` | OOB auxiliary — callback identifier/payload suggestions | mode, callback_url |
| `bb_idor` | IDOR privilege escalation detection — double token comparison + serial number enumeration | url, token_owner, token_attacker, param, method |
| `bb_cloud_check` | Cloud service security — S3/metadata/cloud configuration leakage | url |
| `bb_waf_check` | WAF fingerprinting — 14 WAF + bypass suggestions | url |
| `bb_session` | Multi-step process — Session persistence + request chain | steps (JSON) |
| `bb_report` | Vulnerability report generation — SRC format Markdown | vuln_type, target, param, payload, impact, detail, poc |
### General Parameter Description
| Parameter | Applicable Tools | Description |
|------|---------|------|
| `auth_token` | All HTTP tools | Bearer Token, automatically adds `Authorization: Bearer xxx` header |
| `cookie` | All HTTP tools | Cookie string, automatically adds `Cookie: xxx` header |
| `proxy` | All HTTP tools | Proxy address, e.g., `http://127.0.0.1:8080` |
| `timeout` | All HTTP tools | Request timeout seconds (default 15) |
| `waf_mode` | Vulnerability detection | `off` / `safe` (slow down + UA rotation) / `aggressive` (attempt to bypass) |
| `method` | Vulnerability detection | `GET` or `POST`, default GET |
| `body` | Vulnerability detection | POST request body, e.g., `username=admin&password=test` |
| `custom_payloads` | sqli/xss/ssti/cmdi/ssrf/lfi | Comma-separated custom payloads, merged with built-in payloads for execution |
| `request_delay` | Vulnerability detection + dir_scan | Request interval seconds, automatically increased to 3s after WAF detection |
---
## Usage Examples
### Information Collection -> Vulnerability Detection Full Process
```bash
# 1. Fingerprinting (identify tech stack + WAF + classification)
bb_fingerprint url="https://target.com"
# 2. Directory scanning
bb_dir_scan url="https://target.com"
# 3. Parameter discovery
bb_param_discover url="https://target.com/api"
# 4. Vulnerability detection (using discovered parameters + custom payloads)
bb_sqli url="https://target.com/page?id=1" params="id" \
custom_payloads="' OR 1=1 -- ,' AND SLEEP(5) -- "
bb_xss url="https://target.com/search?q=test" params="q" \
custom_payloads="<script>alert(1)</script>,<img src=x onerror=alert(1)>"
bb_ssti url="https://target.com/welcome?name=test" params="name"
bb_cmdi url="https://target.com/ping?host=127.0.0.1" params="host"
bb_ssrf url="https://target.com/fetch?url=http://example.com" params="url"
bb_lfi url="https://target.com/file?name=test.txt" params="name"
bb_cors url="https://api.target.com/data"
bb_open_redirect url="https://target.com/redirect?url=https://example.com"
bb_xxe url="https://target.com/xml/parse"
# 5. Authentication testing
bb_jwt_analyze token="eyJhbGciOiJIUzI1NiIs..."
bb_jwt_attack token="..." mode="none"
bb_graphql url="https://target.com/graphql"
# 6. Multi-step business process
bb_session steps='[
{"method":"POST","url":"https://target.com/login","body":"user=admin&pass=test"},
{"method":"GET","url":"https://target.com/api/profile"}
]'
# 7. Report generation + bb_send full format example
bb_report vuln_type="sqli" target="https://target.com/page?id=1" \
payload="' OR 1=1 -- " impact="Can obtain all database data"
# bb_send: JSON automatic recognition
bb_send url="https://api.example.com/login" method="POST" \
body='{"user":"admin","pass":"test"}'
# bb_send: Form automatic recognition
bb_send url="https://example.com/search" method="POST" \
body="q=test&page=1"
# bb_send: File upload (multipart/form-data)
bb_send url="https://example.com/upload" method="POST" \
files="file=/path/to/shell.php" body="action=upload"
# bb_send: XML manual Content-Type specification
bb_send url="https://example.com/api" method="POST" \
headers="Content-Type: application/xml" \
body='<?xml version="1.0"?><root>data</root>'
```
### Authentication Scanning
```bash
# Bearer Token
bb_sqli url="https://target.com/api/search" params="q" auth_token="eyJ..."
# Session Cookie
bb_xss url="https://target.com/search" params="q" cookie="JSESSIONID=ABCD1234"
```
### WAF Protection Scanning
```bash
# Detect WAF first
bb_waf_check url="https://target.com"
# WAF protection scanning (automatic slow down + UA rotation)
bb_sqli url="https://target.com/page?id=1" waf_mode="safe" request_delay="3"
```
---
## Project Structure
```
src/xuanmu_bb/
├── server.py # MCP entry (39 tools, registry mode)
├── client.py # HTTP client (proxy/cookie/UA rotation/anti-seal policy)
├── utils.py # Common tools + ResultBuilder structured output
├── data/
│ ├── payloads.py # SQLi/XSS/SSTI/CMDI/SSRF/LFI payloads
│ ├── dicts.py # Subdomain/directory dictionaries + port mapping + weak passwords
│ ├── fingerprints.py # Web fingerprint library + WAF signatures
│ ├── fingerprints_enhanced.py # Enhanced fingerprint library (79 entries, 27 categories)
│ ├── fingerprints_hub.py # FingerprintHub full (2,224 entries, 365KB)
│ ├── patterns.py # Sensitive information regular + security header list
│ └── waf.py # WAF detection engine
├── recon/ # Reconnaissance module (5 tools)
├── vuln/ # Vulnerability detection module (15 tools, all support secondary confirmation)
├── auth/ # Authentication security module (5 tools)
├── extract/ # Information extraction module (5 tools)
└── tools/ # Tool module (9 tools + fingerprint_importer)
```
---
## Technical Features
- **Fully self-contained** — No dependencies on nmap/nuclei/burp and other external tools, pure Python implementation
- **Structured JSON output** — All vulnerability detection returns unified format, LLM can directly parse and link
- **Detection secondary confirmation** — SQLi/XSS/SSTI/CMDI/SSRF/LFI automatic verification reduces false positives
- **2300+ fingerprint library** — Integrates FingerprintHub + Wappalyzer + EHole, covers 27 technical categories
- **Favicon hash** — MMH3 32-bit calculation, compatible with Shodan/EHole fingerprint matching
- **Custom payload** — All vulnerability tools support user injection of custom payloads
- **Anti-seal policy** — User-Agent rotation / request interval control / proxy support / WAF breaking
- **Registry mode** — server.py adds tools requiring only one tuple, no repetitive template code
- **16 unit tests** — Covers utils/payloads/dicts core modules
---
## License
This project is for legal security testing and vulnerability mining only. Users must comply with relevant laws and regulations.
---
**Xuanmu-BugBounty-mcp** (c) 2026 Xuanmu Security Team · guaidao2
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available