Scanning Projects with Mend 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

Java (including Scala and Kotlin)

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

If the scanned project is in JDK8, it is possible to use Java 8, Java 11, or Java 17, 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) or JDK 17.
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)

Configuring Mend 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
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 mend 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

Maven

fileSystemScan=False
maven.resolveDependencies=True
maven.aggregateModules=True (False by default)

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)

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 Mend 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 the Python Package manager, the following parameters should be set before scanning Python Projects:

fileSystemScan=False (True by default)
python.resolveDependencies=True

The following are settings that impact Mend 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.resolveSetupFiles=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)

Preparing the Project Package

Java

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

JAVA

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:

CODE

npm install

Python

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

CODE

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 Mend 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.

CODE

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 Mend Prioritize is Precise Scan. For Java Projects, there is an option to choose Fast Scan mode which will retrieve results in a shorter time, with the same level of shields accuracy but with less granular traces. 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:

JS

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 Mend 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:

PY

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 Mend Prioritize will scan
d - The location for the Project's folder that will be examined by the Unified Agent

Performance Optimization Tips (for all modes & languages)

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

CODE

-XX:+UseG1GC

Ensure 8GB of ram are available for the scan by adding the following to the Java command line:

CODE

-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 - for more details, refer to: Troubleshooting Mend Prioritize