sap-jenkins-library/resources/metadata/whitesource.yaml

metadata:
  name: whitesourceExecuteScan
  description: BETA
  longDescription: |-
    BETA
    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.
    !!! 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.
    !!! warn "Restrictions"
        Currently the step does contain hardened scan configurations for `scanType` `'pip'` and `'go'`. Other environments are still being elaborated,
        so please thoroughly check your results and do not take them for granted by default.
        Also not all environments have been thoroughly tested already therefore you might need to tweak around with the default containers used or
        create your own ones to adequately support your scenario. To do so please modify `dockerImage` and `dockerWorkspace` parameters.
        The step expects an environment containing the programming language related compiler/interpreter as well as the related build tool. For a list
        of the supported build tools per environment please refer to the [WhiteSource Unified Agent Documentation](https://whitesource.atlassian.net/wiki/spaces/WD/pages/33718339/Unified+Agent).    
spec:
  inputs:
    secrets:
      - name: userTokenCredentialsId
        description: Jenkins 'Secret text' credentials ID containing Whitesource user token.
        type: jenkins
      - name: orgAdminUserTokenCredentialsId
        description: Jenkins 'Secret text' credentials ID containing Whitesource org admin token.
        type: jenkins
    params:
      - 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: buildDescriptorFile
        type: string
        description: "Explicit path to the build descriptor file."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - 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: 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: securityVulnerabilities
        type: bool
        description: "Whether security compliance is considered and reported as part of the assessment."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: timeout
        type: int
        description: "Timeout in seconds until an HTTP call is forcefully terminated."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 900
      - 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: configFilePath
        type: string
        description: "Explicit path to the WhiteSource Unified Agent configuration file."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: ./wss-generated-file.config
      - name: reportDirectoryName
        type: string
        description: "Name of the directory to save vulnerability/risk reports to"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "whitesource-reports"
      - 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
        default: false
      - 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: parallelLimit
        type: string
        description: '[NOT IMPLEMENTED] Limit of parallel jobs being run at once in case of `scanType:
          ''mta''` based scenarios, defaults to `15`.'
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 15
      - name: reporting
        type: bool
        description: "Whether assessment is being done at all, defaults to `true`"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: serviceUrl
        type: string
        description: "URL to the WhiteSource server API used for communication."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: "https://saas.whitesourcesoftware.com/api"
      - 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: orgToken
        type: string
        description: "WhiteSource token identifying your organization."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        mandatory: true
        resourceRef:
          - name: orgAdminUserTokenCredentialsId
            type: secret
      - name: userToken
        type: string
        description: "WhiteSource token identifying the user executing the scan."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        mandatory: true
        resourceRef:
          - name: userTokenCredentialsId
            type: secret
      - 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: 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: emailAddressesOfInitialProductAdmins
        type: "[]string"
        description: "The list of email addresses to assign as product admins for newly created WhiteSource products."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: productVersion
        type: string
        description: "Version of the WhiteSource product to be created and used for results aggregation,
          usually determined automatically."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        resourceRef:
          - name: commonPipelineEnvironment
            param: artifactVersion
      - name: jreDownloadUrl
        type: string
        description: "[NOT IMPLEMENTED] URL used for downloading the Java Runtime Environment (JRE) required to run the
          WhiteSource Unified Agent."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: productName
        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."
        mandatory: true
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - 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: vulnerabilityReportTitle
        type: string
        description: "Title of vulnerability report written during the assessment phase."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "WhiteSource Security Vulnerability Report"
      - 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: scanType
        type: string
        description: "Type of development stack used to implement the solution.
          For scan types other than `mta`, `maven`, and `npm`,
          the WhiteSource Unified Agent is downloaded and used to perform the scan.
          If the parameter is not provided, it is derived from the parameter `buildTool`,
          which is usually configured in the general section of the pipeline config file."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        possibleValues: ["golang", "gradle", "maven", "mta", "npm", "pip", "yarn"]
      - name: cvssSeverityLimit
        type: string
        description: "Limit of tolerable CVSS v3 score upon assessment and in consequence fails the build,
          defaults to  `-1`."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "-1"
      - name: includes
        type: string
        description: "Space separated list of file path patterns to include in the scan, slashes must be escaped for sed."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: '**\/src\/main\/**\/*.java **\/*.py **\/*.go **\/*.js **\/*.ts'
      - name: excludes
        type: string
        description: Space separated list of file path patterns to exclude in the scan
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "tests/**/*.py **/src/test/**/*.java"
      - name: productToken
        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: agentParameters
        type: string
        description: "[NOT IMPLEMENTED] Additional parameters passed to the Unified Agent command line."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS

        # 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

      # 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
    resources:
      - name: buildDescriptor
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: golang
      - name: opensourceConfiguration
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: golang
      - name: checkmarx
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: golang
      - name: buildDescriptor
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: maven
      - name: opensourceConfiguration
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: maven
      - name: buildDescriptor
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: mta
      - name: opensourceConfiguration
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: mta
      - name: buildDescriptor
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: npm
      - name: opensourceConfiguration
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: npm
      - name: buildDescriptor
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: pip
      - name: opensourceConfiguration
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: pip
      - name: buildDescriptor
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: sbt
      - name: opensourceConfiguration
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: sbt
      - name: buildDescriptor
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: dub
      - name: checkmarx
        type: stash
        conditions:
          - conditionRef: strings-equal
            params:
              - name: scanType
                value: dub
  containers:
    - image: maven:3.5-jdk-8
      workingDir: /home/java
      env: []
      conditions:
        - conditionRef: strings-equal
          params:
            - name: scanType
              value: maven
    - image: node:lts-stretch
      workingDir: /home/node
      env: []
      conditions:
        - conditionRef: strings-equal
          params:
            - name: scanType
              value: npm
    - image: hseeberger/scala-sbt:8u181_2.12.8_1.2.8
      workingDir: /home/scala
      env: []
      conditions:
        - conditionRef: strings-equal
          params:
            - name: scanType
              value: sbt
    - image: buildpack-deps:stretch-curl
      workingDir: /home/dub
      env: []
      conditions:
        - conditionRef: strings-equal
          params:
            - name: scanType
              value: dub