osv-scanner-mcp 0.14.1 → 0.15.0

package/README.md

@@ -18,6 +18,7 @@ An MCP server that wraps Google's [OSV-Scanner](https://github.com/google/osv-sc
 - **Java project scan**: `scan_java_project` scans only the Java (Maven / Gradle) manifests and returns a formatted report
 - **JAR/WAR scan**: `scan_java_artifact` detects known vulnerabilities from the metadata inside JAR/WAR archives, for projects without a lockfile or with only shaded/fat JARs (best-effort identification, stated explicitly in `coverage`)
 - **SBOM scan**: `scan_sbom` checks the dependencies recorded in a CycloneDX/SPDX JSON SBOM. It states explicitly that the SBOM's completeness and its match with the actual artifacts are not verified
+- **Scan history (opt-in)**: With `OSV_MCP_HISTORY=1`, each scan is recorded locally, and `scan_history` lists past runs and shows what changed since the previous run (new and resolved vulnerabilities, version changes, coverage changes)
 - **Severity-sorted reports**: Vulnerabilities are grouped by package and sorted by CVSS score, with five severity labels (critical / high / medium / low / unknown) and summary counts
 - **Fixed versions**: Each vulnerability includes `fixed_versions`, sorted correctly by Maven version precedence (including non-semver forms such as `2.17.1-RELEASE`), Semantic Versioning precedence for npm, Go, and Rust, and PEP 440 for PyPI
 - **Security first**: No shell execution, a fixed argument allowlist, path normalization and boundary checks, scanning private copies instead of the original files, and timeouts and output size limits are built in
@@ -130,6 +131,9 @@ npm run build
 | `OSV_MCP_PREFER_DOWNLOAD` | If `1` or `true`, always use the checksum-verified downloaded binary instead of osv-scanner on `PATH` (protects against a fake binary planted on `PATH`; an explicit `OSV_SCANNER_PATH` still takes precedence) |
 | `OSV_MCP_NO_CANDIDATE_CHECK` | If `1` or `true`, `suggest_fix` does not query OSV about recommended versions (`candidate_check` is `disabled`, and recommended versions are not checked for known vulnerabilities that do not affect the current version) |
 | `OSV_MCP_NO_REMOTE_RESOLUTION` | If `1` or `true`, transitive dependencies of `pom.xml` and `requirements.txt` are not resolved through deps.dev. **This stops only the requests to deps.dev; package names and versions are still sent to `api.osv.dev` for the vulnerability lookup.** Vulnerabilities in transitive dependencies are then not detected, and responses say so in `dependency_resolution.warning`. See [Network destinations and privacy](#network-destinations-and-privacy) |
+| `OSV_MCP_HISTORY` | If `1` or `true`, records each scan in the local scan history (disabled by default). See [`scan_history`](#scan_history) |
+| `OSV_MCP_HISTORY_DIR` | Absolute path of the history directory (default `$XDG_STATE_HOME/osv-scanner-mcp/history`, or `~/.local/state/osv-scanner-mcp/history`) |
+| `OSV_MCP_HISTORY_MAX_ENTRIES` | Number of runs kept (default `500`, maximum `5000`). Older runs are deleted, and the total size is also capped at 100 MiB |
 
 > **Recommendation**: The server works without `OSV_MCP_ALLOWED_ROOT`, but then any absolute path can be scanned. To prevent malicious instructions (prompt injection) from scanning unintended directories, set it to the root of your projects (for example `~/projects`). Pass it in the client configuration, for example `"env": {"OSV_MCP_ALLOWED_ROOT": "/Users/you/projects"}` (in Codex CLI's TOML, use a `[mcp_servers.osv-scanner.env]` section).
 
@@ -172,6 +176,7 @@ As an additional layer of defense, you can limit what the server can read and wr
 - Read access: the server itself (the directory containing `dist` and `node_modules`), the scan targets (`OSV_MCP_ALLOWED_ROOT`), the temporary directory, and the osv-scanner binary
 - The temporary directory (`os.tmpdir()`, `$TMPDIR` on macOS) needs read access under **both the symlinked and the resolved path** (on macOS, `/var/folders/...` is a symbolic link to `/private/var/folders/...`). Write access is needed on the resolved path
 - If you use the automatic download, also allow reading and writing the cache (`$XDG_CACHE_HOME/osv-scanner-mcp`, by default `~/.cache/osv-scanner-mcp`). Otherwise, set `OSV_SCANNER_PATH`
+- If you enable the scan history (`OSV_MCP_HISTORY=1`), also allow reading and writing the history directory (`OSV_MCP_HISTORY_DIR`, or the default under `~/.local/state`). The server warns at startup if it is not allowed
 - `--allow-child-process` is required to run osv-scanner. **osv-scanner runs as a child process and is not restricted by the permission model** (Node itself warns that this flag weakens the permission model). The impact is limited because osv-scanner only receives verified private copies, but use an OS-level mechanism such as a container if you need stronger isolation
 - If a required permission is missing, the server prints a warning to stderr at startup, and scans return `permission_denied` (naming the missing permission and the path)
 
@@ -466,6 +471,44 @@ For npm, Go, PyPI, and Rust, the "same release line" is the range a caret (`^`)
 - Ecosystems without recommendation support (such as RubyGems from an SBOM) return `verification: "unsupported_ecosystem"`, and current versions that cannot be parsed (such as npm git or local path dependencies) return `verification: "unparseable_version"`. In both cases each CVE gets `tier: "unsupported"` and is not counted as unfixed (whether a fixed version exists is not evaluated; check `fixed_versions` in `scan_project` or `explain_vulnerability`).
 - `coverage` is the same as in `scan_project`. If a manifest has no lockfile or a file was excluded, `complete` is `false`, and those dependencies are not included in the suggestions. The `skipped_manifests` / `scope_warning` fields of v0.4.2 and earlier were merged into `coverage.skipped_files` / `coverage.warning`.
 
+### `scan_history`
+
+Lists past runs of the scan tools (`scan_project`, `suggest_fix`, `scan_java_project`, `scan_java_artifact`, `scan_sbom`) and shows what changed between the last two runs. No scan is run.
+
+**Recording is disabled by default**, because the history keeps package names and paths on disk. Enable it with `OSV_MCP_HISTORY=1` in the server's `env`; runs are recorded from then on. Without it, this tool returns `history_disabled`.
+
+**Input**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `project_path` | string (optional) | A scanned target (project directory, lockfile, JAR/WAR, or SBOM). Filters the runs and adds `changes` |
+| `limit` | number (optional) | Number of runs to list (default 10, maximum 50) |
+| `run_id` | string (optional) | An `id` from `runs`. Returns the details of that run instead of the list |
+
+**Output**
+
+- `history`: the directory, `max_entries`, the number of matching runs (`recorded_runs`), and `skipped_records` if some files could not be read or were invalid
+- `runs`: newest first, with `id`, `started_at`, `tool`, the target, `status` (`ok` or `error` with `error_kind`), `coverage_complete`, vulnerability counts, and `duration_ms`
+- `changes` (with `project_path`): for each kind of scan (`project` for `scan_project` and `suggest_fix`, `java_project`, `artifact`, `sbom`), a comparison of the **last two successful runs**:
+  - `new_vulnerabilities` / `resolved_vulnerabilities`: compared per package (ecosystem and name). A vulnerability is the same if its ID or any alias matches, so a change of the primary ID in OSV is not reported as new. A vulnerability that remains after a version change is neither new nor resolved
+  - `reason` of a resolved vulnerability: `version_changed` (the package is still reported, at another version: `current_versions`), `package_not_reported` (the package is no longer in the results: it was upgraded to a version without known vulnerabilities, removed, or is no longer scanned; scan results list only vulnerable packages, so these cannot be told apart), or `same_version_not_reported` (same version, no longer reported, for example because the OSV data changed)
+  - `version_changes`: packages whose versions changed, with `still_affected` (the vulnerabilities that remain)
+  - `coverage_changes`: changes of `coverage.complete` and added or removed manifests
+  - `incomplete`: set when the comparison is partial (a run exceeded the record size limit or the findings limit)
+- `run` (with `run_id`): the details of one run, including its manifests, coverage gaps, severity breakdown, and the recorded packages and vulnerability IDs (up to 500 packages)
+
+> **Note**: Changes are computed from the OSV data at the time of each scan, so they can also appear when only the vulnerability database changed.
+
+**What is recorded**: one JSON file per run, with the tool, time, server and pinned OSV-Scanner versions, the target paths, coverage, counts, and the packages with their vulnerability IDs and aliases (and, for `suggest_fix`, the recommended versions). Vulnerability summaries, details, and error messages are not recorded. A run whose record would exceed 1 MiB keeps only the summary (`findings_omitted`), and if that is still too large, only part of its manifest list (`manifests_truncated`; manifest changes are then not compared). Target paths longer than 4,096 characters (longer than any path that can exist) are truncated and marked `target_truncated`.
+
+**Storage and safety**:
+
+- The directory is created with mode `0700` and files with `0600`. The server refuses a directory that is a symbolic link or is owned by another user (scans still succeed; a warning is printed to stderr)
+- Each run is written to a temporary file and renamed, so concurrent server processes do not corrupt each other's records. Recording failures never fail the scan
+- History files are treated as untrusted input: each is read with a size limit, validated, and its strings are sanitized before being returned
+- When `OSV_MCP_ALLOWED_ROOT` is set, only runs whose target is inside the allowed root are returned, and a `project_path` outside it is refused with `path_outside_allowed_root`
+- To delete the history, remove the directory
+
 ### `explain_vulnerability`
 
 Returns the details of a vulnerability, given its GHSA or CVE ID, **fetched directly from the OSV database API (api.osv.dev)** (no scan is run). IDs from the scan results can be passed as they are. This is especially useful for vulnerabilities published after the client LLM's knowledge cutoff.
@@ -520,6 +563,9 @@ Returns JSON with a machine-readable `kind`, together with `isError: true`:
 | `invalid_vulnerability_id` | The vulnerability ID is malformed |
 | `vulnerability_not_found` | No vulnerability with the ID exists in the OSV database |
 | `api_request_failed` | The request to the OSV API failed (network, timeout, or a non-2xx response) |
+| `history_disabled` | The scan history is disabled (`scan_history`; set `OSV_MCP_HISTORY=1`) |
+| `history_unavailable` | The history directory cannot be used (for example a symbolic link or owned by another user) |
+| `history_run_not_found` | No recorded run with the given `run_id` (or the ID is malformed) |
 | `internal_error` | An unexpected error (no internal details are returned) |
 
 ## Security design
@@ -566,6 +612,7 @@ Design notes and open items are in [docs/DESIGN_TODO.md](docs/DESIGN_TODO.md) (i
 - [x] English tool descriptions and messages
 - [x] `scan_project` for Rust (`Cargo.lock`, crates.io crates only) and RustSec informational advisories
 - [x] `suggest_fix` and direct/transitive dependencies for Rust
+- [x] Scan history and changes between runs (`scan_history`, opt-in)
 - [ ] Direct and transitive dependencies for `gradle.lockfile` and the YAML/TOML lockfiles
 
 ## License

package/dist/history/historyDiff.js

@@ -0,0 +1,124 @@
+/**
+ * 同じ対象・同じ種類の2回のスキャンの比較(docs/DESIGN_TODO.md「スキャンの実行履歴」)。
+ *
+ * - 脆弱性は、IDか別名が1つでも重なれば同じとみなす(OSVの代表IDが入れ替わっても新規・解消と誤らない)
+ * - パッケージ(エコシステムと名前)単位で比べる。版が変わっても残っている脆弱性は、新規にも解消にも数えない
+ * - スキャン結果には脆弱なパッケージしか載らないため、結果から消えたパッケージが「更新された」のか
+ *   「削除された」のかは区別できない。解消の理由はその限界に合わせて分ける
+ * - 差分はスキャンの時点のOSVのデータに依存する(コードを変えていなくてもデータの更新で増減する)
+ */
+const MAX_LISTED = 500;
+function packageKey(f) {
+    return JSON.stringify([f.ecosystem, f.name]);
+}
+function identities(v) {
+    return [v.id, ...v.aliases];
+}
+/** パッケージの全ての版の脆弱性のIDと別名の集合(照合を件数に比例する時間で行うため) */
+function identitySet(findings) {
+    const ids = new Set();
+    for (const f of findings)
+        for (const v of f.vulnerabilities)
+            for (const id of identities(v))
+                ids.add(id);
+    return ids;
+}
+/** IDか別名のどれかが集合に含まれるか */
+function overlaps(ids, target) {
+    return identities(target).some((id) => ids.has(id));
+}
+function versionsOf(findings) {
+    return [...new Set(findings.map((f) => f.version))].sort();
+}
+function byPackage(findings) {
+    const map = new Map();
+    for (const f of findings) {
+        const key = packageKey(f);
+        const list = map.get(key) ?? [];
+        list.push(f);
+        map.set(key, list);
+    }
+    return map;
+}
+function change(f, v) {
+    return { ecosystem: f.ecosystem, name: f.name, version: f.version, id: v.id, aliases: v.aliases, ...(v.informational !== undefined ? { informational: v.informational } : {}) };
+}
+export function compareHistoryRecords(older, newer) {
+    const result = {
+        from: { id: older.id, started_at: older.started_at, tool: older.tool },
+        to: { id: newer.id, started_at: newer.started_at, tool: newer.tool },
+        new_vulnerabilities: [],
+        resolved_vulnerabilities: [],
+        version_changes: [],
+        coverage_changes: {},
+    };
+    if (older.coverage_complete !== newer.coverage_complete) {
+        result.coverage_changes.complete = { from: older.coverage_complete, to: newer.coverage_complete };
+    }
+    const reasons = [];
+    if (older.manifests_truncated || newer.manifests_truncated) {
+        reasons.push("one of the runs recorded only part of its manifest list (the record size limit was reached), so manifest changes are not shown");
+    }
+    else if (older.manifests !== undefined && newer.manifests !== undefined) {
+        const before = new Set(older.manifests.map((m) => m.path));
+        const after = new Set(newer.manifests.map((m) => m.path));
+        const added = [...after].filter((p) => !before.has(p)).sort();
+        const removed = [...before].filter((p) => !after.has(p)).sort();
+        if (added.length > 0)
+            result.coverage_changes.manifests_added = added.slice(0, MAX_LISTED);
+        if (removed.length > 0)
+            result.coverage_changes.manifests_removed = removed.slice(0, MAX_LISTED);
+    }
+    if (older.findings === undefined || newer.findings === undefined) {
+        reasons.unshift("One of the runs has no recorded findings (it exceeded the record size limit), so vulnerabilities cannot be compared");
+        result.incomplete = reasons.join("; ");
+        return result;
+    }
+    if (older.findings_truncated || newer.findings_truncated)
+        reasons.push("one of the runs recorded only part of its findings (the findings limit was reached)");
+    // パッケージ(エコシステムと名前)単位で比べる。版が変わっても残っている脆弱性は新規・解消のどちらにも数えない
+    const before = byPackage(older.findings);
+    const after = byPackage(newer.findings);
+    const empty = [];
+    for (const [key, newList] of after) {
+        const oldList = before.get(key) ?? empty;
+        const oldIds = identitySet(oldList);
+        let stillAffected = 0;
+        for (const f of newList) {
+            for (const v of f.vulnerabilities) {
+                if (overlaps(oldIds, v))
+                    stillAffected++;
+                else
+                    result.new_vulnerabilities.push(change(f, v));
+            }
+        }
+        const fromVersions = versionsOf(oldList);
+        const toVersions = versionsOf(newList);
+        if (oldList.length > 0 && JSON.stringify(fromVersions) !== JSON.stringify(toVersions)) {
+            result.version_changes.push({ ecosystem: newList[0].ecosystem, name: newList[0].name, from: fromVersions, to: toVersions, still_affected: stillAffected });
+        }
+    }
+    for (const [key, oldList] of before) {
+        const newList = after.get(key) ?? empty;
+        const newIds = identitySet(newList);
+        const currentVersions = versionsOf(newList);
+        const reason = newList.length === 0 ? "package_not_reported"
+            : JSON.stringify(versionsOf(oldList)) === JSON.stringify(currentVersions) ? "same_version_not_reported" : "version_changed";
+        for (const f of oldList) {
+            for (const v of f.vulnerabilities) {
+                if (overlaps(newIds, v))
+                    continue;
+                result.resolved_vulnerabilities.push({ ...change(f, v), reason, ...(reason === "version_changed" ? { current_versions: currentVersions } : {}) });
+            }
+        }
+    }
+    for (const list of [result.new_vulnerabilities, result.resolved_vulnerabilities, result.version_changes]) {
+        if (list.length > MAX_LISTED) {
+            reasons.push(`only the first ${MAX_LISTED} entries of a list are shown`);
+            list.length = MAX_LISTED;
+        }
+    }
+    if (reasons.length > 0)
+        result.incomplete = [...new Set(reasons)].join("; ");
+    return result;
+}

package/dist/history/historyRecord.js

@@ -0,0 +1,276 @@
+/**
+ * 実行履歴の1件の内容(要約と差分用の識別子)。ツールの応答(JSON)から作り、読み出し時に形式を確かめる。
+ * 結果の全文・エラーメッセージは保存しない(docs/DESIGN_TODO.md「スキャンの実行履歴」)。
+ */
+import { asArray, asRecord, asString, asStrings } from "../utils/unknownJson.js";
+import { MAX_RECORD_BYTES } from "./historyStore.js";
+export const HISTORY_TOOLS = ["scan_project", "suggest_fix", "scan_java_project", "scan_java_artifact", "scan_sbom"];
+export function scanKind(tool) {
+    switch (tool) {
+        case "scan_project":
+        case "suggest_fix":
+            return "project";
+        case "scan_java_project":
+            return "java_project";
+        case "scan_java_artifact":
+            return "artifact";
+        case "scan_sbom":
+            return "sbom";
+    }
+}
+const MAX_FINDING_PACKAGES = 5_000;
+const MAX_FINDING_VULNERABILITIES = 20_000;
+const MAX_ALIASES = 20;
+const MAX_MANIFESTS = 1_000;
+const MAX_TEXT = 512;
+const MAX_SEVERITY_KEYS = 16;
+/** 対象のパスの長さの上限(LinuxのPATH_MAX。これより長いパスは実在しえず、スキャンは失敗する) */
+const MAX_PATH = 4096;
+function text(value) {
+    const s = asString(value);
+    return s === null ? null : s.slice(0, MAX_TEXT);
+}
+/** 対象のパス。照合に使うため、MAX_TEXTより長いパスもそのまま残す */
+function pathText(value) {
+    const s = asString(value);
+    return s === null ? null : { path: s.slice(0, MAX_PATH), truncated: s.length > MAX_PATH };
+}
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : null;
+}
+function vulnerabilitiesOf(raw, budget) {
+    const out = [];
+    for (const item of asArray(raw)) {
+        const vuln = asRecord(item);
+        const id = text(vuln?.id);
+        if (id === null)
+            continue;
+        if (budget.remaining <= 0)
+            return null;
+        budget.remaining--;
+        const aliases = [...new Set([...asStrings(vuln.aliases), ...(text(vuln.cve) !== null ? [text(vuln.cve)] : [])])]
+            .filter((a) => a !== id).slice(0, MAX_ALIASES).map((a) => a.slice(0, MAX_TEXT));
+        const informational = text(vuln.informational);
+        out.push({ id, aliases, ...(informational !== null ? { informational } : {}) });
+    }
+    return out;
+}
+/** ツールの応答から差分用の識別子を取り出す。上限を超えたらtruncated */
+function findingsOf(tool, payload) {
+    const findings = [];
+    const budget = { remaining: MAX_FINDING_VULNERABILITIES };
+    const source = tool === "suggest_fix" ? asArray(payload.suggestions) : asArray(payload.packages);
+    for (const item of source) {
+        const pkg = asRecord(item);
+        if (pkg === null)
+            continue;
+        const name = text(tool === "suggest_fix" ? pkg.package : pkg.name);
+        const version = text(tool === "suggest_fix" ? pkg.current_version : pkg.version);
+        const ecosystem = text(pkg.ecosystem);
+        if (name === null || version === null || ecosystem === null)
+            continue;
+        if (findings.length >= MAX_FINDING_PACKAGES)
+            return { findings, truncated: true };
+        const vulnerabilities = vulnerabilitiesOf(tool === "suggest_fix" ? pkg.per_cve_detail : pkg.vulnerabilities, budget);
+        if (vulnerabilities === null)
+            return { findings, truncated: true };
+        findings.push({
+            ecosystem, name, version, vulnerabilities,
+            ...(tool === "suggest_fix"
+                ? { recommended_upgrade: text(pkg.recommended_upgrade), upgrade_tier: text(pkg.upgrade_tier), verification: text(pkg.verification) ?? "unknown" }
+                : {}),
+        });
+    }
+    return { findings, truncated: false };
+}
+function manifestsOf(payload) {
+    const coverage = asRecord(payload.coverage);
+    const raw = coverage?.manifests ?? payload.manifests;
+    if (raw === undefined)
+        return undefined;
+    const out = [];
+    for (const item of asArray(raw).slice(0, MAX_MANIFESTS)) {
+        const rec = asRecord(item);
+        const p = text(rec?.path ?? item);
+        if (p !== null)
+            out.push({ path: p, ecosystem: text(rec?.ecosystem), format: text(rec?.format) });
+    }
+    return out;
+}
+/** 深刻度別の件数。キーの数も抑える(1件の大きさの上限を保証するため) */
+function severityOf(severity) {
+    if (severity === null)
+        return null;
+    return Object.fromEntries(Object.entries(severity).filter(([, v]) => count(v) !== null).slice(0, MAX_SEVERITY_KEYS).map(([k, v]) => [k.slice(0, 32), count(v)]));
+}
+const GAP_FIELDS = ["lockfile_missing", "unpinned_requirements", "unscannable_requirements", "unscannable_crates", "skipped_files", "unidentified_jars", "unidentified_packages"];
+function gapsOf(payload) {
+    const coverage = asRecord(payload.coverage);
+    const gaps = {};
+    for (const field of GAP_FIELDS) {
+        const value = coverage?.[field];
+        if (Array.isArray(value))
+            gaps[field] = value.length;
+    }
+    const skipped = payload.skipped_manifests; // scan_java_project
+    if (Array.isArray(skipped))
+        gaps.skipped_manifests = skipped.length;
+    return Object.keys(gaps).length > 0 ? gaps : undefined;
+}
+/** ツールの応答(JSONテキスト)から1件を作る。応答を解釈できない場合はエラーの記録にする */
+export function buildHistoryRecord(context, responseText, isError) {
+    let payload = null;
+    try {
+        payload = asRecord(JSON.parse(responseText));
+    }
+    catch {
+        payload = null;
+    }
+    const input = pathText(context.inputPath) ?? { path: "", truncated: false };
+    const resolved = pathText(payload?.project_dir) ?? pathText(context.resolvedInput) ?? input;
+    const base = {
+        schema: 1,
+        id: context.id,
+        started_at: context.startedAt.toISOString(),
+        duration_ms: Math.max(0, Math.round(context.durationMs)),
+        tool: context.tool,
+        kind: scanKind(context.tool),
+        server_version: context.serverVersion,
+        osv_scanner: { pinned_version: context.pinnedScannerVersion, source: context.scannerSource },
+        target: { input: input.path, resolved: resolved.path },
+        ...(input.truncated || resolved.truncated ? { target_truncated: true } : {}),
+        allowed_root_set: context.allowedRootSet,
+    };
+    const errorKind = text(asRecord(payload?.error)?.kind);
+    if (isError || payload === null || errorKind !== null) {
+        return { ...base, status: "error", error_kind: errorKind ?? "unknown", coverage_complete: null };
+    }
+    const coverage = asRecord(payload.coverage);
+    const complete = typeof coverage?.complete === "boolean" ? coverage.complete : null;
+    const severity = asRecord(payload.severity_breakdown);
+    const { findings, truncated } = findingsOf(context.tool, payload);
+    const record = {
+        ...base,
+        status: "ok",
+        coverage_complete: complete,
+        ...(manifestsOf(payload) !== undefined ? { manifests: manifestsOf(payload) } : {}),
+        ...(gapsOf(payload) !== undefined ? { coverage_gaps: gapsOf(payload) } : {}),
+        counts: {
+            vulnerable_package_count: count(payload.vulnerable_package_count ?? payload.identified_vulnerable_package_count),
+            vulnerability_count: count(payload.vulnerability_count ?? payload.identified_vulnerability_count),
+            informational_count: count(payload.informational_count) ?? 0,
+            severity_breakdown: severityOf(severity),
+        },
+        findings,
+        ...(truncated ? { findings_truncated: true } : {}),
+    };
+    if (context.tool === "suggest_fix") {
+        // suggest_fixの応答には脆弱性の総数が無いため、提案の脆弱性の数を数える
+        record.counts.vulnerability_count = findings.reduce((n, f) => n + f.vulnerabilities.filter((v) => v.informational === undefined).length, 0);
+    }
+    return record;
+}
+function fitting(value) {
+    const text = JSON.stringify(value);
+    return Buffer.byteLength(text, "utf8") <= MAX_RECORD_BYTES ? text : null;
+}
+/**
+ * 保存する文字列。1件の上限(読み出しの上限と同じ)に必ず収める:
+ * findingsを省き、それでも超えればマニフェストの一覧を半分ずつ減らし、最後は一覧を省く
+ * (残りの項目は文字列の長さ・件数に上限があり、上限を十分に下回る。対象のパスも含む)
+ */
+export function serializeHistoryRecord(record) {
+    const full = fitting(record);
+    if (full !== null)
+        return full;
+    const { findings: _findings, findings_truncated: _truncated, manifests, ...rest } = record;
+    const summary = { ...rest, findings_omitted: true };
+    if (manifests === undefined)
+        return JSON.stringify(summary);
+    const withAll = fitting({ ...summary, manifests });
+    if (withAll !== null)
+        return withAll;
+    for (let n = Math.floor(manifests.length / 2); n > 0; n = Math.floor(n / 2)) {
+        const partial = fitting({ ...summary, manifests: manifests.slice(0, n), manifests_truncated: true });
+        if (partial !== null)
+            return partial;
+    }
+    const last = fitting({ ...summary, manifests_truncated: true });
+    // 残りの項目はどれも大きさに上限があるため通常は届かない。読み戻せないファイルは書かない(記録側が警告する)
+    if (last === null)
+        throw new Error("The history record exceeds the size limit even without findings and manifests");
+    return last;
+}
+/** 読み出した記録の形式を確かめる(履歴のファイルは信頼しない)。解釈できなければnull */
+export function parseHistoryRecord(id, raw) {
+    const rec = asRecord(raw);
+    if (rec === null || rec.schema !== 1 || rec.id !== id)
+        return null;
+    const tool = asString(rec.tool);
+    if (tool === null || !HISTORY_TOOLS.includes(tool))
+        return null;
+    const target = asRecord(rec.target);
+    const input = pathText(target?.input)?.path ?? null;
+    const resolved = pathText(target?.resolved)?.path ?? null;
+    const startedAt = text(rec.started_at);
+    const status = rec.status === "ok" || rec.status === "error" ? rec.status : null;
+    if (input === null || resolved === null || startedAt === null || status === null)
+        return null;
+    const osv = asRecord(rec.osv_scanner);
+    const source = asString(osv?.source);
+    const findings = [];
+    for (const item of asArray(rec.findings).slice(0, MAX_FINDING_PACKAGES)) {
+        const f = asRecord(item);
+        const ecosystem = text(f?.ecosystem);
+        const name = text(f?.name);
+        const version = text(f?.version);
+        if (ecosystem === null || name === null || version === null)
+            continue;
+        const vulnerabilities = (vulnerabilitiesOf(f.vulnerabilities, { remaining: MAX_FINDING_VULNERABILITIES }) ?? []);
+        findings.push({
+            ecosystem, name, version, vulnerabilities,
+            ...("recommended_upgrade" in f ? { recommended_upgrade: text(f.recommended_upgrade) } : {}),
+            ...("upgrade_tier" in f ? { upgrade_tier: text(f.upgrade_tier) } : {}),
+            ...(text(f.verification) !== null ? { verification: text(f.verification) } : {}),
+        });
+    }
+    const counts = asRecord(rec.counts);
+    const severity = asRecord(counts?.severity_breakdown);
+    return {
+        schema: 1,
+        id,
+        started_at: startedAt,
+        duration_ms: count(rec.duration_ms) ?? 0,
+        tool: tool,
+        kind: scanKind(tool),
+        server_version: text(rec.server_version) ?? "unknown",
+        osv_scanner: {
+            pinned_version: text(osv?.pinned_version) ?? "unknown",
+            source: source === "OSV_SCANNER_PATH" || source === "pinned_download" ? source : "PATH_or_pinned_download",
+        },
+        target: { input, resolved },
+        ...(rec.target_truncated === true ? { target_truncated: true } : {}),
+        allowed_root_set: rec.allowed_root_set === true,
+        status,
+        ...(status === "error" ? { error_kind: text(rec.error_kind) ?? "unknown" } : {}),
+        coverage_complete: typeof rec.coverage_complete === "boolean" ? rec.coverage_complete : null,
+        ...(Array.isArray(rec.manifests) ? { manifests: manifestsOf({ manifests: rec.manifests }) ?? [] } : {}),
+        ...(asRecord(rec.coverage_gaps) !== null
+            ? { coverage_gaps: Object.fromEntries(Object.entries(asRecord(rec.coverage_gaps)).filter(([, v]) => count(v) !== null).map(([k, v]) => [k.slice(0, 64), count(v)])) }
+            : {}),
+        ...(counts !== null
+            ? {
+                counts: {
+                    vulnerable_package_count: count(counts.vulnerable_package_count),
+                    vulnerability_count: count(counts.vulnerability_count),
+                    informational_count: count(counts.informational_count) ?? 0,
+                    severity_breakdown: severityOf(severity),
+                },
+            }
+            : {}),
+        ...(Array.isArray(rec.findings) ? { findings } : {}),
+        ...(rec.findings_truncated === true ? { findings_truncated: true } : {}),
+        ...(rec.findings_omitted === true ? { findings_omitted: true } : {}),
+        ...(rec.manifests_truncated === true ? { manifests_truncated: true } : {}),
+    };
+}

package/dist/history/historyRecorder.js

@@ -0,0 +1,53 @@
+/**
+ * スキャンのツール呼び出しを実行履歴に記録する。記録の失敗はスキャンを失敗させない(stderrに警告するだけ)。
+ */
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { PINNED_OSV_SCANNER_VERSION } from "../osv/binaryDownloader.js";
+import { buildHistoryRecord, serializeHistoryRecord } from "./historyRecord.js";
+import { newRecordId, writeHistoryRecord } from "./historyStore.js";
+function scannerSource(env) {
+    if (env.OSV_SCANNER_PATH?.trim())
+        return "OSV_SCANNER_PATH";
+    const prefer = env.OSV_MCP_PREFER_DOWNLOAD?.trim().toLowerCase();
+    if (prefer === "1" || prefer === "true" || prefer === "yes")
+        return "pinned_download";
+    return "PATH_or_pinned_download";
+}
+async function resolveInput(input) {
+    const absolute = path.resolve(input);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** ツールを実行し、履歴が有効なら結果の要約を記録してから、結果をそのまま返す */
+export async function withHistory(tool, inputPath, run, options) {
+    if (!options.config.enabled)
+        return run();
+    const startedAt = new Date();
+    const started = performance.now();
+    const result = await run();
+    const durationMs = performance.now() - started;
+    try {
+        const record = buildHistoryRecord({
+            id: newRecordId(startedAt),
+            startedAt,
+            durationMs,
+            tool,
+            serverVersion: options.serverVersion,
+            pinnedScannerVersion: PINNED_OSV_SCANNER_VERSION,
+            scannerSource: scannerSource(options.env ?? process.env),
+            inputPath: typeof inputPath === "string" ? inputPath : String(inputPath),
+            resolvedInput: await resolveInput(typeof inputPath === "string" ? inputPath : String(inputPath)),
+            allowedRootSet: options.allowedRootSet,
+        }, result.content[0]?.text ?? "", result.isError === true);
+        await writeHistoryRecord(options.config, record.id, serializeHistoryRecord(record));
+    }
+    catch (error) {
+        (options.warn ?? ((m) => console.error(m)))(`osv-scanner-mcp: [warning] The scan history could not be recorded: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return result;
+}

package/dist/history/historyStore.js

@@ -0,0 +1,147 @@
+/**
+ * スキャンの実行履歴の保存(docs/DESIGN_TODO.md「スキャンの実行履歴」)。
+ *
+ * - 既定は無効。OSV_MCP_HISTORY=1の場合だけ記録する(社内のパッケージ名・パスをディスクに残すため)
+ * - 保存先: OSV_MCP_HISTORY_DIR(絶対パス) → $XDG_STATE_HOME/osv-scanner-mcp/history → ~/.local/state/osv-scanner-mcp/history
+ * - 1回=1ファイル(`<UTC時刻>-<乱数>.json`)。一時ファイルに書いてからrenameする(複数のプロセスが同時に書いても混ざらない)
+ * - ディレクトリは0700・ファイルは0600。シンボリックリンク・他人の所有するディレクトリには書かない
+ * - 履歴のファイルは本サーバー以外も書き換えられる前提で、読むときはサイズの上限付きで安全に読み、形式を確かめる
+ */
+import { randomBytes } from "node:crypto";
+import { chmod, lstat, mkdir, readdir, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { readRegularFile } from "../utils/safeRead.js";
+export const HISTORY_ENV = "OSV_MCP_HISTORY";
+export const HISTORY_DIR_ENV = "OSV_MCP_HISTORY_DIR";
+export const HISTORY_MAX_ENTRIES_ENV = "OSV_MCP_HISTORY_MAX_ENTRIES";
+const DEFAULT_MAX_ENTRIES = 500;
+const MAX_MAX_ENTRIES = 5_000;
+/** 履歴全体の合計サイズの上限 */
+const DEFAULT_MAX_TOTAL_BYTES = 100 * 1024 * 1024;
+/** 1件の上限。超える場合は差分用の識別子を省いて要約だけ記録する */
+export const MAX_RECORD_BYTES = 1024 * 1024;
+/** scan_historyで1回に読む量の合計の上限 */
+const MAX_READ_TOTAL_BYTES = 64 * 1024 * 1024;
+/** 書き込みに失敗して残った一時ファイルを消すまでの時間 */
+const STALE_TMP_MS = 60 * 60 * 1000;
+const RECORD_NAME = /^\d{8}T\d{9}Z-[0-9a-f]{12}\.json$/;
+const TMP_NAME = /^\.\d{8}T\d{9}Z-[0-9a-f]{12}\.json\.tmp$/;
+function truthy(value) {
+    const v = value?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+/** 既定の保存先(XDG Base Directoryの状態の置き場所) */
+export function defaultHistoryDir(env = process.env) {
+    const state = env.XDG_STATE_HOME?.trim();
+    const base = state !== undefined && state !== "" && path.isAbsolute(state) ? state : path.join(os.homedir(), ".local", "state");
+    return path.join(base, "osv-scanner-mcp", "history");
+}
+export function historyConfigFromEnv(env = process.env) {
+    const explicit = env[HISTORY_DIR_ENV]?.trim();
+    const dir = explicit !== undefined && explicit !== "" && path.isAbsolute(explicit) ? path.resolve(explicit) : defaultHistoryDir(env);
+    const requested = Number.parseInt(env[HISTORY_MAX_ENTRIES_ENV]?.trim() ?? "", 10);
+    const maxEntries = Number.isInteger(requested) && requested > 0 ? Math.min(requested, MAX_MAX_ENTRIES) : DEFAULT_MAX_ENTRIES;
+    return { enabled: truthy(env[HISTORY_ENV]), dir, maxEntries, maxTotalBytes: DEFAULT_MAX_TOTAL_BYTES };
+}
+/** 設定が無効なまま読み書きしようとした場合や、保存先が安全でない場合の理由 */
+export class HistoryUnavailableError extends Error {
+}
+/**
+ * 保存先を作成し、安全か確かめる: 実体のディレクトリ(シンボリックリンクでない)で、所有者が自分。
+ * 権限が広ければ0700に絞る。読み書きには解決後の実パスを使う(読み込みの境界の確認が実パスで行われるため)
+ */
+export async function ensureHistoryDir(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const info = await lstat(dir);
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new HistoryUnavailableError(`The history directory is not a regular directory: ${dir}`);
+    }
+    const uid = process.getuid?.();
+    if (uid !== undefined && info.uid !== uid) {
+        throw new HistoryUnavailableError(`The history directory is not owned by the current user: ${dir}`);
+    }
+    if ((info.mode & 0o077) !== 0)
+        await chmod(dir, 0o700);
+    return realpath(dir);
+}
+/** ファイル名に使うUTC時刻(並べ替えで時刻順になる) */
+function stamp(date) {
+    return date.toISOString().replace(/[-:]/g, "").replace(".", "");
+}
+export function newRecordId(date = new Date()) {
+    return `${stamp(date)}-${randomBytes(6).toString("hex")}`;
+}
+/** 1件を書く。一時ファイルに書いてからrenameし、古いものを削除する */
+export async function writeHistoryRecord(config, id, content) {
+    const dir = await ensureHistoryDir(config.dir);
+    const name = `${id}.json`;
+    if (!RECORD_NAME.test(name))
+        throw new HistoryUnavailableError(`Invalid history record id: ${id}`);
+    const tmp = path.join(dir, `.${name}.tmp`);
+    await writeFile(tmp, content, { mode: 0o600, flag: "wx" });
+    try {
+        await rename(tmp, path.join(dir, name));
+    }
+    catch (error) {
+        await unlink(tmp).catch(() => undefined);
+        throw error;
+    }
+    await pruneHistory({ ...config, dir });
+}
+/** 件数・合計サイズの上限を超えた古い記録と、残った一時ファイルを削除する(他のプロセスとの競合は無視する) */
+export async function pruneHistory(config, now = Date.now()) {
+    const names = await readdir(config.dir);
+    for (const name of names.filter((n) => TMP_NAME.test(n))) {
+        const file = path.join(config.dir, name);
+        const info = await lstat(file).catch(() => null);
+        if (info !== null && info.isFile() && now - info.mtimeMs > STALE_TMP_MS)
+            await unlink(file).catch(() => undefined);
+    }
+    const records = names.filter((n) => RECORD_NAME.test(n)).sort(); // 古い順
+    const remove = new Set(records.slice(0, Math.max(0, records.length - config.maxEntries)));
+    let total = 0;
+    // 新しい順に合計し、上限を超えた分より古いものを削除する
+    for (const name of [...records].reverse()) {
+        if (remove.has(name))
+            continue;
+        const info = await stat(path.join(config.dir, name)).catch(() => null);
+        if (info === null)
+            continue;
+        total += info.size;
+        if (total > config.maxTotalBytes)
+            remove.add(name);
+    }
+    for (const name of remove)
+        await unlink(path.join(config.dir, name)).catch(() => undefined);
+}
+/**
+ * 記録を新しい順に読む。読めない・大きすぎる・JSONでないファイル、読み込みの合計の上限を超えた分はskippedに数える
+ */
+export async function readHistoryRecords(config) {
+    const dir = await ensureHistoryDir(config.dir);
+    const names = (await readdir(dir)).filter((n) => RECORD_NAME.test(n)).sort().reverse().slice(0, config.maxEntries);
+    const records = [];
+    let skipped = 0;
+    let remaining = MAX_READ_TOTAL_BYTES;
+    for (const name of names) {
+        if (remaining <= 0) {
+            skipped++;
+            continue;
+        }
+        const read = await readRegularFile(path.join(dir, name), { maxBytes: Math.min(MAX_RECORD_BYTES, remaining), boundary: dir });
+        if (!read.ok) {
+            if (read.failure !== "not_found")
+                skipped++; // 読んでいる間に削除されたものは数えない
+            continue;
+        }
+        remaining -= read.bytes.length;
+        try {
+            records.push({ id: name.slice(0, -".json".length), data: JSON.parse(read.bytes.toString("utf8")) });
+        }
+        catch {
+            skipped++;
+        }
+    }
+    return { records, skipped };
+}

package/dist/index.js

@@ -11,6 +11,9 @@
  * - OSV_MCP_PREFER_DOWNLOAD: 1/true指定時、PATH上のバイナリを使わず検証済み自動ダウンロードを優先
  * - OSV_MCP_NO_REMOTE_RESOLUTION: 1/true指定時、pom.xmlの推移的依存をdeps.devで解決しない
  * - OSV_MCP_NO_CANDIDATE_CHECK: 1/true指定時、suggest_fixの推奨先のOSV照会を行わない
+ * - OSV_MCP_HISTORY: 1/true指定時、スキャンの実行履歴(要約と差分用の識別子)をローカルに記録する(既定は無効)
+ * - OSV_MCP_HISTORY_DIR: 実行履歴の保存先(絶対パス。既定は$XDG_STATE_HOME/osv-scanner-mcp/history)
+ * - OSV_MCP_HISTORY_MAX_ENTRIES: 保持する実行履歴の件数(既定500)
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -21,6 +24,9 @@ import { handleScanProject } from "./tools/scanProject.js";
 import { handleScanJavaArtifact } from "./tools/scanJavaArtifact.js";
 import { handleScanSbom } from "./tools/scanSbom.js";
 import { handleSuggestFix } from "./tools/suggestFix.js";
+import { handleScanHistory } from "./tools/scanHistory.js";
+import { withHistory } from "./history/historyRecorder.js";
+import { historyConfigFromEnv } from "./history/historyStore.js";
 import { realpathSync } from "node:fs";
 import os from "node:os";
 import { defaultCacheDir } from "./osv/binaryDownloader.js";
@@ -54,15 +60,20 @@ if (startupWarning !== null) {
         tmpDirReal,
         cacheDir: scannerPath ? undefined : defaultCacheDir(),
         scannerPath: scannerPath || undefined,
+        historyDir: historyConfigFromEnv().enabled ? historyConfigFromEnv().dir : undefined,
     })) {
         console.error(`osv-scanner-mcp: [warning] ${warning}`);
     }
 }
 // NOTE: リリース時はpackage.jsonのversionと同じ値に更新すること
+const SERVER_VERSION = "0.15.0";
 const server = new McpServer({
     name: "osv-scanner-mcp",
-    version: "0.14.1",
+    version: SERVER_VERSION,
 });
+const historyConfig = historyConfigFromEnv();
+/** スキャンのツールを実行履歴に記録する(OSV_MCP_HISTORYが無効なら何もしない) */
+const recorded = (tool, input, run) => withHistory(tool, input, run, { config: historyConfig, serverVersion: SERVER_VERSION, allowedRootSet: allowedRootFromEnv() !== undefined });
 server.registerTool("scan_project", {
     title: "Scan project dependencies for vulnerabilities (Java / JavaScript / Python / Go / Rust)",
     description: "Detects the lockfiles and manifests in a project and scans the dependencies for known vulnerabilities (CVE/GHSA). " +
@@ -81,7 +92,7 @@ server.registerTool("scan_project", {
             .min(1)
             .describe("Absolute path to the project directory, or to a supported lockfile or manifest"),
     },
-}, async ({ project_path }) => handleScanProject({ project_path }, { allowedRoot: allowedRootFromEnv() }));
+}, async ({ project_path }) => recorded("scan_project", project_path, () => handleScanProject({ project_path }, { allowedRoot: allowedRootFromEnv() })));
 server.registerTool("scan_java_project", {
     title: "Scan a Java project for vulnerabilities",
     description: "Scans a Java (Maven) project with Google OSV-Scanner and returns the known vulnerabilities (CVE/GHSA) in its dependencies as a JSON report sorted by severity. " +
@@ -94,7 +105,7 @@ server.registerTool("scan_java_project", {
             .min(1)
             .describe("Absolute path to the project directory, or to a pom.xml / gradle.lockfile"),
     },
-}, async ({ project_path }) => handleScanJavaProject({ project_path }, { allowedRoot: allowedRootFromEnv() }));
+}, async ({ project_path }) => recorded("scan_java_project", project_path, () => handleScanJavaProject({ project_path }, { allowedRoot: allowedRootFromEnv() })));
 server.registerTool("suggest_fix", {
     title: "Recommend upgrades that fix vulnerabilities",
     description: "Scans the project with the same detection as scan_project and recommends an upgrade version for each vulnerable package. " +
@@ -118,7 +129,7 @@ server.registerTool("suggest_fix", {
             .min(1)
             .describe("Absolute path to the project directory, or to a supported lockfile or manifest"),
     },
-}, async ({ project_path }) => handleSuggestFix({ project_path }, { allowedRoot: allowedRootFromEnv() }));
+}, async ({ project_path }) => recorded("suggest_fix", project_path, () => handleSuggestFix({ project_path }, { allowedRoot: allowedRootFromEnv() })));
 server.registerTool("explain_vulnerability", {
     title: "Explain a vulnerability",
     description: "Fetches the details of a vulnerability by GHSA or CVE ID from the OSV database (api.osv.dev). " +
@@ -141,7 +152,7 @@ server.registerTool("scan_java_artifact", {
     inputSchema: {
         artifact_path: z.string().min(1).describe("Absolute path to a JAR/WAR file, or to a directory to search"),
     },
-}, async ({ artifact_path }) => handleScanJavaArtifact({ artifact_path }, { allowedRoot: allowedRootFromEnv() }));
+}, async ({ artifact_path }) => recorded("scan_java_artifact", artifact_path, () => handleScanJavaArtifact({ artifact_path }, { allowedRoot: allowedRootFromEnv() })));
 server.registerTool("scan_sbom", {
     title: "Scan an SBOM for vulnerabilities",
     description: "Scans the dependencies that can be identified in a CycloneDX 1.4/1.5/1.6 or SPDX 2.2/2.3 JSON SBOM. " +
@@ -150,7 +161,22 @@ server.registerTool("scan_sbom", {
     inputSchema: {
         sbom_path: z.string().min(1).describe("Absolute path to a CycloneDX/SPDX JSON SBOM file"),
     },
-}, async ({ sbom_path }) => handleScanSbom({ sbom_path }, { allowedRoot: allowedRootFromEnv() }));
+}, async ({ sbom_path }) => recorded("scan_sbom", sbom_path, () => handleScanSbom({ sbom_path }, { allowedRoot: allowedRootFromEnv() })));
+server.registerTool("scan_history", {
+    title: "Show the scan history and what changed",
+    description: "Lists recorded runs of the scan tools (scan_project, suggest_fix, scan_java_project, scan_java_artifact, scan_sbom), newest first, " +
+        "with their time, target, coverage, and vulnerability counts. With project_path, also compares the last two successful runs of each kind for that target: " +
+        "new_vulnerabilities, resolved_vulnerabilities (reason: version_changed, package_not_reported, or same_version_not_reported), version_changes, and coverage_changes. " +
+        "With run_id, returns the details of one run, including the recorded packages and vulnerability IDs. " +
+        "Recording is off by default and must be enabled with OSV_MCP_HISTORY=1 (otherwise the error kind is history_disabled). " +
+        "Changes reflect the OSV data at the time of each scan, so they can also appear when only the vulnerability database changed. " +
+        "Only summaries and identifiers are kept, not full results.",
+    inputSchema: {
+        project_path: z.string().min(1).optional().describe("Absolute path of a scanned target (project directory, lockfile, JAR/WAR, or SBOM) to filter by and compare"),
+        limit: z.number().int().min(1).max(50).optional().describe("Number of runs to list (default 10, maximum 50)"),
+        run_id: z.string().min(1).max(64).optional().describe("ID of a run from the runs list, to show its details"),
+    },
+}, async ({ project_path, limit, run_id }) => handleScanHistory({ project_path, limit, run_id }, { config: historyConfig, allowedRoot: allowedRootFromEnv() }));
 // シグナル・stdinの終了時に一時ディレクトリと実行中のosv-scannerを片付ける(接続前に登録する)
 installShutdownHandlers();
 // 前回の異常終了で残った一時ディレクトリの掃除。起動を遅らせないよう待たない

package/dist/tools/scanHistory.js

@@ -0,0 +1,162 @@
+/**
+ * `scan_history`ツールのハンドラ: スキャンの実行履歴の一覧・1回の詳細・直近2回の比較を返す
+ * (docs/DESIGN_TODO.md「スキャンの実行履歴」)。
+ *
+ * - 履歴が無効ならhistory_disabled(空の結果は「履歴がない」と誤読されるため)
+ * - OSV_MCP_ALLOWED_ROOT設定時は、対象が許可ルートの内側の回だけを返す
+ * - 履歴のファイルは信頼しない入力として形式を確かめ、文字列は返す前にも無害化する
+ */
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { ScanToolError } from "../errors.js";
+import { compareHistoryRecords } from "../history/historyDiff.js";
+import { parseHistoryRecord } from "../history/historyRecord.js";
+import { HISTORY_ENV, HistoryUnavailableError, readHistoryRecords } from "../history/historyStore.js";
+import { sanitizeExternalText } from "../utils/externalText.js";
+import { assertInsideAllowedRoot, isInsideDir } from "../utils/projectWalk.js";
+import { errorResult, jsonResult } from "./toolResult.js";
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+const MAX_DETAIL_PACKAGES = 500;
+const RUN_ID = /^\d{8}T\d{9}Z-[0-9a-f]{12}$/;
+const NOTE = "Changes are computed from the vulnerability data at the time of each scan: they can also appear when the OSV database changes " +
+    "without any change to the project. Scan results list only vulnerable packages, so a package that disappears from the results " +
+    "may have been upgraded to a version without known vulnerabilities, removed, or no longer scanned (reason: package_not_reported)";
+/** 応答に含める文字列をすべて無害化する(履歴のファイルは書き換えられうる) */
+function sanitizeDeep(value) {
+    if (typeof value === "string")
+        return sanitizeExternalText(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeDeep);
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [sanitizeExternalText(k), sanitizeDeep(v)]));
+    }
+    return value;
+}
+async function resolveLoosely(input) {
+    const absolute = path.resolve(input);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute; // 削除済みのプロジェクトの履歴も引けるようにする
+    }
+}
+function summary(record) {
+    return {
+        id: record.id,
+        started_at: record.started_at,
+        tool: record.tool,
+        target: record.target.input,
+        project: record.target.resolved,
+        status: record.status,
+        ...(record.error_kind !== undefined ? { error_kind: record.error_kind } : {}),
+        coverage_complete: record.coverage_complete,
+        ...(record.counts !== undefined
+            ? {
+                vulnerable_package_count: record.counts.vulnerable_package_count,
+                vulnerability_count: record.counts.vulnerability_count,
+                ...(record.counts.informational_count > 0 ? { informational_count: record.counts.informational_count } : {}),
+            }
+            : {}),
+        duration_ms: record.duration_ms,
+    };
+}
+function detail(record) {
+    const findings = record.findings ?? [];
+    return {
+        ...summary(record),
+        server_version: record.server_version,
+        osv_scanner: record.osv_scanner,
+        allowed_root_set: record.allowed_root_set,
+        ...(record.target_truncated ? { target_truncated: true } : {}),
+        ...(record.manifests !== undefined ? { manifests: record.manifests } : {}),
+        ...(record.manifests_truncated ? { manifests_truncated: true } : {}),
+        ...(record.coverage_gaps !== undefined ? { coverage_gaps: record.coverage_gaps } : {}),
+        ...(record.counts?.severity_breakdown ? { severity_breakdown: record.counts.severity_breakdown } : {}),
+        ...(record.findings !== undefined ? { findings: findings.slice(0, MAX_DETAIL_PACKAGES) } : {}),
+        ...(findings.length > MAX_DETAIL_PACKAGES ? { findings_omitted_from_response: findings.length - MAX_DETAIL_PACKAGES } : {}),
+        ...(record.findings_truncated ? { findings_truncated: true } : {}),
+        ...(record.findings_omitted ? { findings_omitted: true } : {}),
+    };
+}
+function matchesProject(record, resolvedQuery, absoluteQuery) {
+    return record.target.resolved === resolvedQuery || path.resolve(record.target.input) === absoluteQuery;
+}
+/** 種類ごとに、直近の成功した2回を比べる */
+function changesByKind(records) {
+    const kinds = [...new Set(records.map((r) => r.kind))];
+    return kinds.map((kind) => {
+        const ok = records.filter((r) => r.kind === kind && r.status === "ok"); // 新しい順
+        if (ok.length < 2)
+            return { kind, note: "Fewer than two successful runs of this kind are recorded, so there is nothing to compare yet" };
+        return { kind, ...compareHistoryRecords(ok[1], ok[0]) };
+    });
+}
+export async function handleScanHistory(args, options) {
+    try {
+        if (!options.config.enabled) {
+            throw new ScanToolError("history_disabled", `The scan history is disabled. Set ${HISTORY_ENV}=1 in the MCP server environment to record scans from then on ` +
+                "(records are kept locally; see the README for the location and limits)");
+        }
+        if (args.run_id !== undefined && !RUN_ID.test(args.run_id)) {
+            throw new ScanToolError("history_run_not_found", "run_id is not a valid history record ID (use an id from the runs list)");
+        }
+        const limit = Math.min(Math.max(1, Math.floor(args.limit ?? DEFAULT_LIMIT)), MAX_LIMIT);
+        const rootReal = options.allowedRoot !== undefined ? await resolveLoosely(options.allowedRoot) : undefined;
+        let resolvedQuery;
+        let absoluteQuery;
+        if (args.project_path !== undefined) {
+            if (typeof args.project_path !== "string" || args.project_path.trim() === "") {
+                throw new ScanToolError("project_not_found", "project_path is empty");
+            }
+            absoluteQuery = path.resolve(args.project_path);
+            resolvedQuery = await resolveLoosely(args.project_path);
+            if (rootReal !== undefined)
+                assertInsideAllowedRoot(resolvedQuery, rootReal);
+        }
+        let stored;
+        try {
+            stored = await readHistoryRecords(options.config);
+        }
+        catch (error) {
+            if (error instanceof HistoryUnavailableError)
+                throw new ScanToolError("history_unavailable", error.message);
+            throw error;
+        }
+        let skipped = stored.skipped;
+        const records = [];
+        for (const { id, data } of stored.records) {
+            const record = parseHistoryRecord(id, data);
+            if (record === null) {
+                skipped++;
+                continue;
+            }
+            // 許可ルートを狭めて起動し直した場合に、範囲外の過去の情報を返さない
+            if (rootReal !== undefined && !isInsideDir(rootReal, record.target.resolved))
+                continue;
+            records.push(record);
+        }
+        if (args.run_id !== undefined) {
+            const record = records.find((r) => r.id === args.run_id);
+            if (record === undefined)
+                throw new ScanToolError("history_run_not_found", `No recorded run with id ${args.run_id} is available`);
+            return jsonResult(sanitizeDeep({ run: detail(record), note: NOTE }));
+        }
+        const selected = resolvedQuery !== undefined ? records.filter((r) => matchesProject(r, resolvedQuery, absoluteQuery)) : records;
+        return jsonResult(sanitizeDeep({
+            history: {
+                directory: options.config.dir,
+                max_entries: options.config.maxEntries,
+                recorded_runs: selected.length,
+                ...(skipped > 0 ? { skipped_records: skipped } : {}),
+            },
+            runs: selected.slice(0, limit).map(summary),
+            ...(resolvedQuery !== undefined ? { changes: changesByKind(selected) } : {}),
+            note: NOTE,
+        }));
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}

package/dist/utils/permissionCheck.js

@@ -34,5 +34,9 @@ export function permissionModelWarnings(input, permission = process.permission)
         warnings.push(`Writing to the osv-scanner cache is not allowed: ${input.cacheDir} ` +
             "(to use the automatic download, add --allow-fs-write and --allow-fs-read; otherwise set OSV_SCANNER_PATH)");
     }
+    if (input.historyDir !== undefined && (!permission.has("fs.write", inside(input.historyDir)) || !permission.has("fs.read", inside(input.historyDir)))) {
+        warnings.push(`Reading and writing the scan history directory is not allowed: ${input.historyDir} ` +
+            "(add --allow-fs-read and --allow-fs-write for it, or unset OSV_MCP_HISTORY; scans still run but are not recorded)");
+    }
     return warnings;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osv-scanner-mcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "MCP server that wraps Google's OSV-Scanner to scan Java projects for known vulnerabilities",
   "type": "module",
   "license": "Apache-2.0",