vuln-intel-mcp 0.1.0__tar.gz

vuln_intel_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.DS_Store

vuln_intel_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Raj
+
+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.

vuln_intel_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: vuln-intel-mcp
+Version: 0.1.0
+Summary: Local MCP server for CVE remediation intelligence from public sources (NVD, CISA KEV, FIRST EPSS). Your model does the reasoning — no API keys, no external LLM calls, no data leaves your machine.
+Project-URL: Homepage, https://clawofrohan.com/vuln-intel
+Project-URL: Source, https://github.com/rohanrajnist/vuln-intel-mcp
+Author: Rohan Raj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cisa-kev,cve,epss,mcp,nvd,security,servicenow,threat-intelligence,vulnerability
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# vuln-intel-mcp
+
+A local **MCP server** that gives any AI agent — Claude Desktop, Claude Code, Cline, Cursor, or your own — CVE remediation intelligence from public sources: **NVD**, **CISA KEV**, and **FIRST EPSS**.
+
+**Your model does the reasoning. This server does not.**
+
+That is the whole point: the server only does the token-free work — fetching public vulnerability data over HTTP and computing an objective priority. It **never calls an LLM, needs no API key, and sends nothing anywhere except read-only requests to public vulnerability databases.** The remediation write-up and the ServiceNow note are produced by *your* model, in *your* session, from the structured facts the tools return. No one's API tokens are consumed but your own.
+
+Built by [Rohan Raj](https://clawofrohan.com/vuln-intel). A hosted demo with AI synthesis and a live cost ledger runs at **clawofrohan.com/vuln-intel**.
+
+---
+
+## Install & connect
+
+You need Python 3.10+. The easiest runner is [`uv`](https://docs.astral.sh/uv/) (`uvx` downloads and runs on demand — nothing to install permanently).
+
+### Claude Code
+
+```bash
+claude mcp add vuln-intel -- uvx vuln-intel-mcp
+```
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "vuln-intel": {
+      "command": "uvx",
+      "args": ["vuln-intel-mcp"]
+    }
+  }
+}
+```
+
+### Cline / Cursor / any MCP client
+
+Same shape — command `uvx`, args `["vuln-intel-mcp"]`. Or if you installed it with `pip install vuln-intel-mcp`, use command `vuln-intel-mcp` with no args.
+
+Restart the client, and ask it something like *"Should I patch CVE-2024-3400?"* or *"What's the exploit status of Log4Shell?"*
+
+---
+
+## Tools
+
+| Tool | What it returns (token-free) | What your model does with it |
+|------|------------------------------|------------------------------|
+| `cve_lookup` | NVD facts, CVSS, CWEs, affected products, fix versions from CPE data, EPSS probability, CISA KEV status, and a computed **P1–P4** priority | Writes fix versions, remediation steps, workarounds, and a ServiceNow VR note |
+| `cve_search` | Candidate CVEs for a free-form product/keyword query (NVD keyword search) | Picks the right CVE, then calls `cve_lookup` |
+| `cve_exploit_intel` | Public exploit signals — KEV exploited/ransomware flags, EPSS score, and public GitHub repos referencing the CVE (often PoC/exploit code) | Judges weaponization and urgency |
+
+---
+
+## Optional environment variables
+
+All optional — the server works with none. These raise **your own** public-API rate limits:
+
+- `NVD_API_KEY` — a free [NVD API key](https://nvd.nist.gov/developers/request-an-api-key) for higher NVD throughput.
+- `GITHUB_TOKEN` — a GitHub token for more GitHub repo searches in `cve_exploit_intel`.
+
+---
+
+## Privacy
+
+- No telemetry. No account. No key required.
+- Outbound requests go only to `services.nvd.nist.gov`, `api.first.org`, `cisa.gov`, and (for exploit intel) `api.github.com`.
+- The CVE ids and search terms you look up are sent to those public services, exactly as if you visited them in a browser.
+
+## License
+
+MIT © Rohan Raj

vuln_intel_mcp-0.1.0/README.md

@@ -0,0 +1,73 @@
+# vuln-intel-mcp
+
+A local **MCP server** that gives any AI agent — Claude Desktop, Claude Code, Cline, Cursor, or your own — CVE remediation intelligence from public sources: **NVD**, **CISA KEV**, and **FIRST EPSS**.
+
+**Your model does the reasoning. This server does not.**
+
+That is the whole point: the server only does the token-free work — fetching public vulnerability data over HTTP and computing an objective priority. It **never calls an LLM, needs no API key, and sends nothing anywhere except read-only requests to public vulnerability databases.** The remediation write-up and the ServiceNow note are produced by *your* model, in *your* session, from the structured facts the tools return. No one's API tokens are consumed but your own.
+
+Built by [Rohan Raj](https://clawofrohan.com/vuln-intel). A hosted demo with AI synthesis and a live cost ledger runs at **clawofrohan.com/vuln-intel**.
+
+---
+
+## Install & connect
+
+You need Python 3.10+. The easiest runner is [`uv`](https://docs.astral.sh/uv/) (`uvx` downloads and runs on demand — nothing to install permanently).
+
+### Claude Code
+
+```bash
+claude mcp add vuln-intel -- uvx vuln-intel-mcp
+```
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "vuln-intel": {
+      "command": "uvx",
+      "args": ["vuln-intel-mcp"]
+    }
+  }
+}
+```
+
+### Cline / Cursor / any MCP client
+
+Same shape — command `uvx`, args `["vuln-intel-mcp"]`. Or if you installed it with `pip install vuln-intel-mcp`, use command `vuln-intel-mcp` with no args.
+
+Restart the client, and ask it something like *"Should I patch CVE-2024-3400?"* or *"What's the exploit status of Log4Shell?"*
+
+---
+
+## Tools
+
+| Tool | What it returns (token-free) | What your model does with it |
+|------|------------------------------|------------------------------|
+| `cve_lookup` | NVD facts, CVSS, CWEs, affected products, fix versions from CPE data, EPSS probability, CISA KEV status, and a computed **P1–P4** priority | Writes fix versions, remediation steps, workarounds, and a ServiceNow VR note |
+| `cve_search` | Candidate CVEs for a free-form product/keyword query (NVD keyword search) | Picks the right CVE, then calls `cve_lookup` |
+| `cve_exploit_intel` | Public exploit signals — KEV exploited/ransomware flags, EPSS score, and public GitHub repos referencing the CVE (often PoC/exploit code) | Judges weaponization and urgency |
+
+---
+
+## Optional environment variables
+
+All optional — the server works with none. These raise **your own** public-API rate limits:
+
+- `NVD_API_KEY` — a free [NVD API key](https://nvd.nist.gov/developers/request-an-api-key) for higher NVD throughput.
+- `GITHUB_TOKEN` — a GitHub token for more GitHub repo searches in `cve_exploit_intel`.
+
+---
+
+## Privacy
+
+- No telemetry. No account. No key required.
+- Outbound requests go only to `services.nvd.nist.gov`, `api.first.org`, `cisa.gov`, and (for exploit intel) `api.github.com`.
+- The CVE ids and search terms you look up are sent to those public services, exactly as if you visited them in a browser.
+
+## License
+
+MIT © Rohan Raj

vuln_intel_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vuln-intel-mcp"
+version = "0.1.0"
+description = "Local MCP server for CVE remediation intelligence from public sources (NVD, CISA KEV, FIRST EPSS). Your model does the reasoning — no API keys, no external LLM calls, no data leaves your machine."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Rohan Raj" }]
+keywords = ["mcp", "cve", "vulnerability", "security", "servicenow", "nvd", "cisa-kev", "epss", "threat-intelligence"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Security",
+]
+dependencies = ["mcp>=1.2.0", "httpx>=0.27"]
+
+[project.scripts]
+vuln-intel-mcp = "vuln_intel_mcp.server:main"
+
+[project.urls]
+Homepage = "https://clawofrohan.com/vuln-intel"
+Source = "https://github.com/rohanrajnist/vuln-intel-mcp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vuln_intel_mcp"]

vuln_intel_mcp-0.1.0/src/vuln_intel_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""vuln-intel-mcp — local CVE intelligence MCP server (public data only)."""
+__version__ = "0.1.0"

vuln_intel_mcp-0.1.0/src/vuln_intel_mcp/server.py

@@ -0,0 +1,256 @@
+"""vuln-intel-mcp — local MCP server for CVE remediation intelligence.
+
+Design principle: this server does ONLY the token-free work — fetching public
+data (NVD, CISA KEV, FIRST EPSS, public GitHub) over HTTP and computing an
+objective priority. It never calls an LLM and needs no API keys. The reasoning
+(remediation narrative, ServiceNow note) is done by *your* model, in your own
+session, from the structured facts these tools return. Nothing leaves your
+machine except read-only requests to public vulnerability databases.
+
+By Rohan Raj — hosted demo with AI synthesis at https://clawofrohan.com/vuln-intel
+"""
+import os
+import re
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+NVD_URL = "https://services.nvd.nist.gov/rest/json/cves/2.0"
+EPSS_URL = "https://api.first.org/data/v1/epss"
+KEV_URL = "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json"
+GH_URL = "https://api.github.com/search/repositories"
+CVE_RE = re.compile(r"^CVE-\d{4}-\d{4,7}$", re.IGNORECASE)
+UA = {"User-Agent": "vuln-intel-mcp"}
+# Optional: set NVD_API_KEY / GITHUB_TOKEN for higher public rate limits (still your keys, not ours).
+NVD_KEY = os.environ.get("NVD_API_KEY")
+GH_TOKEN = os.environ.get("GITHUB_TOKEN")
+
+_kev_cache = {"loaded": False, "ids": {}}
+
+mcp = FastMCP(
+    "vuln-intel",
+    instructions=(
+        "Vulnerability Response intelligence from public data (NVD, CISA KEV, "
+        "FIRST EPSS). These tools return structured facts and an objective "
+        "priority; YOU synthesize the remediation guidance and ServiceNow note "
+        "from them. No external LLM is called and no API key is required."
+    ),
+)
+
+
+async def _client():
+    return httpx.AsyncClient(timeout=30, headers=UA)
+
+
+def _nvd_headers():
+    return {**UA, **({"apiKey": NVD_KEY} if NVD_KEY else {})}
+
+
+async def _load_kev(cx):
+    if not _kev_cache["loaded"]:
+        try:
+            r = await cx.get(KEV_URL)
+            r.raise_for_status()
+            _kev_cache["ids"] = {
+                v["cveID"].upper(): v for v in r.json().get("vulnerabilities", [])
+            }
+            _kev_cache["loaded"] = True
+        except Exception:
+            pass
+    return _kev_cache["ids"]
+
+
+def _parse_nvd(cve):
+    desc = next((d["value"] for d in cve.get("descriptions", []) if d["lang"] == "en"), "")
+    cvss = severity = vector = None
+    metrics = cve.get("metrics", {})
+    for key in ("cvssMetricV40", "cvssMetricV31", "cvssMetricV30", "cvssMetricV2"):
+        if metrics.get(key):
+            m = metrics[key][0]
+            d = m.get("cvssData", {})
+            cvss, severity = d.get("baseScore"), d.get("baseSeverity") or m.get("baseSeverity")
+            vector = d.get("vectorString")
+            break
+    cwes = sorted({
+        de["value"] for w in cve.get("weaknesses", []) for de in w.get("description", [])
+        if de["value"].startswith("CWE")
+    })
+    affected, fix_hints = [], []
+    for cfg in cve.get("configurations", []):
+        for node in cfg.get("nodes", []):
+            for m in node.get("cpeMatch", []):
+                if not m.get("vulnerable"):
+                    continue
+                p = m["criteria"].split(":")
+                prod = f"{p[3]}/{p[4]}".replace("_", " ")
+                if m.get("versionEndExcluding"):
+                    hint = f"{prod}: fixed in {m['versionEndExcluding']} (upgrade to that version or later)"
+                    if hint not in fix_hints:
+                        fix_hints.append(hint)
+                entry = prod if p[5] in ("*", "-") else f"{prod} {p[5]}"
+                if entry not in affected and len(affected) < 12:
+                    affected.append(entry)
+    refs = [{"url": r["url"], "tags": r.get("tags", [])} for r in cve.get("references", [])]
+    advisories = [r["url"] for r in refs if {"Patch", "Vendor Advisory"} & set(r["tags"])][:6]
+    return {
+        "description": desc, "cvss": cvss, "severity": severity, "vector": vector,
+        "cwes": cwes[:6], "affected_products": affected, "fix_hints_from_cpe": fix_hints[:10],
+        "vendor_advisories": advisories, "references": [r["url"] for r in refs[:10]],
+        "published": cve.get("published"), "last_modified": cve.get("lastModified"),
+    }
+
+
+def _priority(kev, cvss, epss):
+    cvss, epss = cvss or 0, epss or 0
+    if kev:
+        return {"level": "P1", "rationale": "Actively exploited in the wild (CISA KEV) — remediate immediately",
+                "kev_due_date": kev.get("dueDate"), "ransomware_use": kev.get("knownRansomwareCampaignUse")}
+    if cvss >= 9 or epss >= 0.5:
+        return {"level": "P2", "rationale": "Critical severity or high exploit probability — urgent patching"}
+    if cvss >= 7 or epss >= 0.1:
+        return {"level": "P3", "rationale": "High severity — remediate within standard patch cycle"}
+    return {"level": "P4", "rationale": "Moderate/low — batch with routine maintenance"}
+
+
+@mcp.tool()
+async def cve_lookup(cve_id: str) -> dict:
+    """Fetch structured facts and an objective priority for a known CVE.
+
+    Returns NVD data (description, CVSS, CWEs, affected products, fix versions
+    from CPE ranges, vendor advisories), the FIRST EPSS exploit probability, and
+    CISA KEV exploited-in-the-wild status — plus a computed P1-P4 priority. No
+    LLM is called. From the returned facts, YOU should write: the fix version(s),
+    ordered remediation steps, any workarounds, and a one-sentence ServiceNow
+    Vulnerability Response note. Note that final prioritization also needs asset
+    criticality from the caller's CMDB.
+
+    Args:
+        cve_id: A CVE identifier, e.g. "CVE-2021-44228".
+    """
+    cve_id = cve_id.strip().upper()
+    if not CVE_RE.match(cve_id):
+        return {"error": "Invalid CVE id — expected CVE-YYYY-NNNN"}
+    async with await _client() as cx:
+        try:
+            nvd_r = await cx.get(NVD_URL, params={"cveId": cve_id}, headers=_nvd_headers())
+            nvd_r.raise_for_status()
+            vulns = nvd_r.json().get("vulnerabilities") or []
+            if not vulns:
+                return {"error": f"{cve_id} not found in NVD"}
+            nvd = _parse_nvd(vulns[0]["cve"])
+        except Exception as e:
+            return {"error": f"NVD request failed: {type(e).__name__}"}
+        epss = percentile = None
+        try:
+            er = await cx.get(EPSS_URL, params={"cve": cve_id})
+            rows = er.json().get("data") or []
+            if rows:
+                epss, percentile = float(rows[0]["epss"]), float(rows[0]["percentile"])
+        except Exception:
+            pass
+        kev = (await _load_kev(cx)).get(cve_id)
+    return {
+        "cve": cve_id,
+        "priority": _priority(kev, nvd["cvss"], epss),
+        "actively_exploited_kev": bool(kev),
+        "kev_details": {k: kev.get(k) for k in ("requiredAction", "dueDate", "knownRansomwareCampaignUse")} if kev else None,
+        "epss": {"probability": epss, "percentile": percentile},
+        **nvd,
+        "data_sources": "NVD, FIRST EPSS, CISA KEV (public)",
+        "your_task": "Write remediation guidance (fix versions, ordered steps, workarounds) and a "
+                     "one-sentence ServiceNow VR note from these facts. Final priority also needs "
+                     "asset criticality from the CMDB.",
+    }
+
+
+@mcp.tool()
+async def cve_search(query: str, limit: int = 5) -> dict:
+    """Find candidate CVE ids for a free-form query via NVD keyword search.
+
+    Use when you don't already know the CVE id and can't recall it — e.g. a
+    product and version, or a keyword phrase. (For well-known incident names
+    like "Log4Shell" you likely already know the CVE — call cve_lookup directly.)
+    Returns candidate CVEs with a description snippet and CVSS so you can pick.
+
+    Args:
+        query: Free-form product, keyword, or description.
+        limit: Max candidates to return (default 5).
+    """
+    async with await _client() as cx:
+        try:
+            r = await cx.get(NVD_URL, params={"keywordSearch": query.strip(),
+                             "resultsPerPage": max(1, min(limit, 10))}, headers=_nvd_headers())
+            r.raise_for_status()
+            items = r.json().get("vulnerabilities") or []
+        except Exception as e:
+            return {"error": f"NVD search failed: {type(e).__name__}"}
+    out = []
+    for it in items[:limit]:
+        c = it["cve"]
+        desc = next((d["value"] for d in c.get("descriptions", []) if d["lang"] == "en"), "")
+        cvss = None
+        for key in ("cvssMetricV31", "cvssMetricV30", "cvssMetricV2"):
+            if c.get("metrics", {}).get(key):
+                cvss = c["metrics"][key][0]["cvssData"].get("baseScore")
+                break
+        out.append({"id": c["id"], "cvss": cvss, "description": desc[:200]})
+    return {"query": query, "candidates": out}
+
+
+@mcp.tool()
+async def cve_exploit_intel(cve_id: str) -> dict:
+    """Gather public exploit signals for a CVE — no LLM, no proprietary feed.
+
+    Returns objective, public exploit indicators: CISA KEV exploited/ransomware
+    status, the FIRST EPSS exploit probability, and public GitHub repositories
+    that reference the CVE (frequently proof-of-concept or exploit code), ranked
+    by stars. Interpret these signals yourself to judge weaponization/urgency.
+
+    Args:
+        cve_id: A CVE identifier, e.g. "CVE-2024-3400".
+    """
+    cve_id = cve_id.strip().upper()
+    if not CVE_RE.match(cve_id):
+        return {"error": "Invalid CVE id"}
+    async with await _client() as cx:
+        kev = (await _load_kev(cx)).get(cve_id)
+        epss = None
+        try:
+            er = await cx.get(EPSS_URL, params={"cve": cve_id})
+            rows = er.json().get("data") or []
+            if rows:
+                epss = float(rows[0]["epss"])
+        except Exception:
+            pass
+        repos = []
+        try:
+            h = {**UA, **({"Authorization": f"Bearer {GH_TOKEN}"} if GH_TOKEN else {})}
+            gr = await cx.get(GH_URL, params={"q": cve_id, "sort": "stars", "per_page": 6}, headers=h)
+            if gr.status_code == 200:
+                for r in gr.json().get("items", [])[:6]:
+                    repos.append({"repo": r["full_name"], "url": r["html_url"],
+                                  "stars": r["stargazers_count"], "description": (r.get("description") or "")[:120]})
+            elif gr.status_code == 403:
+                repos = {"note": "GitHub rate limit hit — set GITHUB_TOKEN env var for more searches"}
+        except Exception:
+            pass
+    return {
+        "cve": cve_id,
+        "actively_exploited_kev": bool(kev),
+        "ransomware_campaign_use": kev.get("knownRansomwareCampaignUse") if kev else None,
+        "kev_due_date": kev.get("dueDate") if kev else None,
+        "epss_probability": epss,
+        "public_github_repos": repos,
+        "data_sources": "CISA KEV, FIRST EPSS, public GitHub search",
+        "your_task": "Judge exploitation likelihood and weaponization from these public signals. "
+                     "Presence of high-star repos referencing the CVE often indicates public PoC/exploit code.",
+    }
+
+
+def main():
+    """Console entry point — runs the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

vuln_intel_mcp-0.1.0/test_stdio.py

@@ -0,0 +1,22 @@
+"""Smoke test: spawn the packaged server over stdio and exercise the tools."""
+import asyncio
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+async def main():
+    params = StdioServerParameters(command="vuln-intel-mcp", args=[])
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as s:
+            await s.initialize()
+            tools = await s.list_tools()
+            print("TOOLS:", [t.name for t in tools.tools])
+            r = await s.call_tool("cve_lookup", {"cve_id": "CVE-2021-44228"})
+            print("LOOKUP:", r.content[0].text[:350])
+            r2 = await s.call_tool("cve_exploit_intel", {"cve_id": "CVE-2024-3400"})
+            print("EXPLOIT:", r2.content[0].text[:300])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())