blackdome-mcp 0.1.0__tar.gz

blackdome_mcp-0.1.0/.github/workflows/publish-mcp.yml

@@ -0,0 +1,31 @@
+name: Publish to MCP Registry
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Validate server metadata
+        run: ./mcp-publisher validate server.json
+
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish server metadata
+        run: ./mcp-publisher publish server.json

blackdome_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+__pycache__/
+*.egg-info/
+.mcpregistry_*
+*.pyc

blackdome_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlackDome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blackdome_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: blackdome-mcp
+Version: 0.1.0
+Summary: BlackDome MCP Server — AI agent access to live honeypot threat intelligence, attacker IPs, IOCs, and credential intel.
+Project-URL: Homepage, https://blackdome.ai
+Project-URL: Documentation, https://blackdome.ai/docs/mcp
+Project-URL: Repository, https://github.com/blackdome-ai/blackdome-mcp
+Author-email: BlackDome <support@blackdome.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,blackdome,honeypot,iocs,mcp,security,threat-intel
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.blackdome-ai/blackdome -->
+
+# BlackDome MCP Server
+
+Give your AI agents direct access to **live honeypot threat intelligence**. Look up attacker IPs, browse indicators of compromise (IOCs), inspect captured credentials and malware payloads, profile threat actors, and render a real-time global attack map — all from Claude, Cursor, or any MCP-compatible client.
+
+Most tools are **free and need no API key** (the public community tier). A subset of high-value intelligence requires a paid plan.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install blackdome-mcp
+```
+
+### Configure
+
+The free public tools work with **no API key**. To unlock the paid tiers (credential intelligence, payloads, actors, warboard, STIX export), get an API key at **[https://blackdome.ai/pricing](https://blackdome.ai/pricing)**.
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "blackdome": {
+      "command": "blackdome-mcp",
+      "env": {
+        "BLACKDOME_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+> The `env` block is optional — omit `BLACKDOME_API_KEY` to run free public tools only.
+
+#### Claude Code
+
+```bash
+claude mcp add blackdome -- blackdome-mcp
+# Optional — only needed for paid tools:
+export BLACKDOME_API_KEY="your-api-key-here"
+```
+
+#### Cursor
+
+Add to your MCP settings:
+
+```json
+{
+  "blackdome": {
+    "command": "blackdome-mcp",
+    "env": {
+      "BLACKDOME_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+## Available Tools
+
+Free tools work with no key. Paid tools require an API key whose plan includes the listed feature.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `lookup_attacker_ip` | **Free** | Full dossier for one attacker IP — events, protocols, credentials (passwords masked), MITRE, edge nodes |
+| `top_attackers` | **Free** | Most active attacker IPs over a window — pick one to drill into |
+| `attack_map` | **Free** | Recent geolocated attack events for a live map (limit ≥ 10) |
+| `attack_heatmap` | **Free** | Country-aggregated attack heatmap with centroids (limit ≥ 5) |
+| `credential_preview` | **Free** | Sample of recent credentials (masked server-side) + teaser totals |
+| `verify_sigil` | **Free** | Verify a BlackDome Sigil / audit record by id |
+| `recent_iocs` | **Free** | Browse recent IOCs with full filter set (72h community delay) |
+| `ioc_trends` | **Free** | Aggregated IOC trends — totals, breakdowns, daily new, top MITRE |
+| `export_iocs` | **Free** (json/csv) · **Pro** (stix) | Export the IOC feed; STIX bundle needs the `stix_export` feature |
+| `search_credentials` | **Enterprise** (`credential_intel`) | Search the global credential corpus with PLAINTEXT passwords |
+| `credential_stats` | **Enterprise** (`credential_intel`) | Aggregate credential stats — top usernames/passwords, breakdowns |
+| `list_payloads` | **Pro** (`api_access`) | List captured malware payloads, or fetch one by sha256 (VT/MB intel) |
+| `get_actor` | **Pro** (`api_access`) | List clustered threat actors, or fetch one actor's sessions |
+| `warboard` | **Pro** (`api_access`) | Sigil leaderboard with intrusion narratives + attacker command tails |
+| `whoami` | **Any key** | Check your tenant, plan, features and live quota |
+
+**Plans:** Community (free) → Pro ($299, adds `stix_export`, `api_access`) → Enterprise ($2000, adds `credential_intel`, `bulk_api`) → OEM ($5000). See [pricing](https://blackdome.ai/pricing).
+
+## Example Prompts
+
+Once connected, try asking your AI assistant:
+
+- *"Who are the top attackers hitting the honeypots this month?"*
+- *"Look up attacker IP 176.65.139.56 and summarize what they tried."*
+- *"Show me the latest malicious sha256 IOCs from the last week."*
+- *"What are the IOC trends — which MITRE techniques are spiking?"*
+- *"Render a heatmap of where attacks are coming from."*
+- *"Export the IOC feed as CSV so I can load it into my SIEM."*
+- *"What plan am I on and which features do I have?"* (runs `whoami`)
+- *"Search captured SSH credentials for the username root."* (paid)
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BLACKDOME_API_KEY` | No | — | Bearer API key. Free tools work without it; paid tools require it |
+| `BLACKDOME_BASE_URL` | No | `https://api.blackdome.ai` | API base URL |
+| `BLACKDOME_TIMEOUT` | No | `15` | Request timeout in seconds |
+
+## Rate Limits
+
+The free community tier is capped at roughly **30 requests/minute** and **100 requests/day**, and community IOC data carries a **72-hour freshness delay**. Paid plans raise these limits substantially (Enterprise: 1000 req/min, 50,000 req/day). When you hit a limit the server returns a clear `429` error with retry timing. Use `whoami` to see your live quota.
+
+## Security
+
+- **Read-only.** Every tool is a GET request — the server never mutates BlackDome data.
+- **Keyless free tier.** Public tools require no API key and expose only community-tier data.
+- **Masked credentials.** The free `lookup_attacker_ip` tool masks captured passwords to `********` before returning them; `credential_preview` is masked server-side. Plaintext passwords are returned **only** by the paid `search_credentials` tool, which requires the `credential_intel` feature.
+- **Secrets stay local.** Your API key is read from the environment and sent only to the BlackDome API over HTTPS. No data is stored by the MCP server — it proxies directly to BlackDome.
+
+## License
+
+MIT

blackdome_mcp-0.1.0/README.md

@@ -0,0 +1,121 @@
+<!-- mcp-name: io.github.blackdome-ai/blackdome -->
+
+# BlackDome MCP Server
+
+Give your AI agents direct access to **live honeypot threat intelligence**. Look up attacker IPs, browse indicators of compromise (IOCs), inspect captured credentials and malware payloads, profile threat actors, and render a real-time global attack map — all from Claude, Cursor, or any MCP-compatible client.
+
+Most tools are **free and need no API key** (the public community tier). A subset of high-value intelligence requires a paid plan.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install blackdome-mcp
+```
+
+### Configure
+
+The free public tools work with **no API key**. To unlock the paid tiers (credential intelligence, payloads, actors, warboard, STIX export), get an API key at **[https://blackdome.ai/pricing](https://blackdome.ai/pricing)**.
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "blackdome": {
+      "command": "blackdome-mcp",
+      "env": {
+        "BLACKDOME_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+> The `env` block is optional — omit `BLACKDOME_API_KEY` to run free public tools only.
+
+#### Claude Code
+
+```bash
+claude mcp add blackdome -- blackdome-mcp
+# Optional — only needed for paid tools:
+export BLACKDOME_API_KEY="your-api-key-here"
+```
+
+#### Cursor
+
+Add to your MCP settings:
+
+```json
+{
+  "blackdome": {
+    "command": "blackdome-mcp",
+    "env": {
+      "BLACKDOME_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+## Available Tools
+
+Free tools work with no key. Paid tools require an API key whose plan includes the listed feature.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `lookup_attacker_ip` | **Free** | Full dossier for one attacker IP — events, protocols, credentials (passwords masked), MITRE, edge nodes |
+| `top_attackers` | **Free** | Most active attacker IPs over a window — pick one to drill into |
+| `attack_map` | **Free** | Recent geolocated attack events for a live map (limit ≥ 10) |
+| `attack_heatmap` | **Free** | Country-aggregated attack heatmap with centroids (limit ≥ 5) |
+| `credential_preview` | **Free** | Sample of recent credentials (masked server-side) + teaser totals |
+| `verify_sigil` | **Free** | Verify a BlackDome Sigil / audit record by id |
+| `recent_iocs` | **Free** | Browse recent IOCs with full filter set (72h community delay) |
+| `ioc_trends` | **Free** | Aggregated IOC trends — totals, breakdowns, daily new, top MITRE |
+| `export_iocs` | **Free** (json/csv) · **Pro** (stix) | Export the IOC feed; STIX bundle needs the `stix_export` feature |
+| `search_credentials` | **Enterprise** (`credential_intel`) | Search the global credential corpus with PLAINTEXT passwords |
+| `credential_stats` | **Enterprise** (`credential_intel`) | Aggregate credential stats — top usernames/passwords, breakdowns |
+| `list_payloads` | **Pro** (`api_access`) | List captured malware payloads, or fetch one by sha256 (VT/MB intel) |
+| `get_actor` | **Pro** (`api_access`) | List clustered threat actors, or fetch one actor's sessions |
+| `warboard` | **Pro** (`api_access`) | Sigil leaderboard with intrusion narratives + attacker command tails |
+| `whoami` | **Any key** | Check your tenant, plan, features and live quota |
+
+**Plans:** Community (free) → Pro ($299, adds `stix_export`, `api_access`) → Enterprise ($2000, adds `credential_intel`, `bulk_api`) → OEM ($5000). See [pricing](https://blackdome.ai/pricing).
+
+## Example Prompts
+
+Once connected, try asking your AI assistant:
+
+- *"Who are the top attackers hitting the honeypots this month?"*
+- *"Look up attacker IP 176.65.139.56 and summarize what they tried."*
+- *"Show me the latest malicious sha256 IOCs from the last week."*
+- *"What are the IOC trends — which MITRE techniques are spiking?"*
+- *"Render a heatmap of where attacks are coming from."*
+- *"Export the IOC feed as CSV so I can load it into my SIEM."*
+- *"What plan am I on and which features do I have?"* (runs `whoami`)
+- *"Search captured SSH credentials for the username root."* (paid)
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BLACKDOME_API_KEY` | No | — | Bearer API key. Free tools work without it; paid tools require it |
+| `BLACKDOME_BASE_URL` | No | `https://api.blackdome.ai` | API base URL |
+| `BLACKDOME_TIMEOUT` | No | `15` | Request timeout in seconds |
+
+## Rate Limits
+
+The free community tier is capped at roughly **30 requests/minute** and **100 requests/day**, and community IOC data carries a **72-hour freshness delay**. Paid plans raise these limits substantially (Enterprise: 1000 req/min, 50,000 req/day). When you hit a limit the server returns a clear `429` error with retry timing. Use `whoami` to see your live quota.
+
+## Security
+
+- **Read-only.** Every tool is a GET request — the server never mutates BlackDome data.
+- **Keyless free tier.** Public tools require no API key and expose only community-tier data.
+- **Masked credentials.** The free `lookup_attacker_ip` tool masks captured passwords to `********` before returning them; `credential_preview` is masked server-side. Plaintext passwords are returned **only** by the paid `search_credentials` tool, which requires the `credential_intel` feature.
+- **Secrets stay local.** Your API key is read from the environment and sent only to the BlackDome API over HTTPS. No data is stored by the MCP server — it proxies directly to BlackDome.
+
+## License
+
+MIT

blackdome_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "blackdome-mcp"
+version = "0.1.0"
+description = "BlackDome MCP Server — AI agent access to live honeypot threat intelligence, attacker IPs, IOCs, and credential intel."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "BlackDome", email = "support@blackdome.ai" }]
+keywords = ["mcp", "threat-intel", "blackdome", "security", "iocs", "honeypot", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[project.scripts]
+blackdome-mcp = "blackdome_mcp.server:main"
+
+[project.urls]
+Homepage = "https://blackdome.ai"
+Documentation = "https://blackdome.ai/docs/mcp"
+Repository = "https://github.com/blackdome-ai/blackdome-mcp"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]

blackdome_mcp-0.1.0/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.blackdome-ai/blackdome",
+  "title": "BlackDome Threat Intel",
+  "description": "Live honeypot threat intel: attacker IPs, IOCs, credentials, payloads, actors.",
+  "websiteUrl": "https://blackdome.ai",
+  "repository": {
+    "url": "https://github.com/blackdome-ai/blackdome-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "blackdome-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "BLACKDOME_API_KEY",
+          "description": "Optional Bearer API key. Free public tools work without it; paid tiers (credential intel, payloads, actors, warboard, STIX export) require a key. Get one at https://blackdome.ai/pricing",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "BLACKDOME_BASE_URL",
+          "description": "API base URL (default https://api.blackdome.ai).",
+          "isRequired": false,
+          "default": "https://api.blackdome.ai"
+        },
+        {
+          "name": "BLACKDOME_TIMEOUT",
+          "description": "HTTP request timeout in seconds (default 15). Increase for large STIX/CSV exports.",
+          "isRequired": false,
+          "default": "15"
+        }
+      ]
+    }
+  ]
+}

blackdome_mcp-0.1.0/src/blackdome_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""BlackDome MCP Server — AI agent access to live honeypot threat intelligence."""
+
+__version__ = "0.1.0"