osv-scanner-mcp 0.1.0

package/dist/osv/binaryManager.js

@@ -0,0 +1,79 @@
+/**
+ * OSV-Scannerバイナリの解決(docs/DESIGN_TODO.md 方式C)。
+ * MVPでは自動ダウンロードは行わず、「存在チェック → なければ案内メッセージ」で対応する。
+ * 探索順: 環境変数 OSV_SCANNER_PATH → PATH上の osv-scanner
+ */
+import { access, constants, stat } from "node:fs/promises";
+import path from "node:path";
+import { ScanToolError } from "../errors.js";
+export const OSV_SCANNER_PATH_ENV = "OSV_SCANNER_PATH";
+const BINARY_NAME = process.platform === "win32" ? "osv-scanner.exe" : "osv-scanner";
+async function isExecutableFile(filePath) {
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile())
+            return false;
+        await access(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** OSV-Scannerバイナリのパスを返す。見つからなければnull。 */
+export async function findOsvScannerBinary(env = process.env) {
+    const explicit = env[OSV_SCANNER_PATH_ENV];
+    if (explicit !== undefined && explicit.trim() !== "") {
+        // 明示指定が無効な場合はPATHにフォールバックせず失敗させる(意図しないバイナリの実行を防ぐ)
+        return (await isExecutableFile(explicit)) ? explicit : null;
+    }
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (dir === "")
+            continue;
+        const candidate = path.join(dir, BINARY_NAME);
+        if (await isExecutableFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** インストール案内メッセージ。バイナリ未検出かつ自動ダウンロード不可のときに返す。 */
+export function installGuidance(env = process.env) {
+    const explicit = env[OSV_SCANNER_PATH_ENV];
+    const envNote = explicit !== undefined && explicit.trim() !== ""
+        ? `環境変数 ${OSV_SCANNER_PATH_ENV}(${explicit})が実行可能ファイルを指していません。パスを確認してください。`
+        : `インストール済みの場合は、環境変数 ${OSV_SCANNER_PATH_ENV} でバイナリのパスを指定することもできます。`;
+    return [
+        "OSV-Scannerが見つかりません。以下のいずれかの方法でインストールしてください:",
+        "  - Homebrew: brew install osv-scanner",
+        "  - Go: go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest",
+        "  - 公式リリース: https://github.com/google/osv-scanner/releases (取得後はチェックサム検証を推奨)",
+        `  - または環境変数 ${AUTO_DOWNLOAD_ENV} の無効化(=0)を解除すると、検証済み公式バイナリを自動ダウンロードします`,
+        envNote,
+    ].join("\n");
+}
+export const AUTO_DOWNLOAD_ENV = "OSV_MCP_AUTO_DOWNLOAD";
+function isAutoDownloadEnabled(env) {
+    const value = env[AUTO_DOWNLOAD_ENV]?.trim().toLowerCase();
+    return value !== "0" && value !== "false";
+}
+/**
+ * バイナリのパスを解決する。
+ * 探索順: OSV_SCANNER_PATH(明示指定時はダウンロードにフォールバックしない)
+ * → PATH → 自動ダウンロード(チェックサム検証付き、OSV_MCP_AUTO_DOWNLOAD=0で無効化)。
+ * どれも不可なら案内メッセージ付きのScanToolErrorを投げる。
+ */
+export async function resolveOsvScannerBinary(env = process.env, options = {}) {
+    const binary = await findOsvScannerBinary(env);
+    if (binary !== null) {
+        return binary;
+    }
+    const explicit = env[OSV_SCANNER_PATH_ENV];
+    const explicitlySpecified = explicit !== undefined && explicit.trim() !== "";
+    // 明示指定が無効な場合は、意図しないバイナリの使用を避けるためダウンロードしない
+    if (!explicitlySpecified && isAutoDownloadEnabled(env)) {
+        const download = options.downloadFn ??
+            (async () => (await import("./binaryDownloader.js")).ensureOsvScannerDownloaded());
+        return download();
+    }
+    throw new ScanToolError("binary_not_found", installGuidance(env));
+}

package/dist/osv/osvApi.js

@@ -0,0 +1,74 @@
+/**
+ * OSVデータベースAPI(api.osv.dev)のクライアント。
+ *
+ * `explain_vulnerability`用に単一の脆弱性レコードを取得する。
+ * セキュリティ考慮:
+ * - 脆弱性IDはURLパス組み立てに使うため、英数字とハイフンのみの厳格な形式検証を行う
+ *   (LLM由来の入力によるパス/クエリインジェクション対策)
+ * - タイムアウトとレスポンスサイズ上限を設ける(DoS対策)
+ * - レスポンスは外部由来データとして防御的にパースする(呼び出し側)
+ */
+import { ScanToolError } from "../errors.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_BASE_URL = "https://api.osv.dev";
+/**
+ * OSVのID形式(GHSA-xxxx-xxxx-xxxx、CVE-YYYY-NNNN等)。
+ * 英数字とハイフンのみ・先頭は英数字・最大64文字に制限する。
+ */
+const OSV_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]{2,63}$/;
+/** 脆弱性IDを検証し、不正ならScanToolErrorを投げる。 */
+export function validateVulnerabilityId(id) {
+    const trimmed = id.trim();
+    if (!OSV_ID_PATTERN.test(trimmed)) {
+        throw new ScanToolError("invalid_vulnerability_id", "脆弱性IDの形式が不正です。GHSA-xxxx-xxxx-xxxx または CVE-YYYY-NNNN 形式のIDを指定してください");
+    }
+    return trimmed;
+}
+/**
+ * OSVデータベースから脆弱性レコードを1件取得する。
+ *
+ * @returns `JSON.parse`済みのOSVレコード(形式不明な外部データとして扱うこと)
+ */
+export async function fetchOsvRecord(id, options = {}) {
+    const validatedId = validateVulnerabilityId(id);
+    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/vulns/${encodeURIComponent(validatedId)}`;
+    let response;
+    try {
+        response = await fetchFn(url, { 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.status === 404) {
+        // OSVの正規IDはGHSA等であり、CVE-IDはエイリアス解決できない場合がある
+        const hint = validatedId.toUpperCase().startsWith("CVE-")
+            ? "。CVE-IDで見つからない場合は、スキャン結果のid(GHSA-ID)で照会してください"
+            : "";
+        throw new ScanToolError("vulnerability_not_found", `指定されたIDの脆弱性がOSVデータベースに見つかりません: ${validatedId}${hint}`);
+    }
+    if (!response.ok) {
+        throw new ScanToolError("api_request_failed", `OSV APIがエラーを返しました(HTTP ${response.status})`);
+    }
+    const contentLength = Number(response.headers.get("content-length") ?? "0");
+    if (contentLength > maxBytes) {
+        throw new ScanToolError("output_too_large", `OSV APIのレスポンスがサイズ上限(${maxBytes}バイト)を超えました`);
+    }
+    const body = await response.text();
+    // 文字数(UTF-16単位)ではなくUTF-8バイト数で判定する(マルチバイト本文のズレ防止)
+    if (Buffer.byteLength(body, "utf8") > maxBytes) {
+        throw new ScanToolError("output_too_large", `OSV APIのレスポンスがサイズ上限(${maxBytes}バイト)を超えました`);
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new ScanToolError("api_request_failed", "OSV APIのレスポンスをJSONとして解釈できませんでした");
+    }
+}

package/dist/osv/runner.js

@@ -0,0 +1,103 @@
+/**
+ * OSV-Scannerの実行ラッパー。
+ *
+ * セキュリティ設計(docs/DESIGN_TODO.md):
+ * - シェルを経由しない`spawn`+引数配列で実行(コマンドインジェクション対策)
+ * - OSV-Scannerへ渡す引数は固定リストのみ。呼び出し側から任意フラグは注入できない
+ *   (対象パスは位置引数1つだけで、projectDetectorでrealpath解決済みの絶対パスを渡す)
+ * - タイムアウトと出力サイズ上限を設ける(ハング・巨大出力によるDoS対策)
+ *
+ * 終了コード(2.4.0で実機確認):
+ *   0 = スキャン成功・脆弱性なし / 1 = スキャン成功・脆弱性あり / 128 = 対象パッケージなし
+ */
+import { spawn } from "node:child_process";
+import { ScanToolError } from "../errors.js";
+import { resolveOsvScannerBinary } from "./binaryManager.js";
+import { parseOsvScanOutput } from "./scanReport.js";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+/** エラー詳細に含めるstderrの上限(外部由来テキストをそのまま膨らませない) */
+const MAX_STDERR_DETAIL_BYTES = 8 * 1024;
+/** OSV-Scannerに渡す固定引数。ここに無いオプションは一切使わない(ホワイトリスト) */
+const FIXED_SCAN_ARGS = ["scan", "source", "-r", "--format", "json"];
+const EXIT_NO_VULNS = 0;
+const EXIT_VULNS_FOUND = 1;
+const EXIT_NO_PACKAGES = 128;
+function execOsvScanner(binaryPath, projectDir, timeoutMs, maxOutputBytes) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(binaryPath, [...FIXED_SCAN_ARGS, projectDir], {
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.kill("SIGKILL");
+            reject(error);
+        };
+        const timer = setTimeout(() => {
+            fail(new ScanToolError("scan_timeout", `OSV-Scannerが${Math.round(timeoutMs / 1000)}秒以内に完了しませんでした`));
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > maxOutputBytes) {
+                fail(new ScanToolError("output_too_large", `OSV-Scannerの出力がサイズ上限(${maxOutputBytes}バイト)を超えました`));
+                return;
+            }
+            stdoutChunks.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderrBytes >= MAX_STDERR_DETAIL_BYTES)
+                return;
+            stderrBytes += chunk.length;
+            stderrChunks.push(chunk);
+        });
+        child.on("error", (error) => {
+            fail(new ScanToolError("scan_failed", `OSV-Scannerを起動できませんでした: ${error.message}`));
+        });
+        child.on("close", (exitCode, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                exitCode,
+                signal,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8").slice(0, MAX_STDERR_DETAIL_BYTES),
+            });
+        });
+    });
+}
+/**
+ * projectDirをOSV-Scannerでスキャンし、整形済みレポートを返す。
+ *
+ * @param projectDir スキャン対象ディレクトリ。**必ず`detectJavaProject`で検証済みの
+ *   絶対パスを渡すこと**(このレイヤーではパス検証を行わない)
+ */
+export async function runOsvScan(projectDir, options = {}) {
+    const binaryPath = options.binaryPath ?? (await resolveOsvScannerBinary());
+    const result = await execOsvScanner(binaryPath, projectDir, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES);
+    if (result.exitCode === EXIT_NO_PACKAGES) {
+        throw new ScanToolError("no_packages_found", `OSV-Scannerがスキャン対象のパッケージを検出できませんでした: ${projectDir}(pom.xmlに依存関係が定義されているか確認してください)`, result.stderr);
+    }
+    if (result.exitCode !== EXIT_NO_VULNS && result.exitCode !== EXIT_VULNS_FOUND) {
+        const status = result.exitCode !== null ? `exit code ${result.exitCode}` : `signal ${result.signal}`;
+        throw new ScanToolError("scan_failed", `OSV-Scannerが異常終了しました(${status})`, result.stderr);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ScanToolError("invalid_output", "OSV-Scannerの出力をJSONとして解釈できませんでした", result.stdout.slice(0, 1000));
+    }
+    return parseOsvScanOutput(parsed);
+}

package/dist/osv/scanReport.js

@@ -0,0 +1,186 @@
+/**
+ * `scan_java_project`ツールの出力スキーマと、OSV-Scanner JSON出力からの変換。
+ *
+ * docs/DESIGN_TODO.mdの実機調査で確定した方針:
+ * - 脆弱性のグルーピングは`packages[].groups[]`(1エントリ=1脆弱性)をそのまま活用し、
+ *   独自グルーピングは持たない
+ * - `max_severity`は空文字列のケースが実在する(CVE-2015-6420で確認)ため、
+ *   数値化できない値はscore=null / severity="unknown"として例外を投げずに扱う
+ * - 同一pom.xmlが複数の`results[]`エントリに分かれるケースがあるため、
+ *   pathでグルーピングせず全`results[].packages[]`をフラットに集約する
+ *
+ * OSV-Scannerの出力は外部由来データなので、形式が想定と異なっても例外を投げず
+ * 読み取れた範囲でレポートを構築する(欠損フィールドはスキップ)。
+ */
+import { compareMavenVersions } from "../utils/mavenVersion.js";
+import { asArray, asRecord, asString, asStrings } from "../utils/unknownJson.js";
+/** 外部由来のsummaryをLLMに渡す際の長さ上限(プロンプト肥大・DoS対策) */
+const MAX_SUMMARY_LENGTH = 500;
+const CVSS_CRITICAL = 9.0;
+const CVSS_HIGH = 7.0;
+const CVSS_MEDIUM = 4.0;
+function severityFromScore(score) {
+    if (score === null)
+        return "unknown";
+    if (score >= CVSS_CRITICAL)
+        return "critical";
+    if (score >= CVSS_HIGH)
+        return "high";
+    if (score >= CVSS_MEDIUM)
+        return "medium";
+    return "low";
+}
+/** `max_severity`をCVSSスコアに変換する。空文字・非数値・範囲外はnull(unknown扱い)。 */
+function parseSeverityScore(raw) {
+    if (raw === null || raw.trim() === "")
+        return null;
+    const score = Number(raw);
+    return Number.isFinite(score) && score >= 0 && score <= 10 ? score : null;
+}
+function truncateSummary(summary) {
+    return summary.length > MAX_SUMMARY_LENGTH ? `${summary.slice(0, MAX_SUMMARY_LENGTH)}…` : summary;
+}
+/** groupのidsに対応するOSVエントリ詳細(`packages[].vulnerabilities[]`)を探す。 */
+function findVulnDetails(details, ids) {
+    const found = [];
+    for (const detailRaw of details) {
+        const detail = asRecord(detailRaw);
+        if (!detail)
+            continue;
+        const id = asString(detail.id);
+        if (id !== null && ids.includes(id))
+            found.push(detail);
+    }
+    return found;
+}
+function extractSummary(vulnDetails) {
+    for (const detail of vulnDetails) {
+        const summary = asString(detail.summary);
+        if (summary !== null && summary.trim() !== "")
+            return truncateSummary(summary);
+    }
+    return null;
+}
+/**
+ * OSVエントリの`affected[].ranges[].events[].fixed`から修正版を収集する。
+ * 1つのOSVエントリが複数パッケージをカバーしうるため、対象パッケージ名で絞り込む。
+ */
+function extractFixedVersions(vulnDetails, packageName) {
+    const versions = new Set();
+    for (const detail of vulnDetails) {
+        for (const affectedRaw of asArray(detail.affected)) {
+            const affected = asRecord(affectedRaw);
+            if (!affected)
+                continue;
+            const affectedName = asString(asRecord(affected.package)?.name);
+            if (affectedName !== null && affectedName !== packageName)
+                continue;
+            for (const rangeRaw of asArray(affected.ranges)) {
+                for (const eventRaw of asArray(asRecord(rangeRaw)?.events)) {
+                    const fixed = asString(asRecord(eventRaw)?.fixed);
+                    if (fixed !== null && fixed !== "")
+                        versions.add(fixed);
+                }
+            }
+        }
+    }
+    return [...versions].sort(compareMavenVersions);
+}
+/**
+ * OSV-Scannerの`--format json`出力を`scan_java_project`のレポートに変換する。
+ *
+ * @param raw `JSON.parse`済みのOSV-Scanner出力(形式不明な外部データとして扱う)
+ */
+export function parseOsvScanOutput(raw) {
+    const sourceFiles = [];
+    const packageMap = new Map();
+    for (const resultRaw of asArray(asRecord(raw)?.results)) {
+        const result = asRecord(resultRaw);
+        if (!result)
+            continue;
+        const sourcePath = asString(asRecord(result.source)?.path);
+        if (sourcePath !== null && !sourceFiles.includes(sourcePath)) {
+            sourceFiles.push(sourcePath);
+        }
+        for (const pkgRaw of asArray(result.packages)) {
+            const pkgObj = asRecord(pkgRaw);
+            if (!pkgObj)
+                continue;
+            const info = asRecord(pkgObj.package);
+            const name = asString(info?.name);
+            const version = asString(info?.version);
+            if (name === null || version === null)
+                continue;
+            const ecosystem = asString(info?.ecosystem) ?? "unknown";
+            // 同一パッケージが複数のresults[]エントリに分かれても1つに集約する
+            const key = `${ecosystem}:${name}@${version}`;
+            let entry = packageMap.get(key);
+            if (!entry) {
+                entry = { name, version, ecosystem, vulns: new Map() };
+                packageMap.set(key, entry);
+            }
+            const details = asArray(pkgObj.vulnerabilities);
+            for (const groupRaw of asArray(pkgObj.groups)) {
+                const group = asRecord(groupRaw);
+                if (!group)
+                    continue;
+                const ids = asStrings(group.ids);
+                const aliases = asStrings(group.aliases);
+                const primaryId = ids[0] ?? aliases[0];
+                if (primaryId === undefined || entry.vulns.has(primaryId))
+                    continue;
+                const score = parseSeverityScore(asString(group.max_severity));
+                const vulnDetails = findVulnDetails(details, ids);
+                entry.vulns.set(primaryId, {
+                    id: primaryId,
+                    cve: aliases.find((a) => a.startsWith("CVE-")) ??
+                        (primaryId.startsWith("CVE-") ? primaryId : null),
+                    aliases: [...new Set([...ids, ...aliases])].filter((a) => a !== primaryId),
+                    severity_score: score,
+                    severity: severityFromScore(score),
+                    summary: extractSummary(vulnDetails),
+                    fixed_versions: extractFixedVersions(vulnDetails, name),
+                });
+            }
+        }
+    }
+    return buildReport(sourceFiles, packageMap);
+}
+/** ソート用: unknown(null)はどの数値スコアよりも後ろに置く */
+function sortScore(score) {
+    return score ?? -1;
+}
+function buildReport(sourceFiles, packageMap) {
+    const severityBreakdown = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        unknown: 0,
+    };
+    let vulnerabilityCount = 0;
+    const packages = [...packageMap.values()]
+        .filter((entry) => entry.vulns.size > 0)
+        .map((entry) => {
+        const vulnerabilities = [...entry.vulns.values()].sort((a, b) => sortScore(b.severity_score) - sortScore(a.severity_score) || cmpId(a.id, b.id));
+        for (const vuln of vulnerabilities) {
+            severityBreakdown[vuln.severity]++;
+            vulnerabilityCount++;
+        }
+        return { name: entry.name, version: entry.version, ecosystem: entry.ecosystem, vulnerabilities };
+    })
+        .sort((a, b) => maxScore(b.vulnerabilities) - maxScore(a.vulnerabilities) || cmpId(a.name, b.name));
+    return {
+        source_files: sourceFiles,
+        vulnerable_package_count: packages.length,
+        vulnerability_count: vulnerabilityCount,
+        severity_breakdown: severityBreakdown,
+        packages,
+    };
+}
+function maxScore(vulns) {
+    return vulns.reduce((max, v) => Math.max(max, sortScore(v.severity_score)), -1);
+}
+function cmpId(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/osv/suggestFix.js

@@ -0,0 +1,120 @@
+/**
+ * `suggest_fix`の3段階Tierフォールバック(docs/DESIGN_TODO.mdで確定したアルゴリズム)。
+ *
+ * 同一パッケージの`fixed_versions`には複数のサポートブランチ(major.minor系統)への
+ * バックポート修正が混在する(例: log4jの2.3.x / 2.12.x / メインライン)。単純な
+ * 最大バージョンではなく「現在のバージョンに最も近い系統の修正版」を優先して提案する。
+ *
+ * CVEごとの探索順:
+ *   Tier 1 (same_minor):     現在と同じmajor.minor系統内の修正版(最小の変更で済む)
+ *   Tier 2 (major_internal): 同一メジャー内の最小の修正版(マイナーバージョンアップ)
+ *   Tier 3 (cross_major):    全体最小の修正版(メジャーアップグレード、破壊的変更の可能性)
+ *
+ * パッケージ全体の推奨(recommended_upgrade)は全CVEのTier結果の最大値
+ * (= すべての修正可能なCVEを解消できる最小バージョン)。
+ * 現在より新しい修正版が存在しないCVEはunfixedとして明示し、推奨計算から除外する。
+ */
+import { compareMavenVersions, mavenVersionSeries } from "../utils/mavenVersion.js";
+function classifyTier(currentSeries, candidate) {
+    const candidateSeries = mavenVersionSeries(candidate);
+    if (currentSeries === null || candidateSeries === null)
+        return "cross_major";
+    if (currentSeries.major !== candidateSeries.major)
+        return "cross_major";
+    if (currentSeries.minor !== candidateSeries.minor)
+        return "major_internal";
+    return "same_minor";
+}
+/**
+ * 1つのCVEに対する修正版をTierフォールバックで選ぶ。
+ * 現在バージョンより新しい修正版が存在しなければnull(unfixed)。
+ */
+function pickFixForCve(currentVersion, currentSeries, fixedVersions) {
+    // 現在以下の修正版は別ブランチ向けバックポート(現在も影響を受けたまま)なので除外
+    const candidates = fixedVersions
+        .filter((v) => compareMavenVersions(v, currentVersion) > 0)
+        .sort(compareMavenVersions);
+    if (candidates.length === 0)
+        return null;
+    if (currentSeries !== null) {
+        for (const tier of ["same_minor", "major_internal"]) {
+            const found = candidates.find((v) => classifyTier(currentSeries, v) === tier);
+            if (found !== undefined)
+                return { version: found, tier };
+        }
+    }
+    const version = candidates[0];
+    return { version, tier: classifyTier(currentSeries, version) };
+}
+function buildNote(currentSeries, recommended, tier, fixableCount, unfixedCount) {
+    if (recommended === null) {
+        return `全${unfixedCount}件のCVEに現在より新しい修正版が存在しない(unfixed)`;
+    }
+    const label = currentSeries !== null ? `${currentSeries.major}.${currentSeries.minor}` : null;
+    let note;
+    switch (tier) {
+        case "same_minor":
+            note = `現在の${label}系統内の${recommended}で、修正版が存在する${fixableCount}件のCVEをすべて解消できる`;
+            break;
+        case "major_internal":
+            note = `${label}系統向けの修正版は存在しない。同一メジャー(${currentSeries.major}.x)内では${recommended}が${fixableCount}件のCVEを解消する最小版`;
+            break;
+        default:
+            note =
+                label !== null
+                    ? `同一メジャー(${currentSeries.major}.x)内に修正版が存在しない。${recommended}へのメジャーアップグレードが必要(破壊的変更の可能性あり)`
+                    : `現在バージョンの系統を判定できないため、全体最小の修正版${recommended}を提示`;
+    }
+    if (unfixedCount > 0) {
+        note += `。残り${unfixedCount}件は修正版が存在せず、このアップグレードでは解消されない`;
+    }
+    return note;
+}
+/** 1パッケージ分のアップグレード提案を組み立てる。 */
+export function suggestUpgradeForPackage(pkg) {
+    const currentSeries = mavenVersionSeries(pkg.version);
+    const details = [];
+    let recommended = null;
+    let unfixedCount = 0;
+    for (const vuln of pkg.vulnerabilities) {
+        const pick = pickFixForCve(pkg.version, currentSeries, vuln.fixed_versions);
+        if (pick === null) {
+            unfixedCount++;
+            details.push({
+                id: vuln.id,
+                cve: vuln.cve,
+                severity: vuln.severity,
+                fixed_in: null,
+                tier: "unfixed",
+            });
+            continue;
+        }
+        details.push({
+            id: vuln.id,
+            cve: vuln.cve,
+            severity: vuln.severity,
+            fixed_in: pick.version,
+            tier: pick.tier,
+        });
+        if (recommended === null || compareMavenVersions(pick.version, recommended) > 0) {
+            recommended = pick.version;
+        }
+    }
+    const fixableCount = details.length - unfixedCount;
+    // 推奨バージョン自体のTierは「現在バージョンとの系統関係」で再分類する
+    // (per-CVEのTierの寄せ集めではなく、実際に行うアップグレードの距離を表す)
+    const upgradeTier = recommended !== null ? classifyTier(currentSeries, recommended) : null;
+    return {
+        package: pkg.name,
+        current_version: pkg.version,
+        ecosystem: pkg.ecosystem,
+        recommended_upgrade: recommended,
+        upgrade_tier: upgradeTier,
+        upgrade_note: buildNote(currentSeries, recommended, upgradeTier, fixableCount, unfixedCount),
+        per_cve_detail: details,
+    };
+}
+/** スキャンレポート全体からパッケージごとの提案一覧を作る(深刻度順を維持)。 */
+export function suggestUpgrades(packages) {
+    return packages.map(suggestUpgradeForPackage);
+}

package/dist/osv/vulnerabilityExplanation.js

@@ -0,0 +1,118 @@
+/**
+ * OSVレコードから`explain_vulnerability`の出力を組み立てる。
+ *
+ * OSV APIのレスポンスは外部由来データとして防御的に扱う:
+ * - 欠損・型不正のフィールドは例外を投げずスキップ
+ * - `details`(markdown)等の自由テキストは長さ上限で切り詰め、
+ *   構造化フィールドとして返す(プロンプトインジェクション対策として
+ *   「指示」ではなく「データ」として扱われる形を維持する)
+ * - 参照URLはhttp/httpsのみ許可し、件数上限を設ける
+ */
+import { asArray, asRecord, asString, asStrings } from "../utils/unknownJson.js";
+const MAX_DETAILS_LENGTH = 4000;
+const MAX_ALIASES = 20;
+const MAX_SEVERITY_ENTRIES = 5;
+const MAX_AFFECTED = 10;
+const MAX_RANGES_PER_AFFECTED = 10;
+const MAX_REFERENCES = 20;
+function truncate(text, maxLength) {
+    return text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
+}
+function parseSeverity(raw) {
+    const entries = [];
+    for (const item of asArray(raw)) {
+        const record = asRecord(item);
+        const type = asString(record?.type);
+        const score = asString(record?.score);
+        if (type !== null && score !== null)
+            entries.push({ type, score });
+        if (entries.length >= MAX_SEVERITY_ENTRIES)
+            break;
+    }
+    return entries;
+}
+/**
+ * OSVの`ranges[].events[]`(introduced/fixed/last_affectedのイベント列)を
+ * 「introducedで開始し、fixed/last_affectedで閉じる」区間のリストに畳み込む。
+ */
+function parseRanges(raw) {
+    const ranges = [];
+    for (const rangeRaw of asArray(raw)) {
+        for (const eventRaw of asArray(asRecord(rangeRaw)?.events)) {
+            const event = asRecord(eventRaw);
+            if (!event)
+                continue;
+            const introduced = asString(event.introduced);
+            const fixed = asString(event.fixed);
+            const lastAffected = asString(event.last_affected);
+            const last = ranges[ranges.length - 1];
+            if (introduced !== null) {
+                ranges.push({ introduced, fixed: null, last_affected: null });
+            }
+            else if (fixed !== null && last !== undefined && last.fixed === null) {
+                last.fixed = fixed;
+            }
+            else if (lastAffected !== null && last !== undefined && last.last_affected === null) {
+                last.last_affected = lastAffected;
+            }
+            if (ranges.length >= MAX_RANGES_PER_AFFECTED)
+                return ranges;
+        }
+    }
+    return ranges;
+}
+function parseAffected(raw) {
+    const affected = [];
+    for (const item of asArray(raw)) {
+        const record = asRecord(item);
+        if (!record)
+            continue;
+        const pkg = asRecord(record.package);
+        const name = asString(pkg?.name);
+        if (name === null)
+            continue;
+        affected.push({
+            package: name,
+            ecosystem: asString(pkg?.ecosystem) ?? "unknown",
+            ranges: parseRanges(record.ranges),
+        });
+        if (affected.length >= MAX_AFFECTED)
+            break;
+    }
+    return affected;
+}
+function parseReferences(raw) {
+    const references = [];
+    for (const item of asArray(raw)) {
+        const record = asRecord(item);
+        const url = asString(record?.url);
+        // 外部URLはhttp/httpsのみ許可(file:等の想定外スキームを排除)
+        if (url === null || !/^https?:\/\//.test(url))
+            continue;
+        references.push({ type: asString(record?.type) ?? "WEB", url });
+        if (references.length >= MAX_REFERENCES)
+            break;
+    }
+    return references;
+}
+/**
+ * OSVレコードを整形する。
+ *
+ * @param requestedId レコードにidが無い場合のフォールバック表示用
+ */
+export function buildVulnerabilityExplanation(raw, requestedId) {
+    const record = asRecord(raw);
+    const summary = asString(record?.summary);
+    const details = asString(record?.details);
+    return {
+        id: asString(record?.id) ?? requestedId,
+        aliases: asStrings(record?.aliases).slice(0, MAX_ALIASES),
+        summary: summary !== null && summary.trim() !== "" ? truncate(summary, 500) : null,
+        details: details !== null && details.trim() !== "" ? truncate(details, MAX_DETAILS_LENGTH) : null,
+        severity: parseSeverity(record?.severity),
+        published: asString(record?.published),
+        modified: asString(record?.modified),
+        affected: parseAffected(record?.affected),
+        references: parseReferences(record?.references),
+    };
+}