osv-scanner-mcp 0.14.1 → 0.16.0

package/README.md

@@ -7,17 +7,19 @@
 
 An MCP server that wraps Google's [OSV-Scanner](https://github.com/google/osv-scanner). Ask an MCP client such as Claude to "check this project for vulnerabilities", and it returns the known vulnerabilities (CVE / GHSA) in your dependencies as a report sorted by severity, together with recommended upgrades.
 
-> **Status**: [Published on npm](https://www.npmjs.com/package/osv-scanner-mcp) (`npx -y osv-scanner-mcp`). Supports lockfiles and manifests for Java (Maven / Gradle), JavaScript (npm / yarn / pnpm / bun), Python (Poetry / uv / Pipenv / PDM / requirements.txt), Go, and Rust (`Cargo.lock`), with upgrade recommendations for Maven, npm, PyPI, Go, and crates.io. Setup instructions are provided for Claude Code, Claude Desktop, Codex CLI, Antigravity, and VS Code (GitHub Copilot).
+> **Status**: [Published on npm](https://www.npmjs.com/package/osv-scanner-mcp) (`npx -y osv-scanner-mcp`). Supports lockfiles and manifests for Java (Maven / Gradle), JavaScript (npm / yarn / pnpm / bun), Python (Poetry / uv / Pipenv / PDM / requirements.txt), Go, Rust (`Cargo.lock`), and .NET (NuGet: `packages.lock.json`, `obj/project.assets.json`, `packages.config`, `*.deps.json`, and project files), with upgrade recommendations for Maven, npm, PyPI, Go, and crates.io. Setup instructions are provided for Claude Code, Claude Desktop, Codex CLI, Antigravity, and VS Code (GitHub Copilot).
 
 ## Features
 
-- **One-shot multi-language scan**: Pass a project path to `scan_project`, and it detects and scans the Java, JavaScript, Python, Go, and Rust lockfiles in the project together. Dependencies that could not be scanned (for example, a manifest without a lockfile or an unpinned requirement) are reported up front in `coverage`
+- **One-shot multi-language scan**: Pass a project path to `scan_project`, and it detects and scans the Java, JavaScript, Python, Go, Rust, and .NET lockfiles in the project together. Dependencies that could not be scanned (for example, a manifest without a lockfile or an unpinned requirement) are reported up front in `coverage`
 - **Upgrade recommendations**: `suggest_fix` recommends, for each vulnerable package, the upgrade closest to the current release line that addresses its fix targets, for Maven, npm, PyPI, Go, and Rust (crates.io). Known unfixed and informational advisories remain visible. The recommended version is also checked against the OSV database for additional fix-target vulnerabilities
 - **Rust without false positives**: For `Cargo.lock`, only crates from crates.io are scanned. Your own workspace crates, git dependencies, and crates from private registries are not looked up as crates.io crates (OSV-Scanner alone would match them by name, and send their names to the OSV API). RustSec notices about unmaintained or unsound crates are labeled `informational` and counted apart from vulnerabilities
-- **Direct and transitive dependencies**: Packages are marked as direct or transitive dependencies (from `package-lock.json`, `go.mod`, `requirements.txt`, and `pom.xml`), and update hints are tailored accordingly, for example by naming the direct dependency that pulls in a transitive one
+- **.NET without guessing versions**: Each project file is matched to its own lockfile or `obj/project.assets.json`. Without one, only its direct `PackageReference` items are scanned, and a `Version="x"` (which means x or higher) is reported as a lower bound. References whose version cannot be known without running MSBuild (properties, conditions, floating versions, `Update` / `Remove`) are listed instead of being looked up: OSV treats an unparsable version as older than every release and would report every vulnerability for it
+- **Direct and transitive dependencies**: Packages are marked as direct or transitive dependencies (from `package-lock.json`, `go.mod`, `requirements.txt`, `pom.xml`, `Cargo.lock`, and the .NET files), and update hints are tailored accordingly, for example by naming the direct dependency that pulls in a transitive one
 - **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 +132,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).
 
@@ -158,6 +163,7 @@ As an additional layer of defense, you can limit what the server can read and wr
         "--allow-fs-write=/private/var/folders/xx/yyyy/T",
         "--allow-fs-read=/opt/homebrew/bin/osv-scanner",
         "--allow-child-process",
+        "--allow-addons",
         "/path/to/OSV-Scanner-MCP/dist/index.js"
       ],
       "env": {
@@ -172,7 +178,9 @@ 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
+- On macOS and Windows, `--allow-addons` is also required for the trusted Koffi native binding used to verify the path of an open file handle. Native code is outside Node's permission sandbox. On Linux, use `--allow-fs-read=/proc/self/fd` instead; `/proc` must be mounted. If the OS cannot verify the opened object, boundary-protected reads fail closed. Keep OS-level isolation when scanning in a stronger sandbox.
 - 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)
 
 ### Network destinations and privacy
@@ -183,7 +191,7 @@ Destinations confirmed with osv-scanner v2.4.0 (2026-10-07) and v2.7.0, the pinn
 |---|---|---|
 | Scanning `pom.xml` (`scan_project` / `scan_java_project` / `suggest_fix`) | `api.osv.dev`, **`api.deps.dev`** | Package names and versions. To resolve transitive dependencies, the names and versions of the dependencies declared in `pom.xml` (including internal packages) are sent to deps.dev |
 | Scanning `requirements.txt` (`scan_project` / `suggest_fix`) | `api.osv.dev`, **`api.deps.dev`** | As with `pom.xml`, the names and versions of the listed dependencies are sent to deps.dev to resolve transitive dependencies. Package indexes given with `--index-url` and similar options are not contacted |
-| Scanning lockfiles (`gradle.lockfile`, npm lockfiles such as `package-lock.json`, Python lockfiles such as `poetry.lock`, `go.mod`, `Cargo.lock`) | `api.osv.dev` | Package names and versions (lockfiles already list every dependency, so nothing is resolved remotely). For `Cargo.lock`, only crates from crates.io are sent: the names of your own crates, git dependencies, and private-registry crates are not sent (confirmed 2026-10-11). **Git dependencies in npm lockfiles** (`package-lock.json`, `yarn.lock`, and so on) are looked up by their repository URL (ecosystem `GIT`) and commit, so the host name and path of a private git repository (for example `https://git.example.com/team/repo`) are sent (since osv-scanner 2.6.0) |
+| Scanning lockfiles (`gradle.lockfile`, npm lockfiles such as `package-lock.json`, Python lockfiles such as `poetry.lock`, `go.mod`, `Cargo.lock`) | `api.osv.dev` | Package names and versions (lockfiles already list every dependency, so nothing is resolved remotely). For `Cargo.lock`, only crates from crates.io are sent: the names of your own crates, git dependencies, and private-registry crates are not sent (confirmed 2026-10-11). **For .NET, packages from private NuGet feeds are sent as well**: lockfiles do not record which feed a package came from, so they cannot be told apart (a `nuget.config` in the scanned directory that lists other sources adds a warning to `coverage.nuget_warnings`). The names of your own projects (`type: project` and so on) are not sent. **Git dependencies in npm lockfiles** (`package-lock.json`, `yarn.lock`, and so on) are looked up by their repository URL (ecosystem `GIT`) and commit, so the host name and path of a private git repository (for example `https://git.example.com/team/repo`) are sent (since osv-scanner 2.6.0) |
 | `scan_java_artifact` / `scan_sbom` | `api.osv.dev` | Names and versions of the identified packages |
 | `suggest_fix` checking recommended versions | `api.osv.dev` | The names of packages with a recommendation (already sent during the scan) and the candidate versions (published fixed versions). Disable with `OSV_MCP_NO_CANDIDATE_CHECK=1` |
 | `explain_vulnerability` | `api.osv.dev` | The vulnerability ID |
@@ -198,7 +206,7 @@ Both api.osv.dev and deps.dev are operated by Google. **In every configuration,
 
 ### `scan_project`
 
-Detects the lockfiles and manifests in a project and scans the Java / JavaScript / Python / Go / Rust dependencies together. Package managers and builds are never run.
+Detects the lockfiles and manifests in a project and scans the Java / JavaScript / Python / Go / Rust / .NET dependencies together. Package managers and builds are never run.
 
 **Input**
 
@@ -215,13 +223,24 @@ Detects the lockfiles and manifests in a project and scans the Java / JavaScript
 | Python (PyPI) | `poetry.lock`, `uv.lock`, `Pipfile.lock`, `pdm.lock`, `requirements.txt` (and variants such as `requirements-dev.txt`) |
 | Go | `go.mod` |
 | Rust (crates.io) | `Cargo.lock` (lockfile versions 1 to 4) |
+| .NET (NuGet) | `packages.lock.json` / `packages.<project>.lock.json`, `obj/project.assets.json`, `packages.config` / `packages.<project>.config`, `*.deps.json`, and `*.csproj` / `*.fsproj` / `*.vbproj` (direct references only, when no lockfile matches) |
 
-`.git`, `node_modules`, `target`, `build`, `.idea`, `.vscode`, `.venv`, `venv`, `site-packages`, `__pycache__`, `.tox`, `vendor`, `.cargo`, and symbolic links are not searched. Only the detected files are passed to OSV-Scanner, each with its format given explicitly (`coverage.manifests` in the response is exactly the scan scope). The search limits are the same as for `scan_java_project`.
+`.git`, `node_modules`, `target`, `build`, `.idea`, `.vscode`, `.venv`, `venv`, `site-packages`, `__pycache__`, `.tox`, `vendor`, `.cargo`, `bin` and `obj` in a directory that contains a .NET project file (build output of that project), and symbolic links are not searched. Only the detected files are passed to OSV-Scanner, each with its format given explicitly (`coverage.manifests` in the response is exactly the scan scope). The search limits are the same as for `scan_java_project`.
 
 **`requirements.txt` files are not passed to OSV-Scanner as they are.** The server parses them, rewrites only the dependency lines it can interpret into simple forms such as `name==version`, and scans a private temporary copy (deleted after the scan). OSV-Scanner interprets include directives on its own (it even treats `- r ../x.txt`, with a space, as an include and reads files outside the scan scope), so the copy never contains include directives or options. Includes (`-r` / `--requirement`) are expanded by the server, and only when the included file is inside the project directory.
 
 **`Cargo.lock` files are not passed to OSV-Scanner as they are either.** OSV-Scanner (v2.4.0 and v2.7.0) ignores where each package comes from and looks every package up as a crates.io crate, so a workspace crate, a git fork, or a private-registry crate with the same name and version as a vulnerable crates.io crate is reported as vulnerable, and its name is sent to the OSV API. The server parses `Cargo.lock` and scans a private copy that lists only the packages whose source is crates.io (`registry+https://github.com/rust-lang/crates.io-index` or `sparse+https://index.crates.io/`), like `cargo audit`. Packages replaced with `[replace]` are not scanned, because they are not used (the replacement is classified by its own source). The parser accepts only what Cargo writes; if a `Cargo.lock` contains anything else, the whole file is excluded and listed in `skipped_files` instead of being scanned partially. Cargo is never run.
 
+**.NET files are not passed to OSV-Scanner as they are either.** OSV-Scanner (v2.7.0) looks the project's own projects in `*.deps.json` up as NuGet packages, and passes `.csproj` versions such as `$(Version)` or `[1.0,2.0)` to OSV as they are; OSV treats a version it cannot parse as older than every release, so every known vulnerability of the package is reported (confirmed 2026-10-23). The server parses every .NET file and scans a private copy in `packages.lock.json` format that lists only the packages it can look up. Neither `dotnet restore` nor MSBuild is run, and project files are never evaluated.
+
+- **Matching per project file.** For each `*.csproj` / `*.fsproj` / `*.vbproj`, the first source confirmed to belong to it is used: `packages.<project>.lock.json`; `packages.lock.json` only when the directory has a single project file; neither, when the project sets `NuGetLockFilePath`; `packages.<project>.config` or `packages.config` under the same rule; then `obj/project.assets.json`, only when its `project.restore.projectPath` names this project file (projects in one directory share `obj`). A lockfile that cannot be matched to a project is still scanned, but no project counts as covered by it
+- **Projects without a matching source** (including projects with no `PackageReference` of their own, since `Directory.Build.props` or the SDK can add references) are scanned from their direct `PackageReference` items only, and listed in `lockfile_missing` with `status: "direct_only"` (or `"unconfirmed"` when a lockfile exists but cannot be matched). Transitive dependencies are not scanned, so `complete` is `false`. Enable `RestorePackagesWithLockFile` to scan them
+- **`PackageReference` versions.** `[x]` is looked up as x. `x`, `[x,)`, and `[x,y)` mean x or higher (NuGet prefers the lowest available version, which may be above x), so they are looked up at x and the packages are marked `version_is_lower_bound: true`. A lower bound that is excluded or missing, `$(...)`, `*`, and a missing version (central package management) are not looked up
+- **References that might not apply are not looked up**: a `Condition` on the reference, its `ItemGroup`, or its `Version`; references inside `Choose` or `Target`; names that also have `Update` or `Remove` in the file, or in a `Directory.Build.props` / `Directory.Build.targets` in the scanned directory; names included more than once; and `VersionOverride`. They are listed in `unresolved_package_references` with the reason
+- **Runtime packs** of self-contained apps in `*.deps.json` are looked up under their package names (the SDK writes them as `runtimepack.<name>`, which OSV does not match)
+- **Not looked up from restore results**: entries of an unknown type, and versions that are not plain NuGet versions (listed in `unscannable_nuget_packages`). Your own projects are counted in `local_projects`
+- XML (project files, `packages.config`, `nuget.config`) is read by a small parser that rejects `DOCTYPE`, entity declarations, and CDATA. JSON files use the same structural checks as the npm lockfiles (16 MiB per file). Up to 200,000 packages and 1,000 .NET files are looked up per scan; files beyond the limit are listed in `skipped_files`. A character reference that is not a valid character (such as `&#x110000;`) makes the file uninterpretable instead of failing the scan
+
 **`package-lock.json` copies get a `resolved` URL where it is missing.** osv-scanner 2.7.0 treats entries without `resolved` as local packages and does not look them up, which would silently skip bundled dependencies (`inBundle`) and registry packages in lockfiles generated with npm's `omit-lockfile-registry-resolved=true`. The private copy that is scanned gets a public-registry URL for those entries (entries under `node_modules/` that are not links and have a plain version, and aliases such as `npm:lodash@4.17.20` in lockfile version 1), so they are looked up as before; the original file is not changed.
 
 **npm JSON limits:** Normalization of `package-lock.json` and `npm-shrinkwrap.json` is limited to 16 MiB per file and 64 MiB per scan, for both input and output. Before parsing, JSON nesting is limited to 128 levels and structural markers (containers, commas, and colons outside strings) to 1,000,000 per file and 2,000,000 per analysis phase. Changed copies use compact JSON, with their size checked before serialization. A lockfile that exceeds these limits is scanned as it is, without filling in `resolved` (OSV-Scanner parses large lockfiles itself; the limits only bound this server's own parsing and rewriting), and it is listed in `coverage.skipped_files` with the reason, so `complete` is `false`: entries without `resolved` in it may not have been looked up. Workspace membership and dependency-relation lookups use the same structural checks and remain unconfirmed or unknown when limits are reached.
@@ -263,6 +282,7 @@ Detects the lockfiles and manifests in a project and scans the Java / JavaScript
   - `unscannable_requirements`: lines that are not scanned, with the reason: `-e`, `name @ URL`, paths, includes that were not expanded (outside the project directory, missing, URLs, or over the limits), constraint files (`-c`, not applied), and options or version specifiers that cannot be interpreted. Lines that cannot be interpreted are recorded here instead of being ignored
   - `local_crates` (only when a `Cargo.lock` was scanned): the number of crates without a source in `Cargo.lock` (workspace members and path dependencies). They are your own code and are not scanned; they do not make `complete` false. A third-party crate vendored as a path dependency is not scanned either (as with `cargo audit`)
   - `unscannable_crates` (only when a `Cargo.lock` was scanned): git dependencies (their versions do not correspond to crates.io releases) and crates from registries other than crates.io (a crate with the same name on crates.io may be a different crate). They are not scanned, so `complete` is false. Source URLs are not included in the response
+  - `local_projects`, `unscannable_nuget_packages`, `unresolved_package_references`, `nuget_warnings` (only when a .NET file was found): see the .NET notes above. `nuget_warnings` notes lower bounds, a possibly stale `project.assets.json` (more than a minute older than its project file; smaller differences are ignored because a clone writes files in any order), references that cannot be checked from project files alone (SDK-implicit references and `Directory.Build.*` outside the scanned directory), and package sources other than nuget.org. Entries in `unscannable_nuget_packages` and `unresolved_package_references` make `complete` false
   - `skipped_files`: files excluded from the scan, with the reason (a `Cargo.lock` that cannot be interpreted with certainty, a `requirements.txt` that cannot be read or is larger than 1 MiB, or a `pom.xml` whose parent POM chain references a file outside the allowed root). A `pom.xml` scanned without its parent POM, because the parent could not be read, is also listed here with the reason (see [Parent POMs](#parent-poms))
   - Each list holds up to 200 entries; the number of omitted entries is returned in `omitted_items`
 - `ecosystem_breakdown` includes ecosystems with zero findings, to show that they were scanned
@@ -273,9 +293,10 @@ Detects the lockfiles and manifests in a project and scans the Java / JavaScript
   - `requirements.txt`: dependencies written in the file are direct; dependencies resolved through deps.dev are transitive
   - `pom.xml`: OSV-Scanner reports the dependencies declared in `pom.xml` (and its parent POMs) and the transitive dependencies resolved through deps.dev as separate results (`source.type` `lockfile` / `unknown`), and this split is used (so parent POMs, profiles, properties, and dependency management are interpreted exactly as OSV-Scanner does). `introduced_by` / `declared_in` are not available. This relies on undocumented OSV-Scanner output, so anything unexpected is reported as `unknown`
   - `Cargo.lock`: crates.io dependencies immediately required by a local/workspace/path crate are direct; crates.io dependencies reachable through them (including git and alternate-registry origins) are transitive. `introduced_by` names the first direct dependency on each path. References are resolved by exact name, version, and source where provided; ambiguous references are not guessed. Replacements are followed. `declared_in` lists project-relative Cargo.toml paths only when every declaring crate has a unique matching manifest. Otherwise `declaring_crates` names the unmapped declaring crates (up to 10, with the rest in `declaring_crates_omitted`). Dev/build/target-specific distinctions are unavailable. Traversal over 2,000,000 edges returns `unknown`
+  - .NET: `Direct` / `Transitive` in `packages.lock.json`; the dependencies of `project.frameworks` in `project.assets.json`; the dependencies of the project library in `*.deps.json`; and every reference read from a project file are direct. `packages.config` does not say, so it is `unknown`. `introduced_by` and `declared_in` are not available yet
   - Other formats (`gradle.lockfile`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, `poetry.lock`, `uv.lock`, `Pipfile.lock`, and `pdm.lock`), npm lockfile version 1, and entries not reachable from the project are `unknown`. If lockfiles disagree, the value is `mixed`
 - `dependency_groups` is the raw dependency group reported by OSV-Scanner (for example `dev`). It is missing or inaccurate for some lockfile formats (absent for pnpm, `optional` for pdm, and so on), so treat it as informational
-- Upgrade recommendations (`suggest_fix`) are available for Maven, npm, PyPI, Go, and Rust (crates.io)
+- Upgrade recommendations (`suggest_fix`) are available for Maven, npm, PyPI, Go, and Rust (crates.io). NuGet packages are returned with `verification: "unsupported_ecosystem"` for now
 
 ### `scan_java_project`
 
@@ -466,6 +487,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 +579,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
@@ -529,7 +591,7 @@ The following measures keep the vulnerability scanner itself from becoming an at
 - **Supply chain**: The automatic download is limited to the official GitHub Releases and a pinned version, and is verified against **a SHA256 checksum embedded in the package** (the SHA256SUMS file from the release is not trusted, so tampering on the release side is detected). The binary is not made executable until it passes verification, and cached binaries are verified again on every use. `OSV_MCP_PREFER_DOWNLOAD=1` avoids unverified binaries on `PATH`
 - **Command injection**: Commands are run with `spawn` and an argument array, never through a shell. OSV-Scanner receives only a fixed list of arguments, plus verified absolute paths
 - **Snapshots (no gap between checking and reading)**: OSV-Scanner never receives the original files. Lockfiles, `pom.xml` (including the parent POM chain), and JAR/WARs are read safely once, copied into a private temporary directory (accessible only by the owner, deleted afterwards), and the copies are both checked and scanned. Replacing the original files or directories after the check has no effect on the results. Parent POMs are copied into the temporary directory at their original relative positions, so OSV-Scanner can follow relative paths but only finds the verified copies (references that climb out of the temporary directory with repeated `..` are excluded). Reads refuse a symbolic link at the final path component and anything that is not a regular file (so named pipes cannot stall the server), and afterwards the path is resolved again to confirm that it is still inside the boundary and is the same file that was opened. The copies are limited to 2 GiB in total (`scan_input_too_large`). When the server is terminated (SIGTERM/SIGINT/SIGHUP, or stdin closing), the temporary directories are deleted and running OSV-Scanner processes are stopped. Directories left behind by an uncatchable termination such as SIGKILL are deleted at a later startup (only directories whose names exactly match this server's prefixes, owned by the current user, not symbolic links, and unmodified for 24 hours or more)
-- **Path traversal**: Input paths are resolved with `realpath` (following symbolic links) before the boundary check. Manifest searches do not follow symbolic links. OSV-Scanner never receives a directory, only the detected manifests, each with its format given explicitly (given a directory, OSV-Scanner also reads `requirements.txt` files there and follows their `-r ../x.txt` includes outside the scan scope). `requirements.txt` files are not passed as they are: only the dependency lines the server could interpret are normalized and written to a private copy without any include directives, so even if OSV-Scanner's interpretation of includes differs from the server's, files outside the scope are never read. `Cargo.lock` files are likewise replaced by a copy the server writes, listing only crates.io packages A `pom.xml` whose parent POM chain references a file outside `OSV_MCP_ALLOWED_ROOT` is excluded ([Parent POMs](#parent-poms))
+- **Path traversal**: Input paths are resolved with `realpath` (following symbolic links) before the boundary check. Manifest searches do not follow symbolic links. OSV-Scanner never receives a directory, only the detected manifests, each with its format given explicitly (given a directory, OSV-Scanner also reads `requirements.txt` files there and follows their `-r ../x.txt` includes outside the scan scope). `requirements.txt` files are not passed as they are: only the dependency lines the server could interpret are normalized and written to a private copy without any include directives, so even if OSV-Scanner's interpretation of includes differs from the server's, files outside the scope are never read. `Cargo.lock` files are likewise replaced by a copy the server writes, listing only crates.io packages, and every .NET file by a `packages.lock.json` copy listing only packages with a known version. A `pom.xml` whose parent POM chain references a file outside `OSV_MCP_ALLOWED_ROOT` is excluded ([Parent POMs](#parent-poms))
 - **Denial of service**: Timeouts and limits on stdout and on the stderr excerpt. Scanner output is parsed defensively and malformed output does not throw. The number of concurrent scans is limited (2 by default) so that parallel requests cannot start unlimited processes. The server's own analysis reads each file once and reuses the result (lockfiles for npm workspace membership, `Cargo.lock` files, shared `requirements.txt` includes, parent POMs), with a limit on the total amount read. Responses do not include the internal affected-range data, which keeps large scans to a fraction of their former size
 - **Fail-closed mode**: `OSV_MCP_REQUIRE_ALLOWED_ROOT=1` refuses to start the server when no allowed root is set
 - **Restricted permissions (optional)**: The server works under Node's permission model, reports denied access as `permission_denied`, and warns about missing permissions at startup ([Running with restricted permissions](#running-with-restricted-permissions))
@@ -566,6 +628,9 @@ 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)
+- [x] `scan_project` for .NET (NuGet), with per-project matching and lower bounds for project files
+- [ ] `suggest_fix` for .NET (NuGet)
 - [ ] 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,279 @@
+/**
+ * 実行履歴の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", "unscannable_nuget_packages",
+    "unresolved_package_references", "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 } : {}),
+    };
+}