Scanning Projects with WhiteSource Prioritize

Overview

This scanning mode targets a single application and project folder in order to find effective open source vulnerabilities within your project.

Prerequisites

Supported Platforms

  • Microsoft Windows (Windows Server 2016; or Windows 10) 

  • Linux Ubuntu

  • Red Hat Enterprise Linux (with an installation of java-11-openjdk-devel)

Supported Languages

Language

Supported Environments

Notes

Language

Supported Environments

Notes

Java (including Scala and Kotlin)

Oracle JDK (8 or 11)
OpenJDK (8 or 11)
Zulu JDK (8 or 11)
Amazon Corretto (8 or 11) 

  • If the scanned project is in JDK8, it is possible to use either Java 8 or Java 11 for the Prioritize scan. If the scanned project is in JDK11, the Prioritize scan must also run with Java 11.0.2 or above in JDK11 (LTS versions only).

  • Project profiles: Maven, Gradle, POJO (Project without Package Manager)

  • Supported analysis targets: .jar, .war, .ear 

JavaScript (Node.JS server-side only)

Node.JS (npm & yarn package managers)

  • Supported analysis target: package.json

  • NodeJS project should have a main entry specified by an existing index.js file or defined in package.json

Python

Projects with pip dependency manager, written and running in Python 3.5-3.8, or Python 2.7

Analysis is supported for Python projects with either a single requirements.txt file (pip format, with explicit references to PyPI) or a setup.py file.

  • Prior to analysis, all project and dependency .py files should be parsed without syntax errors.

  • Analysis is currently not supported for multi-module projects, or for frameworks

  • Analysis is supported for Python as a single-language project

  • Analysis is supported only for dependencies containing code in py files (dummy packages that only reference to other dependencies are not supported, binary python file like .so are not supported as well).

  • For analysis, the pip version (python.pipPath as specified in the Unified Agent configuration file) should be compliant with the Python version (python.path as specified in the Unified Agent configuration file) deployed on the relevant machine (i.e., the output of the following commands must be the same: [1] python -m pip –version [2] pip –version)

  • For analysis, any Python virtual environment (i.e., folder) must not be located under the folder that is being examined by EUA (i.e., referenced via the -d parameter)

C#

.NET Core 3.0 or 3.1 (LTS)

  • Scanned C# project: Any LTS version of .NET Core or .NET Framework (single module & single language C# projects).

  • Prioritize supports NuGet projects (csproj-based and packages.config)

    • NuGet project with packages.config will be supported only when Nuget version 5.4 and above is used.

  • Prioritize requires that the csproj uses "PackageReference", "ProjectReference" or "Reference" dependencies.

    • The Unified Agent will ignore the "Condition" in "ItemGroup" and will bring the dependencies under that "ItemGroup" (whether or not the "Condition" holds)

    • The Unified Agent will ignore "IncludeAssets", "ExcludeAssets" and "PrivateAssets" and will bring the corresponding "PackageReference" and its dependencies

Configuring WhiteSource Prioritize Parameters

The following parameters must be set in the Unified Agent configuration file (wss-unified-agent.config). Refer here for additional documentation regarding the Unified Agent configuration parameters.

Parameter

Usage

Description

Parameter

Usage

Description

wss.url

wss.url=https://saas.whitesourcesoftware.com/agent

 

enableImpactAnalysis

enableImpactAnalysis=True

Activate the analysis module within the Unified Agent scan.

apiKey

apiKey=organizationToken

 

productName

productName=YourSelectedProductName

 

resolveAllDependencies

resolveAllDependencies=False

Edit the resolveAllDependencies parameter to specify that all resolvers should be disabled, and only the specific resolver should be enabled. By default it is set to True, whereas for WhiteSource Prioritize scans it must be False.

Parameters for Java-based Projects

The following parameters must be set according to project’s package manager:

Package Manager

Parameters

Package Manager

Parameters

Maven

  • fileSystemScan=False

  • maven.resolveDependencies=True

  • maven.aggregateModules=True (False by default)

  • maven.downloadMissingDependencies=False (True by default)

    • It is recommended to download all the dependencies to the local repository before a Prioritize scan.

In case the local Maven cache folder is different than its default, it should also be set in the following parameter

  • maven.m2RepositoryPath

Gradle

  • fileSystemScan=False

  • gradle.resolveDependencies=True

  • gradle.aggregateModules=True (False by default)

  • gradle.downloadMissingDependencies=False (True by default)

    • It is recommended to download all the dependencies to the local repository before Prioritize scan.

In case the local Gradle cache folder is different than its default it should be set in the following parameter as well:

  • gradle.localRepositoryPath

POJO (without Package Manager)

  • fileSystemScan=true (default value)

  • includes=**/*.jar

In case of scanning Java project without a package manager the command line parameter -iaLanguage should be set to Java

Parameters for JavaScript-based Projects

The following are additional settings required by WhiteSource Prioritize for JavaScript-based projects:

  • fileSystemScan=False (True by default)

  • npm.resolveDependencies=True

  • npm.ignoreNpmLsErrors=False (default)

  • npm.resolveLockFile=False

In case of a Yarn based project, the following flag should be set:

  • npm.yarnProject=True

Parameters for Python-based Projects

In order to include only dependencies resolved by Python Package manager, the following parameter should be set before scanning Python Projects.

  • fileSystemScan=False (True by default)

  • python.resolveDependencies=True

The following are settings that impact WhiteSource Prioritize for Python-based projects with their default values. A detailed description of these parameters and their defaults is available in the Unified Agent Configuration Parameter documentation). Unless needed for a specific environment customization, these parameters must remain with their default values.

  • python.resolveHierarchyTree=True

  • python.ignoreSourceFiles=True

  • python.ignorePipInstallErrors=False

  • python.installVirtualenv=False

  • python.requirementsFileIncludes=[requirements.txt]

  • python.resolveSetupPyFiles=False

  • python.indexUrl=[default https://pypi.org/simple]

  • python.runPoetryPrepStep=False

  • python.resolvePipEditablePackages=False

  • python.runPipenvPreStep=False

  • python.pipenvDevDependencies=False

  • python.resolveGlobalPackages=False

  • python.path=python (default value, can be customized to a specific path)

  • python.pipPath= pip or pip3 depend on the required pip version (pip by default)

Parameters for C#-based Projects

The following are additional settings required by WhiteSource Prioritize for C#-based projects:

  • fileSystemScan=False (True by default)

  • nuget.runPreStep=True (False by default)

  • nuget.resolveDependencies=True

The following parameters must be set according to a project’s dependencies reference:

Dependencies Reference Method

Parameters

Dependencies Reference Method

Parameters

PackageReference (csproj based with assets.json)

  • nuget.resolveAssetsFiles=True

  • nuget.resolvePackagesConfigFiles=False

packages.config based (csproj and packages.config)

  • nuget.resolveAssetsFiles=False

  • nuget.resolvePackagesConfigFiles=True

Combined (default)

  • nuget.resolveAssetsFiles=True

  • nuget.resolvePackagesConfigFiles=True

Preparing the Project Package

Java

  • Build the project and generate a target folder including the jar file, as in the following example for Maven:

1 mvn -Dmaven.test.skip=true install
  • It is highly recommended that all the dependencies are already downloaded and stored locally in order to save time for the automated pre-steps during the scan.

JavaScript

  • Prioritize requires you to install any related project packages before the scan, by running the package manager (npm or yarn) install command:

1 npm install

C#

  • Prioritize requires that the .NET build command is successful in the scanning environment (i.e., the console message displays build succeeded).

Python

  • Prioritize requires you to install any related project packages before the scan, by running the following command:

1 pip install -r requirements.txt

Running the Unified Agent

Specify the command line used to analyze a given Project with the following parameters:

  • The location for a single binary target (e.g., .jar or .war) that WhiteSource Prioritize should scan (using the -appPath argument)

  • The location for the Project's folder (containing dependency manager files, e.g., .pom for Maven) that should be examined by the Unified Agent (using the -d argument)

Java

Specify the command line used to analyze a given Project as described in the figure above.

1 java -jar /UA-Agent/wss-unified-agent.jar -c /UA-Agent/wss-unified-agent.config -appPath /projectFolder/project.jar -d /projectFolder

Fast Scan Mode

By default, the analysis mode of WhiteSource Prioritize is Precise Scan. For Java Projects, there is an option to choose Fast Scan mode that will retrieve results in a shorter time, with the same level of shields accuracy but with less granular traces (for red shields, such traces will have a label induction in the results view). This can be done by adding the following optional parameter to the Java command line:

-euaMode 1

JavaScript 

Specify the command line used to analyze a given Project:

1 java -jar /UA-Agent/wss-unified-agent.jar -c /UA-Agent/wss-unified-agent.config -appPath /projectFolder/package.json -d /projectFolder
  • appPath - The location for a single target (package.json file under the project folder) that WhiteSource Prioritize will scan

    • JavaScript scans do not support appPath with spaces

    • NodeJS project should have a main entry specified by an existing index.js file or defined in package.json

  • d - The location for the Project's folder that will be examined by the Unified Agent

Python

Specify the command line used to analyze a given Project:

1 java -jar /UA-Agent/wss-unified-agent.jar -c /UA-Agent/wss-unified-agent.config -appPath /projectFolder/requirements.txt -d /projectFolder
  • appPath - The location for a single target (requirements.txt or setup.py file under the project folder) that WhiteSource Prioritize will scan

  • d - The location for the Project's folder that will be examined by the Unified Agent

C# 

Specify the command line used to analyze a given Project:

1 java -jar /UA-Agent/wss-unified-agent.jar -c /UA-Agent/wss-unified-agent.config -appPath /projectfolder/bin/Debug/netcoreapp3.1/project.dll -d /projectFolder
  • appPath - The path of the main managed assembly dll or exe file (as opposed to native assembly)

  • d - The path of the project's folder containing the .csproj file of the application that must be analyzed

Performance Optimization Tips (for all modes & languages)

  • It is recommended to use G1 garbage collector when scanning with WhiteSource Prioritize by adding the following to the Java command line:

1 -XX:+UseG1GC
  • Ensure 8GB of ram are available for the scan by adding the following to the Java command line:

1 -Xmx8g

Examining Analysis Exit Codes

The analysis will display the following EUA code at successful completion: [EUA000] Analysis completed successfully.

If the analysis reports an exit code other than [EUA000], the Unified Agent returns a [-100] exit code. Depending on conditions encountered during analysis, alternative exit codes may be displayed at completion - refer here for more details.