Unified Agent の導入(Getting Started with the Unified Agent)
概要
このページでは、UnifiedAgentの使用を開始する方法について説明します。
前提条件
UnifiedAgentを実行するコンピュータに次のJavaバージョンのいずれかがあることを確認します 。
Java JDK 8
Java JRE 8
Java JDK 11
Java JDK 17
プロジェクトの種類に応じて、関連するパッケージマネージャーがインストールされていることを確認してください。
C＃ |
|
Elixir、Erlang | ミックス |
Go |
|
Haskell | カバール |
Java |
|
JavaScript |
|
Objective-C、Swift | CocoaPods-プロジェクトがビルドされていない場合にのみ必要 |
OCaml | Opam |
PHP | Composer-プロジェクトがビルドされていない場合にのみ必要 |
Python |
|
R | Packrat-使用する場合 |
Ruby | バンドラー |
Rust | Cargo-プロジェクトが構築されていない場合にのみ必要 |
Scala | SBT |
統合エージェントの使用法の概要
1 | |
2 | |
3 | 次のいずれかを実行します。
（このページの実行例を参照してください） |
4 |
UnifiedAgentのダウンロード
Unified Agentの最新バージョンは、 AmazonS3またはGitHubから ダウンロードできます。
22.3.2 | 20-03-2022 |
以前のUnifiedAgentバージョン
注：Unified Agentバージョンは、リリース後1年間利用可能であり、サポートされます。
ユニファイドエージェントの設定
統合エージェントを構成するには、いくつかの方法があります。
環境変数（推奨）
設定ファイルで使用可能なすべてのパラメータは、環境変数を使用してUnifiedAgentに渡すことができます。詳細については、こちらを参照してください。設定ファイル
-c引数を使用して、コマンドラインで設定ファイルをUnifiedAgentに渡すことができます。ファイルが指定されていない場合、UnifiedAgentはwss-unified-agent.config現在の作業ディレクトリで指定された設定ファイルを探します。詳細については、こちらを参照してください。
デフォルトの構成設定を利用するには、空の構成ファイルを作成し、変更するパラメーターのみを追加することをお勧めします。参考までにこちらをご覧ください。コマンドラインパラメータ
UnifiedAgentは、コマンドラインオプションとパラメータをサポートしています。詳細については、こちらを参照してください。
構成は、次の優先順位で適用されます。
コマンドラインパラメータ
環境変数
構成ファイル
デフォルト値
完全な設定パラメータのリファレンスについては、 UnifiedAgentの設定パラメータの ページを参照してください。
最低限必要な構成パラメーターの設定
使用可能な方法のいずれかで、UnifiedAgentを実行するために次の設定パラメータを設定します。
APIキー | WS_APIKEY | apiKey | -apiKey | 組織の識別子。これは、WhiteSourceユーザーインターフェイスの[組織]セクションの[統合]ページにあります。このページを表示するには、管理者レベルのアクセス権が必要です。 |
WhiteSourceのURL | WS_WSS_URL | wss.url | -wss.url |
|
ユーザー・キー | WS_USERKEY | ユーザー・キー | -ユーザー・キー | 必須。ユーザーキーを生成する方法については、次のリンクを参照してください。 |
商品名 | WS_PRODUCTNAME | 商品名 | -製品 | スキャンの実行後に作成された製品の名前。 |
プロジェクト名 | WS_PROJECTNAME | projectName | -事業 | スキャンの実行後に作成されたプロジェクトの名前 |
スキャンのベストプラクティス
一般的なヒント
どのチームメンバーがスキャンしているかを確認するために、 ユーザーレベルのアクセスを強制できるようにしてuserKeyを要求します。
注：userKeyは、API呼び出しおよびgenerateScanReportなどのレポートパラメーターにも必要です。最適な検出は、アプリケーションの作成に使用された依存関係ファイルが利用可能なビルドが成功した後にスキャンするときに達成されます。
注：これにより、Unified Agentは、以下で説明するように、3つの検出方法すべてでライブラリを検出できるようになります。
検出方法
依存関係の解決
検出中、マニフェストファイル（Pythonのrequirements.txtなど）を使用して、使用されているパッケージの特定のバージョンを特定します。
バイナリとソースファイルのマッチングの概要
WhiteSource Unified Agentは、バイナリとソースファイル（.pyPythonの.jarファイルやJavaのファイルなど）も検出し、それらをWhiteSourceインデックスと照合します。
WhiteSourceは、バイナリファイルとソースファイルを、それらが発生した可能性が最も高いリポジトリ（GitHub、SourceForgeなど）と照合します。
WhiteSourceナレッジベースには、最大3億4,000万のファイルと最大4,500万のオープンソースプロジェクトが含まれています。
依存関係解決プロセスを利用して解決できる既知のパッケージがない場合は、ファイル照合方法が必要です。
一致したソースファイルごとに、そのソースの可能性のある発信元が独自のアルゴリズムを使用して決定されます。SmartMatch
詳細については、「ソースファイルの一致アルゴリズム：SmartMatch」を参照してください。既存の組織でSmartMatchを有効にすることをお勧めします。
SmartMatchは、新しく作成された組織に対してデフォルトで有効になっています。
サポートされているファイル形式には、ハッシュマッチングで現在サポートされているすべてのファイル形式が一覧表示されます。
バイナリ一致は、各ファイルの正確なハッシュに対してのみ発生します。
この機能は
fileSystemScan=false、デフォルト値がであるように設定することで無効にできますtrue。
ユニファイドエージェントの実行
コマンドラインからUnifiedAgentを実行するには、ビルドパイプラインの一部として、またはコードベースが配置されているディレクトリで、シェルスクリプトタスクで次のコマンドを実行します。
cd <your codebase directory>
Linux / macOS：
export WS_APIKEY=<your-api-key>export WS_USERKEY=<your-user-key>export WS_PRODUCTNAME=<your-product-name>export WS_PROJECTNAME=<your-project-name>export WS_WSS_URL=https://saas.whitesourcesoftware.com/agentjava -jar wss-unified-agent.jar
ウィンドウズ：
set WS_APIKEY=<your-api-key>set WS_USERKEY=<your-user-key>set WS_PRODUCTNAME=<your-product-name>set WS_PROJECTNAME=<your-project-name>set WS_WSS_URL=https://saas.whitesourcesoftware.com/agentjava -jar wss-unified-agent.jar
ノート：
-dパラメータを指定して、現在の作業ディレクトリ以外の別のディレクトリをスキャンします。
フルパスまたは相対パスを使用できますが、スペースを含むパスは二重引用符で囲む必要があります（""）。
スキャン手順と概要の表示と理解
Unified Agentコマンドラインインターフェイスを使用すると、スキャンの一部として実行されたステップを表示し、各ステップにかかった時間を理解できます。
開始/終了表示
スキャンステップごとに開始/終了表示が表示されます。例えば：
1
2
3
4
5
6
7
8
9
10
11
12
------------------------------------------------------------------------
-------------------- Start: Pre-Step & Resolve Dependencies ------------
------------------------------------------------------------------------
[INFO] [2019-03-07 13:58:02,775 +0200] - Trying to resolve MAVEN dependencies
[INFO] [2019-03-07 13:58:02,776 +0200] - topFolder = C:\Users\Me\Desktop\UAtests\GenerateScanReport\generateScanReport\Data
[INFO] [2019-03-07 13:58:07,105 +0200] - Start parsing pom files
[INFO] [2019-03-07 13:58:07,112 +0200] - End parsing pom files , found : search-engine,search-engine-client,search-engine-server
[INFO] [2019-03-07 13:58:07,191 +0200] - Trying to resolve HTML dependencies
[INFO] [2019-03-07 13:58:09,113 +0200] -
------------------------------------------------------------------------
-------------------- End: Pre-Step & Resolve Dependencies --------------
------------------------------------------------------------------------
要約表
スキャンの最後に、各ステップに関連するすべての情報を含む要約も表示されます。次の列が含まれています。
ステップ：スキャンの関連するステップ
完了ステータス： 「COMPLETED」または「FAILED」のいずれか
経過： そのステップにかかった時間。サブステップは、合計経過実行時間には含まれないことに注意してください（Maven、HTMLなど）。
コメント： 利用可能な場合は、ステップに関する詳細情報。
例えば：
1
2
3
4
5
6
7
8
9
10
11
12
13
Step Completion Status Elapsed Comments
======================================================================================================================================================
Fetch Configuration COMPLETED 00:00:00.078 --------
Scan Files Matching 'Includes' Pattern COMPLETED 00:00:00.014 1 source/binary files
Pre-Step & Resolve Dependencies COMPLETED 00:00:06.378 7 total dependencies (7 unique)
MAVEN COMPLETED 00:00:04.416 5 total dependencies (5 unique)
HTML COMPLETED 00:00:01.922 2 total dependencies (2 unique)
Update Inventory COMPLETED 00:00:01.551 2 updated projects
======================================================================================================================================================
Elapsed running time: 00:00:08.021
======================================================================================================================================================
Process finished with exit code SUCCESS (0)
実行例
以下は、UnifiedAgent実行のさまざまな使用例の構文例です。
インライン環境変数を使用したUnifiedAgentの実行：
export WS_APIKEY=<your-api-key>export WS_USERKEY=<your-user-key>WS_PRODUCTNAME=<your-product-name> WS_PROJECTNAME=<your-project-name> java -jar ./wss-unified-agent.jar
設定ファイルを使用したUnifiedAgentの実行：
java -jar ./wss-unified-agent.jar -c /path/to/config/file -d /directory/to/scan
複数のフォルダまたはファイルでUnifiedAgentを実行する：
export WS_APIKEY=<your-api-key>export WS_USERKEY=<your-user-key>export WS_PRODUCTNAME=<your-product-name>export WS_PROJECTNAME=<your-project-name>java -jar ./wss-unified-agent.jar -d /directory/to/scan,/directory/to/scan2,/file/to/scan
ポリシーチェックを使用してUnifiedAgentを実行し、CI / CDパイプラインを切断するためにエラーコードを返します。
export WS_APIKEY=<your-api-key>export WS_USERKEY=<your-user-key>export WS_PRODUCTNAME=<your-product-name>export WS_PROJECTNAME=<your-project-name>export WS_CHECKPOLICIES=trueexport WS_FORCECHECKALLDEPENDENCIES=trueexport WS_FORCEUPDATE=trueexport WS_FORCEUPDATE_FAILBUILDONPOLICYVIOLATION=truejava -jar ./wss-unified-agent.jar
プロキシを使用したUnifiedAgentの実行：
export WS_APIKEY=<your-api-key>export WS_USERKEY=<your-user-key>export WS_PRODUCTNAME=<your-product-name>export WS_PROJECTNAME=<your-project-name>export WS_PROXY_HOST=<your-proxy-host-name>export WS_PROXY_PORT=<your-proxy-port-number>export WS_PROXY_USER=<your-proxy-username>export WS_PROXY_PASS=<your-proxy-password>java -jar ./wss-unified-agent.jar
CI / CDパイプラインとWhiteSourcePrioritizeの実行に関する追加の例は、https://github.com/whitesource-ft/ws-examplesにあります。