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 |
|
influx | measurement step_data
whitesource_data |
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¶
Details¶
agentDownloadUrl¶
URL used to download the latest version of the WhiteSource Unified Agent.
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 |
|
Resource references | none |
agentFileName¶
Locally used name for the Unified Agent jar file after download.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | wss-unified-agent.jar |
Secret | no |
Configuration scope |
|
Resource references | none |
agentParameters¶
[NOT IMPLEMENTED] List of additional parameters passed to the Unified Agent command line.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_agentParameters (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
agentUrl¶
URL to the WhiteSource agent endpoint.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | https://saas.whitesourcesoftware.com/agent |
Secret | no |
Configuration scope |
|
Resource references | none |
aggregateVersionWideReport¶
This does not run a scan, instead just generated a report for all projects with projectVersion = config.ProductVersion
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
buildDescriptorExcludeList¶
List of build descriptors and therefore modules to exclude from the scan and assessment activities.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | - unit-tests/pom.xml - integration-tests/pom.xml |
Secret | no |
Configuration scope |
|
Resource references | none |
buildDescriptorFile¶
Explicit path to the build descriptor file.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_buildDescriptorFile (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
buildTool¶
Defines the tool which is used for building the artifact.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_buildTool (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: buildTool |
configFilePath¶
Explicit path to the WhiteSource Unified Agent configuration file.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | ./wss-unified-agent.config |
Secret | no |
Configuration scope |
|
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).
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
containerShell¶
Jenkins-specific: Used for proper environment setup.
Allows to specify the shell to be executed for container with containerName.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
createProductFromPipeline¶
Whether to create the related WhiteSource product on the fly based on the supplied pipeline configuration.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_customScanVersion (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
cvssSeverityLimit¶
Limit of tolerable CVSS v3 score upon assessment and in consequence fails the build, defaults to -1
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | -1 |
Secret | no |
Configuration scope |
|
Resource references | none |
defaultNpmRegistry¶
URL of the npm registry to use. Defaults to https://registry.npmjs.org/
Scope | Details |
---|---|
Aliases | npm/defaultNpmRegistry |
Type | string |
Mandatory | no |
Default | $PIPER_defaultNpmRegistry (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerEnvVars¶
Jenkins-specific: Used for proper environment setup.
Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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.
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 |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerOptions¶
Jenkins-specific: Used for proper environment setup.
Docker options to be set when starting the container.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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.
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 |
|
Resource references | none |
dockerVolumeBind¶
Jenkins-specific: Used for proper environment setup.
Volumes that should be mounted into the docker container.
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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
.
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 |
|
Resource references | none |
emailAddressesOfInitialProductAdmins¶
The list of email addresses to assign as product admins for newly created WhiteSource products.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_emailAddressesOfInitialProductAdmins (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
excludes¶
List of file path patterns to exclude in the scan.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_excludes (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
globalSettingsFile¶
Path to the mvn settings file that should be used as global settings file.
Scope | Details |
---|---|
Aliases | maven/globalSettingsFile |
Type | string |
Mandatory | no |
Default | $PIPER_globalSettingsFile (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
includes¶
List of file path patterns to include in the scan.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_includes (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
installCommand¶
[NOT IMPLEMENTED] Install command that can be used to populate the default docker image for some scenarios.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_installCommand (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
jreDownloadUrl¶
URL used for downloading the Java Runtime Environment (JRE) required to run the WhiteSource Unified Agent.
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 |
|
Resource references | none |
licensingVulnerabilities¶
[NOT IMPLEMENTED] Whether license compliance is considered and reported as part of the assessment.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
m2Path¶
Path to the location of the local repository that should be used.
Scope | Details |
---|---|
Aliases | maven/m2Path |
Type | string |
Mandatory | no |
Default | $PIPER_m2Path (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
orgToken¶
WhiteSource token identifying your organization.
Scope | Details |
---|---|
Aliases | - whitesourceOrgToken - whitesource/orgToken (deprecated) |
Type | string |
Mandatory | yes |
Default | $PIPER_orgToken (if set) |
Secret | yes |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - whitesourceProductName - whitesource/productName (deprecated) |
Type | string |
Mandatory | no |
Default | $PIPER_productName (if set) |
Secret | no |
Configuration scope |
|
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
.
Scope | Details |
---|---|
Aliases | - whitesourceProductToken - whitesource/productToken (deprecated) |
Type | string |
Mandatory | no |
Default | $PIPER_productToken (if set) |
Secret | no |
Configuration scope |
|
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!
Scope | Details |
---|---|
Aliases | whitesourceProjectName |
Type | string |
Mandatory | no |
Default | $PIPER_projectName (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
projectSettingsFile¶
Path to the mvn settings file that should be used as project settings file.
Scope | Details |
---|---|
Aliases | maven/projectSettingsFile |
Type | string |
Mandatory | no |
Default | $PIPER_projectSettingsFile (if set) |
Secret | no |
Configuration scope |
|
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
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_projectToken (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
reporting¶
Whether assessment is being done at all, defaults to true
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
scanImage¶
For buildTool: docker
: Defines the docker image which should be scanned.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_scanImage (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
scanImageIncludeLayers¶
For buildTool: docker
: Defines if layers should be included.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
scanImageRegistryUrl¶
For buildTool: docker
: Defines the registry where the scanImage is located.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_scanImageRegistryUrl (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
securityVulnerabilities¶
Whether security compliance is considered and reported as part of the assessment.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
serviceUrl¶
URL to the WhiteSource API endpoint.
Scope | Details |
---|---|
Aliases | - whitesourceServiceUrl - whitesource/serviceUrl (deprecated) |
Type | string |
Mandatory | no |
Default | https://saas.whitesourcesoftware.com/api |
Secret | no |
Configuration scope |
|
Resource references | none |
stashContent¶
Jenkins-specific: Used for proper environment setup.
Specific stashes that should be considered for the step execution.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | - buildDescriptor - opensourceConfiguration - checkmarx |
Secret | no |
Configuration scope |
|
Resource references | none |
timeout¶
Timeout in seconds until an HTTP call is forcefully terminated.
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 900 |
Secret | no |
Configuration scope |
|
Resource references | none |
userToken¶
User token to access WhiteSource. In Jenkins use case this is automatically filled through the credentials.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_userToken (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: userTokenCredentialsId Vault paths:
|
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - productVersion - whitesourceProductVersion - whitesource/productVersion (deprecated) |
Type | string |
Mandatory | no |
Default | $PIPER_version (if set) |
Secret | no |
Configuration scope |
|
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'
Scope | Details |
---|---|
Aliases | defaultVersioningModel |
Type | string |
Mandatory | no |
Default | major |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityReportFormat¶
Format of the file the vulnerability report is written to.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | xlsx |
Possible values | - xlsx - json - xml |
Secret | no |
Configuration scope |
|
Resource references | none |
vulnerabilityReportTitle¶
Title of vulnerability report written during the assessment phase.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | WhiteSource Security Vulnerability Report |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - whitesourceUserTokenCredentialsId - whitesource/userTokenCredentialsId (deprecated) |
Type | string |
Configuration scope |
|
orgAdminUserTokenCredentialsId¶
Jenkins-specific: Used for proper environment setup. See using credentials for details.
Jenkins 'Secret text' credentials ID containing Whitesource org admin token.
Scope | Details |
---|---|
Aliases | - whitesourceOrgAdminUserTokenCredentialsId - whitesource/orgAdminUserTokenCredentialsId (deprecated) |
Type | string |
Configuration scope |
|
Exceptions¶
None
Examples¶
whitesourceExecuteScan script: this, scanType: 'pip', productName: 'My Whitesource Product', userTokenCredentialsId: 'companyAdminToken', orgAdminUserTokenCredentialsId: 'orgAdminToken', orgToken: 'myWhitesourceOrganizationToken'