# 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](https://www.cve.org/Downloads) | Canonical CVE JSON 5 records |
| [NVD API 2.0](https://nvd.nist.gov/developers/vulnerabilities) | Recent CVEs, CVSS, and CWE enrichment |
| [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | Evidence of exploitation in the wild |
| [FIRST EPSS](https://api.first.org/epss/) | Daily 30-day exploitation probability and percentile |
| [OSV](https://osv.dev/docs/) | Package, version, and commit vulnerability matching |
| [Bugcrowd VRT 1.19](https://bugcrowd.com/vulnerability-rating-taxonomy) | 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

```powershell
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:

```json
{
  "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](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`:

```text
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:

```powershell
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.