metadata: name: whitesourceExecuteScan description: Execute a WhiteSource scan longDescription: |- With this step [WhiteSource](https://www.whitesourcesoftware.com) 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](https://whitesource.atlassian.net/wiki/spaces/WD/pages/33718339/Unified+Agent). !!! note "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. spec: inputs: secrets: - name: userTokenCredentialsId aliases: - name: whitesourceUserTokenCredentialsId - name: whitesource/userTokenCredentialsId deprecated: true description: Jenkins 'Secret text' credentials ID containing Whitesource user token. type: jenkins - name: orgAdminUserTokenCredentialsId aliases: - name: whitesourceOrgAdminUserTokenCredentialsId - name: whitesource/orgAdminUserTokenCredentialsId deprecated: true description: Jenkins 'Secret text' credentials ID containing Whitesource org admin token. type: jenkins - name: dockerConfigJsonCredentialsId description: Jenkins 'Secret file' credentials ID containing Docker config.json (with registry credential(s)). You can find more details about the Docker credentials in the [Docker documentation](https://docs.docker.com/engine/reference/commandline/login/). type: jenkins aliases: - name: dockerCredentialsId deprecated: true - name: githubTokenCredentialsId description: Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub. type: jenkins params: - name: agentDownloadUrl type: string description: "URL used to download the latest version of the WhiteSource Unified Agent." scope: - PARAMETERS - STAGES - STEPS default: https://github.com/whitesource/unified-agent-distribution/releases/latest/download/wss-unified-agent.jar - name: agentFileName type: string description: "Locally used name for the Unified Agent jar file after download." scope: - PARAMETERS - STAGES - STEPS default: "wss-unified-agent.jar" - name: agentParameters type: "[]string" description: "[NOT IMPLEMENTED] List of additional parameters passed to the Unified Agent command line." scope: - PARAMETERS - STAGES - STEPS - name: agentUrl aliases: - name: whitesourceAgentUrl type: string description: "URL to the WhiteSource agent endpoint." scope: - GENERAL - PARAMETERS - STAGES - STEPS default: "https://saas.whitesourcesoftware.com/agent" - name: aggregateVersionWideReport type: bool description: "This does not run a scan, instead just generated a report for all projects with projectVersion = config.ProductVersion" scope: - PARAMETERS - STAGES - STEPS - name: assessmentFile type: string description: "Explicit path to the assessment YAML file." scope: - PARAMETERS - STAGES - STEPS default: "hs-assessments.yaml" - name: buildDescriptorExcludeList type: "[]string" description: "List of build descriptors and therefore modules to exclude from the scan and assessment activities." scope: - PARAMETERS - STAGES - STEPS default: ["unit-tests/pom.xml", "integration-tests/pom.xml"] - name: buildDescriptorFile type: string description: "Explicit path to the build descriptor file." scope: - PARAMETERS - STAGES - STEPS - name: buildTool type: string description: "Defines the tool which is used for building the artifact." mandatory: true scope: - GENERAL - PARAMETERS - STAGES - STEPS resourceRef: - name: commonPipelineEnvironment param: buildTool - name: configFilePath type: string description: "Explicit path to the WhiteSource Unified Agent configuration file." scope: - PARAMETERS - STAGES - STEPS default: ./wss-unified-agent.config - name: containerRegistryPassword description: "For `buildTool: docker`: Password for container registry access - typically provided by the CI/CD environment." type: string scope: - PARAMETERS - STAGES - STEPS secret: true resourceRef: - name: commonPipelineEnvironment param: container/repositoryPassword - name: commonPipelineEnvironment param: custom/repositoryPassword - name: containerRegistryUser description: "For `buildTool: docker`: Username for container registry access - typically provided by the CI/CD environment." type: string scope: - PARAMETERS - STAGES - STEPS secret: true resourceRef: - name: commonPipelineEnvironment param: container/repositoryUsername - name: commonPipelineEnvironment param: custom/repositoryUsername - name: createProductFromPipeline type: bool description: "Whether to create the related WhiteSource product on the fly based on the supplied pipeline configuration." scope: - PARAMETERS - STAGES - STEPS default: true - name: customScanVersion type: string description: Custom version of the WhiteSource project used as source. longDescription: |- Defines a custom version for the WhiteSource scan which deviates from the typical versioning pattern using [`version`](#version) and [`versioningModel`](#versioningModel). It allows to set non-numeric versions as well and supersedes the value of [`version`](#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. scope: - GENERAL - PARAMETERS - STAGES - STEPS - name: cvssSeverityLimit type: string description: "Limit of tolerable CVSS v3 score upon assessment and in consequence fails the build." scope: - PARAMETERS - STAGES - STEPS default: "-1" - name: scanPath type: string description: "Directory where to start WhiteSource scan." scope: - PARAMETERS - STAGES - STEPS default: "." - name: dockerConfigJSON type: string description: Path to the file `.docker/config.json` - this is typically provided by your CI/CD system. You can find more details about the Docker credentials in the [Docker documentation](https://docs.docker.com/engine/reference/commandline/login/). scope: - PARAMETERS - STAGES - STEPS secret: true resourceRef: - name: commonPipelineEnvironment param: custom/dockerConfigJSON - name: dockerConfigJsonCredentialsId type: secret - type: vaultSecretFile name: dockerConfigFileVaultSecretName default: docker-config - name: emailAddressesOfInitialProductAdmins type: "[]string" description: "The list of email addresses to assign as product admins for newly created WhiteSource products." scope: - PARAMETERS - STAGES - STEPS - name: excludes type: "[]string" description: List of file path patterns to exclude in the scan. scope: - PARAMETERS - STAGES - STEPS - name: failOnSevereVulnerabilities type: bool description: Whether to fail the step on severe vulnerabilties or not scope: - PARAMETERS default: true - name: includes type: "[]string" description: List of file path patterns to include in the scan. scope: - PARAMETERS - STAGES - STEPS - name: installCommand type: string description: "[NOT IMPLEMENTED] Install command that can be used to populate the default docker image for some scenarios." scope: - PARAMETERS - STAGES - STEPS - name: jreDownloadUrl aliases: - name: whitesource/jreDownloadUrl deprecated: true type: string description: "URL used for downloading the Java Runtime Environment (JRE) required to run the WhiteSource Unified Agent." scope: - GENERAL - PARAMETERS - STAGES - STEPS default: "https://github.com/SAP/SapMachine/releases/download/sapmachine-11.0.2/sapmachine-jre-11.0.2_linux-x64_bin.tar.gz" - name: licensingVulnerabilities type: bool description: "[NOT IMPLEMENTED] Whether license compliance is considered and reported as part of the assessment." scope: - PARAMETERS - STAGES - STEPS default: true - name: orgToken aliases: - name: whitesourceOrgToken - name: whitesource/orgToken deprecated: true type: string description: "WhiteSource token identifying your organization." scope: - GENERAL - PARAMETERS - STAGES - STEPS secret: true mandatory: true resourceRef: - name: orgAdminUserTokenCredentialsId type: secret - type: vaultSecret name: whitesourceVaultSecret default: whitesource - name: productName aliases: - name: whitesourceProductName - name: whitesource/productName deprecated: true type: string description: "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: - GENERAL - PARAMETERS - STAGES - STEPS - name: productToken aliases: - name: whitesourceProductToken - name: whitesource/productToken deprecated: true type: string description: "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: - GENERAL - PARAMETERS - STAGES - STEPS - name: version aliases: - name: productVersion - name: whitesourceProductVersion - name: whitesource/productVersion deprecated: true type: string description: Version of the WhiteSource product to be created and used for results aggregation. longDescription: |- 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: - GENERAL - PARAMETERS - STAGES - STEPS resourceRef: - name: commonPipelineEnvironment param: artifactVersion - name: projectName aliases: - name: whitesourceProjectName type: string description: "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: - PARAMETERS - STAGES - STEPS - name: projectToken type: string description: "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: - GENERAL - PARAMETERS - STAGES - STEPS - name: reporting type: bool description: "Whether assessment is being done at all, defaults to `true`" scope: - PARAMETERS - STAGES - STEPS default: true - name: scanImage type: string description: "For `buildTool: docker`: Defines the docker image which should be scanned." resourceRef: - name: commonPipelineEnvironment param: container/imageNameTag scope: - PARAMETERS - STAGES - STEPS - name: scanImageRegistryUrl type: string description: "For `buildTool: docker`: Defines the registry where the scanImage is located." resourceRef: - name: commonPipelineEnvironment param: container/registryUrl scope: - PARAMETERS - STAGES - STEPS - name: securityVulnerabilities type: bool description: "Whether security compliance is considered and reported as part of the assessment." scope: - PARAMETERS - STAGES - STEPS default: true - name: serviceUrl aliases: - name: whitesourceServiceUrl - name: whitesource/serviceUrl deprecated: true type: string description: "URL to the WhiteSource API endpoint." scope: - GENERAL - PARAMETERS - STAGES - STEPS default: "https://saas.whitesourcesoftware.com/api" - name: timeout type: int description: "Timeout in seconds until an HTTP call is forcefully terminated." scope: - PARAMETERS - STAGES - STEPS default: 900 - name: userToken type: string description: User token to access WhiteSource. In Jenkins use case this is automatically filled through the credentials. scope: - GENERAL - PARAMETERS - STAGES - STEPS secret: true mandatory: true resourceRef: - name: userTokenCredentialsId type: secret - type: vaultSecret name: whitesourceVaultSecret default: whitesource - name: versioningModel type: string description: "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: - PARAMETERS - STAGES - STEPS - GENERAL default: "major" aliases: - name: defaultVersioningModel - name: vulnerabilityReportFormat type: string description: "Format of the file the vulnerability report is written to." possibleValues: [xlsx, json, xml] scope: - PARAMETERS - STAGES - STEPS default: xlsx - name: vulnerabilityReportTitle type: string description: "Title of vulnerability report written during the assessment phase." scope: - PARAMETERS - STAGES - STEPS default: "WhiteSource Security Vulnerability Report" # Global maven settings, should be added to all maven steps - name: projectSettingsFile type: string description: "Path to the mvn settings file that should be used as project settings file." scope: - GENERAL - STEPS - STAGES - PARAMETERS aliases: - name: maven/projectSettingsFile - name: globalSettingsFile type: string description: "Path to the mvn settings file that should be used as global settings file." scope: - GENERAL - STEPS - STAGES - PARAMETERS aliases: - name: maven/globalSettingsFile - name: m2Path type: string description: "Path to the location of the local repository that should be used." scope: - GENERAL - STEPS - STAGES - PARAMETERS aliases: - name: maven/m2Path - name: installArtifacts type: bool description: "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: - GENERAL - STEPS - STAGES - PARAMETERS # Global npm settings, should be added to all npm steps - name: defaultNpmRegistry type: string description: "URL of the npm registry to use. Defaults to https://registry.npmjs.org/" scope: - PARAMETERS - GENERAL - STAGES - STEPS aliases: - name: npm/defaultNpmRegistry - name: githubToken description: "GitHub personal access token as per https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line" scope: - GENERAL - PARAMETERS - STAGES - STEPS type: string secret: true aliases: - name: access_token resourceRef: - name: githubTokenCredentialsId type: secret - type: vaultSecret default: github name: githubVaultSecretName - name: createResultIssue type: bool description: Activate creation of a result issue in GitHub. longDescription: | Whether the step creates a GitHub issue containing the scan results in the originating repo. Since optimized pipelines are headless the creation is implicitly activated for scheduled runs. resourceRef: - name: commonPipelineEnvironment param: custom/isOptimizedAndScheduled scope: - GENERAL - PARAMETERS - STAGES - STEPS default: false - name: githubApiUrl description: "Set the GitHub API URL." scope: - GENERAL - PARAMETERS - STAGES - STEPS type: string default: "https://api.github.com" - name: owner aliases: - name: githubOrg description: "Set the GitHub organization." resourceRef: - name: commonPipelineEnvironment param: github/owner scope: - GENERAL - PARAMETERS - STAGES - STEPS type: string - name: repository aliases: - name: githubRepo description: "Set the GitHub repository." resourceRef: - name: commonPipelineEnvironment param: github/repository scope: - GENERAL - PARAMETERS - STAGES - STEPS type: string - name: assignees description: Defines the assignees for the Github Issue created/updated with the results of the scan as a list of login names. scope: - PARAMETERS - STAGES - STEPS type: "[]string" default: [] mandatory: false - name: customTlsCertificateLinks type: "[]string" description: "List of download links to custom TLS certificates. This is required to ensure trusted connections to instances with repositories (like nexus) when publish flag is set to true." scope: - GENERAL - PARAMETERS - STAGES - STEPS resources: - name: buildDescriptor type: stash - name: opensourceConfiguration type: stash - name: checkmarx type: stash outputs: resources: - name: commonPipelineEnvironment type: piperEnvironment params: - name: custom/whitesourceProjectNames type: "[]string" - name: influx type: influx params: - name: step_data fields: - name: whitesource type: bool - name: whitesource_data fields: - name: vulnerabilities type: int - name: major_vulnerabilities type: int - name: minor_vulnerabilities type: int - name: policy_violations type: int - name: reports type: reports params: - filePattern: "**/whitesource-ip.json" type: whitesource-ip - filePattern: "whitesource-riskReport.pdf" type: whitesource-ip - filePattern: "**/toolrun_whitesource_*.json" type: whitesource-ip - filePattern: "**/piper_whitesource_vulnerability_report.html" type: whitesource-security - filePattern: "whitesource-riskReport.pdf" type: whitesource-security - filePattern: "**/toolrun_whitesource_*.json" type: whitesource-security containers: - image: buildpack-deps:stretch-curl workingDir: /tmp env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: dub - name: buildTool value: docker - image: devxci/mbtci-java11-node14 workingDir: /home/mta env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: mta - image: golang:1 workingDir: /go env: [] options: - name: -u value: "0" conditions: - conditionRef: strings-equal params: - name: buildTool value: golang - image: gradle workingDir: /home/gradle env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: gradle - image: hseeberger/scala-sbt:8u181_2.12.8_1.2.8 workingDir: /tmp env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: sbt - image: maven:3.5-jdk-8 workingDir: /tmp env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: maven - image: node:lts-stretch workingDir: /home/node env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: npm - image: python:3.6-stretch workingDir: /tmp env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: pip - image: node:lts-stretch workingDir: /home/node env: [] conditions: - conditionRef: strings-equal params: - name: buildTool value: yarn