osv-scanner-mcp 0.1.12 → 0.3.0

package/README.md

@@ -12,6 +12,8 @@ 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非対応の表記にも対応)
 - **セキュリティ第一の設計**: シェル非経由の実行・引数ホワイトリスト・パス正規化と境界チェック・タイムアウト/出力サイズ上限を実装段階から組み込んでいます
@@ -178,6 +180,57 @@ Java(Maven)プロジェクトをスキャンし、既知の脆弱性レポート
 - `fixed_versions` はMaven優先順位で昇順。複数のリリース系統(例: 2.12系バックポートと2.15系)が混在することがあります。空配列は「修正版が存在しない」ことを意味します
 - `severity_score` が取得できない脆弱性は `null` / `"unknown"` として扱います
 
+### `scan_java_artifact`
+
+JAR/WARファイルの実体をスキャンします。既存のマニフェスト方式とは別ツールです。
+
+```json
+{ "artifact_path": "/absolute/path/to/application.war" }
+```
+
+`artifact_path` はJAR/WARファイル、または探索するディレクトリの絶対パスです。
+ディレクトリ指定では `target` や `build` も探索します。`.git`、`node_modules`、`.idea`、`.vscode` と探索中のシンボリックリンクは除外します。
+探索上限は深さ8・100ファイル・10,000エントリです。上限に達して探索を完了できない場合は、結果を黙って省略せず `artifact_search_limit_exceeded` を返します。対象を絞って再実行してください。
+`OSV_MCP_ALLOWED_ROOT` による制限も適用されます。
+
+OSV-Scanner 2.4.0の `java/archive` プラグインを使用し、ネストJARもスキャナー側で解析します。Javaコードやビルドは実行しません。
+識別にはアーカイブ内メタデータを用いるため、除去済みメタデータやshaded/minimized JAR内の依存を見落とす場合があります。
+
+**出力の読み方:**
+
+- 先頭の `coverage` に `jars_found`、`jars_identified`、`unidentified_jars` を返します。件数はWARも含む、ファイルシステム上で列挙した外側のアーカイブ単位です。ネストJARの総数ではありません。
+- `artifacts[].status` は `identified_with_vulnerabilities` / `identified_without_known_vulnerabilities` / `unidentified` の3値です。「同定済み」は少なくとも1件のMaven座標を取得できた意味であり、全依存の同定ではありません。
+- `coverage.completeness` は常に `incomplete`。`identified_vulnerability_count: 0` は安全性の保証ではありません。
+- `packages` は同定できた脆弱なパッケージの詳細です。複数アーカイブに含まれる同一パッケージ・脆弱性は全体集計では重複排除します。
+- JAR/WARが無い場合は `no_scannable_artifacts`、全件同定不能の場合は警告を含む成功レポートです。
+
+`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段階フォールバックで選定します:
@@ -297,6 +350,7 @@ npm run build             # dist/ へビルド
 - [x] npmパッケージ化(`npx osv-scanner-mcp`)
 - [x] OSV-Scannerバイナリの自動ダウンロード(チェックサム検証付き)
 - [x] Gradle対応(lockfile方式)
+- [x] `scan_java_artifact` ツール: JAR/WAR実体スキャン(lockfileが無い・shaded/fat JARのみのプロジェクト向け)
 
 ## ライセンス
 

package/dist/index.js

@@ -15,6 +15,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 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 };
@@ -32,7 +34,7 @@ if (startupWarning !== null) {
 // NOTE: リリース時はpackage.jsonのversionと同じ値に更新すること
 const server = new McpServer({
     name: "osv-scanner-mcp",
-    version: "0.1.12",
+    version: "0.3.0",
 });
 server.registerTool("scan_java_project", {
     title: "Javaプロジェクトの脆弱性スキャン",
@@ -74,6 +76,24 @@ server.registerTool("explain_vulnerability", {
             .describe("脆弱性のID(例: GHSA-jfh8-c2jp-5v3q、CVE-2021-44228)"),
     },
 }, async ({ vulnerability_id }) => handleExplainVulnerability({ vulnerability_id }));
+server.registerTool("scan_java_artifact", {
+    title: "JAR/WAR実体の脆弱性スキャン",
+    description: "JAR/WARファイルまたはディレクトリ内の実体をスキャンする。ビルドやJavaコードの実行は行わない。" +
+        "メタデータによるベストエフォート同定のため、coverageと同定不能ファイルを必ず確認すること。" +
+        "completenessは常にincomplete。検出0件でも安全性や全依存の同定を保証しない。",
+    inputSchema: {
+        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/artifactReport.js

@@ -0,0 +1,60 @@
+import { ScanToolError } from "../errors.js";
+import { sanitizeExternalText } from "../utils/externalText.js";
+import { asArray, asRecord } from "../utils/unknownJson.js";
+import { parseOsvScanOutput } from "./scanReport.js";
+const WARNING = "Best-effort metadata identification only. Missing or removed metadata can hide dependencies, even in identified archives. Zero identified vulnerabilities does not establish safety.";
+const HINT = "Metadata may be missing (shaded/minimized archive). Scan the build project's lockfile instead.";
+function isIdentifiedPackage(raw) {
+    const info = asRecord(asRecord(raw)?.package);
+    if (info?.ecosystem !== "Maven" || typeof info.name !== "string" || typeof info.version !== "string")
+        return false;
+    const parts = info.name.split(":");
+    return parts.length === 2 && parts.every((part) => part.trim() !== "" && part.toLowerCase() !== "unknown") &&
+        info.version.trim() !== "" && info.version.toLowerCase() !== "unknown";
+}
+export function buildArtifactReport(raw, artifactPaths) {
+    const results = asRecord(raw)?.results;
+    if (!Array.isArray(results)) {
+        throw new ScanToolError("invalid_output", "OSV-Scanner artifact output is missing its results array");
+    }
+    const byPath = new Map();
+    for (const result of results) {
+        const record = asRecord(result);
+        const source = asRecord(record?.source);
+        // Identity comparison must precede display sanitization, which can collapse distinct names.
+        const sourcePath = source?.path;
+        if (source?.type !== "artifact" || typeof sourcePath !== "string" || !artifactPaths.includes(sourcePath))
+            continue;
+        const packages = asArray(record?.packages).filter(isIdentifiedPackage);
+        if (packages.length > 0)
+            byPath.set(sourcePath, [...(byPath.get(sourcePath) ?? []), ...packages]);
+    }
+    const normalized = [...byPath].map(([file, packages]) => ({ source: { path: file }, packages }));
+    const report = parseOsvScanOutput({ results: normalized });
+    const artifacts = artifactPaths.map((file) => {
+        const packages = byPath.get(file);
+        const identified = packages !== undefined;
+        const perFile = parseOsvScanOutput({ results: [{ packages: packages ?? [] }] });
+        return {
+            path: sanitizeExternalText(file),
+            status: !identified ? "unidentified" : perFile.vulnerability_count > 0
+                ? "identified_with_vulnerabilities" : "identified_without_known_vulnerabilities",
+            identified_vulnerability_count: perFile.vulnerability_count,
+        };
+    });
+    return {
+        coverage: {
+            jars_found: artifactPaths.length,
+            jars_identified: byPath.size,
+            unidentified_jars: artifacts.filter((item) => item.status === "unidentified")
+                .map(({ path }) => ({ path, hint: HINT })),
+            completeness: "incomplete",
+            warning: WARNING,
+        },
+        artifacts,
+        identified_vulnerability_count: report.vulnerability_count,
+        identified_vulnerable_package_count: report.vulnerable_package_count,
+        severity_breakdown: report.severity_breakdown,
+        packages: report.packages,
+    };
+}

package/dist/osv/binaryDownloader.js

@@ -15,6 +15,7 @@ import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
 import os from "node:os";
 import path from "node:path";
 import { ScanToolError } from "../errors.js";
+import { readResponseBytes } from "../utils/readResponseBytes.js";
 /** ピン留めするOSV-Scannerのバージョン。更新時は下のチェックサムも必ず更新すること */
 export const PINNED_OSV_SCANNER_VERSION = "2.4.0";
 /**
@@ -70,15 +71,14 @@ async function downloadAsset(url, fetchFn, timeoutMs) {
     if (!response.ok) {
         throw new ScanToolError("binary_download_failed", `OSV-Scannerのダウンロードに失敗しました(HTTP ${response.status}): ${url}`);
     }
-    const contentLength = Number(response.headers.get("content-length") ?? "0");
-    if (contentLength > MAX_BINARY_BYTES) {
-        throw new ScanToolError("binary_download_failed", `ダウンロードサイズが上限(${MAX_BINARY_BYTES}バイト)を超えています`);
+    try {
+        return await readResponseBytes(response, MAX_BINARY_BYTES, new ScanToolError("binary_download_failed", `ダウンロードサイズが上限(${MAX_BINARY_BYTES}バイト)を超えています`));
     }
-    const buffer = Buffer.from(await response.arrayBuffer());
-    if (buffer.byteLength > MAX_BINARY_BYTES) {
-        throw new ScanToolError("binary_download_failed", `ダウンロードサイズが上限(${MAX_BINARY_BYTES}バイト)を超えています`);
+    catch (error) {
+        if (error instanceof ScanToolError)
+            throw error;
+        throw new ScanToolError("binary_download_failed", "OSV-Scannerのダウンロード本文を受信できませんでした");
     }
-    return buffer;
 }
 /**
  * ピン留めバージョンのOSV-Scannerをキャッシュから返す。

package/dist/osv/osvApi.js

@@ -9,6 +9,7 @@
  * - レスポンスは外部由来データとして防御的にパースする(呼び出し側)
  */
 import { ScanToolError } from "../errors.js";
+import { readResponseBytes } from "../utils/readResponseBytes.js";
 const DEFAULT_TIMEOUT_MS = 15_000;
 const DEFAULT_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 const DEFAULT_BASE_URL = "https://api.osv.dev";
@@ -56,14 +57,15 @@ export async function fetchOsvRecord(id, options = {}) {
     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}バイト)を超えました`);
+    let body;
+    try {
+        const bytes = await readResponseBytes(response, maxBytes, new ScanToolError("output_too_large", `OSV APIのレスポンスがサイズ上限(${maxBytes}バイト)を超えました`));
+        body = new TextDecoder().decode(bytes);
     }
-    const body = await response.text();
-    // 文字数(UTF-16単位)ではなくUTF-8バイト数で判定する(マルチバイト本文のズレ防止)
-    if (Buffer.byteLength(body, "utf8") > maxBytes) {
-        throw new ScanToolError("output_too_large", `OSV APIのレスポンスがサイズ上限(${maxBytes}バイト)を超えました`);
+    catch (error) {
+        if (error instanceof ScanToolError)
+            throw error;
+        throw new ScanToolError("api_request_failed", "OSV APIのレスポンス本文を受信できませんでした");
     }
     try {
         return JSON.parse(body);

package/dist/osv/runner.js

@@ -4,7 +4,8 @@
  * セキュリティ設計(docs/DESIGN_TODO.md):
  * - シェルを経由しない`spawn`+引数配列で実行(コマンドインジェクション対策)
  * - OSV-Scannerへ渡す引数は固定リストのみ。呼び出し側から任意フラグは注入できない
- *   (対象パスは位置引数1つだけで、projectDetectorでrealpath解決済みの絶対パスを渡す)
+ *   (プロジェクトは検証済みディレクトリ1つ、実体スキャンは列挙済みのJAR/WAR絶対パスだけを渡す)
+ * - SBOMは検証・サイズ制限済みの専用一時コピー1つだけを渡す
  * - タイムアウトと出力サイズ上限を設ける(ハング・巨大出力によるDoS対策)
  *
  * 終了コード(2.4.0で実機確認):
@@ -38,12 +39,23 @@ const DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
 const MAX_STDERR_DETAIL_BYTES = 8 * 1024;
 /** OSV-Scannerに渡す固定引数。ここに無いオプションは一切使わない(ホワイトリスト) */
 const FIXED_SCAN_ARGS = ["scan", "source", "-r", "--format", "json"];
+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, projectDir, timeoutMs, maxOutputBytes) {
+function execOsvScanner(binaryPath, targetPaths, timeoutMs, maxOutputBytes, mode) {
     return new Promise((resolve, reject) => {
-        const child = spawn(binaryPath, [...FIXED_SCAN_ARGS, projectDir], {
+        const child = spawn(binaryPath, [
+            ...SCAN_ARGS[mode], ...targetPaths,
+        ], {
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -101,25 +113,43 @@ function execOsvScanner(binaryPath, projectDir, timeoutMs, maxOutputBytes) {
  *   絶対パスを渡すこと**(このレイヤーではパス検証を行わない)
  */
 export async function runOsvScan(projectDir, options = {}) {
+    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, "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, mode) {
     const limit = options.maxConcurrentScans ?? maxConcurrentScansFromEnv();
     if (activeScans >= limit) {
         throw new ScanToolError("too_many_concurrent_scans", `同時実行できるスキャンは${limit}件までです(現在${activeScans}件実行中)。実行中のスキャン完了後に再試行してください`);
     }
     activeScans++;
     try {
-        return await runOsvScanUnguarded(projectDir, options);
+        return await runOsvScanUnguarded(targetPaths, options, mode);
     }
     finally {
         activeScans--;
     }
 }
-async function runOsvScanUnguarded(projectDir, options) {
+async function runOsvScanUnguarded(targetPaths, options, mode) {
     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);
+    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 (mode !== "project" && result.exitCode === EXIT_NO_PACKAGES && result.stdout.trim() === "") {
+        return { results: [] };
     }
-    if (result.exitCode !== EXIT_NO_VULNS && result.exitCode !== EXIT_VULNS_FOUND) {
+    if (result.exitCode !== EXIT_NO_VULNS && result.exitCode !== EXIT_VULNS_FOUND &&
+        !(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);
     }
@@ -130,5 +160,5 @@ async function runOsvScanUnguarded(projectDir, options) {
     catch {
         throw new ScanToolError("invalid_output", "OSV-Scannerの出力をJSONとして解釈できませんでした", result.stdout.slice(0, 1000));
     }
-    return parseOsvScanOutput(parsed);
+    return parsed;
 }

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/scanJavaArtifact.js

@@ -0,0 +1,14 @@
+import { buildArtifactReport } from "../osv/artifactReport.js";
+import { runOsvArtifactScan } from "../osv/runner.js";
+import { detectJavaArtifacts } from "../utils/artifactDetector.js";
+import { errorResult, jsonResult } from "./toolResult.js";
+export async function handleScanJavaArtifact(args, options = {}) {
+    try {
+        const { artifactPaths } = await detectJavaArtifacts(args.artifact_path, options);
+        const raw = await runOsvArtifactScan(artifactPaths, options);
+        return jsonResult(buildArtifactReport(raw, artifactPaths));
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}

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/artifactDetector.js

@@ -0,0 +1,61 @@
+import { opendir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { ScanToolError } from "../errors.js";
+// Build output directories must be included for artifact scans.
+const SKIPPED_DIRS = new Set([".git", "node_modules", ".idea", ".vscode"]);
+const isArchive = (file) => /\.(jar|war)$/i.test(file);
+export async function detectJavaArtifacts(inputPath, options = {}) {
+    if (typeof inputPath !== "string" || inputPath.trim() === "" || !path.isAbsolute(inputPath)) {
+        throw new ScanToolError("project_not_found", "Specify an absolute JAR/WAR or directory path");
+    }
+    let targetPath;
+    try {
+        targetPath = await realpath(inputPath);
+    }
+    catch {
+        throw new ScanToolError("project_not_found", `Path does not exist: ${inputPath}`);
+    }
+    if (options.allowedRoot !== undefined) {
+        const root = await realpath(options.allowedRoot);
+        const relative = path.relative(root, targetPath);
+        if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new ScanToolError("path_outside_allowed_root", "Artifact path is outside the allowed root");
+        }
+    }
+    const info = await stat(targetPath);
+    if (info.isFile() && isArchive(targetPath))
+        return { targetPath, artifactPaths: [targetPath] };
+    if (!info.isDirectory()) {
+        throw new ScanToolError("no_scannable_artifacts", "The selected file is not a JAR/WAR archive");
+    }
+    const maxDepth = options.maxDepth ?? 8;
+    const maxArtifacts = options.maxArtifacts ?? 100;
+    const maxEntries = options.maxEntries ?? 10_000;
+    const artifactPaths = [];
+    let visited = 0;
+    const limitError = () => new ScanToolError("artifact_search_limit_exceeded", "Artifact discovery limit exceeded; select a smaller directory or an individual JAR/WAR");
+    async function walk(dir, depth) {
+        const entries = await opendir(dir);
+        for await (const entry of entries) {
+            if (++visited > maxEntries)
+                throw limitError();
+            const child = path.join(dir, entry.name);
+            if (entry.isFile() && isArchive(entry.name)) {
+                if (artifactPaths.length >= maxArtifacts)
+                    throw limitError();
+                artifactPaths.push(child);
+            }
+            else if (entry.isDirectory() && !SKIPPED_DIRS.has(entry.name)) {
+                if (depth >= maxDepth)
+                    throw limitError();
+                await walk(child, depth + 1);
+            }
+            // Dirent predicates do not follow symlinks. Never hand these to the scanner.
+        }
+    }
+    await walk(targetPath, 1);
+    if (artifactPaths.length === 0) {
+        throw new ScanToolError("no_scannable_artifacts", "No JAR/WAR archives found in the selected directory");
+    }
+    return { targetPath, artifactPaths: artifactPaths.sort() };
+}

package/dist/utils/readResponseBytes.js

@@ -0,0 +1,33 @@
+/** Read a fetch body without retaining more than the configured byte limit. */
+export async function readResponseBytes(response, maxBytes, sizeError) {
+    if (Number(response.headers.get("content-length")) > maxBytes) {
+        // Cleanup must not delay or replace the size-limit error.
+        void response.body?.cancel().catch(() => { });
+        throw sizeError;
+    }
+    if (response.body === null)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value.byteLength > maxBytes - total)
+                throw sizeError;
+            total += value.byteLength;
+            if (value.byteLength > 0)
+                chunks.push(value);
+        }
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        void reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

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.1.12",
+  "version": "0.3.0",
   "description": "MCP server that wraps Google's OSV-Scanner to scan Java projects for known vulnerabilities",
   "type": "module",
   "license": "Apache-2.0",
@@ -42,10 +42,10 @@
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "@vitest/coverage-v8": "^4.1.9",
+    "@types/node": "^26.5.0",
+    "@vitest/coverage-v8": "^5.0.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9"
+    "vitest": "^5.0.1"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",