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

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 shapes
• references/cli_commands.md — all 13 CLI commands with real flags
• GitHub: https://github.com/zebbern/pocmap