Kitsune vulnerability research MCP

This local MCP server keeps vulnerability intelligence, research scope, scanner results, evidence receipts, Bugcrowd VRT assessments, and report drafts in one SQLite ledger.

It is built for authorized defensive research. It does not scan targets, execute exploits, run shell commands, submit reports, or publish disclosures.

Data sources

The server uses fixed adapters. A caller cannot supply another origin.

Source	What it provides
CVE.org	Canonical CVE JSON 5 records
NVD API 2.0	Recent CVEs, CVSS, and CWE enrichment
CISA KEV	Evidence of exploitation in the wild
FIRST EPSS	Daily 30-day exploitation probability and percentile
OSV	Package, version, and commit vulnerability matching
Bugcrowd VRT 1.19	Finding category and baseline priority

CVE.org is the canonical record. NVD is enrichment and recent-record discovery. KEV and EPSS are separate signals. VRT is a technical baseline, not authorization or a guaranteed bounty rating.

Requirements

• Node.js 24 or newer
• npm 10 or newer
• An absolute import root if SARIF or evidence files will be imported

No API key is required for the public feeds. NVD_API_KEY is optional and is sent only to NVD.

Install and verify

npm install
npm test
npm run check
npm run lint
npm run build

The source is available under the MIT license. The package is not published to npm.

MCP client configuration

Build first, then point the client at the compiled stdio entry point:

{
  "mcpServers": {
    "kitsune-vuln-research": {
      "command": "node",
      "args": [
        "--disable-warning=ExperimentalWarning",
        "C:\\path\\to\\kitsune-vuln-research-mcp\\dist\\index.js"
      ],
      "env": {
        "VULN_IMPORT_ROOTS": "C:\\absolute\\path\\to\\scanner-output",
        "VULN_LOG_LEVEL": "warn"
      }
    }
  }
}

License

MIT. See LICENSE.

The built-in Node SQLite module still carries an ExperimentalWarning in Node 24. The narrow command-line flag keeps that warning out of MCP stderr without suppressing other warning classes.

Configuration

Variable	Meaning
VULN_DATA_DIR	Absolute state directory. Defaults to the local application-data directory.
VULN_IMPORT_ROOTS	Allowed absolute roots for SARIF and evidence reads. Uses ; on Windows and : on Linux or macOS.
NVD_API_KEY	Optional NVD key. Never persisted.
VULN_OFFLINE	Set to true to block all network tools while keeping cached reads available.
VULN_LOG_LEVEL	error, warn, or info. Default: warn.

Runtime state is kept under VULN_DATA_DIR:

vuln-research.sqlite
cases/
  <case-id>/
    evidence/
    exports/

SQLite uses foreign keys, WAL mode, prepared statements, and append-only event receipts. Source payloads and evidence are SHA-256 hashed.

Intelligence tools

Tool	Behavior
vuln_sync_recent_cves	Cache NVD CVEs from a published or modified window of at most 120 days.
vuln_get_cve	Read one cached CVE or refresh it from CVE.org and NVD.
vuln_search_cves	Search cached CVEs with bounded pagination.
vuln_sync_kev	Refresh CISA KEV and annotate cached CVEs.
vuln_sync_epss	Refresh EPSS for 1 to 100 explicit CVE IDs.
vuln_query_osv_package	Query OSV for one package/version or commit.
vuln_get_source_status	Return fetch state, source timestamps, errors, and stale flags.
vuln_refresh_vrt	Atomically refresh the fixed Bugcrowd VRT 1.19 snapshot.
vuln_search_vrt	Search terminal VRT paths and baseline priorities.
vuln_prioritize_candidates	Order cached CVEs by KEV, EPSS, CVSS, then modification time.

Candidate ordering is research priority. It does not replace CVSS, VRT, reproduced impact, or program rules.

Research tools

Tool	Behavior
research_register_scope	Store an external authorization reference, assets, methods, and validity window.
research_check_scope	Explain whether one target and method are currently allowed.
research_create_case	Create a case after a successful scope decision.
research_get_case_state	Read a case's scope state, SARIF, evidence, findings, patch checks, and report receipts.
research_import_sarif	Copy and parse bounded SARIF 2.1.0 from an import root.
research_record_evidence	Copy one bounded file and return its SHA-256 receipt.
research_assess_finding	Record the full VRT path, impact, prerequisites, scope evidence, and confidence.
research_export_report	Write a local Markdown draft. It never submits the report.
research_record_patch_verification	Attach same-case evidence and a patch outcome to a finding.

Registering a scope here does not create permission. authorization_ref must point to the real bounty brief, contract, ticket, or lab authorization.

Normal workflow

1. Set VULN_IMPORT_ROOTS to the scanner-output directory.
2. Refresh recent CVEs, KEV, EPSS, and VRT.
3. Register the real program scope and validity window.
4. Create a case for one exact target and allowed method.
5. Run Semgrep, CodeQL, Trivy, Grype, or another approved scanner outside this MCP.
6. Import its SARIF output and record reproduction evidence.
7. Select a terminal VRT path and record actual impact.
8. Export a local draft for human review.

Scanner messages and advisory text are treated as untrusted data. They cannot change scope, tool selection, SQL, paths, or report structure.

Import security

• Import roots must be absolute and explicitly configured.
• Canonical paths must remain inside an allowed root.
• Symbolic-link imports, Windows device paths, and alternate data streams are rejected.
• Files are limited to 25 MiB by default.
• Stored evidence names are generated by the server.
• Duplicate evidence and SARIF results are identified by hashes or stable fingerprints.

Stale feeds and offline work

Call vuln_get_source_status before using cached intelligence. NVD, KEV, EPSS, and VRT are stale after 24 hours. Canonical CVE and OSV query state are stale after seven days.

If a source is unavailable, the last good cache remains readable. Set VULN_OFFLINE=true when a session must make no network requests.

Tests

The suite uses recorded fixtures by default. It covers schemas, source limits, origin isolation, scope matching, path containment, SARIF prompt-injection strings, evidence hashing, VRT assessment, report escaping, MCP discovery, and restart persistence.

evaluation.xml contains ten stable, read-only questions based on the fixed 2026 fixtures under tests/fixtures.

Build and seed those fixtures into a new absolute data directory before running the evaluations:

npm run seed:evaluation -- C:\absolute\unused\evaluation-data

The seeder refuses to overwrite an existing database. Point VULN_DATA_DIR at that directory when starting the evaluation server.