whitesourceExecuteScan.yaml

metadata:
  name: whitesourceExecuteScan
  description: Execute a Mend (formerly known as WhiteSource) scan
  longDescription: |-
    With this step [Mend](https://www.mend.io/) (formerly known as Whitesource) security and license compliance scans can be executed and assessed.
    Mend 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 Mend Unified Agent. For details please refer to the [Mend Unified Agent Documentation](https://docs.mend.io/bundle/unified_agent/page/overview_of_the_unified_agent.html).

    !!! 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
      - name: golangPrivateModulesGitTokenCredentialsId
        description: Jenkins 'Username with password' credentials ID containing username/password for http access to your git repos where your go private modules are stored.
        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: useGlobalConfiguration
        type: bool
        description: "The parameter is applicable for multi-module mend projects. If set to true, the configuration file will be used for all modules. Otherwise each module will require its own configuration file in the module folder."
        scope:
          - PARAMETERS
          - GENERAL
          - STAGES
          - STEPS
        default: false
      - 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. A negative value (like the default of -1) means that the build won't fail."
        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: "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. The URL is a HTTP 302 Temp Redirect to the always latest available SapMachine 17, linux-x64, JRE"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: "https://sap.github.io/SapMachine/latest/17/linux-x64/jre"
      - 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: scanImages
        type: "[]string"
        description: "For `buildTool: docker`: Allowing to scan multiple docker images. In case parent project will not contain any dependecies, use skipParentProjectResolution parameter"
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/imageNameTags
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: skipParentProjectResolution
        type: bool
        description: "Parameter for multi-module, multi-images projects to skip the parent project resolution for reporing purpose. Could be used if parent project is set as just a placeholder for scan and doesn't contain any dependencies."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: false
      - name: activateMultipleImagesScan
        type: bool
        description: "Use this parameter to activate the scan of multiple images. Additionally you'll need to provide skipParentProjectResolution and scanImages parameters"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: false
      - 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, all artifacts will be installed to the local Maven repository to ensure availability before running WhiteSource.
          Currently, this parameter is not honored in whitesourceExecuteScan step, as it is internally managed by UA with the 'runPreStep'.
          In the future, this parameter will be honored based on the individual build tool."
        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: npmIncludeDevDependencies
        type: bool
        description: "Enable this if you wish to include NPM DEV dependencies in the scan report"
        scope:
          - PARAMETERS
          - GENERAL
          - STAGES
          - STEPS
        default: false
        aliases:
          - name: npm/includeDevDependencies
      - name: disableNpmSubmodulesAggregation
        type: bool
        description: "The default Mend behavior is to aggregate all submodules of NPM project into one project in Mend. This parameter disables this behavior, thus for each submodule a separate project is created."
        default: false
        scope:
          - PARAMETERS
          - GENERAL
          - STAGES
          - STEPS
      - 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
      - name: privateModules
        type: "string"
        description: Tells go which modules shall be considered to be private (by setting [GOPRIVATE](https://pkg.go.dev/cmd/go#hdr-Configuration_for_downloading_non_public_code)).
        scope:
          - GENERAL
          - STEPS
          - STAGES
          - PARAMETERS
        alias:
          - goprivate
      - name: privateModulesGitToken
        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
        resourceRef:
          - name: golangPrivateModulesGitTokenCredentialsId
            type: secret
            param: password
          - type: vaultSecret
            name: golangPrivateModulesGitTokenVaultSecret
            default: golang
      - name: SkipProjectsWithEmptyTokens
        description: Skips projects with empty tokens after scanning. This is for testing purposes only and should not be used until we roll out the new parameter
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        type: bool
        default: false
    resources:
      - name: buildDescriptor
        type: stash
      - name: opensourceConfiguration
        type: stash
      - name: checkmarx
        type: stash
      - name: checkmarxOne
        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: "**/*risk-report.pdf"
            type: whitesource-ip
          - filePattern: "**/toolrun_whitesource_*.json"
            type: whitesource-ip
          - filePattern: "**/piper_whitesource_vulnerability_report.html"
            type: whitesource-security
          - filePattern: "**/*risk-report.pdf"
            type: whitesource-security
          - filePattern: "**/toolrun_whitesource_*.json"
            type: whitesource-security
          - filePattern: "**/piper_whitesource_vulnerability.sarif"
            type: whitesource-security
          - filePattern: "**/piper_whitesource_sbom.xml"
            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-buster
      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-buster
      workingDir: /home/node
      env: []
      conditions:
        - conditionRef: strings-equal
          params:
            - name: buildTool
              value: yarn