osv-scanner-mcp 0.1.12 → 0.2.0

package/README.md

@@ -12,6 +12,7 @@ Google製 [OSV-Scanner](https://github.com/google/osv-scanner) をラップす
 ## 特徴
 
 - **ワンショットスキャン**: `scan_java_project` ツールにプロジェクトパスを渡すだけで、検出→スキャン→整形済みレポートまで一気に返します
+- **JAR/WAR実体スキャン**: `scan_java_artifact` ツールで、lockfileが無い・shaded/fat JARしか手元にないプロジェクトでもアーカイブ内メタデータから既知の脆弱性を検出します(ベストエフォート同定であることを明示するcoverage情報付き)
 - **深刻度順のレポート**: パッケージごとに脆弱性をCVSSスコア順に整理し、5段階の深刻度ラベル(critical / high / medium / low / unknown)とサマリ集計付きで返します
 - **修正版の提示**: 各脆弱性の `fixed_versions` をMavenバージョン優先順位規則で正しくソートして含めます(`2.17.1-RELEASE` のようなsemver非対応の表記にも対応)
 - **セキュリティ第一の設計**: シェル非経由の実行・引数ホワイトリスト・パス正規化と境界チェック・タイムアウト/出力サイズ上限を実装段階から組み込んでいます
@@ -178,6 +179,33 @@ 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レベルのメモリ制限やサンドボックスを提供するものではありません。
+
 ### `suggest_fix`
 
 スキャンを実行し、脆弱なパッケージごとに**推奨アップグレードバージョン**を提案します。単純な最大バージョンではなく、現在のバージョンに最も近いリリース系統の修正版を3段階フォールバックで選定します:
@@ -297,6 +325,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,7 @@ 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 { handleSuggestFix } from "./tools/suggestFix.js";
 import { ALLOWED_ROOT_ENV, allowedRootStartupError, allowedRootStartupWarning, } from "./utils/startupConfig.js";
 export { ALLOWED_ROOT_ENV };
@@ -32,7 +33,7 @@ if (startupWarning !== null) {
 // NOTE: リリース時はpackage.jsonのversionと同じ値に更新すること
 const server = new McpServer({
     name: "osv-scanner-mcp",
-    version: "0.1.12",
+    version: "0.2.0",
 });
 server.registerTool("scan_java_project", {
     title: "Javaプロジェクトの脆弱性スキャン",
@@ -74,6 +75,15 @@ 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] }));
 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,7 @@
  * セキュリティ設計(docs/DESIGN_TODO.md):
  * - シェルを経由しない`spawn`+引数配列で実行(コマンドインジェクション対策)
  * - OSV-Scannerへ渡す引数は固定リストのみ。呼び出し側から任意フラグは注入できない
- *   (対象パスは位置引数1つだけで、projectDetectorでrealpath解決済みの絶対パスを渡す)
+ *   (プロジェクトは検証済みディレクトリ1つ、実体スキャンは列挙済みのJAR/WAR絶対パスだけを渡す)
  * - タイムアウトと出力サイズ上限を設ける(ハング・巨大出力によるDoS対策)
  *
  * 終了コード(2.4.0で実機確認):
@@ -38,12 +38,18 @@ 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 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, artifactMode) {
     return new Promise((resolve, reject) => {
-        const child = spawn(binaryPath, [...FIXED_SCAN_ARGS, projectDir], {
+        const child = spawn(binaryPath, [
+            ...(artifactMode ? FIXED_ARTIFACT_ARGS : FIXED_SCAN_ARGS), ...targetPaths,
+        ], {
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -101,25 +107,39 @@ function execOsvScanner(binaryPath, projectDir, timeoutMs, maxOutputBytes) {
  *   絶対パスを渡すこと**(このレイヤーではパス検証を行わない)
  */
 export async function runOsvScan(projectDir, options = {}) {
+    return parseOsvScanOutput(await runScan([projectDir], options, false));
+}
+/** 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);
+}
+async function runScan(targetPaths, options, artifactMode) {
     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, artifactMode);
     }
     finally {
         activeScans--;
     }
 }
-async function runOsvScanUnguarded(projectDir, options) {
+async function runOsvScanUnguarded(targetPaths, options, artifactMode) {
     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, artifactMode);
+    if (result.exitCode === EXIT_NO_PACKAGES && !artifactMode) {
+        throw new ScanToolError("no_packages_found", `OSV-Scannerがスキャン対象のパッケージを検出できませんでした: ${targetPaths[0]}(pom.xmlに依存関係が定義されているか確認してください)`, result.stderr);
+    }
+    if (artifactMode && 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 &&
+        !(artifactMode && 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 +150,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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osv-scanner-mcp",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "MCP server that wraps Google's OSV-Scanner to scan Java projects for known vulnerabilities",
   "type": "module",
   "license": "Apache-2.0",
@@ -42,7 +42,7 @@
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.5.0",
     "@vitest/coverage-v8": "^4.1.9",
     "typescript": "^7.0.2",
     "vitest": "^4.1.9"