shyshlakov/pci-dss-mcp

The dependency scanner now uses a govulncheck-style privacy model: it bulk-downloads the public OSV Go vulnerability snapshot once and intersects locally against go.mod. Module names (private or public) are no longer sent to OSV.dev. The only outbound request is a generic GET on the public snapshot URL at storage.googleapis.com/osv-vulnerabilities/Go/all.zip, indistinguishable from any other govulncheck consumer.

BREAKING

check_dependencies mode parameter: online and offline keywords removed. Only auto (default) is supported. Callers passing the removed values now receive an explicit migration error pointing to docs/check_dependencies.md and this CHANGELOG. Pre-stable BREAKING; no deprecation shims, since the previous keywords were the privacy-leak vector.

Highlights

Privacy

• Zero outbound to api.osv.dev during any scan. The QueryBatch path that POSTed module names is gone.
• Cache directory resolution chain: PCI_MCP_CACHE_DIR -> XDG_CACHE_HOME/pci-dss-mcp/vuln-cache -> $HOME/.pci-dss-mcp/vuln-cache -> os.UserCacheDir/pci-dss-mcp/vuln-cache -> hard-fail. CWD-relative fallback removed. Existing users at $HOME/.pci-dss-mcp continue to work without migration.
• New env var OSV_BASE_URL for enterprise self-hosted OSV mirrors. Default unchanged.

HTTP cache lifecycle

• 0-24h fresh tier: zero outbound, read directly from disk.
• 24h-7d: conditional GET via If-None-Match and If-Modified-Since (304 Not Modified = revalidate, near-zero bytes).
• Greater than 7d: force-refresh.
• Cross-process file lock via gofrs/flock prevents parallel-scan races and cache corruption during refresh.
• New INFO findings emit only on actual fallback paths: DEP-CACHE-COLD (cache absent + network refresh failed), DEP-CACHE-STALE (stale fallback used because network refresh failed), DEP-CACHE-NO-DIR (no writable cache directory found in resolution chain). The previous file-age-based STALE emit on every >7d cache was removed.

Removed (Internal)

• scanner/depscanner.OSVClient.QueryBatch() deleted, along with QueryBatchRequest, QueryBatchResponse, Query, QueryPackage, VulnRef, QueryResult types.
• scanner/depscanner.scanOnline() and scanner/depscanner.scanAuto() consolidated into the cache-ensure path.
• The defaultOSVBaseURL constant retained for the single-vuln FetchVuln path.

Migration

For callers of check_dependencies and the wrapper tools (generate_compliance_report / triage_findings dep_scan_mode):

• mode="online": replace with mode="auto" (or omit mode, default is auto). Behavior change: privacy by default. First scan downloads ~8MB cache.
• mode="offline": replace with mode="auto". The TTL-driven cache covers the air-gapped use case. Bind-mount $HOME/.pci-dss-mcp into the container or set PCI_MCP_CACHE_DIR to an air-gap-allowed path. Run update_vulnerability_db once with network access to bootstrap. See docs/check_dependencies.md for the canonical bind-mount pattern.

Verification

| Gate | Result |
|------|--------|
| make vet | PASS |
| make test (race, all packages) | PASS |
| make test-fixture (golden regression) | PASS |
| Behavioral parity vs v0.6.2 (violation table on golden fixture) | PASS (only rules_coverage.depscanner extension; violation rows unchanged) |
| Live-path vs fixture-copy smoke parity (49 CRITICAL / 89 HIGH / 27 MEDIUM / 0 LOW / 59 INFO) | PASS |
| G6 manual smoke (tcpdump observation): zero packets to api.osv.dev on cold and warm cache | PASS |
| G7 manual smoke (Docker bind-mount UX): host-side cache persists across --rm runs, mtime stable on warm path, ephemeral when no bind-mount | PASS |
| TestQueryBatchSymbolDeleted (reflection-based privacy regression gate) | PASS |
| TestNetTrafficZeroQueryBatch (records every outbound during fixture scan, asserts zero module-name fragments leak via body or URL) | PASS |
| TestCacheLifecycle (8 subtests: cache_hit_fresh, cache_miss_cold, revalidate_304, revalidate_200, force_refresh_gt7d, corrupted_cache, parallel_cold_cache, stale_fallback_network_failed) | PASS |
| TestAirGappedScan (cold_cache_no_network, no_writable_dir) | PASS |
| TestOSVBaseURLOverride (env-var trust boundary) | PASS |

Severity counts on testdata/vulnerable-payment-service remain byte-identical to v0.6.2: 49 CRITICAL / 89 HIGH / 27 MEDIUM / 0 LOW / 59 INFO. No detection logic changed for any other scanner.

Distribution

• go install github.com/shyshlakov/[email protected]
• Multi-arch Docker (linux/amd64 + linux/arm64), cosign-signed via OIDC: ghcr.io/shyshlakov/pci-dss-mcp:0.6.3 and :latest
• MCP Registry: io.github.shyshlakov/pci-dss-mcp v0.6.3 (auto-published on tag)

Pull request

Merged via #25.