Unified Agent の導入(Getting Started with the Unified Agent)



概要

このページでは、UnifiedAgentの使用を開始する方法について説明します。

前提条件

  1. UnifiedAgentを実行するコンピュータに次のJavaバージョンのいずれかがあることを確認します 。

    • Java JDK 8

    • Java JRE 8

    • Java JDK 11

    • Java JDK 17

  2. プロジェクトの種類に応じて、関連するパッケージマネージャーがインストールされていることを確認してください。

プロジェクトタイプ

パッケージマネージャー

プロジェクトタイプ

パッケージマネージャー

C#

  • NuGet + .Net

  • Paket

ElixirErlang

ミックス

Go

  • Dep

  • Godep

  • Vndr

  • Gogradle

  • Govendor

  • Gopm

  • Glide

  • Vgo

  • Modules

  • Bazel

Haskell

カバール

Java

  • Maven

  • Gradle

  • ANT

  • Bazel

JavaScript

  • Yarn-プロジェクトがビルドされていない場合にのみ必要

  • NPM-プロジェクトがビルドされていない場合(または検出がNPMを使用するように設定されている場合)にのみ必要です

  • Bower

Objective-C、Swift

CocoaPods-プロジェクトがビルドされていない場合にのみ必要  

OCaml

Opam

PHP

Composer-プロジェクトがビルドされていない場合にのみ必要

Python

  • Poetry

  • Pipenv

  • Conda

R

Packrat-使用する場合

Ruby

バンドラー

Rust

Cargo-プロジェクトが構築されていない場合にのみ必要

Scala

SBT

統合エージェントの使用法の概要

ステップ #

ステップ名

ステップ #

ステップ名

1

Unified Agentの最新バージョンをダウンロードして、 その整合性 を確認します。

2

ユニファイドエージェントを設定します。

3

次のいずれかを実行します。

(このページの実行例を参照してください)

4

WhiteSource組織ポータルで結果を表示します。

UnifiedAgentのダウンロード

Unified Agentの最新バージョンは、 AmazonS3またはGitHubから ダウンロードできます。

最新の統合エージェントバージョン

ファイル

特徴

発売日

最新の統合エージェントバージョン

ファイル

特徴

発売日

22.3.2

wss-unified-agent.jar

リリースノート22.3.2

20-03-2022

以前のUnifiedAgentバージョン

:Unified Agentバージョンは、リリース後1年間利用可能であり、サポートされます。  

バージョン

ファイル

特徴

発売日

MD5

コメントコメント

バージョン

ファイル

特徴

発売日

MD5

コメントコメント

バージョン

ファイル

特徴

発売日

MD5

コメントコメント

バージョン

ファイル

特徴

発売日

MD5

コメントコメント

22.3.1

wss-unified-agent.jar

リリースノート22.3.1

20-03-2022

該当なし

該当なし

22.2.2.2

wss-unified-agent.jar

リリースノート22.2.2.2

20-03-2022

該当なし

該当なし

22.2.2.1

wss-unified-agent.jar

リリースノート22.2.2.1

09-03-2022

該当なし

該当なし

22.2.2

wss-unified-agent.jar

リリースノート22.2.2

06-03-2022

該当なし

該当なし

22.2.1

wss-unified-agent.jar

リリースノート22.2.1

20-02-2022

該当なし

該当なし

22.1.2

wss-unified-agent-22.1.2.jar

リリースノート22.1.2

06-02-2022

該当なし

該当なし

22.1.1.1

wss-unified-agent-22.1.1.1.jar

リリースノート22.1.1.1

27-01-2022

該当なし

該当なし

22.1.1

wss-unified-agent-22.1.1.jar

リリースノート22.1.1

23-01-2022

該当なし

該当なし

21.12.2

wss-unified-agent-21.12.2.jar

リリースノート21.12.2

09-01-2022

該当なし

該当なし

21.12.1

wss-unified-agent-21.12.1.jar

リリースノート21.12.1

26-12-2021

9F459173DD2F4A1B0BCA16E3387248D6

該当なし

21.11.2.1

wss-unified-agent-21.11.2.1.jar

リリースノート21.11.2.1

16-12-2021

C938CB75252B312961D16FBA3FC0F443

該当なし

21.11.2

wss-unified-agent-21.11.2.jar

リリースノート21.11.2

12-12-2021

1EEDF78497CD5801D152B19CC7E65C69

該当なし

21.11.1

wss-unified-agent-21.11.1.jar

リリースノート21.11.1

28-11-2021

BA19E92BC8B508AA93CC7652EC878B1B

該当なし

21.10.2

wss-unified-agent-21.10.2.jar

リリースノート21.10.2

14-11-2021

90A989C0D60A70FCC9A62AF2D54F5E9B

該当なし

21.10.1

wss-unified-agent-21.10.1.jar

リリースノート21.10.1

31-10-2021

74BB03F271E93CAB9FD3710FC6B786DB

該当なし

21.9.1.1

wss-unified-agent-21.9.1.1.jar

リリースノート21.9.1.1

25-10-2021

706694E349EA14CB04C4621B70D99A93

該当なし

21.9.1

wss-unified-agent-21.9.1.jar

リリースノート21.9.1

17-10-2021

510303D7588212C666F16B042A05BC3F

該当なし

21.8.1.1

wss-unified-agent-21.8.1.1.jar

リリースノート21.8.1.1

31-08-2021

239DAD256F1E8BFAF7361FDEECE3E2CE

該当なし

21.8.1

wss-unified-agent-21.8.1.jar

リリースノート21.8.1

29-08-2021

5E066881180AB1C1C24748145F784B32

該当なし

21.7.2

wss-unified-agent-21.7.2.jar

リリースノート21.7.2

15-08-2021

90BE9617B380EF507C5D5ABE0191FCFA

該当なし

21.7.1

wss-unified-agent-21.7.1.jar

リリースノート21.7.1

01-08-2021

B18E7F9CACB80993151F4518F852710B

該当なし

21.6.3

wss-unified-agent-21.6.3.jar

リリースノート21.6.3

18-07-2021

B897BADFEBA66A39963717899E327F86

該当なし

21.6.2.2

wss-unified-agent-21.6.2.2.jar

リリースノート21.6.2.2

06-07-2021

BAC44FB66BE88130ECA094A37B81F527

該当なし

21.6.2

wss-unified-agent-21.6.2.jar

リリースノート21.6.2

04-07-2021

5E7FE501C0B1BEF76F64EE683B917012

該当なし

21.6.1

wss-unified-agent-21.6.1.jar

リリースノート21.6.1

20-06-2021

F2EB843816A572904954052756EB66E7

該当なし

21.5.2

wss-unified-agent-21.5.2.jar

リリースノート21.5.2

06-06-2021

8E51FDC3C9EF7FCAE250737BD226C8F6

該当なし

21.5.1

wss-unified-agent-21.5.1.jar

リリースノート21.5.1

23-05-2021

B50664F3840004A868D34D608030005C

該当なし

21.4.2

wss-unified-agent-21.4.2.jar

リリースノート21.4.2

09-05-2021

19ADD8EB5637DBD6BE63B9553576DAF9

該当なし

21.4.1

wss-unified-agent-21.4.1.jar

リリースノート21.4.1

25-04-2021

AD4F3747F519F83A2DF8963FF36D61B4

該当なし

21.3.2.1

wss-unified-agent-21.3.2.1.jar

リリースノート21.3.2.1

13-04-2021

707B193FEB891C1B40DD98A0B433ECA8

該当なし

21.3.2

wss-unified-agent-21.3.2.jar

リリースノート21.3.2

11-04-2021

C3576952F70F574FE6745E754A16A0EE

該当なし

21.3.1

wss-unified-agent-21.3.1.jar

リリースノート21.3.1

04-04-2021

C5639E304DEC915F664CE2B391D5A9D7

該当なし

ユニファイドエージェントの設定

統合エージェントを構成するには、いくつかの方法があります。

  • 環境変数(推奨)
    設定ファイルで使用可能なすべてのパラメータは、環境変数を使用してUnifiedAgentに渡すことができます。詳細については、こちらを参照してください。

  • 設定ファイル
    -c引数を使用して、コマンドラインで設定ファイルをUnifiedAgentに渡すことができます。ファイルが指定されていない場合、UnifiedAgentは wss-unified-agent.config 現在の作業ディレクトリで指定された設定ファイルを探します。詳細については、こちらを参照してください。
    デフォルトの構成設定を利用するには、空の構成ファイルを作成し、変更するパラメーターのみを追加することをお勧めします。参考までにこちらをご覧ください

  • コマンドラインパラメータ
    UnifiedAgentは、コマンドラインオプションとパラメータをサポートしています。詳細については、こちらを参照してください。

構成は、次の優先順位で適用されます。

  1. コマンドラインパラメータ

  2. 環境変数

  3. 構成ファイル

  4. デフォルト値

完全な設定パラメータのリファレンスについては、  UnifiedAgentの設定パラメータの ページを参照してください。

最低限必要な構成パラメーターの設定

使用可能な方法のいずれかで、UnifiedAgentを実行するために次の設定パラメータを設定します。

パラメータ名

環境変数名

構成ファイルのパラメーター名

コマンドラインパラメータ名 

説明

パラメータ名

環境変数名

構成ファイルのパラメーター名

コマンドラインパラメータ名 

説明

APIキー

WS_APIKEY

apiKey

-apiKey

組織の識別子。これは、WhiteSourceユーザーインターフェイスの[組織]セクションの[統合]ページにあります。このページを表示するには、管理者レベルのアクセス権が必要です。

WhiteSourceのURL

WS_WSS_URL

wss.url

-wss.url

/agent追加されたサーバーURL 。これは、WhiteSource UserInterfaceのIntegrateページのOrganizationセクションにもあります。このページを表示するには、管理者レベルのアクセス権が必要です。

例:https ://saas.whitesourcesoftware.com/agent

ユーザー・キー

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/agent
java -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/agent
java -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=true
export WS_FORCECHECKALLDEPENDENCIES=true
export WS_FORCEUPDATE=true
export WS_FORCEUPDATE_FAILBUILDONPOLICYVIOLATION=true
java -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にあります。