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: 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 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: 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 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