

whitesourceExecuteScan

Description

BETA

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.

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.

Restrictions

Currently the step does contain hardened scan configurations for scanType 'pip' and 'go'. Other environments are still being elaborated, so please thoroughly check your results and do not take them for granted by default. Also not all environments have been thoroughly tested already therefore you might need to tweak around with the default containers used or create your own ones to adequately support your scenario. To do so please modify dockerImage and dockerWorkspace parameters. The step expects an environment containing the programming language related compiler/interpreter as well as the related build tool. For a list of the supported build tools per environment please refer to the WhiteSource Unified Agent Documentation.

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

name	mandatory	default	possible values
agentDownloadUrl	no	https://github.com/whitesource/unified-agent-distribution/releases/latest/download/${config.agentFileName}
agentFileName	no	wss-unified-agent.jar
agentParameters	no	``
buildDescriptorExcludeList	no	[]
buildDescriptorFile	no	scanType=golang:./Gopkg.toml scanType=maven:./pom.xml scanType=mta:<empty> scanType=npm:./package.json scanType=pip:./setup.py scanType=sbt:./build.sbt scanType=dub:./dub.json
configFilePath	no	./wss-unified-agent.config
createProductFromPipeline	no	true
cvssSeverityLimit	no	-1	-1 to switch failing off, any positive integer between 0 and 10 to fail on issues with the specified limit or above
dockerEnvVars	no	scanType=golang:<empty> scanType=maven:<empty> scanType=mta:<empty> scanType=npm:<empty> scanType=pip:<empty> scanType=sbt:<empty> scanType=dub:<empty>
dockerImage	no	scanType=golang:golang:1.12-stretch scanType=maven:maven:3.5-jdk-8 scanType=mta:<empty> scanType=npm:node:lts-stretch scanType=pip:python:3.7.2-stretch scanType=sbt:hseeberger/scala-sbt:8u181_2.12.8_1.2.8 scanType=dub:buildpack-deps:stretch-curl
dockerOptions	no	scanType=golang:<empty> scanType=maven:<empty> scanType=mta:<empty> scanType=npm:<empty> scanType=pip:<empty> scanType=sbt:<empty> scanType=dub:<empty>
dockerWorkspace	no	scanType=golang:/home/dep scanType=maven:/home/java scanType=mta:<empty> scanType=npm:/home/node scanType=pip:/home/python scanType=sbt:/home/scala scanType=dub:/home/dub
emailAddressesOfInitialProductAdmins	no	[]
installCommand	no
licensingVulnerabilities	no	true	true, false
parallelLimit	no	15
reporting	no	true	true, false
scanImage	no
scanImageRegistryUrl	no
scanType	no		golang, maven, mta, npm, pip, sbt, dub
script	yes
securityVulnerabilities	no	true	true, false
stashContent	no	scanType=golang:[buildDescriptor, opensourceConfiguration, checkmarx] scanType=maven:[buildDescriptor, opensourceConfiguration] scanType=mta:[buildDescriptor, opensourceConfiguration] scanType=npm:[buildDescriptor, opensourceConfiguration] scanType=pip:[buildDescriptor, opensourceConfiguration] scanType=sbt:[buildDescriptor, opensourceConfiguration] scanType=dub:[buildDescriptor, checkmarx]
timeout	no	0
verbose	no	false	true, false
vulnerabilityReportFileName	no	piper_whitesource_vulnerability_report
vulnerabilityReportTitle	no	WhiteSource Security Vulnerability Report
whitesource/jreDownloadUrl	no
whitesource/orgAdminUserTokenCredentialsId	no
whitesource/orgToken	yes
whitesource/productName	yes
whitesource/productToken	no
whitesource/productVersion	no
whitesource/projectNames	no
whitesource/serviceUrl	no	https://saas.whitesourcesoftware.com/api
whitesource/userTokenCredentialsId	yes

• agentDownloadUrl - URL used to download the latest version of the WhiteSource Unified Agent.
• agentFileName - Locally used name for the Unified Agent jar file after download.
• agentParameters - Additional parameters passed to the Unified Agent command line.
• buildDescriptorExcludeList - List of build descriptors and therefore modules to exclude from the scan and assessment activities.
• buildDescriptorFile - Explicit path to the build descriptor file.
• configFilePath - Explicit path to the WhiteSource Unified Agent configuration file.
• createProductFromPipeline - Whether to create the related WhiteSource product on the fly based on the supplied pipeline configuration.
• cvssSeverityLimit - Limit of tollerable CVSS v3 score upon assessment and in consequence fails the build, defaults to -1.
• dockerEnvVars - Environment variables to set in the container, e.g. [http_proxy: 'proxy:8080'].
• dockerImage - Docker image to be used for scanning.
• dockerOptions - Docker only: Docker options to be set when starting the container (List or String).
• dockerWorkspace - Docker workspace to be used for scanning.
• emailAddressesOfInitialProductAdmins - The list of email addresses to assign as product admins for newly created WhiteSource products.
• installCommand - Install command that can be used to populate the default docker image for some scenarios.
• licensingVulnerabilities - Whether license compliance is considered and reported as part of the assessment.
• parallelLimit - Limit of parallel jobs being run at once in case of scanType: 'mta' based scenarios, defaults to 15.
• reporting - Whether assessment is being done at all, defaults to true.
• scanImage - For scanType: docker: defines the docker image which should be scanned
• scanImageRegistryUrl - For scanType: docker: defines the registry where the scanImage is located
• scanType - Type of development stack used to implement the solution.
• script - 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.
• securityVulnerabilities - Whether security compliance is considered and reported as part of the assessment.
• stashContent - List of stashes to be unstashed into the workspace before performing the scan.
• timeout - Timeout in seconds until a HTTP call is forcefully terminated.
• verbose - Whether verbose output should be produced.
• vulnerabilityReportFileName - Name of the file the vulnerability report is written to.
• vulnerabilityReportTitle - Title of vulnerability report written during the assessment phase.
• whitesource/jreDownloadUrl - URL used for downloading the Java Runtime Environment (JRE) required to run the WhiteSource Unified Agent.
• whitesource/orgAdminUserTokenCredentialsId - Jenkins credentials ID referring to the organization admin's token.
• whitesource/orgToken - WhiteSource token identifying your organization.
• whitesource/productName - Name of the WhiteSource product to be created and used for results aggregation.
• whitesource/productToken - Token of the WhiteSource product to be created and used for results aggregation, usually determined automatically.
• whitesource/productVersion - Version of the WhiteSource product to be created and used for results aggregation, usually determined automatically.
• whitesource/projectNames - List of WhiteSource projects to be included in the assessment part of the step, usually determined automatically.
• whitesource/serviceUrl - URL to the WhiteSource server API used for communication, defaults to https://saas.whitesourcesoftware.com/api.
• whitesource/userTokenCredentialsId - Jenkins credentials ID referring to the product admin's token.

Step configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter	general	step/stage
agentDownloadUrl		X
agentFileName		X
agentParameters		X
buildDescriptorExcludeList		X
buildDescriptorFile		X
configFilePath		X
createProductFromPipeline		X
cvssSeverityLimit		X
dockerEnvVars		X
dockerImage		X
dockerOptions		X
dockerWorkspace		X
emailAddressesOfInitialProductAdmins		X
installCommand		X
licensingVulnerabilities		X
parallelLimit		X
reporting		X
scanImage		X
scanImageRegistryUrl		X
scanType	X	X
script
securityVulnerabilities		X
stashContent		X
timeout		X
verbose	X	X
vulnerabilityReportFileName		X
vulnerabilityReportTitle		X
whitesource/jreDownloadUrl	X	X
whitesource/orgAdminUserTokenCredentialsId	X	X
whitesource/orgToken	X	X
whitesource/productName	X	X
whitesource/productToken	X	X
whitesource/productVersion	X	X
whitesource/projectNames	X	X
whitesource/serviceUrl	X	X
whitesource/userTokenCredentialsId	X	X

Dependencies

The step depends on the following Jenkins plugins

• credentials-binding
• docker
• kubernetes
• pipeline-utility-steps
• workflow-basic-steps
• workflow-cps
• workflow-cps-global-lib
• workflow-durable-task-step

The kubernetes plugin is only used if running in a kubernetes environment. Transitive dependencies are omitted.

The list might be incomplete.

Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.

Exceptions

None

Examples

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