osv-scanner-mcp 0.7.0 → 0.8.0

package/README.md

@@ -124,6 +124,7 @@ npm run build
 | `OSV_MCP_MAX_CONCURRENT_SCANS` | 同時実行できるスキャン数の上限(デフォルト `2`、最大 `16`)。超過したリクエストは待たずに即時エラーになります |
 | `OSV_MCP_AUTO_DOWNLOAD` | `0` または `false` でバイナリの自動ダウンロードを無効化(デフォルト有効) |
 | `OSV_MCP_PREFER_DOWNLOAD` | `1` または `true` 指定時、PATH上のosv-scannerを使わず、チェックサム検証済みの自動ダウンロードバイナリを常に使用します(PATH汚染による偽バイナリ実行の防止。`OSV_SCANNER_PATH` の明示指定は引き続き最優先) |
+| `OSV_MCP_NO_CANDIDATE_CHECK` | `1` または `true` 指定時、`suggest_fix` の推奨先のOSV照会を行いません(応答の `candidate_check` は `disabled`。推奨先に、現在の版には該当しない既知の脆弱性がないことは確認されません) |
 | `OSV_MCP_NO_REMOTE_RESOLUTION` | `1` または `true` 指定時、`pom.xml` と `requirements.txt` の推移的依存を deps.dev で解決しません。**止まるのは deps.dev への送信だけで、脆弱性照会のためパッケージの名前とバージョンは引き続き `api.osv.dev` に送られます**。推移的依存の脆弱性は検出できなくなり、その旨が応答の `dependency_resolution.warning` に示されます。詳細は[通信先とプライバシー](#通信先とプライバシー) |
 
 > **推奨**: `OSV_MCP_ALLOWED_ROOT` は未設定でも動作しますが、その場合は任意の絶対パスをスキャンできてしまいます。悪意ある指示(プロンプトインジェクション)経由で意図しないディレクトリをスキャンさせられる経路を塞ぐため、プロジェクト置き場のルート(例: `~/projects`)を設定しておくことを推奨します。各クライアントの設定で `"env": {"OSV_MCP_ALLOWED_ROOT": "/Users/you/projects"}` のように渡せます(Codex CLIのTOMLでは `[mcp_servers.osv-scanner.env]` セクション)。
@@ -145,6 +146,7 @@ osv-scanner v2.4.0 で接続先を実機確認した結果です(2026-10-07)。
 | `requirements.txt` のスキャン(`scan_project` / `suggest_fix`) | `api.osv.dev`、**`api.deps.dev`** | `pom.xml` と同じく、推移的依存の解決のため記載された依存の名前とバージョンが deps.dev に送られます。`--index-url` 等に書かれた取得先へは接続しません |
 | lockfileのスキャン(`gradle.lockfile`、`package-lock.json` 等のnpm系、`poetry.lock` 等のPython系、`go.mod`) | `api.osv.dev` | パッケージの名前とバージョン(lockfileに全依存が記載済みのため、解決のための外部接続はしません) |
 | `scan_java_artifact` / `scan_sbom` | `api.osv.dev` | 同定できたパッケージの名前とバージョン |
+| `suggest_fix` の推奨先の照会 | `api.osv.dev` | 推奨を出したパッケージの名前(スキャンで照会済みのもの)と、推奨候補の版(公開されている修正版)。`OSV_MCP_NO_CANDIDATE_CHECK=1` で無効化できます |
 | `explain_vulnerability` | `api.osv.dev` | 指定した脆弱性ID |
 | バイナリの自動ダウンロード(初回のみ) | GitHub(公式Releases) | なし(ピン留めしたバージョンのバイナリを取得) |
 
@@ -326,7 +328,7 @@ OSV-Scanner 2.4.0の `java/archive` プラグインを使用し、ネストJAR
 - **対応形式**: UTF-8 JSONのCycloneDX 1.4 / 1.5 / 1.6、SPDX 2.2 / 2.3。XML、SPDX tag-value、SPDX 3は未対応です。
 - **入力**: 16MiB以下のローカル通常ファイルの絶対パス。ファイル名は任意で、内容から形式を判別します。CycloneDXは`components`、SPDXは`packages`配列が必要です。形式・主要構造の確認であり、仕様全体のJSON Schema検証ではありません。
 - **識別情報**: CycloneDXの`components[].purl`、SPDXの`packages[].externalRefs`にバージョン付きPackage URLを含めてください。例: `pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1`。詳細は[OSV-Scanner公式ドキュメント](https://github.com/google/osv-scanner/blob/main/docs/scan-source.md)を参照してください。
-- **安全な読み込み**: 許可ルートと読み込み中のサイズ上限を確認し、権限制限付きの一時コピーだけをスキャンします。元ファイルは変更せず、一時コピーは成功・失敗ともに削除します。
+- **安全な読み込み**: 許可ルートと読み込み中のサイズ上限を確認し、権限制限付きの一時コピーだけをスキャンします。元ファイルは変更せず、一時コピーは成功・失敗ともに削除します。スキャン中にサーバーが終了した場合(SIGTERM/SIGINT/SIGHUP、MCPクライアントがstdinを閉じた場合)も、一時コピーを削除し実行中のOSV-Scannerを止めてから終了します。
 
 出力の先頭に`coverage`を返します。
 
@@ -386,6 +388,15 @@ npm・Go・PyPIの「同じ系統」は、npmの `^`(キャレット)が互換
 - 推奨時は `verification: "verified"`、CVEごとの `recommended_status` は `affected` / `not_affected` / `unknown` です。推奨保留時は `not_evaluated` になります。`per_cve_detail.fixed_in` は各CVE単独の候補であり、最終推奨先の判定は `recommended_status` を参照してください。
 - 現在より新しい修正版候補がないCVEは `tier: "unfixed"` として推奨の修正対象から除外します(情報欠落を含む場合があります)。除外したCVEも推奨先で判定し、その状態を表示します。全CVEがunfixedの場合も `recommended_upgrade` は `null` です。修正版の記載はあるがバージョンとして解釈できないCVE(SemVerでない `13.0` 等)は `tier: "unparseable_fix"` とし、修正版が無いとは扱わず修正対象に残すため、推奨は保留(`no_verified_candidate`)になります。
 - npm・Go・PyPIの提案には更新方法の `update_hint` を付けます。PyPIでは、requirements.txtやpyproject.toml・Pipfileの指定を更新してlockfileを再生成し、推移的依存はpipの制約ファイル(`-c`)やuv・Poetryの上書き設定で版を指定します。推移的依存の場合、npmでは要求している直接依存の更新か、ルートの `package.json` の `overrides`(ルートのプロジェクトでのみ有効)で版を指定します。Goでは `go get <module>@<version>` で更新できます。Goのv2以上のメジャーは別のモジュールパス(`/v2` 等)としてOSV上も別パッケージになるため、新しいメジャー系列の修正版は候補に含まれません。現在の版が疑似バージョン(タグのないコミット)の場合は `upgrade_note` に示します。
+- **推奨先のOSV照会**: 推奨はスキャンで分かった脆弱性(現在の版に該当するもの)の範囲だけで検証しているため、推奨先に現在の版には該当しない新しい脆弱性がありえます(例: cryptography 3.2 の推奨候補 49.0.0 は、44.0.0 で混入し 50.0.0 で修正された2件に該当)。そこで推奨先を `api.osv.dev` に照会し、該当する脆弱性があれば、それも避けるよう修正版を候補に加えて選び直します(この例では 50.0.0 を推奨し、`upgrade_note` に理由を示します)。結果は `candidate_check` に示します:
+  - `clean`: 推奨先に該当する既知の脆弱性はありません
+  - `has_known_vulnerabilities`: 避けられる修正版の候補が見つからず、推奨先が既知の脆弱性に該当します(`recommended_known_vulnerabilities` にID)
+  - `conflict`: OSVが、スキャンした脆弱性に候補が該当すると返しました(手元の範囲情報との食い違い)。他に候補がないため推奨を保留します(`recommended_upgrade: null`、`verification: "no_verified_candidate"`)
+  - `failed`: 照会に失敗したか、応答の形式が不正でした(推奨はスキャンした脆弱性に対して検証済みのまま返します)
+  - `skipped`: 照会回数の上限(1パッケージ4回、1回の呼び出しで合計60回)のため照会していません
+  - `disabled`: `OSV_MCP_NO_CANDIDATE_CHECK=1` で無効化されています
+  
+  照会するのは推奨を出したパッケージだけで、送るのはスキャンで既に照会したパッケージの名前と、推奨候補の版です。OSVの判定が手元の範囲情報と食い違う候補(スキャンした脆弱性に該当と返る候補)は推奨しません。不正な応答(オブジェクトでない応答・レコード、文字列でないページトークン)は「該当なし」とは扱わず失敗とします。照会で見つかった脆弱性は現在の版の脆弱性ではないため、`per_cve_detail` には含めません。
 - 各提案には `scan_project` と同じ `dependency_relation`(と `introduced_by` / `declared_in` / `replaced_in_go_mod`)を付け、`update_hint` を直接/推移的依存の別に応じて具体化します(npmの推移的依存なら `introduced_by` の直接依存の更新と `overrides`、Goの `replace` ならreplaceの版の更新、等)。`unknown` / `mixed` の場合は両方の場合を案内します。
 - requirements.txtの `>=X` / `~=X` の行は、OSV-Scannerが下限Xを使用中の版とみなしてスキャンしています。この依存の提案には `version_is_lower_bound: true` を付け、推奨は「下限を推奨版以上に引き上げる」意味であること(実際にインストールされる版とは異なりうること)を `upgrade_note` に示します。
 - 推奨に未対応のエコシステム(SBOM由来のRubyGems等)は `verification: "unsupported_ecosystem"`、現在の版をバージョンとして解釈できない場合(npmのgit・ローカルパス依存等)は `verification: "unparseable_version"` を返し、どちらもCVEごとの `tier: "unsupported"` として `unfixed` には数えません(修正版の有無は判定していないため。修正版は `scan_project` の `fixed_versions` や `explain_vulnerability` で確認できます)。
@@ -446,7 +457,7 @@ npm・Go・PyPIの「同じ系統」は、npmの `^`(キャレット)が互換
 
 - **サプライチェーン対策**: バイナリの自動ダウンロードは公式GitHub Releasesに限定し、バージョンをピン留め。**パッケージに埋め込まれたSHA256チェックサム**で検証します(配布元のSHA256SUMSファイルは信用しないため、リリース側が改ざんされても検出可能)。検証合格まで実行権限を与えず、キャッシュ済みバイナリも使用のたびに再検証します。`OSV_MCP_PREFER_DOWNLOAD=1` でPATH上の未検証バイナリを使わない運用も選べます
 - **コマンドインジェクション対策**: シェルを経由しない `spawn` + 引数配列で実行。OSV-Scannerへの引数は固定リストのみで、可変部は検証済み絶対パス1つだけ
-- **スナップショット方式(検査と読み込みの不一致の防止)**: OSV-Scannerには元のファイルを一切渡しません。lockfile・`pom.xml`(親POMの連鎖を含む)・JAR/WARは、本サーバーが安全に1回だけ読んだ内容を専用の一時ディレクトリ(所有者のみアクセス可、終了時に削除)へコピーしてスキャンし、検査もそのコピーに対して行います。検査の後で元のファイルやディレクトリを差し替えても結果には影響しません。親POMは元の配置を一時ディレクトリ内に再現してコピーするため、OSV-Scannerが相対パスで親をたどっても、見つかるのは検証してコピーしたファイルだけです(`..` を重ねて一時ディレクトリの外に届く参照は除外)。読み込みは末尾のシンボリックリンクをたどらず、名前付きパイプ等の通常のファイル以外は読まず(処理が止まらない)、読み終えた後にパスを解決し直して境界の内側かつ開いた実体と同じファイルかを確認します。コピーの合計サイズは2GiBまでです(超えると `scan_input_too_large`)
+- **スナップショット方式(検査と読み込みの不一致の防止)**: OSV-Scannerには元のファイルを一切渡しません。lockfile・`pom.xml`(親POMの連鎖を含む)・JAR/WARは、本サーバーが安全に1回だけ読んだ内容を専用の一時ディレクトリ(所有者のみアクセス可、終了時に削除)へコピーしてスキャンし、検査もそのコピーに対して行います。検査の後で元のファイルやディレクトリを差し替えても結果には影響しません。親POMは元の配置を一時ディレクトリ内に再現してコピーするため、OSV-Scannerが相対パスで親をたどっても、見つかるのは検証してコピーしたファイルだけです(`..` を重ねて一時ディレクトリの外に届く参照は除外)。読み込みは末尾のシンボリックリンクをたどらず、名前付きパイプ等の通常のファイル以外は読まず(処理が止まらない)、読み終えた後にパスを解決し直して境界の内側かつ開いた実体と同じファイルかを確認します。コピーの合計サイズは2GiBまでです(超えると `scan_input_too_large`)。SIGKILL等の捕捉できない終了で残った一時ディレクトリは、次回以降の起動時に削除します(名前が本サーバーの接頭辞に完全一致し、自分が所有する実体のディレクトリで、最終更新から24時間以上経過したものだけ。シンボリックリンクはたどりません)
 - **パストラバーサル対策**: 入力パスは `realpath` でシンボリックリンク解決後に境界チェック。pom.xml探索ではシンボリックリンクを辿りません。OSV-Scannerにはディレクトリを渡さず、検出したマニフェストだけを形式を明示して個別に渡します(ディレクトリを渡すと、OSV-Scannerが同じディレクトリの `requirements.txt` も読み、その取り込み指定 `-r ../x.txt` でスキャン範囲の外のファイルを読むため)。`scan_project` でrequirements.txtをスキャンする場合は元ファイルを渡さず、解釈できた依存の行だけを正規化して書いた専用コピーをスキャンします。コピーには取り込み指定を含めないため、OSV-Scannerの取り込みの解釈と本サーバーの解析がずれても、範囲外のファイルは読まれません。`pom.xml` の親POMの連鎖が `OSV_MCP_ALLOWED_ROOT` の外を参照する場合は、その `pom.xml` をスキャン対象から外します([親POMの扱い](#親pomの扱い))
 - **DoS対策**: タイムアウト・stdout上限・stderr抜粋上限を設定。スキャン結果は防御的にパースし、形式不正でも例外を投げません。同時実行スキャン数も上限(デフォルト2)を設け、並列リクエストによるプロセスの無制限起動を防ぎます。本サーバー自身の解析も、同じファイルは1回だけ読んで結果を使い回し(workspaceの収録確認でのlockfile、requirements.txtの共通の取り込み先、親POM)、読む量の合計に上限を設けます
 - **fail-closedな運用モード**: `OSV_MCP_REQUIRE_ALLOWED_ROOT=1` で、スキャン許可ルート未設定時にサーバーの起動自体を拒否できます

package/dist/index.js

@@ -10,6 +10,7 @@
  * - OSV_MCP_AUTO_DOWNLOAD: 0/false指定時、バイナリの自動ダウンロードを無効化
  * - 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照会を行わない
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -20,6 +21,7 @@ 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 { installShutdownHandlers, removeStaleTempDirs } from "./utils/processCleanup.js";
 import { ALLOWED_ROOT_ENV, allowedRootFromEnv, allowedRootStartupError, allowedRootStartupWarning, } from "./utils/startupConfig.js";
 export { ALLOWED_ROOT_ENV };
 // fail-closed: 運用モードで許可ルートが未設定なら、ツールを一切公開せず終了する
@@ -36,7 +38,7 @@ if (startupWarning !== null) {
 // NOTE: リリース時はpackage.jsonのversionと同じ値に更新すること
 const server = new McpServer({
     name: "osv-scanner-mcp",
-    version: "0.7.0",
+    version: "0.8.0",
 });
 server.registerTool("scan_project", {
     title: "プロジェクトの依存の脆弱性スキャン(Java / JavaScript / Python / Go)",
@@ -73,7 +75,7 @@ server.registerTool("suggest_fix", {
         "推奨はJava(Maven / Gradle)・JavaScript(npm)・Python(PyPI)・Goに対応。" +
         "現在のバージョンに最も近いリリース系統の修正版を優先する3段階フォールバック" +
         "(same_minor: 同一系統内 → major_internal: 同一メジャー内 → cross_major: メジャーアップグレード)で選定し、" +
-        "推奨バージョン・アップグレード距離(upgrade_tier)・CVEごとの修正版を返す。npm・Go・PyPIでは0.x系のマイナー更新もcross_major(破壊的変更の可能性)。requirements.txtの下限(>=)でスキャンした依存はversion_is_lower_boundを付け、推奨は下限の引き上げを意味する。直接/推移的依存の別(dependency_relation、npmはintroduced_by・declared_in)に応じて更新方法(update_hint)を示す。" +
+        "推奨バージョン・アップグレード距離(upgrade_tier)・CVEごとの修正版を返す。npm・Go・PyPIでは0.x系のマイナー更新もcross_major(破壊的変更の可能性)。requirements.txtの下限(>=)でスキャンした依存はversion_is_lower_boundを付け、推奨は下限の引き上げを意味する。直接/推移的依存の別(dependency_relation、npmはintroduced_by・declared_in)に応じて更新方法(update_hint)を示す。推奨先はapi.osv.devに照会し、現在の版には該当しない既知の脆弱性があれば避けて選び直す(結果はcandidate_check。has_known_vulnerabilities・failed・skippedの場合は推奨先の安全性が確認できていない。conflictは判定の食い違いで推奨を保留)。" +
         "候補を全修正対象CVEの影響範囲と照合し、情報不足の場合は推奨を保留する。プレリリース版は正式版で解消できない場合だけ推奨し、recommended_is_prereleaseを付ける。" +
         "現在より新しい修正版候補のないCVEはunfixedとして別表示し、推奨先での判定も返す。" +
         "応答のcoverageを必ず確認すること(complete=falseなら提案に含まれない依存がある)。" +
@@ -116,6 +118,13 @@ server.registerTool("scan_sbom", {
         sbom_path: z.string().min(1).describe("CycloneDX/SPDX JSON SBOMファイルの絶対パス"),
     },
 }, async ({ sbom_path }) => handleScanSbom({ sbom_path }, { allowedRoot: allowedRootFromEnv() }));
+// シグナル・stdinの終了時に一時ディレクトリと実行中のosv-scannerを片付ける(接続前に登録する)
+installShutdownHandlers();
+// 前回の異常終了で残った一時ディレクトリの掃除。起動を遅らせないよう待たない
+removeStaleTempDirs().then((removed) => {
+    if (removed > 0)
+        console.error(`osv-scanner-mcp: 前回の終了時に残った一時ディレクトリを${removed}件削除しました`);
+}, () => { });
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // stdoutはMCPプロトコル専用のため、起動ログはstderrへ

package/dist/osv/candidateCheck.js

@@ -0,0 +1,165 @@
+/**
+ * 推奨先のOSV照会(docs/DESIGN_TODO.md「推奨先のOSV照会(v0.8.0候補)詳細設計メモ」)。
+ *
+ * suggest_fixの推奨は、スキャンで分かった脆弱性(現在の版に該当するもの)の影響範囲だけで検証している。
+ * 推奨先に、現在の版には該当しない新しい脆弱性があっても分からない(実例: cryptography 3.2の推奨49.0.0は、
+ * 44.0.0で混入し50.0.0で修正された2件に該当)。推奨先をapi.osv.devに照会し、該当する脆弱性があれば、
+ * それも避けるよう候補を選び直す。
+ *
+ * - 送るのはスキャンで既に照会したパッケージの名前と、公開されている修正版の版だけ(送信先もスキャンと同じ)
+ * - 照会に失敗しても推奨は出す(スキャンした脆弱性に対する検証は済んでいる)。ツール全体をエラーにしない
+ * - 照会の回数・同時実行数に上限を設ける
+ */
+import { ScanToolError } from "../errors.js";
+import { asString, asStrings } from "../utils/unknownJson.js";
+import { sanitizeExternalText } from "../utils/externalText.js";
+import { extractAffectedVersions } from "./affectedVersions.js";
+import { queryOsvPackageVersion } from "./osvApi.js";
+import { extractFixedVersions } from "./scanReport.js";
+import { suggestUpgradeForPackage } from "./suggestFix.js";
+export const NO_CANDIDATE_CHECK_ENV = "OSV_MCP_NO_CANDIDATE_CHECK";
+/** 環境変数で無効化されているか(1/true/yes) */
+export function candidateCheckDisabledFromEnv(env = process.env) {
+    const value = env[NO_CANDIDATE_CHECK_ENV]?.trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes";
+}
+/** OSVレコードのIDと別名 */
+function recordIds(record) {
+    const id = asString(record.id);
+    return [...(id !== null ? [id] : []), ...asStrings(record.aliases)];
+}
+/** 照会の合計回数の残り(パッケージをまたいで共有する) */
+class QueryBudget {
+    remaining;
+    constructor(remaining) {
+        this.remaining = remaining;
+    }
+    take() {
+        if (this.remaining <= 0)
+            return false;
+        this.remaining--;
+        return true;
+    }
+}
+async function checkPackage(pkg, initial, budget, options) {
+    const known = new Set(pkg.vulnerabilities.flatMap((v) => [v.id, ...v.aliases]));
+    const extraTargets = [];
+    const excluded = new Set();
+    const rejected = [];
+    let suggestion = initial;
+    const maxQueries = options.maxQueriesPerPackage ?? 4;
+    for (let query = 0; query < maxQueries; query++) {
+        const candidate = suggestion.recommended_upgrade;
+        if (!budget.take())
+            return { suggestion, status: "skipped", rejected };
+        let records;
+        try {
+            // queryOsvPackageVersionが各レコードをオブジェクトと検証済み(不正な応答は失敗になる)
+            records = (await queryOsvPackageVersion(pkg.ecosystem, pkg.name, candidate, options));
+        }
+        catch (error) {
+            if (error instanceof ScanToolError)
+                return { suggestion, status: "failed", rejected };
+            throw error;
+        }
+        if (records.length === 0)
+            return { suggestion, status: "clean", rejected };
+        // 新しい脆弱性は修正対象に加え、修正版を候補に加える。スキャンで既に知っている脆弱性なのに該当と返った場合は、
+        // 手元の範囲情報とOSVの判定が食い違っているため、その候補を除外する(安全側)
+        let conflict = false;
+        for (const record of records) {
+            const ids = recordIds(record);
+            if (ids.some((id) => known.has(id))) {
+                excluded.add(candidate);
+                conflict = true;
+                continue;
+            }
+            for (const id of ids)
+                known.add(id);
+            extraTargets.push({
+                fixed_versions: extractFixedVersions([record], pkg.name, pkg.ecosystem),
+                affected_versions: extractAffectedVersions([record], ids.slice(0, 1), pkg.name, pkg.ecosystem),
+            });
+        }
+        rejected.push({ version: candidate, count: records.length });
+        const next = suggestUpgradeForPackage(pkg, { extraTargets, excluded });
+        if (next.recommended_upgrade === null) {
+            rejected.pop();
+            const knownVulnerabilities = records.map((record) => asString(record.id)).filter((id) => id !== null);
+            // 判定の食い違い: その候補はスキャンした脆弱性の範囲外とは言えないため、推奨しない(保留する)
+            if (conflict)
+                return { suggestion: withheld(suggestion, candidate), status: "conflict", knownVulnerabilities, rejected };
+            // 新しい脆弱性に修正版がない等で選び直せない: 最後に照会した推奨を、該当する脆弱性とともに返す
+            return { suggestion, status: "has_known_vulnerabilities", knownVulnerabilities, rejected };
+        }
+        suggestion = next;
+    }
+    // 1パッケージの照会回数の上限: 最後に選び直した推奨は照会していない
+    return { suggestion, status: "skipped", rejected };
+}
+/** 推奨を保留した提案(推奨先・Tier・推奨先での判定を外し、verificationをno_verified_candidateにする) */
+function withheld(suggestion, candidate) {
+    const { recommended_is_prerelease: _prerelease, ...rest } = suggestion;
+    return {
+        ...rest,
+        recommended_upgrade: null,
+        upgrade_tier: null,
+        upgrade_note: `候補${candidate}は、スキャンした脆弱性の範囲外と判定しましたが、OSVはその脆弱性に該当すると返しました(範囲情報の食い違い)。` +
+            "安全と確認できる候補がないため推奨を保留します",
+        per_cve_detail: suggestion.per_cve_detail.map((detail) => ({ ...detail, recommended_status: "not_evaluated" })),
+        verification: "no_verified_candidate",
+    };
+}
+function applyResult(result) {
+    const { suggestion, status, knownVulnerabilities, rejected } = result;
+    const notes = [];
+    if (rejected.length > 0) {
+        const found = rejected.map((r) => `${r.version}は${r.count}件の既知の脆弱性に該当`).join("、");
+        notes.push(suggestion.recommended_upgrade !== null
+            ? `推奨先をOSVに照会し、${found}するため、${suggestion.recommended_upgrade}を推奨しています(現在の版には該当しない脆弱性を含む)`
+            : `推奨先をOSVに照会し、${found}するため候補から外しました`);
+    }
+    if (status === "conflict") {
+        // 理由はwithheldの注記に含めた。推奨しかけた版で該当と返った脆弱性はrecommended_known_vulnerabilitiesではなく注記に示す
+        notes.push(`OSVが該当と返した脆弱性: ${knownVulnerabilities.join("、")}`);
+    }
+    else if (status === "has_known_vulnerabilities") {
+        notes.push(`推奨先の${suggestion.recommended_upgrade}は、OSVで${knownVulnerabilities.length}件の既知の脆弱性(recommended_known_vulnerabilities)に該当します。` +
+            "これらを避けられる修正版の候補が見つかりませんでした");
+    }
+    else if (status === "failed") {
+        notes.push("推奨先のOSV照会に失敗したため、推奨先に現在の版には該当しない既知の脆弱性がないことは確認できていません");
+    }
+    else if (status === "skipped") {
+        notes.push("照会回数の上限のため、推奨先のOSV照会を行っていません(推奨先の既知の脆弱性は未確認)");
+    }
+    const { per_cve_detail, verification, ...rest } = suggestion;
+    return {
+        ...rest,
+        upgrade_note: [suggestion.upgrade_note, ...notes].join("。"),
+        candidate_check: status,
+        ...(status === "has_known_vulnerabilities" ? { recommended_known_vulnerabilities: knownVulnerabilities.map(sanitizeExternalText) } : {}),
+        per_cve_detail,
+        verification,
+    };
+}
+/**
+ * 推奨を出したパッケージの推奨先をOSVに照会し、必要なら選び直す。
+ * suggestionsはpackagesと同じ順(suggestUpgradesの結果)であること。推奨のないものはそのまま返す。
+ */
+export async function checkRecommendedCandidates(packages, suggestions, options = {}) {
+    if (options === "disabled") {
+        return suggestions.map((s) => (s.recommended_upgrade === null ? s : { ...s, candidate_check: "disabled" }));
+    }
+    const budget = new QueryBudget(options.maxQueriesTotal ?? 60);
+    const results = [...suggestions];
+    const pending = suggestions.flatMap((s, i) => (s.recommended_upgrade === null ? [] : [i]));
+    // 同時実行数を制限して順に処理する(順番は結果に影響しない。予算はパッケージの順に消費されやすい)
+    const workers = Array.from({ length: Math.max(1, options.concurrency ?? 4) }, async () => {
+        for (let index = pending.shift(); index !== undefined; index = pending.shift()) {
+            results[index] = applyResult(await checkPackage(packages[index], suggestions[index], budget, options));
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/dist/osv/osvApi.js

@@ -74,3 +74,77 @@ export async function fetchOsvRecord(id, options = {}) {
         throw new ScanToolError("api_request_failed", "OSV APIのレスポンスをJSONとして解釈できませんでした");
     }
 }
+/** queryOsvPackageVersionでたどる続きのページの上限 */
+const MAX_QUERY_PAGES = 5;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function malformed() {
+    return new ScanToolError("api_request_failed", "OSV APIのレスポンスの形式が想定と異なります");
+}
+async function readJsonBody(response, maxBytes) {
+    let body;
+    try {
+        const bytes = await readResponseBytes(response, maxBytes, new ScanToolError("output_too_large", `OSV APIのレスポンスがサイズ上限(${maxBytes}バイト)を超えました`));
+        body = new TextDecoder().decode(bytes);
+    }
+    catch (error) {
+        if (error instanceof ScanToolError)
+            throw error;
+        throw new ScanToolError("api_request_failed", "OSV APIのレスポンス本文を受信できませんでした");
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new ScanToolError("api_request_failed", "OSV APIのレスポンスをJSONとして解釈できませんでした");
+    }
+}
+/**
+ * パッケージの版に該当する脆弱性のレコードを取得する(`POST /v1/query`)。
+ * suggest_fixの推奨先の照会に使う。送るのはスキャンで既に照会した名前と、公開されている修正版の版だけ。
+ * 続きのページ(`next_page_token`)は上限までたどり、超えたら失敗とする(一部だけで「該当なし」と判断しない)。
+ *
+ * @returns 脆弱性レコードの配列(形式不明な外部データとして扱うこと)
+ */
+export async function queryOsvPackageVersion(ecosystem, name, version, options = {}) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const url = `${options.baseUrl ?? DEFAULT_BASE_URL}/v1/query`;
+    const vulns = [];
+    let pageToken;
+    for (let page = 0; page < MAX_QUERY_PAGES; page++) {
+        let response;
+        try {
+            response = await fetchFn(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ package: { name, ecosystem }, version, ...(pageToken !== undefined ? { page_token: pageToken } : {}) }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            const isTimeout = error instanceof Error && error.name === "TimeoutError";
+            throw new ScanToolError("api_request_failed", isTimeout
+                ? `OSV APIへのリクエストが${Math.round(timeoutMs / 1000)}秒以内に完了しませんでした`
+                : "OSV APIへの接続に失敗しました(ネットワークを確認してください)");
+        }
+        if (!response.ok) {
+            throw new ScanToolError("api_request_failed", `OSV APIがエラーを返しました(HTTP ${response.status})`);
+        }
+        // 不正な応答を「該当なし」と読まない: ルート・各レコード・ページトークンの型を検証し、違えば失敗とする
+        const body = await readJsonBody(response, maxBytes);
+        if (!isPlainObject(body))
+            throw malformed();
+        if (body.vulns !== undefined && (!Array.isArray(body.vulns) || !body.vulns.every(isPlainObject)))
+            throw malformed();
+        if (body.next_page_token !== undefined && typeof body.next_page_token !== "string")
+            throw malformed();
+        vulns.push(...(body.vulns ?? []));
+        if (body.next_page_token === undefined || body.next_page_token === "")
+            return vulns;
+        pageToken = body.next_page_token;
+    }
+    throw new ScanToolError("api_request_failed", `OSV APIの応答が${MAX_QUERY_PAGES}ページを超えました`);
+}

package/dist/osv/runner.js

@@ -10,6 +10,7 @@
  *   requirements.txt等も読み、その`-r ../x.txt`の取り込みでスキャン範囲の外のファイルを読むため
  * - SBOMは検証・サイズ制限済みの専用一時コピー1つだけを渡す
  * - タイムアウトと出力サイズ上限を設ける(ハング・巨大出力によるDoS対策)
+ * - サーバーの終了時に実行中のプロセスを残さない(processCleanup.tsに登録し、終了時にSIGKILL)
  *
  * 終了コード(2.4.0で実機確認):
  *   0 = スキャン成功・脆弱性なし / 1 = スキャン成功・脆弱性あり / 128 = 対象パッケージなし
@@ -18,6 +19,7 @@ import { spawn } from "node:child_process";
 import path from "node:path";
 import { ScanToolError } from "../errors.js";
 import { isManifestFormat } from "../utils/manifestFormats.js";
+import { trackChildProcess } from "../utils/processCleanup.js";
 import { resolveOsvScannerBinary } from "./binaryManager.js";
 import { parseOsvScanOutput } from "./scanReport.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -96,6 +98,7 @@ function execOsvScanner(binaryPath, targetPaths, timeoutMs, maxOutputBytes, scan
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
         });
+        trackChildProcess(child);
         const stdoutChunks = [];
         const stderrChunks = [];
         let stdoutBytes = 0;

package/dist/osv/scanReport.js

@@ -68,7 +68,7 @@ function extractSummary(vulnDetails) {
  * 範囲の型はエコシステム別(versionScheme.ts)。GIT型のコミットハッシュは集めない。
  * v0.4.1以前はMavenだけを集めていたため、npm・Go・PyPI等で常に空になっていた。
  */
-function extractFixedVersions(vulnDetails, packageName, ecosystem) {
+export function extractFixedVersions(vulnDetails, packageName, ecosystem) {
     const versions = new Set();
     const rangeTypes = versionRangeTypes(ecosystem);
     for (const detail of vulnDetails) {

package/dist/osv/suggestFix.js

@@ -164,8 +164,11 @@ function buildNote(scheme, pkg, recommended, tier, fixableCount, unfixedCount) {
     }
     return note;
 }
-/** 1パッケージ分のアップグレード提案を組み立てる。 */
-export function suggestUpgradeForPackage(pkg) {
+/**
+ * 1パッケージ分のアップグレード提案を組み立てる(同期・純粋)。
+ * contextを渡すと、照会で見つかった脆弱性も避けて候補を選び直す(contextなしの結果が従来の推奨)。
+ */
+export function suggestUpgradeForPackage(pkg, context = {}) {
     const scheme = versionSchemeFor(pkg.ecosystem);
     if (scheme === null)
         return notEvaluatedSuggestion(pkg, "unsupported_ecosystem");
@@ -186,9 +189,13 @@ export function suggestUpgradeForPackage(pkg) {
     const unparseableCount = details.filter((d) => d.tier === "unparseable_fix").length;
     const fixableCount = details.length - unfixedCount;
     // 解釈できない修正版のCVEも修正対象に残す。その影響範囲は情報不足のため、どの候補も検証できず推奨を保留する
-    const targets = pkg.vulnerabilities.filter((_, i) => details[i].tier !== "unfixed");
+    const targets = [
+        ...pkg.vulnerabilities.filter((_, i) => details[i].tier !== "unfixed"),
+        ...(context.extraTargets ?? []),
+    ];
     const candidates = rankCandidates(scheme, pkg.version, targets.flatMap((v) => v.fixed_versions));
-    const recommended = candidates.find((v) => targets.every((target) => candidateStatus(target.affected_versions, v, pkg.ecosystem) === "not_affected")) ?? null;
+    const recommended = candidates.find((v) => !context.excluded?.has(v) &&
+        targets.every((target) => candidateStatus(target.affected_versions, v, pkg.ecosystem) === "not_affected")) ?? null;
     for (let i = 0; i < details.length; i++) {
         details[i].recommended_status = recommended === null ? "not_evaluated" :
             candidateStatus(pkg.vulnerabilities[i].affected_versions, recommended, pkg.ecosystem);
@@ -214,5 +221,5 @@ export function suggestUpgradeForPackage(pkg) {
 }
 /** スキャンレポート全体からパッケージごとの提案一覧を作る(深刻度順を維持)。 */
 export function suggestUpgrades(packages) {
-    return packages.map(suggestUpgradeForPackage);
+    return packages.map((pkg) => suggestUpgradeForPackage(pkg));
 }

package/dist/tools/scanSbom.js

@@ -3,12 +3,15 @@ import os from "node:os";
 import path from "node:path";
 import { runOsvSbomScan } from "../osv/runner.js";
 import { buildSbomReport } from "../osv/sbomReport.js";
+import { SBOM_DIR_PREFIX, trackTempDir } from "../utils/processCleanup.js";
 import { loadSbom } from "../utils/sbomInput.js";
 import { errorResult, jsonResult } from "./toolResult.js";
 export async function handleScanSbom(args, options = {}) {
     try {
         const input = await loadSbom(args.sbom_path, options);
-        const dir = await mkdtemp(path.join(await realpath(os.tmpdir()), "osv-mcp-sbom-"));
+        const dir = await mkdtemp(path.join(await realpath(os.tmpdir()), SBOM_DIR_PREFIX));
+        // シグナル等で終了しても残さない(processCleanup.ts)
+        const untrack = trackTempDir(dir);
         try {
             // A fixed filename selects the native parser, irrespective of the user's filename.
             const snapshotPath = path.join(dir, input.format === "CycloneDX" ? "input.cdx.json" : "input.spdx.json");
@@ -18,6 +21,7 @@ export async function handleScanSbom(args, options = {}) {
         }
         finally {
             await rm(dir, { recursive: true, force: true });
+            untrack();
         }
     }
     catch (error) {

package/dist/tools/suggestFix.js

@@ -5,6 +5,7 @@
  * それ以外はunsupported_ecosystemとして返す。
  */
 import { isRemoteResolutionDisabled } from "../osv/runner.js";
+import { candidateCheckDisabledFromEnv, checkRecommendedCandidates } from "../osv/candidateCheck.js";
 import { suggestUpgrades } from "../osv/suggestFix.js";
 import { sanitizeExternalText } from "../utils/externalText.js";
 import { detectProject } from "../utils/manifestDetector.js";
@@ -16,7 +17,9 @@ export async function handleSuggestFix(args, options = {}) {
         const project = await detectProject(args.project_path, { allowedRoot: options.allowedRoot });
         const noRemoteResolution = isRemoteResolutionDisabled(options);
         const report = await scanFromSnapshot(project, { ...options, noRemoteResolution });
-        const suggestions = suggestUpgrades(markLowerBounds(project, report.packages));
+        const packages = markLowerBounds(project, report.packages);
+        const candidateCheck = options.candidateCheck ?? (candidateCheckDisabledFromEnv() ? "disabled" : {});
+        const suggestions = await checkRecommendedCandidates(packages, suggestUpgrades(packages), candidateCheck);
         const unfixedVulnerabilities = suggestions.reduce((sum, s) => sum + s.per_cve_detail.filter((d) => d.tier === "unfixed").length, 0);
         return jsonResult({
             project_dir: project.projectDir,

package/dist/utils/processCleanup.js

@@ -0,0 +1,127 @@
+/**
+ * サーバー終了時の後始末: スキャン用の一時ディレクトリ(元のファイルのコピーを含む)と
+ * 実行中のosv-scannerプロセスを、サーバーより長く残さない。
+ *
+ * - 通常はスキャンごとの`finally`で削除するが、SIGTERM等で強制終了されると`finally`は実行されない
+ *   (2026-10-07 実機確認: scan_project中にSIGTERMを送るとosv-mcp-snap-*が残った)
+ * - そのため作成中の一時ディレクトリと子プロセスをここに登録し、シグナル・stdinの終了・
+ *   process.exitの時点で同期的に(fs.rmSync・SIGKILL)片付ける
+ * - 前回の異常終了(SIGKILL・電源断等)で残ったものは、起動時に条件を絞って削除する(removeStaleTempDirs)
+ */
+import { rmSync } from "node:fs";
+import { lstat, readdir, realpath, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/** 本サーバーが作る一時ディレクトリの接頭辞(起動時の掃除はこれに完全一致するものだけを対象にする) */
+export const SNAPSHOT_DIR_PREFIX = "osv-mcp-snap-";
+export const SBOM_DIR_PREFIX = "osv-mcp-sbom-";
+/** mkdtempは接頭辞の後ろに6文字の英数字を付ける */
+const TEMP_DIR_NAME = /^osv-mcp-(?:snap|sbom)-[A-Za-z0-9]{6}$/;
+/**
+ * 起動時に削除する残骸の最終更新からの経過時間。別のサーバープロセス(複数のMCPクライアント等)が
+ * 使用中のディレクトリを消さないよう、スキャンのタイムアウト(既定120秒)より十分長くとる
+ */
+export const STALE_TEMP_DIR_AGE_MS = 24 * 60 * 60 * 1000;
+const tempDirs = new Set();
+const children = new Set();
+/** 一時ディレクトリを登録する。戻り値の関数で登録を外す(通常の削除後に呼ぶ) */
+export function trackTempDir(dir) {
+    tempDirs.add(dir);
+    return () => { tempDirs.delete(dir); };
+}
+/** 子プロセスを登録する。終了(close/error)時に自動で登録を外す */
+export function trackChildProcess(child) {
+    children.add(child);
+    const untrack = () => { children.delete(child); };
+    child.once("close", untrack);
+    child.once("error", untrack);
+}
+/**
+ * 登録済みの子プロセスを強制終了し、一時ディレクトリを同期的に削除する。
+ * シグナルハンドラ・exitイベントから呼ぶため、非同期処理を使わず例外も外に出さない
+ */
+export function cleanupSync() {
+    for (const child of children) {
+        // 終了済みのプロセスにはNode側で送らない(PIDの再利用で別プロセスを止めることはない)
+        try {
+            child.kill("SIGKILL");
+        }
+        catch { /* 後始末は続ける */ }
+    }
+    children.clear();
+    for (const dir of tempDirs) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* 他のディレクトリの削除は続ける */ }
+    }
+    tempDirs.clear();
+}
+/** テスト用: 登録状況 */
+export function trackedCounts() {
+    return { tempDirs: tempDirs.size, children: children.size };
+}
+const SHUTDOWN_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"];
+let installed = false;
+/**
+ * 終了時の後始末を登録する(サーバー起動時に1回だけ呼ぶ)。
+ * - SIGTERM/SIGINT/SIGHUP: 後始末して慣例の終了コード(128+シグナル番号)で終了
+ * - stdinの終了(MCPクライアントがトランスポートを閉じた): 後始末して終了コード0で終了。
+ *   応答の送り先が無いため、実行中のスキャンの完了は待たない
+ * - process.exit・未捕捉例外による終了: exitイベントで後始末する
+ */
+export function installShutdownHandlers(stdin = process.stdin) {
+    if (installed)
+        return;
+    installed = true;
+    let shuttingDown = false;
+    const shutdown = (code) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        cleanupSync();
+        process.exit(code);
+    };
+    for (const signal of SHUTDOWN_SIGNALS) {
+        process.on(signal, () => shutdown(128 + (os.constants.signals[signal] ?? 0)));
+    }
+    stdin.once("end", () => shutdown(0));
+    stdin.once("close", () => shutdown(0));
+    process.on("exit", cleanupSync);
+}
+/**
+ * 前回の異常終了で残った一時ディレクトリを削除し、削除した数を返す。次の条件をすべて満たすものだけが対象:
+ * - 名前が本サーバーの接頭辞+mkdtempの6文字に完全一致する
+ * - シンボリックリンクではなく実体のディレクトリ(lstatで判定し、リンクはたどらない)
+ * - 所有者が現在のユーザー
+ * - 最終更新からSTALE_TEMP_DIR_AGE_MS以上経過している
+ *
+ * 一時ディレクトリは通常スティッキービット付きのため、自分が所有するエントリを他のユーザーが
+ * 判定と削除の間に差し替えることはできない。中のシンボリックリンクはrmがリンク自体を消すだけでたどらない。
+ * getuidの無い環境(Windows)では所有者を確認できないため何もしない
+ */
+export async function removeStaleTempDirs(options = {}) {
+    if (typeof process.getuid !== "function")
+        return 0;
+    const uid = process.getuid();
+    const root = options.tmpRoot ?? (await realpath(os.tmpdir()));
+    const now = options.now ?? Date.now();
+    const maxAgeMs = options.maxAgeMs ?? STALE_TEMP_DIR_AGE_MS;
+    let removed = 0;
+    for (const name of await readdir(root)) {
+        if (!TEMP_DIR_NAME.test(name))
+            continue;
+        const dir = path.join(root, name);
+        try {
+            const stats = await lstat(dir);
+            if (!stats.isDirectory() || stats.uid !== uid || now - stats.mtimeMs < maxAgeMs)
+                continue;
+            await rm(dir, { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            // 消えた・読めないものは対象外(他のディレクトリの掃除は続ける)
+        }
+    }
+    return removed;
+}

package/dist/utils/scanSnapshot.js

@@ -9,12 +9,14 @@
  *   最悪でも親が見つからないだけ)
  * - `..`を重ねた参照でスナップショットの外(本物のファイルシステム)に出る親POMは除外する
  * - コピーの合計サイズに上限を設ける
+ * - サーバーがシグナル等で終了しても残さないよう、作成直後に後始末の対象へ登録する(processCleanup.ts)
  */
 import { mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { ScanToolError } from "../errors.js";
 import { decodePomBytes, parentRelativePath } from "./pomParent.js";
+import { SNAPSHOT_DIR_PREFIX, trackTempDir } from "./processCleanup.js";
 import { isInsideDir } from "./projectWalk.js";
 import { copyRegularFile } from "./safeRead.js";
 const DEFAULT_MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024;
@@ -23,19 +25,22 @@ const MAX_PARENT_DEPTH = 10;
 export class ScanSnapshot {
     dir;
     maxTotalBytes;
+    untrack;
     copied = new Map();
     parentCache = new Map();
     /** 再現した配置のルートごとのディレクトリ → 元のルート("/"等) */
     mirroredRoots = new Map();
     used = 0;
     generated = 0;
-    constructor(dir, maxTotalBytes) {
+    constructor(dir, maxTotalBytes, untrack) {
         this.dir = dir;
         this.maxTotalBytes = maxTotalBytes;
+        this.untrack = untrack;
     }
     static async create(maxTotalBytes = DEFAULT_MAX_TOTAL_BYTES) {
-        const dir = await mkdtemp(path.join(await realpath(os.tmpdir()), "osv-mcp-snap-"));
-        return new ScanSnapshot(dir, maxTotalBytes);
+        const dir = await mkdtemp(path.join(await realpath(os.tmpdir()), SNAPSHOT_DIR_PREFIX));
+        // mkdtempの完了から登録までの間にシグナルの処理は割り込まない(同じ同期処理内で登録する)
+        return new ScanSnapshot(dir, maxTotalBytes, trackTempDir(dir));
     }
     /** 再現した配置のルート(実際のファイルシステムの"/"に相当) */
     get treeRoot() {
@@ -107,6 +112,7 @@ export class ScanSnapshot {
     }
     async cleanup() {
         await rm(this.dir, { recursive: true, force: true });
+        this.untrack();
     }
 }
 const UNPARSEABLE = "親POMの指定を確実に解釈できないため(親要素の重複、CDATA・DOCTYPE、プロパティ参照、UTF-8以外の文字コード等)、" +

package/package.json

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