1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

OSV-Scanner-MCP v0.23.0: ネットワークにつながらない環境でも脆弱性をスキャンできるようにしてみた

1
Posted at

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でお知らせください。

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?