...

...

Overview and Default Behavior

If a scanned project uses a configuration file that contains only a defined projectName (where projectToken, productName and productToken are left empty), then the Unified Agent adds the results to the first project it finds in the organization that contains the same project name.
If a multi-module project is scanned with the same configuration as described above, and a project with one of the module names already exists, then the Unified Agent adds the module data to this existing project.

Example: Only 'projectName' is defined and 'projectToken’, ‘productName’ and ‘productToken’ are left empty

...

Changing the Default Behavior

In order to avoid overriding an existing project with the same name, from the Advanced Settings section of the Integrate page, select the checkbox Add project to default product when only project name is provided.

When this checkbox is selected, the following rules apply to all future scans:

...

The generated configuration will contain the list of recommended parameters based on the environment, and also the mandatory parameters: APIKey, ProductName, ProjectName/ProjectToken and Wss.URL. 

To use the Configuration Recommendation mode, do as follows:

1. In the folder that you want to scan, in the command line, enter java -jar unified_agent.jar -detect. 

2. In the folder that was scanned, access the generated file, wss-generated-file.config. 

3. Add the mandatory parameters to the file. 

4. Run the Unified Agent scan: java -jar unified_agent.jar -c wss-generated-file.config.

The includes parameter is supported by this feature, enabling WhiteSource to automatically identify the environment that the user wants to scan and create the configuration file automatically.

...

These exit codes are also available after the process ends, in the environment's last command's return value variable

(Linux: $?,  PowerShell:  $LASTEXITCODE,  Batch: %ERRORLEVEL%)

Exit Codes in Bash

The exit codes WhiteSource returns in the Bash command language should be treated as 'x' modulo 256: 

...

NOTE: The following protocols are supported: 'file://', 'ftp://', 'http://', 'https://'

...

By changing the configuration file to offline mode, any execution of the Unified Agent will store the current configuration and metadata in a JSON .txt file named update-request.txt, located in the newly-created 'whitesource' directory. It is located under the current working directory ($pwd or %cd%). This file can later be manually uploaded to WhiteSource from the Admin Console or via the command line.

...

Update the wss-unified-agent.config file:

• Change the offline property to true.

• For very large projects, it's recommended that you add the property offline.zip=true to reduce the size of the created file. This setting enables zipping the content of the output file.

• To prettify the output file to JSON format, add the offline.prettyJson=true property.

Uploading an Offline Request File 

Upload via command line with configuration file (supported from version 1.8.9): 

Before you begin this procedure, ensure these parameters are properly configured:

• apiKey

• wss.url

• projectName

Execute the Unified Agent with the -requestFiles flag specifying the path to the update-request.txt file you created in the previous step. In order to send more than one file, separate file names with a comma. 

java -jar <path to wss-unified-agent-*.jar> -c <path of config file> -requestFiles <file-path1>[,<file-path2>]

Upload via command line without configuration file (supported from version 1.8.9): 

• Execute the Unified Agent with the -requestFiles flag specifying the path to the update-request.txt file you created in the previous step. In order to send more than one file, separate file names with a comma.

...

For customers using SCM (Git, SVN, Mercurial), refer here for the relevant settings.

...

• Only descriptive information is sent to our servers. All of the processing is done locally on your machine.

• Dimensions CM is also supported by using either Git via Git Connector or Subversion via CM Bridge. 

• You cannot scan both a local repository and a remote repository simultaneously. If you are intending to scan a local repository and not a remote repository, then use the -d parameter instead of the SCM parameters that are described below. 

...

The scm client must be installed on your machine in order to successfully connect to your repository:

• Git

• SVN

• Mercurial

WhiteSource also supports on-premises installations of repositories. 

...

• For Git repositories, provide the repository URL and the branch or tag name. If no branch or tag is defined, it will default to the 'master' branch.

• For SVN repositories, provide the URL for the specific trunk, branch or tag. If no branch or tag is defined, it will default to the 'trunk' branch.

• For Mercurial repositories, provide the repository URL and the branch or tag name. If no is branch or tag is defined, it will default to the 'master' branch.

NOTE: If local files are to be scanned, then remove or comment out the scm parameters.

...

SSH is currently supported only for Git repositories.

Set the scm.ppk property to your private key file path and set the scm.pass property to the passphrase of the private key. If there are none, then leave empty.

...

Default Behavior 

When the failErrorLevel parameter is set to DEFAULT, the behavior of the exit codes stays the same.

Modifying the Default Behavior 

When the failErrorLevel parameter is set to ALL, the Unified Agent returns an error code for all errors in the scan, rather than SUCCESS. This can be useful for customers migrating from the plugins (NPM, MAVEN etc.) to the Unified Agent.

The parameter sets additional scenarios to error instead of success.The following cases are considered as 'Failure':

• resolver.runPrepStep failed (at least one)

• Error in collecting/running dependencies (at least one)

• When ‘productName’ and ‘productToken’ are missing, and no ‘projectToken’ is defined in the configuration file.

...

A summary report in JSON format can be automatically generated locally, in the 'whitesource' folder (created in the directory where the Unified Agent ran), at the end of each scan, using the 'generateScanReport' configuration parameter when running the Unified Agent.
This report includes information on vulnerabilities, policy violations, top fixes and inventory details.

• A JSON scan report which is controlled by the generateScanReport parameter.

• Policy violations reports (JSON and HTML), which are generated when a policy check is performed by the UA (via the checkPolicies parameter).

The default filename format of the JSON report is '<project_name>-<yyyy-mm-dd>T<HHmmss>+<UTC offset>-scan_report.json'. 
For example: 'Demo App-2019-06-04T181226+0300-scan_report.json'

The following configuration parameters are available to control timeouts and file name format for the report:
scanReportTimeoutMinutes: Time-out (in minutes) for the process of generating the scan report. If the timeout interval has passed then the report will not be generated, but the scan will continue.
scanReportFilenameFormat: Controls filename format of a generated scan report.

NOTES:

• Only Organization and Product Administrators can generate this report. The 'userKey' configuration parameter is mandatory for this option.

• In order to generate this report, the configuration parameter 'updateInventory' must be set to true.

• If 'checkPolicies' is set to true then 'forceUpdate' should also be set to true.

• If 'checkPolicies' is set to false then no policy related data will be generated in the report.

...

• If there is an issue with the Java heap size, depending on the machine resources, try to install a 64-bit Java Runtime and use the '–d64' along with the '–Xmx' and '–Xms' switches to increase the Java heap size.

Limitations

• The minimum file size for scanning is 512 bytes. The maximum file size for scanning is 2 GB.

• The Unified Agent supports UTF-8 locales. If other locales are in use, the Unified Agent generates an error when confronting special characters.

• Requests with more than one million dependencies will fail.

• The Maven dependencies detection is based on the Apache Maven Dependency Plugin. Maven projects that use version 3.2.0 of the Maven Dependency Plugin are not supported.

...