こんにちは。WhiteSourceによるオープンソースコンポーネントを特定する仕組みについて、前回は「脆弱性DB」と「Unified-Agent」それぞれの役割について説明しました。またその仕組みの中でオープンソースコンポーネントが特定できない主な原因もお伝えしました。
今回は オープンソースコンポーネントの検出漏れを減らすための設定についてご紹介します。

ユーザーが設定を変更できるのは、Unified-Agent と WhiteSource UI のみとなります。 脆弱性データベースは Whitesource社が管理しており、ユーザーが直接アクセスしたり設定を変更することは出来ません。

尚、本ブログは 前編の内容を前提に書いていますので、不明な用語や仕組みについては前編の方を参照してください。

Unified-Agent の 依存関係スキャン

設定の話に入る前に、Unified-Agent (以下、UA) の重要なスキャン機能である 「依存関係スキャン (Dependency scan)」について説明します。依存関係スキャンを知ることで、UAのスキャンの流れとスキャン設定についての理解をより深めることができます。

依存関係 (Dependency) とは、みなさんが開発しているソースコードが利用する オープンソースコンポーネントを始めとした外部ライブラリ のことです。外部ライブラリは 公開されているリポジトリやWebサイトからダウンロードし、開発プロジェクトで参照するように設定します。
最近ではこの外部ライブラリの取得や管理に パッケージマネージャーを活用することが多くなってきています。パッケージマネージャーを利用するメリットには次のようなことが挙げられます。

• 参照する外部ライブラリ情報を 設定ファイルに定義するだけで、必要な時に取得します。
• 外部ライブラリが更に参照している外部ライブラリといった、ライブラリ間の依存関係も検索して必要なライブラリを全てダウンロードします。
• 開発プロジェクトのリポジトリにダウンロードした外部ライブラリを保管する必要がありません。
• 外部ライブラリは一般的に、パッケージマネージャーがデフォルトで利用するリポジトリからダウンロードするため、ライブラリの取得元が明確です。

パッケージマネージャーを利用することで、利用する オープンソースコンポーネント を依存関係として、開発プロジェクト（のソースコード）と切り離して管理できます。

注) パッケージマネージャーは、ビルドツールの主要な機能の1つとして提供・利用することがあるためビルドツールの方が馴染みのある方もいるかと思います。ですが 本ブログで着目しているのはライブラリ管理であり、WhiteSourceのドキュメントにも Package Managerと記載されていることに準じて、パッケージマネージャーで統一して説明します。

これは WhiteSource が オープンソースコンポーネント を特定する面においても非常に効果的になります。なぜかと言うと、WhiteSourceがスキャンするべきファイルは、オープンソースコンポーネントが含まれている可能性があるファイルだからです。
パッケージマネージャーを利用していれば、そこで管理している依存関係だけをスキャンするだけでよく、プロジェクトで開発しているソースファイルをスキャンする必要が無くなります。更に脆弱性データベースは、パッケージマネージャーが通常利用しているリポジトリのコンポーネントを監視してファイルのSHA-1チェックサムやメタ情報を収集することで、オープンソースコンポーネントのマッチング精度を上げることも出来ます。

つまり、パッケージマネージャーを利用することで、Unified-Agentは、スキャンするべきファイルを絞ることができ、脆弱性データベースは、情報収集するべきオープンソースコンポーネントのリポジトリを絞り込むことが出来ることを意味します。

このような点から、WhiteSourceのUAのスキャンは、まず パッケージマネージャーの利用有無を確認し、依存関係をスキャンしてオープンソースコンポーネントを特定することから始めています。

2020/11/18 時点の Unified-Agent の最新バージョン 20.10.2 が対応しているパッケージマネージャーの一覧は以下の通りです。こちらは、WhiteSourceの こちらのドキュメントの情報を基に整理しております。内容に相違がある場合は WhiteSourceのドキュメントを正としてください。

(*1) この他、Bazal, Docker(イメージ / コンテナ), Linuxディストリビューションのパッケージマネージャー(Debian, RPM, Alpine, Arch Linux, DNF) なども依存関係スキャンが可能です。
(*2) ここに記載しているファイルがあれば、そのパッケージマネージャーを利用しているとみなします。
(*3) パッケージマネージャーに対応したファイル拡張子。詳細は後述します。
(*4) HTMLファイル (.html) があれば、インポート宣言しているライブラリを検索します。

依存関係スキャンが有効だと、ソースファイルはスキャンしない!?

UAは依存関係スキャンが実行できるパッケージマネージャーを検出すると、"そのパッケージマネジャーに対応する拡張子を持つファイルのスキャンをスキップする" 設定がデフォルトで定義されます。例えば C#のプロジェクトの場合、まず "*.csproj" を持つファイルを検出すると、NuGetを利用していると判断し、NuGetを利用して依存関係のスキャンを行います。依存関係スキャン後は 指定したディレクトリ配下のファイルのスキャンを実行しますが、"*.cs" ファイルを検出しても SHA-1チェックサム の計算といったスキャンをスキップします。

これは オープンソースコンポーネントは NuGetを使って管理しているので、"*.cs" などのソースファイルは オープンソースでは無い"プロジェクトで開発している"ソースコードと判断しているためです。このスキップする設定はデフォルトですが、ユーザー側で変更できます。設定ファイル「wss-unified-agent.config」を開きますと、"XXX.resolveDependencies" や "XXX.ignoreSourceFiles" (XXXにはパッケージマネージャーの名称が入ります) といったパラメータがコメントアウト(#) されているのが分かるかと思います。
UAではコメントアウトされているパラメータはデフォルト値がセットされます。 この2つのパラメータはそれぞれ以下の制御とデフォルト値を持ちます。

• XXX.resolveDependencies : そのパッケージマネージャーの依存関係スキャンを有効にするかどうか 。デフォルト値: True (有効）
• XXX.ignoreSourceFiles : そのパッケージマネージャーの依存関係スキャンを有効にした場合、ソースファイルのスキャンをスキップするかどうか。 (デフォルト値: True (スキップする）

つまり ".cs" などの開発ソースファイルをスキャンした場合はいずれかのパラメータのコメントアウトを外し「"nuget.resolveDependencies=Flase" にしてNuGetの依存性スキャンを行わない」と設定したり、「"nuget.ignoreSourceFiles=False" にしてファイルスキャンをスキップしない」と設定してください。

尚、設定ファイルのパラメータには、スキャンするファイルの拡張子やファイル名などを指定する "includes" および スキャンを除外する "excludes" があります。前述の設定変更に加え、これらのパラメータにもスキャンしたいファイルやスキャンしないファイルを正しく指定してください。
UAのパラメータの一覧は、こちらのドキュメントをご参照ください。 パッケージマネージャーによって設定できることが異なりますので、意図した通りにスキャンがされない場合はパラメータとその設定値を確認することをお薦めします。

それでもスキャンできない場合は

ここまでで 依存関係スキャンの仕組みとその設定について説明しました。しかしそれでもまだ 「WhiteSourceのページに結果が表示されない。」「想定していた結果が出力されない。」ということがあります。このような場合は詳細な原因を調査したり 疑わしい点について WhiteSource社に調査を依頼することになります。そのような調査のために役立つ設定をいくつかご紹介します。

Unified-Agentの実行ログのレベルをDEBUGレベルにする

UAのスキャン実行ログをDebugレベルにすることでより詳細な情報が取得できます。 Debugレベルのログを出力するには UAの実行コマンドに "-logLevel debug" パラメータを追加してください。

スキャンレポートを出力する

Debugレベルのログで確認してもエラーは出ておらず、ファイルのスキャンも実施されている。と言った場合は、実際に WhiteSourceのInventoryに登録された情報をスキャンレポートとして取得することができます。
スキャンレポートは、設定ファイルのパラメータ "generateScanReport" を "True" にし、"UserKey" の値に 管理者権限を持ったユーザーアカウントのUserKey (WhiteSourceUI のProfileから確認できます)を設定することで、スキャン実行時に出力されます。

wss-unified-agent.config ファイル(抜粋)

WhiteSourceのUser Profile から UserKeyをコピー

スキャンレポートは リンク先のようなフォーマットで出力され、UAでスキャンし、脆弱性データベースと突き合わせて特定したオープンソースコンポーネントの情報、および脆弱性情報が確認できるので、特定されているファイルと特定されていないファイルを把握することができます。

Unmatched Source Files 機能を使う

UAでスキャンしたSHA-1チェックサムと一致するファイルが脆弱性データベースに存在しなかった場合、オープンソースコンポーネントとして特定されずInventoryに登録されません。このため誤検出、更にはそのファイルの存在すら気づかない可能性があります。このようなリスクを回避する方法として、Unmatched Source File機能があります。
この機能を使うと、UAでスキャンしたが特定できなかったファイルの情報を Inventoryにアップロードします。WhiteSoruce UIでは Unmatched Source Files として検索できますので、検索したファイルが オープンソースコンポーネントであったり、脆弱性が存在する可能性があるなど、いわゆる偽陰性(False Negative)の疑いがあるとして、WhiteSource社に 検証を依頼することなどに活用できます。

Unmatched Source Files は、Projectダッシュボードの Librariesセクション の中の "<project名>_Unmatched_Source_Files" に格納されています。

ここに記載されているファイルのSHA-1チェックサムなどの情報を付けて、WhiteSoruce社に調査をリクエストします。

Unmatched Source Filesの設定は、WhiteSource UI から行います。詳細はこちらのページをご覧ください。

Matching Libraries by Filename 機能を使う

この機能は、"SHA-1チェックサム"から オープンソースコンポーネントとして特定できなかったファイルについて、そのファイル名と 脆弱性データベースに登録されているメタ情報で突き合わせることができます。この機能でスキャンされたファイルは、Inventoryでは "Matched by Finename" と表示されます。設定方法はこちらのページをご覧ください。

検索できたメタ情報のみで特定するため信頼性は下がりますが、Unmatched Source Files 機能と同様、偽陰性を発見することにつながります。ただしファイル名でも一致しなければ Inventoryには登録されないため、正常に特定できなかったファイルをよりInventoryに登録したい場合は、Unmatched Source Files 機能を利用したり、併用することをお薦めします。

まとめ

2回に渡りWhiteSourceがオープンソースコンポーネントとその脆弱性を特定する仕組みについて紹介しました。 みなさんのプロジェクトで利用している オープンソースコンポーネントを正確に特定する 一つのポイントとしては「パッケージマネージャーを活用する」ことが挙げられると思います。パッケージマネージャーを利用していなかったり、利用しているオープンソースコンポーネントの入手元を把握していない場合、オープンソースコンポーネントの特定漏れが多く発生する可能性があります。 その際には ログやレポート、Unmatched Source Files機能を使って、ファイルの特定漏れを検出することはできますが、そもそも自分達が利用しているオープンソースコンポーネントが何かを把握していないと、WhiteSourceのスキャン結果を正しく活用することが難しくなります。

オープンソースコンポーネントを正しく利用することで、WhiteSourceを使って脆弱性などの最新情報を素早く発見することが、プロジェクトの信頼性を向上することにつながると考えます。