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 or 11) |
|
JavaScript (Node.JS server-side only) | Node.JS (npm & yarn package managers) |
|
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.
|
C# | .NET Core 3.0 or 3.1 (LTS) |
|
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 |
---|---|---|
wss.url | ||
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 |
---|---|
In case the local Maven cache folder is different than its default, it should also be set in the following parameter
| |
In case the local Gradle cache folder is different than its default it should be set in the following parameter as well:
| |
POJO (without Package Manager) |
In case of scanning Java project without a package manager the /wiki/spaces/WD/pages/1525383269 -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 |
---|---|
PackageReference (csproj based with assets.json) |
|
packages.config based (csproj and packages.config) |
|
Combined (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:
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:
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:
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.
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:
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:
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:
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:
-XX:+UseG1GC
Ensure 8GB of ram are available for the scan by adding the following to the Java command line:
-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.