# PocMap
[](https://github.com/zebbern/pocmap)
[](https://pypi.org/project/pocmap/)
[](https://zebbern.github.io/pocmap/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://docs.pydantic.dev/)
AI-agent-optimized CVE / PoC / exploit discovery toolkit — CLI, Python API, and MCP server.
**Docs:** [https://zebbern.github.io/pocmap/](https://zebbern.github.io/pocmap/)
## Features
- **Multi-source PoCs** — GitHub, Exploit-DB, Metasploit, Nuclei, labs, bug bounty write-ups; curated indexes first, then GitHub Search fallback for index-lag CVEs
- **MCP server** — 22 tools for Claude Desktop, Cursor, and other MCP clients
- **CLI + CI** — table/json/csv/md/sarif output, exit-code contract, `bulk --fail-on` SARIF gate
- **Cache & offline** — persistent TTL'd HTTP cache and first-class `--offline` mode
- **Bug bounty toolkit** — Python API checklists, workflows, templates, scope (CLI `bugbounty` searches write-ups only)
## Install
```bash
pip install pocmap
pip install "pocmap[server]" # MCP SDK / pocmap-mcp
pip install -e ".[server,dev]" # from a clone
```
Python 3.10+. Optional: `GITHUB_API_TOKEN`, `NVD_API_KEY` for higher rate limits.
More: [Getting started](https://zebbern.github.io/pocmap/getting-started/) · [Configuration](https://zebbern.github.io/pocmap/configuration/)
## Quick start
```bash
pocmap lookup CVE-2021-44228
pocmap bulk cves.txt --format sarif --fail-on kev
pocmap latest --since 7d --severity critical --only-with-poc
pocmap discover "Log4j" --version 2.x
pocmap package PyPI django --version 3.2.0
pocmap doctor
pocmap lookup CVE-2021-44228 --format json
pocmap --offline lookup CVE-2021-44228
```
`pocmap --help` lists all commands. Guides: [CLI reference](https://zebbern.github.io/pocmap/cli/).
### MCP Server Setup
Recommended: [`uv`](https://github.com/astral-sh/uv) on `PATH`, no local clone required.
`--from pocmap[server]` pulls the package with the MCP SDK and runs the `pocmap-mcp`
console script over STDIO.
```json
{
"mcpServers": {
"pocmap": {
"command": "uvx",
"args": ["--from", "pocmap[server]", "pocmap-mcp"],
"env": {
"GITHUB_API_TOKEN": "ghp_xxxxxxxxxxxx",
"NVD_API_KEY": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}
}
}
```
Pin a release by changing the package arg to `pocmap[server]==X.Y.Z`; keep
`pocmap-mcp` as the last arg. Optional env vars raise GitHub / NVD rate limits.
### Running the MCP Server
Requires the `[server]` extra (MCP SDK). Protocol revisions up to `2026-07-28` are
supported; STDIO clients typically negotiate `2025-11-25` at `initialize`.
```bash
pip install "pocmap[server]"
# or from a clone: pip install -e ".[server]"
# STDIO (default — what Claude Desktop / Cursor / most MCP clients expect)
pocmap-mcp
python -m pocmap.mcp_server
# Other transports / flags
pocmap-mcp --transport sse
pocmap-mcp --transport http --host 127.0.0.1 --port 9000
# Non-loopback HTTP/SSE requires a bearer token
POCMAP_MCP_AUTH_TOKEN='replace-with-a-long-random-token' \
pocmap-mcp --transport http --host 0.0.0.0 --port 9000
pocmap-mcp --debug
```
STDIO does not use MCP HTTP authentication. Network transports allow an
unauthenticated loopback bind (`127.0.0.1`, `localhost`, or `::1`). Any other
bind address requires `POCMAP_MCP_AUTH_TOKEN`; when set, every HTTP and SSE
request must send `Authorization: Bearer <token>`. The server does not log the
token. Network requests are rate-limited per authenticated principal by default
to 60 requests per 60 seconds. Set `POCMAP_MCP_RATE_LIMIT` and
`POCMAP_MCP_RATE_WINDOW_SECONDS` to change those limits. Bearer tokens are
credentials: use HTTPS or a trusted TLS-terminating ingress before exposing a
non-loopback bind. The built-in listener does not provide TLS.
The configured token is the single operator principal authorized to call all
MCP tools; invalid credentials are rate-limited separately by client address.
### MCP Tools (22 Total)
| Tool | Category | Description |
|------|----------|-------------|
| `lookup_cve` | CVE Intel | Full CVE details from NVD, CVE.org, CISA KEV, EPSS |
| `get_epss_score` | CVE Intel | EPSS exploitation probability score (0.0-1.0) with risk level |
| `check_kev_status` | CVE Intel | Check CISA Known Exploited Vulnerabilities catalog status |
| `get_attack_techniques` | CVE Intel | MITRE ATT&CK techniques a CVE maps to — how it's exploited and what follows |
| `find_github_pocs` | Exploits | GitHub PoC repos with stars, language, and forks |
| `verify_github_pocs` | Exploits | **Reads PoC source** to score whether a repo really exploits the CVE (opt-in) |
| `find_metasploit_module` | Exploits | Metasploit module availability and msfconsole command |
| `find_exploitdb_entry` | Exploits | ExploitDB entry with searchsploit command |
| `find_nuclei_template` | Exploits | Nuclei scanner template for detection/verification |
| `find_bug_bounty_reports` | Research | Bug bounty write-ups from HackerOne, PentesterLand |
| `find_practice_labs` | Labs | CTF labs on Vulhub and HackTheBox |
| `find_vulhub_docker` | Labs | Vulhub Docker Compose environment with setup steps |
| `find_recent_exploits` | Discovery | Recently published CVEs with PoC/KEV/severity filters |
| `discover_product_cves` | Discovery | Find CVEs by product name with version constraints |
| `discover_package_cves` | Discovery | **Dependency vulnerabilities + the releases that fix them** (OSV, no API key) |
| `cve_to_cpe` | Conversion | Convert CVE to affected CPE identifiers |
| `cpe_to_cve` | Conversion | Find all CVEs affecting a given product (CPE) |
| `generate_json_report` | Reports | **One-shot CVE assessment** — details + all exploits + labs + bug bounty reports for one or many CVEs in a single call |
| `generate_html_report` | Reports | Self-contained HTML report with styled cards |
| `get_cve_assessment_playbook` | Playbooks | Full CVE assessment workflow playbook |
| `get_rapid_response_playbook` | Playbooks | Emergency response playbook for critical CVEs |
| `get_bug_bounty_playbook` | Playbooks | Bug bounty submission workflow playbook |
### MCP Resources
| Resource | URI Pattern | Content |
|----------|-------------|---------|
| CVE Info | `cve://{cve_id}` | Full CVE details as human-readable text |
| Exploits | `exploits://{cve_id}` | All available exploits and PoCs |
| Report | `report://{cve_id}` | Generated vulnerability report (JSON) |
### Example Agent Workflow
```
User: "Should I prioritize CVE-2021-44228, CVE-2023-38408, or CVE-2024-21413?"
Agent:
1. generate_json_report("CVE-2021-44228,CVE-2023-38408,CVE-2024-21413")
2. Read each entry's triage.priority / reasons (KEV, EPSS, exploit counts)
3. Prefer Log4j when triage shows KEV + highest EPSS + most PoCs
```
PoC-only ask → `find_github_pocs` (check `labels` / `trust_score` / `sources`).
Dependency ask → `discover_package_cves` (use `canonical_cve` + `aliases`, not product discovery).
Claude Desktop / Cursor JSON configs and transports:
[Getting started → MCP](https://zebbern.github.io/pocmap/getting-started/#mcp-server).
Tool inventory: [MCP tools](https://zebbern.github.io/pocmap/reference/mcp-tools/).
Agent contract: [`.claude/skills/pocmap-agent/references/mcp_tools.md`](.claude/skills/pocmap-agent/references/mcp_tools.md).
## Python API
```python
from pocmap.services.cve_service import CVEService
with CVEService() as svc:
info = svc.get_cve_info("CVE-2021-44228")
print(info.cvss.base_score, info.kev_status, info.epss)
```
Full service examples: [Python API](https://zebbern.github.io/pocmap/python-api/).
## Docs
| Topic | Link |
|-------|------|
| Getting started / MCP clients | [getting-started](https://zebbern.github.io/pocmap/getting-started/) |
| CLI (`latest`, `discover`, `package`, formats, cache, CI) | [cli](https://zebbern.github.io/pocmap/cli/) |
| Python API | [python-api](https://zebbern.github.io/pocmap/python-api/) |
| Configuration | [configuration](https://zebbern.github.io/pocmap/configuration/) |
| Bug bounty toolkit | [bug-bounty](https://zebbern.github.io/pocmap/bug-bounty/) |
| Verifying PoCs (opt-in) | [verifying-pocs](https://zebbern.github.io/pocmap/verifying-pocs/) |
| Architecture | [architecture](https://zebbern.github.io/pocmap/architecture/) |
| Contributing / plugins | [contributing](https://zebbern.github.io/pocmap/contributing/) |
| Schemas | [schemas](https://zebbern.github.io/pocmap/reference/schemas/) |
## License
MIT — see [LICENSE](LICENSE).
*PocMap is a research and defensive tool. Always operate within applicable law and program scope.*