PocMap Agent Skill
Use PocMap to look up CVEs, find exploits/PoCs, discover recent vulnerabilities,
map products/packages to CVEs, check KEV/EPSS, find bug bounty reports, and locate
practice labs.
Source of truth: src/pocmap/ wins over this skill. The public Python API is
synchronous. Full MCP contracts live in references/mcp_tools.md (canonical
agent consumption guide). CLI flags: references/cli_commands.md.
Quick Start
pip install "pocmap[server]" # CLI + MCP (mcp SDK 2.x / MCPServer via [server])
# from a clone: pip install -e ".[server,dev]"
pocmap lookup CVE-2021-44228
python -m pocmap --help # authoritative CLI list (13 commands)
# MCP server (src/pocmap/mcp/ → pocmap-mcp via mcp_server facade)
uvx --from 'pocmap[server]' pocmap-mcp
pocmap-mcp # after install
python -m pocmap.mcp_server
from pocmap.services import CVEService
with CVEService() as svc:
info = svc.get_cve_info("CVE-2021-44228")
print(info.cvss, info.epss, info.kev_status) # epss is 0–100 in the Python model
Decision Guide
| Goal |
MCP tool |
CLI |
| PoC / exploit repos only |
find_github_pocs (first) |
(shown in lookup) |
| Full assessment of known CVE ID(s) |
generate_json_report |
pocmap lookup / bulk |
| Look up one CVE (metadata) |
lookup_cve |
pocmap lookup CVE-… |
| Recent CVEs / monitoring |
find_recent_exploits |
pocmap latest --since 24h |
| CVEs for a deployed product |
discover_product_cves |
pocmap discover "Product" |
| CVEs for a dependency / lockfile |
discover_package_cves |
— |
GitHub PoCs (+ labels/trust_score/sources) |
find_github_pocs |
(shown in lookup) |
| Metasploit (multi-module; path/type) |
find_metasploit_module (limit>1) |
— |
| ExploitDB / Nuclei |
find_exploitdb_entry / find_nuclei_template |
— |
| Prioritize known CVE IDs |
generate_json_report → read triage |
— |
| How it is exploited (ATT&CK) |
get_attack_techniques |
— |
| Verify PoC is real |
verify_github_pocs (needs POCMAP_ALLOW_FETCH_POC_SOURCE=1) |
— |
| KEV / EPSS |
check_kev_status / get_epss_score |
— |
| Bug bounty / labs |
find_bug_bounty_reports / find_practice_labs / find_vulhub_docker |
bugbounty / labs |
| CVE ↔ CPE |
cve_to_cpe / cpe_to_cve |
cpes / cpe2cve |
| HTML report |
generate_html_report |
pocmap bulk |
| Playbooks |
get_*_playbook |
— |
Key Constraints
- CVE ID:
CVE-YYYY-NNNN+ (^CVE-\d{4}-\d+$). Lowercase is normalized.
- Bulk / report: max 100 CVEs per call.
- EPSS scales (convert at the boundary):
- Filter
min_epss on CLI / find_recent_exploits: 0–100
- MCP normalized CVE fields (
epss_score on lookup_cve, reports, recent): 0.0–1.0
get_epss_score: 0.0–1.0- Python
CVEInfo.epss: 0–100
--since: 1h, 24h, 7d, 30d. Severity: critical|high|medium|low.- Product vs package:
discover_product_cves = deployed product (nginx, Confluence).
discover_package_cves = dependency/SBOM (PyPI/npm/Maven/…) — only tool with fix versions.
- Silent negatives: always read
sources / error category / recent filter_stats.poc_check
before concluding "none". Empty + rate_limited/error means unknown, not none.
Empty ATT&CK list means unmapped, not harmless.
- Package dual IDs: use
canonical_cve + aliases on discover_package_cves rows.
Env vars for MCP. Clients launch the server with a filtered env. Put
GITHUB_API_TOKEN / NVD_API_KEY / POCMAP_* in the client config env block —
shell exports do not reach MCP. Settings: src/pocmap/config.py
(POCMAP_HTTP_TIMEOUT, not POCMAP_REQUEST_TIMEOUT; GITHUB_API_TOKEN, not
POCMAP_GITHUB_TOKEN).
Error Handling (MCP)
Every tool returns a dict (structuredContent), not a JSON string. Failures use
an error envelope — check error first:
error, error_type, category, retryable, context
# category: not_found | rate_limited | offline | network_error |
# invalid_input | permission_error | not_enabled | unknown
Retry only when retryable is true (≈3 attempts with backoff), then surface
suggestion/hint if present.
Architecture (brief)
CLI / MCP → services/ → clients/ → models (pydantic). Services are sync
context managers. Key classes: CVEService, ExploitService (find_exploits /
find_exploits_with_status), ReportService, RecentService,
ProductDiscoveryService, PackageService, LabService, BugBountyService.
References
references/mcp_tools.md — all 22 MCP tools, resources, prompts, return shapesreferences/cli_commands.md — all 13 CLI commands with real flags- GitHub: https://github.com/zebbern/pocmap
1---2name: pocmap-agent3description: Use the PocMap Python package for CVE exploit discovery, vulnerability research, and bug bounty hunting. Provides 22 MCP tools and 13 CLI commands for looking up CVEs, finding exploits/PoCs, discovering recent vulnerabilities, product-based CVE discovery, CPE/CVSS analysis, bug bounty report lookup, and practice lab environments. Trigger when the user mentions CVE lookup, exploit discovery, PoC finding, vulnerability assessment, bug bounty research, security analysis, CPE to CVE conversion, EPSS scoring, KEV catalog checking, recent CVE monitoring, product vulnerability discovery, or security report generation.4---56# PocMap Agent Skill78Use PocMap to look up CVEs, find exploits/PoCs, discover recent vulnerabilities,9map products/packages to CVEs, check KEV/EPSS, find bug bounty reports, and locate10practice labs.1112> **Source of truth:** `src/pocmap/` wins over this skill. The public Python API is13> **synchronous**. Full MCP contracts live in `references/mcp_tools.md` (canonical14> agent consumption guide). CLI flags: `references/cli_commands.md`.1516## Quick Start1718```bash19pip install "pocmap[server]" # CLI + MCP (mcp SDK 2.x / MCPServer via [server])20# from a clone: pip install -e ".[server,dev]"2122pocmap lookup CVE-2021-4422823python -m pocmap --help # authoritative CLI list (13 commands)2425# MCP server (src/pocmap/mcp/ → pocmap-mcp via mcp_server facade)26uvx --from 'pocmap[server]' pocmap-mcp27pocmap-mcp # after install28python -m pocmap.mcp_server29```3031```python32from pocmap.services import CVEService3334with CVEService() as svc:35 info = svc.get_cve_info("CVE-2021-44228")36 print(info.cvss, info.epss, info.kev_status) # epss is 0–100 in the Python model37```3839## Decision Guide4041| Goal | MCP tool | CLI |42|------|----------|-----|43| **PoC / exploit repos only** | **`find_github_pocs`** (first) | (shown in `lookup`) |44| **Full assessment of known CVE ID(s)** | **`generate_json_report`** | `pocmap lookup` / `bulk` |45| Look up one CVE (metadata) | `lookup_cve` | `pocmap lookup CVE-…` |46| Recent CVEs / monitoring | `find_recent_exploits` | `pocmap latest --since 24h` |47| CVEs for a deployed product | `discover_product_cves` | `pocmap discover "Product"` |48| CVEs for a dependency / lockfile | `discover_package_cves` | — |49| GitHub PoCs (+ `labels`/`trust_score`/`sources`) | `find_github_pocs` | (shown in `lookup`) |50| Metasploit (multi-module; path/type) | `find_metasploit_module` (`limit`>1) | — |51| ExploitDB / Nuclei | `find_exploitdb_entry` / `find_nuclei_template` | — |52| Prioritize known CVE IDs | `generate_json_report` → read `triage` | — |53| How it is exploited (ATT&CK) | `get_attack_techniques` | — |54| Verify PoC is real | `verify_github_pocs` (needs `POCMAP_ALLOW_FETCH_POC_SOURCE=1`) | — |55| KEV / EPSS | `check_kev_status` / `get_epss_score` | — |56| Bug bounty / labs | `find_bug_bounty_reports` / `find_practice_labs` / `find_vulhub_docker` | `bugbounty` / `labs` |57| CVE ↔ CPE | `cve_to_cpe` / `cpe_to_cve` | `cpes` / `cpe2cve` |58| HTML report | `generate_html_report` | `pocmap bulk` |59| Playbooks | `get_*_playbook` | — |6061## Key Constraints6263- **CVE ID:** `CVE-YYYY-NNNN+` (`^CVE-\d{4}-\d+$`). Lowercase is normalized.64- **Bulk / report:** max **100** CVEs per call.65- **EPSS scales (convert at the boundary):**66 - Filter `min_epss` on CLI / `find_recent_exploits`: **0–100**67 - MCP normalized CVE fields (`epss_score` on `lookup_cve`, reports, recent): **0.0–1.0**68 - `get_epss_score`: **0.0–1.0**69 - Python `CVEInfo.epss`: **0–100**70- **`--since`:** `1h`, `24h`, `7d`, `30d`. **Severity:** `critical|high|medium|low`.71- **Product vs package:** `discover_product_cves` = deployed product (nginx, Confluence).72 `discover_package_cves` = dependency/SBOM (PyPI/npm/Maven/…) — only tool with fix versions.73- **Silent negatives:** always read `sources` / error `category` / recent `filter_stats.poc_check`74 before concluding "none". Empty + `rate_limited`/`error` means *unknown*, not *none*.75 Empty ATT&CK list means *unmapped*, not harmless.76- **Package dual IDs:** use `canonical_cve` + `aliases` on `discover_package_cves` rows.7778> **Env vars for MCP.** Clients launch the server with a filtered env. Put79> `GITHUB_API_TOKEN` / `NVD_API_KEY` / `POCMAP_*` in the client config `env` block —80> shell exports do not reach MCP. Settings: `src/pocmap/config.py`81> (`POCMAP_HTTP_TIMEOUT`, not `POCMAP_REQUEST_TIMEOUT`; `GITHUB_API_TOKEN`, not82> `POCMAP_GITHUB_TOKEN`).8384## Error Handling (MCP)8586Every tool returns a **dict** (`structuredContent`), not a JSON string. Failures use87an error envelope — check `error` first:8889```text90error, error_type, category, retryable, context91# category: not_found | rate_limited | offline | network_error |92# invalid_input | permission_error | not_enabled | unknown93```9495Retry only when `retryable` is true (≈3 attempts with backoff), then surface96`suggestion`/`hint` if present.9798## Architecture (brief)99100**CLI / MCP → `services/` → `clients/` → `models` (pydantic).** Services are sync101context managers. Key classes: `CVEService`, `ExploitService` (`find_exploits` /102`find_exploits_with_status`), `ReportService`, `RecentService`,103`ProductDiscoveryService`, `PackageService`, `LabService`, `BugBountyService`.104105## References106107- `references/mcp_tools.md` — all **22** MCP tools, resources, prompts, return shapes108- `references/cli_commands.md` — all **13** CLI commands with real flags109- GitHub: https://github.com/zebbern/pocmap
zebbern