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

metadata:
  name: detectExecuteScan
  description: Executes Synopsys Detect scan
  longDescription: |
    This step executes [Synopsys Detect](https://community.synopsys.com/s/document-item?bundleId=integrations-detect&topicId=introduction.html&_LANG=enus) scans.
    Synopsys Detect command line utlity can be used to run various scans including BlackDuck and Polaris scans. This step allows users to run BlackDuck scans by default.
    Please configure your BlackDuck server Url using the serverUrl parameter and the API token of your user using the apiToken parameter for this step.    
spec:
  inputs:
    resources:
      - name: buildDescriptor
        type: stash
      - name: checkmarx
        type: stash
    secrets:
      - name: detectTokenCredentialsId
        aliases:
          - name: apiTokenCredentialsId
        description: Jenkins 'Secret text' credentials ID containing the API token used to authenticate with the Synopsis Detect (formerly BlackDuck) Server.
        type: jenkins
      - name: githubTokenCredentialsId
        description: Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.
        type: jenkins
    params:
      - name: token
        aliases:
          - name: blackduckToken
          - name: detectToken
          - name: apiToken
            deprecated: true
          - name: detect/apiToken
            deprecated: true
        description: Api token to be used for connectivity with Synopsis Detect server.
        type: string
        mandatory: true
        secret: true
        resourceRef:
          - name: detectTokenCredentialsId
            type: secret
          - type: vaultSecret
            name: detectVaultSecretName
            default: detect
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: codeLocation
        description: An override for the name Detect will use for the scan file it creates.
        type: string
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: projectName
        description: Name of the Synopsis Detect (formerly BlackDuck) project.
        aliases:
          - name: detect/projectName
        type: string
        mandatory: true
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: scanners
        description: List of scanners to be used for Synopsis Detect (formerly BlackDuck) scan.
        aliases:
          - name: detect/scanners
        type: "[]string"
        default:
          - signature
        possibleValues:
          - signature
          - source
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: scanPaths
        description: List of paths which should be scanned by the Synopsis Detect (formerly BlackDuck) scan.
        aliases:
          - name: detect/scanPaths
        type: "[]string"
        default:
          - "."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: dependencyPath
        description: Absolute Path of the dependency management file of the project. This path represents the folder which contains the pom file, package.json etc. If the project contains multiple pom files, provide the path to the parent pom file or the base folder of the project
        aliases:
          - name: detect/dependencyPath
        type: "string"
        default: "."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: unmap
        description: Unmap flag will unmap all previous code locations and keep only the current scan results in the specified project version. Set this parameter to true, when the project version needs to store only the latest scan results.
        aliases:
          - name: detect/unmap
        type: bool
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: scanProperties
        description: Properties passed to the Synopsis Detect (formerly BlackDuck) scan. You can find details in the [Synopsis Detect documentation](https://community.synopsys.com/s/document-item?bundleId=integrations-detect&topicId=properties%2Fall-properties.html&_LANG=enus)
        aliases:
          - name: detect/scanProperties
        type: "[]string"
        default:
          - --blackduck.signature.scanner.memory=4096
          - --detect.timeout=6000
          - --blackduck.trust.cert=true
          - --logging.level.com.synopsys.integration=DEBUG
          - --detect.maven.excluded.scopes=test
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: serverUrl
        description: Server URL to the Synopsis Detect (formerly BlackDuck) Server.
        aliases:
          - name: detect/serverUrl
        type: string
        mandatory: true
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: groups
        description: Users groups to be assigned for the Project
        aliases:
          - name: detect/groups
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: failOn
        description: Mark the current build as fail based on the policy categories applied.
        longDescription: |
          A list of policies can be provided which will be applied after the scan is completed. These policies if violated will mark the build/scan result as failed.
          The list of accepted values can be found at [Synopsys detect documentation](https://community.synopsys.com/s/document-item?bundleId=integrations-detect&topicId=properties%2Fconfiguration%2Fproject.html&anchor=fail-on-policy-violation-severities&_LANG=enus)          
        aliases:
          - name: detect/failOn
        type: "[]string"
        default:
          - BLOCKER
        possibleValues:
          - ALL
          - BLOCKER
          - CRITICAL
          - MAJOR
          - MINOR
          - NONE
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: versioningModel
        type: string
        description: The versioning model used for result reporting (based on the artifact version). Example 1.2.3 using `major` will result in version 1
        longDescription: |-
          The versioning model used for result reporting (based on the artifact version).
          For example: the version 1.2.3 of the artifact will result in a version 1 to report into, when `versioningModel: major` is used and will result in a version 1.2 when `versioningModel: major-minor` is used.
          Recommendation for a Continuous Delivery process is to use `versioningModel: major`.          
        scope:
          - PARAMETERS
          - GENERAL
          - STAGES
          - STEPS
        default: "major"
        possibleValues:
          - major
          - major-minor
          - semantic
          - full
      - name: version
        aliases:
          - name: projectVersion
          - name: detect/projectVersion
        type: string
        description: Defines the version number of the artifact being build in the pipeline. It is used as source for the Detect version.
        longDescription: |-
          Defines the version number of the artifact being build in the pipeline.
          It is used for build version creation and as source for the Detect version.
          **Typically it is available through the pipeline run.**
          The project version of the Detect project is calculated using the [`versioningModel`](#versioningmodel).          
        resourceRef:
          - name: commonPipelineEnvironment
            param: artifactVersion
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: customScanVersion
        type: string
        description: "A custom version used along with the uploaded scan results."
        longDescription: |-
          Defines a custom version for the Detect 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. Fortify, Sonar, WhiteSource) and thus allows a common custom version across scan tools.          
        scope: [GENERAL, STAGES, STEPS, PARAMETERS]
      - name: projectSettingsFile
        type: string
        description: "Path or url to the mvn settings file that should be used as project settings file."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        aliases:
          - name: maven/projectSettingsFile
      - name: globalSettingsFile
        type: string
        description: "Path or url to the mvn settings file that should be used as global settings file"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        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 detect.
          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
      - name: includedPackageManagers
        description:
          "The package managers that need to be included for this scan. Providing the package manager names with this parameter will ensure that the build descriptor file of that package manager will be searched in the scan folder
          For the complete list of possible values for this parameter, please refer [Synopsys detect documentation](https://community.synopsys.com/s/document-item?bundleId=integrations-detect&topicId=properties%2Fconfiguration%2Fdetector.html&_LANG=enus&anchor=detector-types-included-advanced)"
        aliases:
          - name: detect/includedPackageManagers
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: excludedPackageManagers
        description:
          "The package managers that need to be excluded for this scan. Providing the package manager names with this parameter will ensure that the build descriptor file of that package manager will be ignored in the scan folder
          For the complete list of possible values for this parameter, please refer [Synopsys detect documentation](https://community.synopsys.com/s/document-item?bundleId=integrations-detect&topicId=properties%2Fconfiguration%2Fdetector.html&_LANG=enus&anchor=detector-types-excluded-advanced)"
        aliases:
          - name: detect/excludedPackageManagers
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: mavenExcludedScopes
        description: "The maven scopes that need to be excluded from the scan. For example, setting the value 'test' will exclude all components which are defined with a test scope in maven"
        aliases:
          - name: detect/mavenExcludedScopes
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: detectTools
        description:
          "The type of BlackDuck scanners to include while running the BlackDuck scan. By default All scanners are included.
          For the complete list of possible values, Please refer [Synopsys detect documentation](https://community.synopsys.com/s/document-item?bundleId=integrations-detect&topicId=properties%2Fconfiguration%2Fpaths.html&_LANG=enus&anchor=detect-tools-included)"
        aliases:
          - name: detect/detectTools
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: scanOnChanges
        description:
          "This flag determines if the scan is submitted to the server. If set to true, then the scan request is submitted to the server only when changes are detected in the Open Source Bill of Materials
          If the flag is set to false, then the scan request is submitted to server regardless of any changes.
          For more details please refer to the [documentation](https://github.com/blackducksoftware/detect_rescan/blob/master/README.md)"
        type: bool
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: customEnvironmentVariables
        description:
          "A list of environment variables which can be set to prepare the environment to run a BlackDuck scan. This includes a list of environment variables defined by
          Synopsys. The full list can be found [here](https://community.synopsys.com/s/document-item?bundleId=integrations-detect&topicId=configuring%2Fenvvars.html&_LANG=enus)
          This list affects the detect script downloaded while running the scan. Right now only detect7.sh is available for downloading"
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: minScanInterval
        description:
          "This parameter controls the frequency (in number of hours) at which the signature scan is re-submitted for scan. When set to a
          value greater than 0, the signature scans are skipped until the specified number of hours has elapsed since the last signature scan."
        type: int
        scope:
          - PARAMETERS
          - 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: failOnSevereVulnerabilities
        type: bool
        description: Whether to fail the step on severe vulnerabilties or not
        scope:
          - PARAMETERS
        default: true
      - name: buildTool
        type: string
        description: "Defines the tool which is used for building the artifact."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        resourceRef:
          - name: commonPipelineEnvironment
            param: buildTool
      - name: excludedDirectories
        description:
          "List of directories which should be excluded from the scan."
        aliases:
          - name: detect/excludedDirectories
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: npmDependencyTypesExcluded
        description:
          "List of npm dependency types which Detect should exclude from the BOM."
        aliases:
          - name: detect/npmDependencyTypesExcluded
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        possibleValues:
          - NONE
          - DEV
          - PEER
      - name: npmArguments
        description:
          "List of additional arguments that Detect will add at then end of the npm ls command line when Detect executes the NPM CLI Detector on an NPM project."
        aliases:
          - name: detect/npmArguments
        type: "[]string"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
  outputs:
    resources:
      - name: influx
        type: influx
        params:
          - name: step_data
            fields:
              - name: detect
                type: bool
          - name: detect_data
            fields:
              - name: vulnerabilities
                type: int
              - name: major_vulnerabilities
                type: int
              - name: minor_vulnerabilities
                type: int
              - name: components
                type: int
              - name: policy_violations
                type: int
      - name: reports
        type: reports
        params:
          - filePattern: "**/*BlackDuck_RiskReport.pdf"
            type: blackduck-ip
          - filePattern: "**/blackduck-ip.json"
            type: blackduck-ip
          - filePattern: "**/toolrun_detectExecute_*.json"
            type: blackduck-ip
          - filePattern: "**/piper_detect_policy_violation_report.html"
            type: blackduck-ip
          - filePattern: "**/*BlackDuck_RiskReport.pdf"
            type: blackduck-security
          - filePattern: "**/detectExecuteScan_policy_*.json"
            type: blackduck-security
          - filePattern: "**/piper_detect_vulnerability_report.html"
            type: blackduck-security
          - filePattern: "**/toolrun_detectExecute_*.json"
            type: blackduck-security
          - filePattern: "**/piper_detect_vulnerability.sarif"
            type: blackduck-security
          - filePattern: "**/piper_hub_detect_sbom.xml"
            type: blackduck-security
  containers:
    - name: openjdk
      image: openjdk:11
      workingDir: /root
      options:
        - name: -u
          value: "0"