Google製OSV-ScannerをMCPサーバーとして使える「OSV-Scanner-MCP」の v0.23.0 をnpmで公開しました。
これまでのスキャンでは、パッケージ名と版をapi.osv.devに送って照会していました。閉じたネットワークの環境では使えず、社内のパッケージ名を外に出したくない場合にも困ります。
今回、事前に用意したOSVのデータベースだけでスキャンするオフラインモード を追加しました。
既定はこれまでどおりオンラインです。オフラインモードは、明示的に有効にしたときだけ使われます。
1. データベースの準備
ネットワークにつながるマシンで、必要なエコシステムのデータベースを取得します。
READMEではソースを取得してビルドした状態で説明しています。
npm ci
npm run build
node dist/index.js cache --ecosystems npm,PyPI --directory /absolute/offline-cache
- 取得するのは、OSVが公開しているエコシステムごとの
all.zip(https://osv-vulnerabilities.storage.googleapis.com)だけです - プロジェクトのファイルは読みません。パッケージ名や版も送りません。送るのは選んだエコシステムの名前だけです
- 対応するデータベース:
Maven・npm・PyPI・Go・crates.io・Packagist・NuGet - 更新は同じコマンドです。選ばなかったデータベースはそのまま残り、更新に失敗したときは前のmanifestが残ります
manifest.jsonとobjects/を含む キャッシュのディレクトリをまるごと オフラインのマシンに移します。サーバー本体とその依存、OSとアーキテクチャに合ったOSV-Scannerのバイナリも別途用意してください(このコマンドはそれらを取得しません)。
2. オフラインでスキャンする
MCPクライアントの設定で、環境変数を指定してサーバーを起動します。
{
"command": "node",
"args": ["/opt/osv-scanner-mcp/dist/index.js"],
"env": {
"OSV_MCP_OFFLINE": "1",
"OSV_MCP_OFFLINE_DB_DIR": "/opt/offline-cache",
"OSV_SCANNER_PATH": "/opt/bin/osv-scanner",
"OSV_MCP_ALLOWED_ROOT": "/projects"
}
}
切断されたマシンでnpxを使うと、npmパッケージの取得が必要になることがあります。サーバーは先にインストールしておいてください。
scan_project・scan_java_project・scan_java_artifact・scan_sbomと、suggest_fixのスキャン部分がローカルのデータベースを使います。応答にはoffline_databaseが加わり、取得した日時、SHA-256、「スナップショットであること」の注意が入ります。
失敗するときは「検出0件」ではなく失敗にする
オフラインで一番危ないのは、データベースが無い・壊れているのに「脆弱性0件」と返してしまうことです。そこで、次の場合は スキャン自体を失敗させます。
- データベースが無い、読めない
- 古すぎる(
OSV_MCP_OFFLINE_MAX_AGE_HOURS、既定168時間。1〜720で指定)、または日時が未来になっている - 内容がmanifestのSHA-256と合わない
また、スキャンごとに検証済みのデータベースの複製を使うので、スキャン中に更新が走っても、読んでいるバイト列は変わりません。
ネットワークには一切フォールバックしない
オフラインモードでは、次をすべて止めます。
- deps.devによる推移的な依存の解決(
pom.xmlやrequirements.txtだけの場合より、lockfileのほうが確実です) - OSV APIへの照会
- OSV-Scannerバイナリの自動ダウンロード(チェックサムを確かめた取得済みのバイナリは再利用できます。
OSV_SCANNER_PATHでの指定も可)
オフラインモードが有効な間は、データベースの準備(cache)も拒否します。
このリリースでオフラインではできないこと
-
explain_vulnerabilityはAPIに問い合わせず、エラーを返します -
suggest_fixは、スキャンで得た影響範囲から推奨の版を計算します。ただし、その候補をAPIやローカルのデータベースで確かめ直すことはしません。candidate_checkはdisabledになり、理由が添えられます - Git/VCSの参照を含むlockfileは拒否します。オフラインの照合ではコミットを確かめられないためです
- ローカルのスナップショットでは、それより新しい勧告が無いことは言えません
容量の上限
- データベースのZIPは1つ512 MiBまで、キャッシュ全体で2 GiB・128個まで
- 更新のたびに、選ばれているmanifestが参照しなくなったオブジェクトと、中断したダウンロードの残りを消します。残るのは、選ばれている世代と新しく取得した世代だけです
- スキャンごとの複製に、一時領域を最大2 GiB使うことがあります
開発: 製品と研究のテストを分けました
npm test(prepublishOnlyが実行するもの)は、製品の範囲だけを試験するようにしました。研究用の検証記録を再現するテストはnpm run test:researchで実行します。研究の記録は、計測したときのpackage.json・package-lock.jsonのバイト列まで固定しているので、計測したコミットでの証拠として扱います。
導入
Node.js 22.13以上が必要です。Claude Codeの場合:
claude mcp add osv-scanner -- npx -y osv-scanner-mcp
既に使っている方は、npx -y osv-scanner-mcpであれば次の起動時に最新版になります(版を固定している場合は更新してください)。オフラインモードの手順はREADMEの「Offline mode and database preparation」とオフライン検証の手順にあります。
まとめ
ネットワークにつながらない環境でも、事前に用意したOSVのデータベースでスキャンできるようになりました。
確かめられないデータで「0件」を返すより失敗を返すこと、ネットワークに黙ってフォールバックしないことを優先しています。
不具合や改善案はGitHub Issuesでお知らせください。