Skip to content

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 Secret pass via ENV or Jenkins credentials (orgAdminUserTokenCredentialsId)
script yes Jenkins only reference to Jenkins main pipeline script
userToken yes Vault Secret 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 Jenkins only
containerShell no Jenkins only
createProductFromPipeline no
customScanVersion no
cvssSeverityLimit no
defaultNpmRegistry no
dockerEnvVars no Jenkins only
dockerImage no Jenkins only
dockerName no Jenkins only
dockerOptions no Jenkins only
dockerPullImage no Jenkins only
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only
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
scanPath no
securityVulnerabilities no
serviceUrl no
stashContent no Jenkins only
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. Detect, Fortify, Sonar) 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.

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

scanPath

Directory where to start WhiteSource scan.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default .
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, buildTool: 'pip', productName: 'My Whitesource Product', userTokenCredentialsId: 'companyAdminToken', orgAdminUserTokenCredentialsId: 'orgAdminToken', orgToken: 'myWhitesourceOrganizationToken'