# webamon-mcp

MCP (Model Context Protocol) server for the [Webamon](https://webamon.com) threat intelligence platform. Lets AI assistants like Claude search scan databases, submit URLs for scanning, browse campaigns, and explore infrastructure clusters — all via Lucene-powered queries across multiple indexes.

Built for the community as part of the [c0c0n 2026](https://india.c0c0n.org/) course: **"Threat Tradecraft: Infrastructure Hunting & Malware Analysis"**.

## Features

- **14 MCP tools** covering all free-tier accessible endpoints
- **Lucene search** across 8 indexes: scans, domains, servers, resources, detections, new_domains, infostealers, and Certificate Transparency Logs (CTL)
- **URL scanning** — submit URLs and retrieve scan reports
- **Campaign & cluster intelligence** — browse tracked phishing/malware campaigns and infrastructure clusters
- **Pro tier ready** — set `WEBAMON_PRO=true` to switch to `pro.webamon.com`

## Available Tools

| Tool | Description |
|------|-------------|
| `search_scans` | Search the scans index (domain names, tags, fingerprints, page titles, etc.) |
| `search_domains` | Search the domains index |
| `search_servers` | Search the servers index (IPs, ASNs, hosting, headers) |
| `search_resources` | Search web resources collected during scans |
| `search_detections` | Search threat detection records |
| `search_new_domains` | Search newly registered domains (NRDs) |
| `search_infostealers` | Search infostealer-related records |
| `search_ctl` | Search Certificate Transparency Log indexes by date |
| `basic_search` | Simple keyword search (non-Lucene) |
| `submit_scan` | Submit a URL for scanning |
| `get_scan_report` | Retrieve a completed scan report by report ID |
| `get_screenshot` | Retrieve the screenshot for a scan report |
| `list_campaigns` | List tracked phishing/malware campaigns |
| `list_clusters` | List infrastructure clusters |

## Installation

```bash
git clone https://github.com/xelemental/webamon-mcp.git
cd webamon-mcp
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

pip install -e .
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "webamon": {
      "command": "C:\\path\\to\\webamon-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "webamon_mcp"],
      "env": {
        "WEBAMON_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**macOS** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "webamon": {
      "command": "/path/to/webamon-mcp/venv/bin/python",
      "args": ["-m", "webamon_mcp"],
      "env": {
        "WEBAMON_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Pro Tier

If you have a Pro API key, add `WEBAMON_PRO` to switch to the pro base URL:

```json
"env": {
  "WEBAMON_API_KEY": "your-pro-api-key",
  "WEBAMON_PRO": "true"
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WEBAMON_API_KEY` | Yes | Your Webamon API key |
| `WEBAMON_PRO` | No | Set to `true` to use `pro.webamon.com` (default: free tier) |
| `WEBAMON_MCP_TRANSPORT` | No | Transport mode — `stdio` (default) or `sse` |

## Lucene Query Examples

```
# Find scans of a specific domain
domain_name:example.com

# Find phishing pages tagged by OpenPhish
tag:openphish

# Find scans with a specific page title
page_title:"Account Verification"

# Find AI-flagged phishing pages
threat_ai:phishing

# Find scans by SSL fingerprint
fingerprint.ssl:"HASH_VALUE"

# Wildcard — all recent entries
*
```

## API Tiers

| Feature | Free | Pro |
|---------|------|-----|
| Base URL | `search.webamon.com` | `pro.webamon.com` |
| Auth | API key (`x-api-key`) | API key (`x-api-key`) |
| Max results | 25 per query | 500 per query |
| Pagination | No | Yes |
| Rate limits | Standard | Higher |
| Monitor API | No | Yes |

## License

MIT

## Author

[Subhajeet Singha](https://github.com/xelemental) ([@xelemental](https://github.com/xelemental))