# Bug Bounty Platform MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-green.svg)](https://modelcontextprotocol.io/)

A unified **Model Context Protocol (MCP)** server enabling AI coding assistants and autonomous agents (**DeepSeek Harness**, **Claude Desktop / Claude Code**, **Cursor**, **Windsurf**, **Antigravity**) to interact with major bug bounty platforms using personal researcher API keys and access tokens.

Supported platforms:
- **HackerOne** (Hacker API v1)
- **YesWeHack** (Researcher API)
- **Intigriti** (Researcher External API v1)

---

## 🌟 Key Features

1. **Unified Multi-Platform Tools**: Single point of interaction to browse programs, read policies, and fetch structured scopes across HackerOne, YesWeHack, and Intigriti.
2. **Intelligent Scope Matcher**: Check if an IP, CIDR block, domain, wildcard (`*.example.com`), or URL prefix belongs to an active program scope.
3. **Graceful Fallback**: Missing API keys for any platform will not crash the server. Only unconfigured platforms are disabled with helpful reminders.
4. **Token-Efficient & Normalized**: All vendor-specific schemas (JSON:API, OpenAPI, REST) are parsed and normalized into compact, standardized Pydantic models.
5. **Live & Stateless**: Direct API calls ensure real-time accuracy without stale local caches.

---

## 🏗 Architecture

```
[ AI Assistant / Agent (DeepSeek Harness, Claude, Cursor) ]
                          │ (JSON-RPC over stdio)
                          ▼
            ┌─────────────────────────────┐
            │   Bounty Platform MCP Server│
            └──────────────┬──────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
[HackerOne Client] [YesWeHack Client] [Intigriti Client]
 (Basic Auth)        (Bearer Token)     (Bearer Token)
        │                  │                  │
        ▼                  ▼                  ▼
 api.hackerone.com  api.yeswehack.com  api.intigriti.com
```

---

## 🚀 Quick Start

### 1. Installation

Clone the repository:
```bash
git clone https://github.com/toannguyen3107/bounty_platform_mcp.git
cd bounty_platform_mcp
```

Create a virtual environment and install dependencies using `uv` (recommended) or `pip`:

Using `uv`:
```bash
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
```

Using `pip`:
```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
```

### 2. Configure Credentials

Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

Edit `.env` with your API credentials:
```env
# HackerOne API Credentials (Basic Auth)
# Generate from HackerOne: Settings -> API Tokens
H1_USERNAME=your_hackerone_username
H1_API_KEY=your_hackerone_api_token

# YesWeHack API Token (Bearer Auth)
# Generate from YesWeHack: Profile -> My YesWeHack Tools -> Personal Access Tokens
YWH_API_TOKEN=your_yeswehack_token

# Intigriti Researcher API Token (Bearer Auth)
# Generate from Intigriti: Settings -> API
INTIGRITI_API_TOKEN=your_intigriti_token
```

> **Note**: You only need to configure the platforms you use. Any platform without credentials will be gracefully skipped.

---

## 🔌 Connecting to AI Agents

### 1. DeepSeek Harness (`dsh`)

Add the MCP server to your DeepSeek Harness configuration (e.g. `~/.dsh/settings.yaml` or harness plugin configuration):

```yaml
mcpServers:
  bounty:
    command: "python"
    args:
      - "C:/Toan/Tools/bounty_platform_mcp/run_server.py"
    env:
      H1_USERNAME: "your_hackerone_username"
      H1_API_KEY: "your_hackerone_api_token"
      YWH_API_TOKEN: "your_yeswehack_token"
      INTIGRITI_API_TOKEN: "your_intigriti_token"
```

### 2. Claude Desktop (`claude_desktop_config.json`)

On Windows: `%APPDATA%\Claude\claude_desktop_config.json`  
On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "bounty-platform": {
      "command": "C:\\Toan\\Tools\\bounty_platform_mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Toan\\Tools\\bounty_platform_mcp\\run_server.py"
      ],
      "env": {
        "H1_USERNAME": "your_hackerone_username",
        "H1_API_KEY": "your_hackerone_api_token",
        "YWH_API_TOKEN": "your_yeswehack_token",
        "INTIGRITI_API_TOKEN": "your_intigriti_token"
      }
    }
  }
}
```

### 3. Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "bounty-platform": {
      "command": "python",
      "args": ["C:/Toan/Tools/bounty_platform_mcp/run_server.py"],
      "env": {
        "H1_USERNAME": "your_hackerone_username",
        "H1_API_KEY": "your_hackerone_api_token",
        "YWH_API_TOKEN": "your_yeswehack_token",
        "INTIGRITI_API_TOKEN": "your_intigriti_token"
      }
    }
  }
}
```

---

## 🛠 Available MCP Tools

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `bounty_get_platforms_status` | *(none)* | Inspect which platforms are configured and see any missing environment variables. |
| `bounty_search_programs` | `query`, `platform`, `bbp_only`, `public_only` | Search bug bounty programs across one or all platforms (`all`, `hackerone`, `yeswehack`, `intigriti`). |
| `bounty_get_program` | `platform`, `identifier` | Fetch detailed program specifications, policies, testing restrictions, and maximum bounties. |
| `bounty_get_scope` | `platform`, `identifier`, `include_oos` | Retrieve all structured in-scope and out-of-scope targets (domains, CIDRs, mobile packages, etc.). |
| `bounty_check_target` | `target`, `platform` | Determine if an asset (`api.target.com`, `10.0.0.1`, `https://target.com/v1`) matches any program scope. |

---

## 🧪 Testing & Verification

Run the comprehensive unit test suite:

```bash
pytest -v
```

Output:
```text
tests/test_config_models.py ................. [ 10%]
tests/test_matcher.py ....................... [ 28%]
tests/test_http_client.py ................... [ 39%]
tests/test_hackerone.py ..................... [ 53%]
tests/test_yeswehack.py ..................... [ 67%]
tests/test_intigriti.py ..................... [ 82%]
tests/test_manager.py ....................... [ 92%]
tests/test_server.py ........................ [100%]
============================= 28 passed in 1.74s ==============================
```

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.