

whitesourceExecuteScan

Execute a WhiteSource scan

Description

With this step WhiteSource security and license compliance scans can be executed and assessed. WhiteSource is a Software as a Service offering based on a so called unified agent that locally determines the dependency tree of a node.js, Java, Python, Ruby, or Scala based solution and sends it to the WhiteSource server for a policy based license compliance check and additional Free and Open Source Software Publicly Known Vulnerabilities detection.

The step uses the so-called WhiteSource Unified Agent. For details please refer to the WhiteSource Unified Agent Documentation.

Docker Images

The underlying Docker images are public and specific to the solution's programming language(s) and therefore may have to be exchanged to fit to and support the relevant scenario. The default Python environment used is i.e. Python 3 based.

Usage

We recommend to define values of step parameters via config.yml file. In this case, calling the step is reduced to one simple line.
Calling the step can be done either via the Jenkins library step or on the command line.

Jenkins Pipeline

library('piper-lib-os')

whitesourceExecuteScan script: this

Command Line

piper whitesourceExecuteScan

Outputs

Output type	Details
commonPipelineEnvironment	custom/whitesourceProjectNames
influx	measurement step_data whitesource measurement whitesource_data vulnerabilities major_vulnerabilities minor_vulnerabilities policy_violations

Prerequisites

Your company has registered an account with WhiteSource and you have enabled the use of so called User Keys to manage access to your organization in WhiteSource via dedicated privileges. Scanning your products without adequate user level access protection imposed on the WhiteSource backend would simply allow access based on the organization token.

Parameters

Overview

Name	Mandatory	Additional information
buildTool	yes
orgToken	yes	pass via ENV or Jenkins credentials (orgAdminUserTokenCredentialsId)
script	yes	reference to Jenkins main pipeline script
userToken	yes	pass via ENV, Vault or Jenkins credentials (userTokenCredentialsId)
agentDownloadUrl	no
agentFileName	no
agentParameters	no
agentUrl	no
aggregateVersionWideReport	no
buildDescriptorExcludeList	no
buildDescriptorFile	no
configFilePath	no
containerCommand	no
containerShell	no
createProductFromPipeline	no
customScanVersion	no
cvssSeverityLimit	no
defaultNpmRegistry	no
dockerEnvVars	no
dockerImage	no
dockerName	no
dockerOptions	no
dockerPullImage	no
dockerVolumeBind	no
dockerWorkspace	no
emailAddressesOfInitialProductAdmins	no
excludes	no
globalSettingsFile	no
includes	no
installArtifacts	no
installCommand	no
jreDownloadUrl	no
licensingVulnerabilities	no
m2Path	no
productName	no
productToken	no
projectName	no
projectSettingsFile	no
projectToken	no
reporting	no
scanImage	no
scanImageIncludeLayers	no
scanImageRegistryUrl	no
securityVulnerabilities	no
serviceUrl	no
stashContent	no
timeout	no
verbose	no	activates debug output
version	no
versioningModel	no
vulnerabilityReportFormat	no
vulnerabilityReportTitle	no

Details

agentDownloadUrl

URL used to download the latest version of the WhiteSource Unified Agent.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	https://github.com/whitesource/unified-agent-distribution/releases/latest/download/wss-unified-agent.jar
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

agentFileName

Locally used name for the Unified Agent jar file after download.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	wss-unified-agent.jar
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

agentParameters

[NOT IMPLEMENTED] List of additional parameters passed to the Unified Agent command line.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_agentParameters (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

agentUrl

URL to the WhiteSource agent endpoint.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	https://saas.whitesourcesoftware.com/agent
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

aggregateVersionWideReport

This does not run a scan, instead just generated a report for all projects with projectVersion = config.ProductVersion

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

buildDescriptorExcludeList

List of build descriptors and therefore modules to exclude from the scan and assessment activities.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	- unit-tests/pom.xml - integration-tests/pom.xml
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

buildDescriptorFile

Explicit path to the build descriptor file.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_buildDescriptorFile (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

buildTool

Defines the tool which is used for building the artifact.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_buildTool (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: buildTool

configFilePath

Explicit path to the WhiteSource Unified Agent configuration file.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	./wss-unified-agent.config
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

containerCommand

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

containerShell

Jenkins-specific: Used for proper environment setup.

Allows to specify the shell to be executed for container with containerName.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

createProductFromPipeline

Whether to create the related WhiteSource product on the fly based on the supplied pipeline configuration.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

customScanVersion

Defines a custom version for the WhiteSource scan which deviates from the typical versioning pattern using version and versioningModel It allows to set non-numeric versions as well and supersedes the value of version which is calculated automatically. The parameter is also used by other scan steps (e.g. BlackDuck Detect) and thus allows a common custom version across scan tools.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_customScanVersion (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cvssSeverityLimit

Limit of tolerable CVSS v3 score upon assessment and in consequence fails the build, defaults to -1.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	-1
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

defaultNpmRegistry

URL of the npm registry to use. Defaults to https://registry.npmjs.org/

back to overview

Scope	Details
Aliases	npm/defaultNpmRegistry
Type	string
Mandatory	no
Default	$PIPER_defaultNpmRegistry (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerEnvVars

Jenkins-specific: Used for proper environment setup.

Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].

back to overview

Scope	Details
Aliases	-
Type	map[string]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerImage

Jenkins-specific: Used for proper environment setup.

Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	buildTool=dub: buildpack-deps:stretch-curl buildTool=docker: buildpack-deps:stretch-curl buildTool=mta: devxci/mbtci:1.0.14 buildTool=golang: golang:1 buildTool=sbt: hseeberger/scala-sbt:8u181_2.12.8_1.2.8 buildTool=maven: maven:3.5-jdk-8 buildTool=npm: node:lts-stretch buildTool=pip: python:3.6-stretch buildTool=yarn: node:lts-stretch
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerName

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerOptions

Jenkins-specific: Used for proper environment setup.

Docker options to be set when starting the container.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerPullImage

Jenkins-specific: Used for proper environment setup.

Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	buildTool=dub: true buildTool=docker: true buildTool=mta: true buildTool=golang: true buildTool=sbt: true buildTool=maven: true buildTool=npm: true buildTool=pip: true buildTool=yarn: true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerVolumeBind

Jenkins-specific: Used for proper environment setup.

Volumes that should be mounted into the docker container.

back to overview

Scope	Details
Aliases	-
Type	map[string]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerWorkspace

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	buildTool=dub: /tmp buildTool=docker: /tmp buildTool=mta: /home/mta buildTool=golang: /go buildTool=sbt: /tmp buildTool=maven: /tmp buildTool=npm: /home/node buildTool=pip: /tmp buildTool=yarn: /home/node
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

emailAddressesOfInitialProductAdmins

The list of email addresses to assign as product admins for newly created WhiteSource products.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_emailAddressesOfInitialProductAdmins (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

excludes

List of file path patterns to exclude in the scan.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_excludes (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

globalSettingsFile

Path to the mvn settings file that should be used as global settings file.

back to overview

Scope	Details
Aliases	maven/globalSettingsFile
Type	string
Mandatory	no
Default	$PIPER_globalSettingsFile (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

includes

List of file path patterns to include in the scan.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_includes (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

installArtifacts

If enabled, it will install all artifacts to the local maven repository to make them available before running whitesource. This is required if any maven module has dependencies to other modules in the repository and they were not installed before.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

installCommand

[NOT IMPLEMENTED] Install command that can be used to populate the default docker image for some scenarios.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_installCommand (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

jreDownloadUrl

URL used for downloading the Java Runtime Environment (JRE) required to run the WhiteSource Unified Agent.

back to overview

Scope	Details
Aliases	whitesource/jreDownloadUrl (deprecated)
Type	string
Mandatory	no
Default	https://github.com/SAP/SapMachine/releases/download/sapmachine-11.0.2/sapmachine-jre-11.0.2_linux-x64_bin.tar.gz
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

licensingVulnerabilities

[NOT IMPLEMENTED] Whether license compliance is considered and reported as part of the assessment.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

m2Path

Path to the location of the local repository that should be used.

back to overview

Scope	Details
Aliases	maven/m2Path
Type	string
Mandatory	no
Default	$PIPER_m2Path (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

orgToken

WhiteSource token identifying your organization.

back to overview

Scope	Details
Aliases	- whitesourceOrgToken - whitesource/orgToken (deprecated)
Type	string
Mandatory	yes
Default	$PIPER_orgToken (if set)
Secret	yes
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: orgAdminUserTokenCredentialsId

productName

Name of the WhiteSource product used for results aggregation. This parameter is mandatory if the parameter createProductFromPipeline is set to true and the WhiteSource product does not yet exist. It is also mandatory if the parameter productToken is not provided.

back to overview

Scope	Details
Aliases	- whitesourceProductName - whitesource/productName (deprecated)
Type	string
Mandatory	no
Default	$PIPER_productName (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

productToken

Token of the WhiteSource product to be created and used for results aggregation, usually determined automatically. Can optionally be provided as an alternative to productName.

back to overview

Scope	Details
Aliases	- whitesourceProductToken - whitesource/productToken (deprecated)
Type	string
Mandatory	no
Default	$PIPER_productToken (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

projectName

The project name used for reporting results in WhiteSource. When provided, all source modules will be scanned into one aggregated WhiteSource project. For scan types maven, mta, npm, the default is to generate one WhiteSource project per module, whereas the project name is derived from the module's build descriptor. For NPM modules, project aggregation is not supported, the last scanned NPM module will override all previously aggregated scan results!

back to overview

Scope	Details
Aliases	whitesourceProjectName
Type	string
Mandatory	no
Default	$PIPER_projectName (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

projectSettingsFile

Path to the mvn settings file that should be used as project settings file.

back to overview

Scope	Details
Aliases	maven/projectSettingsFile
Type	string
Mandatory	no
Default	$PIPER_projectSettingsFile (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

projectToken

Project token to execute scan on. Ignored for scan types maven, mta and npm. Used for project aggregation when scanning with the Unified Agent and can be provided as an alternative to projectName.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_projectToken (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

reporting

Whether assessment is being done at all, defaults to true

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

scanImage

For buildTool: docker: Defines the docker image which should be scanned.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_scanImage (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

scanImageIncludeLayers

For buildTool: docker: Defines if layers should be included.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

scanImageRegistryUrl

For buildTool: docker: Defines the registry where the scanImage is located.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_scanImageRegistryUrl (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

script

Jenkins-specific: Used for proper environment setup.

The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

back to overview

Scope	Details
Aliases	-
Type	Jenkins Script
Mandatory	yes
Default
Secret	no
Configuration scope	☐ parameter ☐ general ☐ steps ☐ stages
Resource references	none

securityVulnerabilities

Whether security compliance is considered and reported as part of the assessment.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

serviceUrl

URL to the WhiteSource API endpoint.

back to overview

Scope	Details
Aliases	- whitesourceServiceUrl - whitesource/serviceUrl (deprecated)
Type	string
Mandatory	no
Default	https://saas.whitesourcesoftware.com/api
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

stashContent

Jenkins-specific: Used for proper environment setup.

Specific stashes that should be considered for the step execution.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	- buildDescriptor - opensourceConfiguration - checkmarx
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

timeout

Timeout in seconds until an HTTP call is forcefully terminated.

back to overview

Scope	Details
Aliases	-
Type	int
Mandatory	no
Default	900
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

userToken

User token to access WhiteSource. In Jenkins use case this is automatically filled through the credentials.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_userToken (if set)
Secret	yes
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: userTokenCredentialsId Vault paths: $(vaultPath)/whitesource

verbose

verbose output

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

version

Version of the WhiteSource product to be created and used for results aggregation. This is usually determined automatically based on the information in the buildTool specific build descriptor file.

back to overview

Scope	Details
Aliases	- productVersion - whitesourceProductVersion - whitesource/productVersion (deprecated)
Type	string
Mandatory	no
Default	$PIPER_version (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: artifactVersion

versioningModel

The default project versioning model used in case projectVersion parameter is empty for creating the version based on the build descriptor version to report results in Whitesource, can be one of 'major', 'major-minor', 'semantic', 'full'

back to overview

Scope	Details
Aliases	defaultVersioningModel
Type	string
Mandatory	no
Default	major
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

vulnerabilityReportFormat

Format of the file the vulnerability report is written to.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	xlsx
Possible values	- xlsx - json - xml
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

vulnerabilityReportTitle

Title of vulnerability report written during the assessment phase.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	WhiteSource Security Vulnerability Report
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

userTokenCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret text' credentials ID containing Whitesource user token.

back to overview

Scope	Details
Aliases	- whitesourceUserTokenCredentialsId - whitesource/userTokenCredentialsId (deprecated)
Type	string
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages

orgAdminUserTokenCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret text' credentials ID containing Whitesource org admin token.

back to overview

Scope	Details
Aliases	- whitesourceOrgAdminUserTokenCredentialsId - whitesource/orgAdminUserTokenCredentialsId (deprecated)
Type	string
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages

Exceptions

None

Examples

whitesourceExecuteScan script: this, scanType: 'pip', productName: 'My Whitesource Product', userTokenCredentialsId: 'companyAdminToken', orgAdminUserTokenCredentialsId: 'orgAdminToken', orgToken: 'myWhitesourceOrganizationToken'