osv.devを読む：脆弱性データ、API、スキャナーを分けて運用する基盤

OSVデータベースとトリアージの役割

osv.devは、オープンソース脆弱性データベースとトリアージサービスです。READMEは、依存関係を調査し、OSV APIを通じて既知の脆弱性と照合する仕組みを説明しています。Web UIはosv.devに配備され、脆弱性情報を検索する画面として利用できます。

OSVの価値は、脆弱性識別子だけを並べることではなく、パッケージ名、版、影響範囲、修正版、エコシステムの情報を依存関係の調査へ結び付ける点にあります。ただし、READMEが示すのはサービスとコードの範囲です。自社の実行環境、設定、到達可能性、補完緩和策までを自動的に判定するとは書かれていません。検出結果は修正優先度を決める材料として扱い、最終的なリスク判定を別に行います。

データをAPIから取得するのか、GCSのダンプから内部処理するのか、Web UIで人が確認するのかで、更新遅延、権限、監査方法が変わります。各経路の取得日時とデータ版を記録し、同じ脆弱性情報を見た時点を追跡できるようにすることが必要です。

OSV-Scannerとosv.devリポジトリの分離

READMEは、依存関係をスキャンするGo製ツールを提供し、そのスキャナーがOSVデータベースへ照会すると説明しています。対象は各種ロックファイル、Debian Dockerコンテナ、SPDXとCycloneDXのSBOM、Gitリポジトリです。スキャナーはgoogle/osv-scannerという別リポジトリに置かれています。

この分離は、サービス本体と利用者向けCLIの責任を分けるものです。google/osv.devにはosv.devをGCPで動かすコードがあり、スキャナー側には依存関係を発見してAPIへ照会する処理があります。OSVのWeb UIが開けても、手元のロックファイルやSBOMが正しく解析されたとは限りません。入力形式、パッケージ名、版表記、依存解決結果をスキャンログで確認します。

SBOMを使う場合は、SPDXとCycloneDXの生成元、作成日時、対象イメージや成果物、コンポーネント識別子を記録します。Gitリポジトリのスキャンでは、対象コミットと取得権限を固定します。検出結果がない場合も、入力が空だったのか、未対応形式だったのか、脆弱性がなかったのかを区別します。READMEは各入力の精度や誤検知率を示していないため、CIへの組込み前に自社の代表データで確認してください。

GCSダンプとAPIを使うデータ経路

OSVのデータダンプはGCSバケットgs://osv-vulnerabilitiesから提供されます。READMEは、利用方法の詳細をデータダンプ文書へ案内しています。大量データを定期取得して社内索引や監査環境へ取り込みたい場合は、APIの逐次照会とダンプの一括取得を用途で分けられます。

一括データは、ネットワーク障害やAPI負荷を減らせる一方、取得時点と更新反映の遅れを管理しなければなりません。API応答と社内ダンプが同じ脆弱性情報を返さないとき、取得日時、データ版、対象パッケージ、比較結果を記録します。READMEはデータの更新周期、保持期間、可用性、レート制限を説明していません。これらを前提にした運用を組む場合は、公式文書と実際の取得結果を別に確認します。

APIドキュメントはgoogle.github.io/osv.dev/api/にあり、総合文書も同じサイトにあります。実装では、API障害、応答遅延、未知のエコシステム、版表記の不一致、データ欠損を個別のエラーとして扱います。取得失敗時に「脆弱性なし」と表示する設計は、未確認を安全と誤認させます。最後に成功したデータ版を表示し、古い結果であることを利用者へ伝えるのが適切です。

GCP構成を支えるディレクトリ分担

このリポジトリは、GCP上でosv.devを動かすためのコードを含みます。bindingsにはOSV APIの言語バインディングがあり、現時点ではGoのみです。deploymentにはTerraformとCloud Deployの設定、一部のCloud Build YAMLがあります。dockerにはCI、デプロイ、Terraform、ESP、ワーカー用のイメージ定義があります。

データと処理の層も分かれています。gcp/datastoreはDatastoreのindex.yaml、gcp/functionsはPyPI脆弱性を公開するCloud Function、gcp/indexerは版を決めるindexer、gcp/websiteはWeb UIのバックエンドとfrontend3、gcp/workersはvanir_signaturesとoss_fuzz_workerのPythonワーカーを担当します。ディレクトリ名は構成の入口を示しますが、個別サービスの可用性やデプロイ順序を保証するものではありません。

ローカル構築では、READMEがgit submodule update --init --recursiveを求めています。サブモジュールを取得しないと、一部のビルドや生成手順が成立しない可能性があります。Goの共有ライブラリとコマンドはgoにあり、cmd/api、cmd/importer、cmd/worker、cmd/exporter、cmd/recoverer、cmd/relationsなどが挙げられています。Python側のosvにはコアライブラリ、エコシステム版管理ヘルパー、Datastoreモデルがあります。GoとPythonの責任範囲を分けて調査するのが安全です。

脆弱性フィードとエコシステムの変換

vulnfeedsには、主にNVDのCVEを変換するGoモジュールがあります。Alpine向けのcmd/alpine、Debian向けのtools/debianも含まれ、Debianのフィード変換はPythonで書かれています。外部脆弱性情報をOSVの形式へ取り込む層があるため、元フィードの識別子、変換規則、影響版、修正版の対応を確認する必要があります。

変換処理を通った情報が自社のパッケージ名へ正しく結び付くかは、エコシステムと版表記に左右されます。OSVデータベースにエントリがあっても、ロックファイルの名前、配布物の名前、SBOMの識別子が一致しなければ期待する検出になりません。スキャン前に対象パッケージを正規化し、スキャン後に元の依存関係と検出結果を対応付けます。

OSVデータだけで修正方針を決める場合は、影響を受ける版、修正版、利用中の版、実行経路、公開範囲、緩和策を別欄に置きます。READMEはフィード変換の存在を説明しますが、各変換の完全性、更新遅延、誤検知、修正判断を保証していません。重要な依存関係では、対象パッケージの公式アドバイザリと照合し、結果の根拠を監査記録へ残します。

貢献、文書、第三者ツールの境界

READMEはコード、データ、文書への貢献を歓迎し、それぞれのContributing手順へ案内しています。質問や提案はGitHub Issue、議論はosv-discussメーリングリストを使えます。文書変更、脆弱性データ追加、コード変更は影響範囲が違うため、変更内容、根拠、対象エコシステム、検証結果を分けて提出します。

OSVを使う第三者ツールとして、Cortex XSOAR、dep-scan、Dependency-Track、GUAC、OSS Review Toolkit、pip-audit、Renovate、TrivyがREADMEに列挙されています。これらはコミュニティ製であり、コアOSVメンテナーがサポートまたは推奨するものではありません。ツール名が公式READMEに掲載されていることを承認や動作保証と解釈せず、各プロジェクトの版、接続方法、結果形式、保守担当を個別に確認します。

適合性を評価する資料としてOpenSSFのConcise Guide for Evaluating Open Source Softwareも案内されています。導入評価では、データ供給、スキャン頻度、修正担当、例外承認、監査保存、通知経路を決めます。第三者ツールをCIへ組み込む場合も、OSVの検出結果とツール固有の判定を別に記録し、片方の停止が全体を「安全」と見せないようにします。

Apache-2.0と脆弱性対応の採用条件

リポジトリのライセンスはApache License 2.0です。著作権表示、ライセンス文、変更表示、NOTICE、特許条項など、配布形態に応じた条件を確認します。Apache-2.0であることは、OSVデータ、外部フィード、第三者ツール、取得したSBOM、各パッケージの利用条件を一つにまとめるものではありません。コード、データ、依存部品、生成物の権利を分けて管理してください。

脆弱性対応の運用では、検出、影響判定、修正、例外承認、再スキャン、完了確認を別の状態にします。OSV APIが返した結果を受け取っただけでは、実行中のサービスが影響を受けるか、修正版へ更新できるか、緩和策が有効かは確定しません。修正した版、再生成したSBOM、再スキャン日時、残存理由を監査記録へ残します。

素材のリポジトリ情報では、最新版リリースとしてv0.1.3、デフォルトブランチはmaster、アーカイブ済みではないことが確認できます。これは取得時点のメタデータであり、サービスの長期保守や対応時間を保証しません。採用前に公式文書、API仕様、データダンプ、スキャナーの版、自社の依存関係を照合し、取得不能時の代替と期限超過時のエスカレーションを決めることが必要です。

CIと監査へOSV結果を組み込む方法

OSVの検出を開発工程へ組み込む場合は、入力取得、依存解決、脆弱性照会、影響判定、修正確認を別の処理として記録します。ロックファイルは生成に使ったマニフェスト、解決日時、対象ブランチ、コミットと結び付けます。SBOMは作成元、作成日時、対象イメージ、コンポーネント識別子、署名の状態を記録します。Gitリポジトリを調べる場合は、対象コミットと取得権限を固定し、作業ツリーの未追跡ファイルを含むかを明示します。

検出結果は、未評価、影響あり、影響なし、修正中、例外承認、再確認済みという状態へ分けます。OSVの脆弱性情報が利用中のパッケージへ一致しても、実行経路、利用機能、権限、到達可能性を見て影響を判定します。修正版が存在する場合は、更新による互換性、データ移行、停止時間、依存関係の連鎖を確認し、直ちに更新できない場合は期限、緩和策、承認者を記録します。

CIを失敗させる条件は、脆弱性の重大度だけでなく、対象が本番に到達するか、修正版があるか、例外期限を過ぎたかで定義します。OSVの結果が取得できなかった場合は、無害と扱わず、検査未完了として通知します。データダンプが古い場合も、最後に成功した版と取得日時を表示します。APIの一時障害、入力形式の未対応、パッケージ名の不一致、脆弱性データの欠損を別のエラーとして扱うことで、誤った安全判定を防げます。

修正後は、依存ファイル、生成SBOM、スキャンログ、OSV照会日時、修正版、テスト結果を一つの変更記録へ束ねます。再スキャンで結果が消えたときも、データ更新による変化、パッケージ変更、誤検知判定を区別します。第三者ツールを使う場合は、OSV-Scanner、Dependency-Track、pip-audit、Trivyなどの結果形式とOSV APIの結果を比較し、どのツールが最終判定を出したかを明記します。

社内監査では、依存関係の一覧、検出された識別子、影響を受ける版、修正版、対応責任者、対応期限、例外理由、再確認日を保存します。個人情報や秘密情報を含むログは必要最小限にし、SBOMやリポジトリ情報の閲覧権限を制限します。READMEは保存期間、権限、通知時間、復旧手順を定めていないため、組織の規程と脆弱性対応計画へ落とし込みます。OSVは検出と情報提供の基盤であり、修正を完了させる責任は利用組織に残ります。

監査結果を配布するときは、検査対象、検査日時、使用したスキャナー版、照会したOSVデータ版、検出件数、未評価件数を添付します。依存関係が変わった時点で再スキャンし、古い判定を新しい成果物へ流用しません。脆弱性情報を外部へ送る場合は、非公開パッケージ名や内部リポジトリ名が漏れないよう入力を確認します。修正期限を過ぎた項目は責任者へ通知し、例外を恒久的な未処理状態にしない運用を設けます。

組織の責任者は、脆弱性の重大度、公開経路、顧客影響、修正難度、期限を基準に対応順を決めます。検出結果を開発者だけへ渡さず、運用、法務、監査、サービス責任者へ必要な範囲で共有します。OSVのデータ更新で判定が変わったときは、変更理由と再評価者を記録します。検査対象と対象外を明確にし、対象外を安全と表現せず、未確認として管理します。判定責任と承認責任を明確に分け、対応履歴を保存します。

編集部の結論

osv.devは、オープンソース依存関係の既知脆弱性を調査し、OSV APIやデータダンプを自社の開発・監査処理へ組み込みたいチームに向いています。リポジトリにはGCP上でサービスを動かすコード、GoとPythonの共有部品、データ取り込み、索引、Web UI、ワーカー、フィード変換が含まれ、スキャナーは別リポジトリとして管理されています。一方、検出結果が自社環境の安全を保証するわけではなく、第三者ツールはコアメンテナーの支援対象ではありません。採用前に対象エコシステム、SBOM形式、データ更新、誤検知、対応期限、障害時の代替を確認してください。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes