# PatchProof MCP

[![CI](https://github.com/eaglebooth/patchproof-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/eaglebooth/patchproof-mcp/actions/workflows/ci.yml)

PatchProof is a focused Model Context Protocol server for npm supply-chain
inspection. Four tools implement one end-to-end chain:

```text
lockfile -> CycloneDX SBOM -> OSV vulnerability -> source reachability
         -> remediation plan -> allowlisted verification -> evidence report
```

## Current Status

The complete public tool set is implemented and covered by focused tests:

- `scan_repository`: authorized-root repository traversal with bounded file
  and byte counting plus explicit truncation diagnostics.
- `generate_sbom`: deterministic CycloneDX-shaped SBOM generation from
  `package-lock.json`.
- `audit_dependencies`: dependency extraction with live OSV queries,
  timeout/retry/cache controls, and an explicit deterministic fallback.
- `generate_evidence_report`: an end-to-end JSON/HTML artifact combining SBOM
  components, matched vulnerabilities, transparent risk scores, import-based
  reachability, ranked upgrades, and optional verification results.

Important limitations:

- Only npm `package-lock.json` repositories are supported.
- Live OSV sends only npm package names and versions to `api.osv.dev`; no
  repository source is transmitted.
- `scan_repository` intentionally returns bounded repository statistics;
  vulnerability matching is handled by `audit_dependencies`.
- Reachability is static import evidence, not runtime code-path proof.
- Verification is disabled by default and can execute only `npm run typecheck`,
  `npm test`, and `npm run build` with `shell: false`.
- The browser demo uses a bundled fixture and does not inspect arbitrary remote
  repositories.
- Missing, malformed, and unreadable lockfiles are reported explicitly rather
  than being presented as clean dependency results.
- Both the local CLI and Vercel deployment use the official stateless
  Streamable HTTP transport.

The Vercel demo exposes a stateless Streamable HTTP endpoint at `/api/mcp`.
For safety, every public tool call is locked to the bundled demo fixture; it
does not accept arbitrary server filesystem paths.
The landing page calls the endpoint directly and lets reviewers run all four
tools without installing an MCP client.

Committed, reproducible report artifacts are available at
`examples/demo-report.json` and `examples/demo-report.html`. GitHub Actions
rebuilds them and fails if the committed evidence becomes stale.
Five additional golden scenarios under `examples/golden/` cover safe,
vulnerable, dev/transitive, malformed-lockfile, and missing-lockfile behavior.

## Agent Workflows

Three machine-readable workflows demonstrate how AI coding agents compose the
four MCP tools:

- `security-triage`
- `release-gate`
- `evidence-review`

Validate them offline:

```bash
npm run workflow:validate
```

Execute one against a running MCP endpoint:

```bash
npm run workflow:run -- release-gate http://127.0.0.1:8765/mcp
```

Client setup guides for Claude Code, Codex, and GitHub Copilot live in
`examples/agent-workflows/`. CyOps session-to-repository provenance is
documented in `docs/cyops-provenance.md`.

## Requirements

- Node.js 20
- npm 10

## Install And Verify

```bash
npm ci
npm run lint
npm run typecheck
npm test
npm run coverage
npm run build
```

The suite contains 82 tests covering core tools, live OSV normalization and caching, CVSS v3.1,
reachability, remediation, verification security, transports, risk scoring,
and five scenario fixtures. CI enforces at least 85% line,
statement, and function coverage and 80% branch coverage. The current verified
coverage values are generated by `npm run coverage` and enforced in CI.

## Run

Build first, then start the stdio MCP server:

```bash
npm run build
npm run start:stdio
```

## Deploy The Live Demo

Import this GitHub repository into Vercel and deploy with the default settings.
The deployment provides:

- `/` - a static project and tool overview;
- `/api/mcp` - the stateless MCP Streamable HTTP endpoint;
- a bundled npm fixture supporting deterministic and live OSV demonstrations.

Verify the deployment:

```bash
curl -X POST https://YOUR-DEPLOYMENT.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Tool Summary

### `scan_repository`

Input:

```json
{
  "repoRoot": "/authorized/repository",
  "includeHidden": false,
  "followSymlinks": false
}
```

Returns the resolved repository root, files scanned, bytes read, duration,
ignored directories, the current findings array, and `truncated` with a reason
when a resource limit stops traversal. Any `repoRoot` override must remain
inside the root authorized by the MCP host.

### `generate_sbom`

Input:

```json
{
  "repoRoot": "/authorized/repository",
  "format": "cyclonedx"
}
```

Returns a deterministic CycloneDX 1.5-shaped component list derived from
`package-lock.json`, including an explicit `lockfileStatus`.

### `audit_dependencies`

Input:

```json
{
  "repoRoot": "/authorized/repository",
  "osvMode": "live",
  "fallbackToMock": true,
  "ecosystem": "npm"
}
```

Returns dependencies and package-linked vulnerabilities with `source` set to
`live`, `mock`, or `mock-fallback`. Live requests use a five-second timeout,
two bounded retries, eight-request concurrency, and a one-hour in-memory
cache. OSV CVSS v3 vectors are converted to reproducible base scores.

### `generate_evidence_report`

Input:

```json
{
  "repoRoot": "/authorized/repository",
  "format": "both",
  "osvMode": "live",
  "fallbackToMock": true,
  "verify": false
}
```

Runs SBOM, OSV auditing, static import reachability, remediation planning, and
optional allowlisted verification. It returns JSON and a self-contained HTML
report. Set `verify=true` only in a trusted local checkout.

## Risk Model

PatchProof ranks each vulnerability with a deterministic `0–100` score:

```text
severity-or-CVSS
× production/dev factor
× direct/transitive factor
× fix-availability factor
```

The report preserves every factor and a human-readable explanation. The model
does not use hidden weights or network data, so identical lockfiles always
produce identical ranking. See `src/risk/scorer.ts`,
`tests/unit/risk-scorer.test.ts`, and `docs/acceptance-evidence.md`.

## Architecture

```text
src/server       MCP registration and CLI
src/tools        four public MCP tool definitions
src/scanners     bounded repository traversal
src/parsers      npm lockfile parsing
src/sbom         deterministic SBOM assembly
src/osv          live OSV client, CVSS v3.1, cache, retry, and mock fallback
src/reachability static import evidence with file and line locations
src/remediation  semver-aware, reachability-informed upgrade planning
src/verification shell-free allowlisted npm verification
src/reporting    end-to-end JSON and HTML evidence assembly
src/risk         transparent deterministic risk scoring
src/security     path, resource, error, and redaction utilities
src/transport    verified stdio and Streamable HTTP transports
tests/unit       infrastructure and focused core-tool tests
fixtures/scenarios safe, vulnerable, dev/transitive, malformed, and missing cases
```

Business logic is kept outside the MCP registry so it can be tested directly.

## Security Notes

- Callers must provide or authorize a repository root.
- Repository traversal is bounded by file, byte, depth, and time limits.
- Common generated directories such as `.git`, `node_modules`, `dist`,
  `build`, and `coverage` are ignored.
- Live OSV receives only `{ package: { ecosystem, name }, version }`.
- Live network failures are explicit and can fall back to deterministic mode.
- Verification never uses a shell and rejects every command outside a fixed
  allowlist.

This is a focused security evidence tool, not a runtime exploitability oracle.
Do not rely on it as the sole source for vulnerability or secret detection.

## CyOps Arena

The repository was scaffolded and iterated with CyOps Humanize using MiniMax
M3. The Git history and planning documents retain the generated implementation
evidence. Manual verification confirmed:

- strict TypeScript typecheck passes;
- the Vitest suite passes;
- the production TypeScript build passes.
- an integration test starts the HTTP server on an ephemeral port and verifies
  the complete four-tool MCP surface through JSON-RPC;
- GitHub Actions independently repeats those checks on Node.js 20 and verifies
  that the committed demo evidence is reproducible.
- Three agent workflows are machine-validated and can be executed over MCP
  JSON-RPC with `scripts/run-agent-workflow.mjs`.

## License

MIT. See `LICENSE`.