# Honeypot MCP Server

A small [Model Context Protocol](https://modelcontextprotocol.io) server that
exposes my live honeypot's threat-intelligence database to an MCP client
(Claude Desktop / Claude Code) as **read-only** tools — so I can investigate
attacker activity by just asking, instead of writing SQL.

The data comes from a self-hosted honeypot stack (Cowrie SSH/Telnet + a custom
HTTP honeypot) writing into PostgreSQL — currently ~530k attack sessions, ~33k
login attempts, and thousands of captured attacker commands and file-staging
events.

## Tools

| Tool | What it returns |
|------|-----------------|
| `honeypot_overview(days)` | Totals (sessions, unique IPs, logins, commands, file events) + breakdown by honeypot/protocol |
| `top_attackers(days, limit)` | Busiest source IPs with country + ASN org |
| `top_credentials(days, limit)` | Most-tried username/password pairs |
| `recent_commands(days, limit)` | Commands attackers ran post-login (TTPs) |
| `attacks_by_country(days, limit)` | Sessions grouped by source country |
| `malware_downloads(days, limit)` | Captured file/malware staging (filename, URL, sha256) |
| `lookup_ip(ip)` | Full profile for one IP: sessions, geo/ASN, creds tried, commands, ban status |

## Safety

- **Read-only by construction.** Every connection opens a read-only transaction
  and every query is a `SELECT`. No tool mutates data.
- The IP passed to `lookup_ip` is validated with `ipaddress` and bound as a query
  parameter — never string-formatted into SQL.
- Recommended: point `HONEYPOT_DATABASE_URL` at a DB role granted `SELECT` only.

## Setup

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # then edit with your connection string
export HONEYPOT_DATABASE_URL="postgresql://user:pass@127.0.0.1:5433/honeypot"

python server.py selftest      # verify DB connectivity
python server.py               # run as an MCP (stdio) server
```

## Connecting a client

**Claude Code** (`claude mcp add`):

```bash
claude mcp add honeypot -- bash -lc 'cd /path/to/honeypot-mcp && \
  HONEYPOT_DATABASE_URL="postgresql://user:pass@127.0.0.1:5433/honeypot" \
  .venv/bin/python server.py'
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "honeypot": {
      "command": "/path/to/honeypot-mcp/.venv/bin/python",
      "args": ["/path/to/honeypot-mcp/server.py"],
      "env": { "HONEYPOT_DATABASE_URL": "postgresql://user:pass@127.0.0.1:5433/honeypot" }
    }
  }
}
```

The DB lives on my server (bound to localhost), so I either run this server
there, or launch it over SSH stdio from my laptop:

```json
{ "mcpServers": { "honeypot": {
  "command": "ssh",
  "args": ["ubuntu", "cd honeypot-mcp && .venv/bin/python server.py"]
}}}
```