osv-scanner-mcp 0.2.0 → 0.3.1

package/README.md

@@ -13,6 +13,7 @@ Google製 [OSV-Scanner](https://github.com/google/osv-scanner) をラップす
 
 - **ワンショットスキャン**: `scan_java_project` ツールにプロジェクトパスを渡すだけで、検出→スキャン→整形済みレポートまで一気に返します
 - **JAR/WAR実体スキャン**: `scan_java_artifact` ツールで、lockfileが無い・shaded/fat JARしか手元にないプロジェクトでもアーカイブ内メタデータから既知の脆弱性を検出します(ベストエフォート同定であることを明示するcoverage情報付き)
+- **SBOM入力スキャン**: `scan_sbom` ツールでCycloneDX/SPDXのJSON SBOMに記録された依存を検査します。SBOMの網羅性や実成果物との一致は未検証であることを明示します
 - **深刻度順のレポート**: パッケージごとに脆弱性をCVSSスコア順に整理し、5段階の深刻度ラベル(critical / high / medium / low / unknown)とサマリ集計付きで返します
 - **修正版の提示**: 各脆弱性の `fixed_versions` をMavenバージョン優先順位規則で正しくソートして含めます(`2.17.1-RELEASE` のようなsemver非対応の表記にも対応)
 - **セキュリティ第一の設計**: シェル非経由の実行・引数ホワイトリスト・パス正規化と境界チェック・タイムアウト/出力サイズ上限を実装段階から組み込んでいます
@@ -206,6 +207,30 @@ OSV-Scanner 2.4.0の `java/archive` プラグインを使用し、ネストJAR
 `suggest_fix` は引き続きマニフェスト方式専用です。experimentalプラグインを使うため、OSV-Scannerのピン留めバージョン更新時には、フラグとJAR/WARの出力形式も再検証してください。
 信頼できないアーカイブの展開はOSV-Scannerのネイティブ処理に依存します。タイムアウト・出力上限はありますが、OSレベルのメモリ制限やサンドボックスを提供するものではありません。
 
+### `scan_sbom`
+
+既存のSBOMに記録された依存をOSV-Scannerで照会します。SBOMの生成、ビルド、JARの実行は行いません。
+
+```json
+{ "sbom_path": "/absolute/path/to/release-sbom.json" }
+```
+
+- **対応形式**: 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)を参照してください。
+- **安全な読み込み**: 許可ルートと読み込み中のサイズ上限を確認し、権限制限付きの一時コピーだけをスキャンします。元ファイルは変更せず、一時コピーは成功・失敗ともに削除します。
+
+出力の先頭に`coverage`を返します。
+
+- `identified_package_count`: スキャナーが識別した、名前・バージョン・エコシステムの重複を除いたパッケージ数。既知脆弱性がないものも含みます。
+- `unidentified_packages`: スキャナー出力に存在したものの、バージョン等が不足しているパッケージ。スキャナー自体が読み飛ばした項目は列挙できないため、この配列が空でも全件検査を意味しません。
+- `status`: 識別できたものがあれば`packages_identified`、なければ`no_packages_identified`。
+- `completeness` / `artifact_match`: ともに`not_verified`。SBOMの依存網羅性や、実際のJARと同一ビルドのものかは自動検証しません。
+
+`sbom`には元ファイルのパス・形式・仕様バージョン・スキャンに用いた入力バイト列のSHA256を返します。`identified_vulnerability_count`と`packages`には識別できた依存の検出結果を返します。**検出0件は「安全」の保証ではありません。** メタデータのないJARを補完するには、そのビルドに対応する正確なSBOMを別途用意してください。
+
+不正JSONは`invalid_sbom`、未対応形式は`unsupported_sbom_format`、入力上限超過は`sbom_too_large`、存在しない・読み取れないファイルは`sbom_not_found`です。空のSBOMや識別できるパッケージがないSBOMは、警告付きの成功レポートになります。既存ツールと同じタイムアウト・出力上限・同時実行枠を使用します。
+
 ### `suggest_fix`
 
 スキャンを実行し、脆弱なパッケージごとに**推奨アップグレードバージョン**を提案します。単純な最大バージョンではなく、現在のバージョンに最も近いリリース系統の修正版を3段階フォールバックで選定します:

package/dist/index.js

@@ -16,6 +16,7 @@ import { z } from "zod";
 import { handleExplainVulnerability } from "./tools/explainVulnerability.js";
 import { handleScanJavaProject } from "./tools/scanJavaProject.js";
 import { handleScanJavaArtifact } from "./tools/scanJavaArtifact.js";
+import { handleScanSbom } from "./tools/scanSbom.js";
 import { handleSuggestFix } from "./tools/suggestFix.js";
 import { ALLOWED_ROOT_ENV, allowedRootStartupError, allowedRootStartupWarning, } from "./utils/startupConfig.js";
 export { ALLOWED_ROOT_ENV };
@@ -33,7 +34,7 @@ if (startupWarning !== null) {
 // NOTE: リリース時はpackage.jsonのversionと同じ値に更新すること
 const server = new McpServer({
     name: "osv-scanner-mcp",
-    version: "0.2.0",
+    version: "0.3.1",
 });
 server.registerTool("scan_java_project", {
     title: "Javaプロジェクトの脆弱性スキャン",
@@ -84,6 +85,15 @@ server.registerTool("scan_java_artifact", {
         artifact_path: z.string().min(1).describe("JAR/WARファイル、または探索するディレクトリの絶対パス"),
     },
 }, async ({ artifact_path }) => handleScanJavaArtifact({ artifact_path }, { allowedRoot: process.env[ALLOWED_ROOT_ENV] }));
+server.registerTool("scan_sbom", {
+    title: "SBOMの脆弱性スキャン",
+    description: "CycloneDX 1.4/1.5/1.6またはSPDX 2.2/2.3のJSON SBOMから識別できる依存をスキャンする。" +
+        "ビルドやJARの実行は行わない。入力は16MiB以下のローカルファイル。" +
+        "SBOMの網羅性・鮮度・実成果物との一致は未検証であり、検出0件でも安全性を保証しない。",
+    inputSchema: {
+        sbom_path: z.string().min(1).describe("CycloneDX/SPDX JSON SBOMファイルの絶対パス"),
+    },
+}, async ({ sbom_path }) => handleScanSbom({ sbom_path }, { allowedRoot: process.env[ALLOWED_ROOT_ENV] }));
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // stdoutはMCPプロトコル専用のため、起動ログはstderrへ

package/dist/osv/runner.js

@@ -5,6 +5,7 @@
  * - シェルを経由しない`spawn`+引数配列で実行(コマンドインジェクション対策)
  * - OSV-Scannerへ渡す引数は固定リストのみ。呼び出し側から任意フラグは注入できない
  *   (プロジェクトは検証済みディレクトリ1つ、実体スキャンは列挙済みのJAR/WAR絶対パスだけを渡す)
+ * - SBOMは検証・サイズ制限済みの専用一時コピー1つだけを渡す
  * - タイムアウトと出力サイズ上限を設ける(ハング・巨大出力によるDoS対策)
  *
  * 終了コード(2.4.0で実機確認):
@@ -42,13 +43,18 @@ const FIXED_ARTIFACT_ARGS = [
     "scan", "source", "--format", "json", "--all-packages", "--no-ignore",
     "--experimental-no-default-plugins", "--experimental-plugins", "java/archive",
 ];
+const FIXED_SBOM_ARGS = [
+    "scan", "source", "--format", "json", "--all-packages", "--no-ignore",
+    "--experimental-no-default-plugins", "--experimental-plugins", "sbom",
+];
+const SCAN_ARGS = { project: FIXED_SCAN_ARGS, artifact: FIXED_ARTIFACT_ARGS, sbom: FIXED_SBOM_ARGS };
 const EXIT_NO_VULNS = 0;
 const EXIT_VULNS_FOUND = 1;
 const EXIT_NO_PACKAGES = 128;
-function execOsvScanner(binaryPath, targetPaths, timeoutMs, maxOutputBytes, artifactMode) {
+function execOsvScanner(binaryPath, targetPaths, timeoutMs, maxOutputBytes, mode) {
     return new Promise((resolve, reject) => {
         const child = spawn(binaryPath, [
-            ...(artifactMode ? FIXED_ARTIFACT_ARGS : FIXED_SCAN_ARGS), ...targetPaths,
+            ...SCAN_ARGS[mode], ...targetPaths,
         ], {
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
@@ -107,39 +113,43 @@ function execOsvScanner(binaryPath, targetPaths, timeoutMs, maxOutputBytes, arti
  *   絶対パスを渡すこと**(このレイヤーではパス検証を行わない)
  */
 export async function runOsvScan(projectDir, options = {}) {
-    return parseOsvScanOutput(await runScan([projectDir], options, false));
+    return parseOsvScanOutput(await runScan([projectDir], options, "project"));
 }
 /** Accept only the exact absolute files enumerated by detectJavaArtifacts. */
 export async function runOsvArtifactScan(artifactPaths, options = {}) {
     if (artifactPaths.length === 0) {
         throw new ScanToolError("no_scannable_artifacts", "No JAR/WAR archives selected");
     }
-    return runScan(artifactPaths, options, true);
+    return runScan(artifactPaths, options, "artifact");
+}
+/** Scan only the private, validated snapshot prepared by handleScanSbom. */
+export async function runOsvSbomScan(snapshotPath, options = {}) {
+    return runScan([snapshotPath], options, "sbom");
 }
-async function runScan(targetPaths, options, artifactMode) {
+async function runScan(targetPaths, options, mode) {
     const limit = options.maxConcurrentScans ?? maxConcurrentScansFromEnv();
     if (activeScans >= limit) {
         throw new ScanToolError("too_many_concurrent_scans", `同時実行できるスキャンは${limit}件までです(現在${activeScans}件実行中)。実行中のスキャン完了後に再試行してください`);
     }
     activeScans++;
     try {
-        return await runOsvScanUnguarded(targetPaths, options, artifactMode);
+        return await runOsvScanUnguarded(targetPaths, options, mode);
     }
     finally {
         activeScans--;
     }
 }
-async function runOsvScanUnguarded(targetPaths, options, artifactMode) {
+async function runOsvScanUnguarded(targetPaths, options, mode) {
     const binaryPath = options.binaryPath ?? (await resolveOsvScannerBinary());
-    const result = await execOsvScanner(binaryPath, targetPaths, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES, artifactMode);
-    if (result.exitCode === EXIT_NO_PACKAGES && !artifactMode) {
+    const result = await execOsvScanner(binaryPath, targetPaths, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES, mode);
+    if (result.exitCode === EXIT_NO_PACKAGES && mode === "project") {
         throw new ScanToolError("no_packages_found", `OSV-Scannerがスキャン対象のパッケージを検出できませんでした: ${targetPaths[0]}(pom.xmlに依存関係が定義されているか確認してください)`, result.stderr);
     }
-    if (artifactMode && result.exitCode === EXIT_NO_PACKAGES && result.stdout.trim() === "") {
+    if (mode !== "project" && result.exitCode === EXIT_NO_PACKAGES && result.stdout.trim() === "") {
         return { results: [] };
     }
     if (result.exitCode !== EXIT_NO_VULNS && result.exitCode !== EXIT_VULNS_FOUND &&
-        !(artifactMode && result.exitCode === EXIT_NO_PACKAGES)) {
+        !(mode !== "project" && result.exitCode === EXIT_NO_PACKAGES)) {
         const status = result.exitCode !== null ? `exit code ${result.exitCode}` : `signal ${result.signal}`;
         throw new ScanToolError("scan_failed", `OSV-Scannerが異常終了しました(${status})`, result.stderr);
     }

package/dist/osv/sbomReport.js

@@ -0,0 +1,55 @@
+import { ScanToolError } from "../errors.js";
+import { sanitizeExternalText } from "../utils/externalText.js";
+import { asRecord, asString } from "../utils/unknownJson.js";
+import { parseOsvScanOutput } from "./scanReport.js";
+export function buildSbomReport(raw, input, snapshotPath) {
+    const results = asRecord(raw)?.results;
+    if (!Array.isArray(results))
+        throw new ScanToolError("invalid_output", "SBOM scan output is missing its results array");
+    const identified = new Set();
+    const unidentified = new Map();
+    const scannable = [];
+    for (const value of results) {
+        const result = asRecord(value);
+        const source = asRecord(result?.source);
+        if (source?.path !== snapshotPath || source.type !== "sbom" || !Array.isArray(result?.packages)) {
+            throw new ScanToolError("invalid_output", "SBOM scan output contains an unexpected source or package list");
+        }
+        for (const item of result.packages) {
+            const pkg = asRecord(asRecord(item)?.package);
+            if (pkg === null)
+                throw new ScanToolError("invalid_output", "SBOM scanner returned a malformed package");
+            const name = asString(pkg?.name);
+            const version = asString(pkg?.version);
+            const ecosystem = asString(pkg?.ecosystem);
+            if (!name?.trim() || !version?.trim() || !ecosystem?.trim() ||
+                [name, version, ecosystem].some((s) => s.trim().toLowerCase() === "unknown") || name === "unknown:unknown") {
+                unidentified.set(JSON.stringify([ecosystem, name, version]), { name, version, ecosystem });
+                continue;
+            }
+            identified.add(JSON.stringify([ecosystem, name, version]));
+            scannable.push(item);
+        }
+    }
+    const report = parseOsvScanOutput({ results: [{ packages: scannable }] });
+    return {
+        coverage: {
+            identified_package_count: identified.size,
+            unidentified_packages: [...unidentified.values()],
+            status: identified.size === 0 ? "no_packages_identified" : "packages_identified",
+            completeness: "not_verified",
+            artifact_match: "not_verified",
+            warning: "Only packages identified from this SBOM are checked. Missing, unsupported or unversioned identifiers can be skipped. SBOM completeness, freshness and correspondence to the actual build are not verified. Zero findings does not establish safety.",
+        },
+        sbom: {
+            path: sanitizeExternalText(input.sourcePath),
+            format: input.format,
+            spec_version: input.specVersion,
+            sha256: input.sha256,
+        },
+        identified_vulnerability_count: report.vulnerability_count,
+        identified_vulnerable_package_count: report.vulnerable_package_count,
+        severity_breakdown: report.severity_breakdown,
+        packages: report.packages,
+    };
+}

package/dist/tools/scanSbom.js

@@ -0,0 +1,26 @@
+import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runOsvSbomScan } from "../osv/runner.js";
+import { buildSbomReport } from "../osv/sbomReport.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-"));
+        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");
+            await writeFile(snapshotPath, input.bytes, { mode: 0o600, flag: "wx" });
+            const raw = await runOsvSbomScan(snapshotPath, options);
+            return jsonResult(buildSbomReport(raw, input, snapshotPath));
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}

package/dist/utils/sbomInput.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import path from "node:path";
+import { ScanToolError } from "../errors.js";
+import { asRecord } from "./unknownJson.js";
+const DEFAULT_MAX_INPUT_BYTES = 16 * 1024 * 1024;
+const CYCLONEDX_VERSIONS = new Set(["1.4", "1.5", "1.6"]);
+const SPDX_VERSIONS = new Set(["SPDX-2.2", "SPDX-2.3"]);
+export async function loadSbom(inputPath, options = {}) {
+    if (typeof inputPath !== "string" || !path.isAbsolute(inputPath)) {
+        throw new ScanToolError("sbom_not_found", "Specify an absolute path to a JSON SBOM file");
+    }
+    let sourcePath;
+    try {
+        sourcePath = await realpath(inputPath);
+    }
+    catch {
+        throw new ScanToolError("sbom_not_found", "The specified SBOM file does not exist");
+    }
+    if (options.allowedRoot !== undefined) {
+        const root = await realpath(options.allowedRoot);
+        const relative = path.relative(root, sourcePath);
+        if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new ScanToolError("path_outside_allowed_root", "SBOM path is outside the allowed root");
+        }
+    }
+    const maxBytes = options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        throw new RangeError("Invalid SBOM size limit");
+    const tooLarge = () => new ScanToolError("sbom_too_large", `SBOM input exceeds ${maxBytes} bytes`);
+    let bytes;
+    try {
+        // Nonblocking open avoids hanging on FIFOs. Refuse a leaf replaced by a symlink.
+        const file = await open(sourcePath, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const info = await file.stat();
+            if (!info.isFile())
+                throw new ScanToolError("sbom_not_found", "SBOM input must be a regular file");
+            if (info.size > maxBytes)
+                throw tooLarge();
+            const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes + 1));
+            const chunks = [];
+            let total = 0;
+            while (true) {
+                const { bytesRead } = await file.read(chunk, 0, Math.min(chunk.length, maxBytes - total + 1), null);
+                if (bytesRead === 0)
+                    break;
+                total += bytesRead;
+                if (total > maxBytes)
+                    throw tooLarge();
+                chunks.push(Buffer.from(chunk.subarray(0, bytesRead)));
+            }
+            bytes = Buffer.concat(chunks, total);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (error instanceof ScanToolError)
+            throw error;
+        throw new ScanToolError("sbom_not_found", "The specified SBOM file could not be read");
+    }
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new ScanToolError("invalid_sbom", "SBOM input must be UTF-8 JSON; XML and tag-value formats are not supported");
+    }
+    const document = asRecord(raw);
+    let format;
+    let specVersion;
+    if (document?.bomFormat === "CycloneDX" && document.spdxVersion === undefined) {
+        if (typeof document.specVersion !== "string" || !CYCLONEDX_VERSIONS.has(document.specVersion)) {
+            throw new ScanToolError("unsupported_sbom_format", "Supported CycloneDX JSON versions: 1.4, 1.5, 1.6");
+        }
+        if (!Array.isArray(document.components) || document.components.some((item) => asRecord(item) === null)) {
+            throw new ScanToolError("invalid_sbom", "CycloneDX input must contain a components array of objects");
+        }
+        format = "CycloneDX";
+        specVersion = document.specVersion;
+    }
+    else if (typeof document?.spdxVersion === "string" && document.bomFormat === undefined) {
+        if (!SPDX_VERSIONS.has(document.spdxVersion)) {
+            throw new ScanToolError("unsupported_sbom_format", "Supported SPDX JSON versions: 2.2, 2.3");
+        }
+        if (!Array.isArray(document.packages) || document.packages.some((item) => asRecord(item) === null)) {
+            throw new ScanToolError("invalid_sbom", "SPDX input must contain a packages array of objects");
+        }
+        format = "SPDX";
+        specVersion = document.spdxVersion;
+    }
+    else {
+        throw new ScanToolError("unsupported_sbom_format", "Expected a CycloneDX or SPDX JSON document");
+    }
+    return { sourcePath, format, specVersion, bytes, sha256: createHash("sha256").update(bytes).digest("hex") };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osv-scanner-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "MCP server that wraps Google's OSV-Scanner to scan Java projects for known vulnerabilities",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,9 +43,9 @@
   },
   "devDependencies": {
     "@types/node": "^26.5.0",
-    "@vitest/coverage-v8": "^4.1.9",
+    "@vitest/coverage-v8": "^5.0.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9"
+    "vitest": "^5.0.1"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",