metadata:
  name: protecodeExecuteScan
  description: Black Duck Binary Analysis (BDBA), previously known as Protecode is an Open Source Vulnerability Scanner that is capable of scanning binaries. It can be used to scan docker images but is supports many other programming languages especially those of the C family.
  longDescription: |-
    Black Duck Binary Analysis (previously known as Protecode) is an Open Source Vulnerability Scan tool which provides the composition of Open Source components in a product along with Security information (no license info is provided).
    BDBA (Protecode) uses a combination of static binary analysis techniques to X-ray the provided software package to identify third-party software components and their exact versions with a high level of confidence. Methods range from simple string matching to proprietary patent-pending techniques.

    !!! hint "Auditing findings (Triaging)"
        Triaging is now supported by the BDBA (Protecode) backend and also Piper does consider this information during the analysis of the scan results though product versions are not supported by BDBA (Protecode). Therefore please make sure that the `fileName` you are providing does either contain a stable version or that it does not contain one at all. By ensuring that you are able to triage CVEs globally on the upload file's name without affecting any other artifacts scanned in the same BDBA (Protecode) group and as such triaged vulnerabilities will be considered during the next scan and will not fail the build anymore.
spec:
  inputs:
    secrets:
      - name: protecodeCredentialsId
        description: Jenkins 'Username with password' credentials ID containing username and password to authenticate to the Protecode system.
        type: jenkins
      - name: protecodeApiKeyCredentialsId
        description: Jenkins 'Secret text' credentials ID containing API Key/token to authenticate to BDBA server.
        type: jenkins
      - name: dockerConfigJsonCredentialsId
        description: Jenkins 'Secret file' credentials ID containing Docker config.json (with registry credential(s)). You can create it like explained in [Prerequisites](https://www.project-piper.io/steps/protecodeExecuteScan/#prerequisites).
        type: jenkins
        aliases:
          - name: dockerCredentialsId
            deprecated: true
    params:
      - name: excludeCVEs
        aliases:
          - name: protecodeExcludeCVEs
        type: string
        description: "DEPRECATED: Do use triaging within the Protecode UI instead"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: ""
      - name: failOnSevereVulnerabilities
        aliases:
          - name: protecodeFailOnSevereVulnerabilities
        type: bool
        description: Whether to fail the step on severe vulnerabilties or not
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: scanImage
        aliases:
          - name: dockerImage
        type: string
        description: "The reference to the docker image to scan with Protecode. Note: If possible please also check [fetchUrl](https://www.project-piper.io/steps/protecodeExecuteScan/#fetchurl) parameter, which might help you to optimize upload time."
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/imageNameTag
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: dockerRegistryUrl
        type: string
        description: The reference to the docker registry to scan with Protecode
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/registryUrl
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - 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: cleanupMode
        type: string
        description: Decides which parts are removed from the Protecode backend after the scan
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: binary
        possibleValues:
          - none
          - binary
          - complete
      - name: filePath
        type: string
        description: The path to the file from local workspace to scan with Protecode
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: timeoutMinutes
        aliases:
          - name: protecodeTimeoutMinutes
        type: string
        description: The timeout to wait for the scan to finish
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 60
      - name: serverUrl
        aliases:
          - name: protecodeServerUrl
        type: string
        description: The URL to the Protecode backend
        mandatory: true
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: reportFileName
        type: string
        description: The file name of the report to be created
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: protecode_report.pdf
      - name: fetchUrl
        type: string
        description: The URL to fetch the file or image to scan with Protecode.
        longDescription: The URL to fetch the file or image to scan with Protecode. The URL must be accessible via public HTTP GET request. To fetch a docker image the URL needs a 'docker-registry-' prefix.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: group
        aliases:
          - name: protecodeGroup
        type: string
        description: The Protecode group ID of your team
        mandatory: true
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: verifyOnly
        aliases:
          - name: reuseExisting
            deprecated: true
        type: bool
        description: Whether the step shall only apply verification checks or whether it does a full scan and check cycle
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: false
      - name: replaceProductId
        type: int
        description: Specify <replaceProductId> which application binary will be replaced and rescanned and product id remains unchanged. By using this parameter, Protecode avoids creating multiple same products. Note this will affect results and feeds. If product id is not specified, then Piper starts auto detection mechanism, more precisely it searches a product id with scanned product name in that specified group, if there are several scans have been done with the same product name then the latest scan id will be fetched from BDBA backend. After obtaining product id, Piper re-uploads / replaces new binary without affecting already existing product id.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: username
        aliases:
          - name: user
            deprecated: true
        type: string
        description: User which is used for the protecode scan
        mandatory: true
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        resourceRef:
          - name: protecodeCredentialsId
            type: secret
            param: username
          - type: vaultSecret
            name: protecodeVaultSecretName
            default: protecode
      - name: password
        type: string
        description: Password which is used for the user
        mandatory: true
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        resourceRef:
          - name: protecodeCredentialsId
            type: secret
            param: password
          - type: vaultSecret
            name: protecodeVaultSecretName
            default: protecode
      - name: userAPIKey
        type: string
        description: User API key which is used for API calls. Replacement for username and password / basic authentication.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        resourceRef:
          - name: protecodeApiKeyCredentialsId
            type: secret
            param: userAPIKey
          - type: vaultSecret
            name: protecodeApiKeyVaultSecretName
            default: protecode
      - name: version
        aliases:
          - name: artifactVersion
            deprecated: true
        type: string
        description: The version of the artifact to allow identification in protecode backend
        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 BDBA 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: 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: pullRequestName
        type: string
        description: The name of the pull request
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: customDataJSONMap
        type: string
        description:
          "The JSON map of key-value pairs to be included in this scan's Custom Data (See protecode API)."
        scope:
          - GENERAL
          - STEPS
          - STAGES
          - PARAMETERS
  outputs:
    resources:
      - name: influx
        type: influx
        params:
          - name: step_data
            fields:
              - name: protecode
                type: bool
          - name: protecode_data
            fields:
              - name: excluded_vulnerabilities
                type: int
              - name: historical_vulnerabilities
                type: int
              - name: major_vulnerabilities
                type: int
              - name: minor_vulnerabilities
                type: int
              - name: triaged_vulnerabilities
                type: int
              - name: vulnerabilities
                type: int
      - name: reports
        type: reports
        params:
          - filePattern: "**/toolrun_protecode_*.json"
            type: protecode
          - paramRef: reportFileName
            type: protecode
          - filePattern: "**/protecodeExecuteScan.json"
            type: protecode
          - filePattern: "**/protecodescan_vulns.json"
            type: protecode