Skip to content

protecodeExecuteScan

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.

Description

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.

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.

Usage

We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.

library('piper-lib-os')

protecodeExecuteScan script: this
piper protecodeExecuteScan

Outputs

Output type Details
influx measurement step_data
  • protecode
  • measurement protecode_data
    • excluded_vulnerabilities
    • historical_vulnerabilities
    • major_vulnerabilities
    • minor_vulnerabilities
    • triaged_vulnerabilities
    • vulnerabilities

Prerequisites

  1. Create a Username / Password credential with the Protecode user in your Jenkins credential store
  2. Look up your Group ID using REST API via curl -u <username> "https://<protecode host>/api/groups/".

If the image is on a protected registry you can provide a Docker config.json file containing the credential information for the registry. You can either use docker login (see the Docker documentation for details) or you can create the file manually using the following script.

#!/bin/bash
auth=$(echo -n "$USER:$PASSWORD" | base64 -w0)
cat <<EOF > config.json
{
    "auths": {
        "$REGISTRY": {
            "auth": "$auth"
        }
    }
}
EOF

REGISTRY is the URL of the protected registry (Example: https://index.docker.io/v1).

Attention: If you reference the file in --dockerConfigJSON or upload the file to the Jenkins credential store, the file has to be named config.json.

Parameters

Overview - Step

Name Mandatory Additional information
group yes
password (yes) Vault Secret pass via ENV, Vault or Jenkins credentials (protecodeCredentialsId)
script (yes) Jenkins only reference to Jenkins main pipeline script
serverUrl yes
username (yes) Vault Secret pass via ENV, Vault or Jenkins credentials (protecodeCredentialsId)
cleanupMode no
containerRegistryPassword no Secret pass via ENV or Jenkins credentials
containerRegistryUser no Secret pass via ENV or Jenkins credentials
customDataJSONMap no
customScanVersion no
dockerConfigJSON no Vault Secret pass via ENV, Vault or Jenkins credentials (dockerConfigJsonCredentialsId)
dockerRegistryUrl no
excludeCVEs no
failOnSevereVulnerabilities no
fetchUrl no
filePath no
pullRequestName no
replaceProductId no
reportFileName no
scanImage no
timeoutMinutes no
userAPIKey no Vault Secret pass via ENV, Vault or Jenkins credentials (protecodeApiKeyCredentialsId)
verbose no activates debug output
verifyOnly no
version no
versioningModel no

Overview - Execution Environment

Orchestrator-specific only

These parameters are relevant for orchestrator usage and not considered when using the command line option.

Name Mandatory Additional information

Details

cleanupMode

Decides which parts are removed from the Protecode backend after the scan

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default binary
Possible values - none
- binary
- complete
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

containerRegistryPassword

For buildTool: docker: Password for container registry access - typically provided by the CI/CD environment.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_containerRegistryPassword (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: container/repositoryPassword
commonPipelineEnvironment:
  reference to: custom/repositoryPassword

containerRegistryUser

For buildTool: docker: Username for container registry access - typically provided by the CI/CD environment.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_containerRegistryUser (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: container/repositoryUsername
commonPipelineEnvironment:
  reference to: custom/repositoryUsername

customDataJSONMap

The JSON map of key-value pairs to be included in this scan's Custom Data (See protecode API).

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_customDataJSONMap (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

customScanVersion

Defines a custom version for the BDBA scan which deviates from the typical versioning pattern using version and versioningModel. It allows to set non-numeric versions as well and supersedes the value of 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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_customScanVersion (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerConfigJSON

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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_dockerConfigJSON (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: custom/dockerConfigJSON
Jenkins credential id:
  id: dockerConfigJsonCredentialsId

Vault resource:
  name: dockerConfigFileVaultSecretName
  default value: docker-config

Vault paths:
  • $(vaultPath)/docker-config
  • $(vaultBasePath)/$(vaultPipelineName)/docker-config
  • $(vaultBasePath)/GROUP-SECRETS/docker-config

dockerRegistryUrl

The reference to the docker registry to scan with Protecode

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_dockerRegistryUrl (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: container/registryUrl

excludeCVEs

DEPRECATED: Do use triaging within the Protecode UI instead

back to overview

Scope Details
Aliases protecodeExcludeCVEs
Type string
Mandatory no
Default ''
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

failOnSevereVulnerabilities

Whether to fail the step on severe vulnerabilties or not

back to overview

Scope Details
Aliases protecodeFailOnSevereVulnerabilities
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

fetchUrl

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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_fetchUrl (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

filePath

The path to the file from local workspace to scan with Protecode

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_filePath (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

group

The Protecode group ID of your team

back to overview

Scope Details
Aliases protecodeGroup
Type string
Mandatory yes
Default $PIPER_group (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

password

Password which is used for the user

back to overview

Scope Details
Aliases -
Type string
Mandatory yes
Default $PIPER_password (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: protecodeCredentialsId
  reference to: password

Vault resource:
  name: protecodeVaultSecretName
  default value: protecode

Vault paths:
  • $(vaultPath)/protecode
  • $(vaultBasePath)/$(vaultPipelineName)/protecode
  • $(vaultBasePath)/GROUP-SECRETS/protecode

pullRequestName

The name of the pull request

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_pullRequestName (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

replaceProductId

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.

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 0
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

reportFileName

The file name of the report to be created

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default protecode_report.pdf
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

scanImage

The reference to the docker image to scan with Protecode. Note: If possible please also check fetchUrl parameter, which might help you to optimize upload time.

back to overview

Scope Details
Aliases dockerImage
Type string
Mandatory no
Default $PIPER_scanImage (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: container/imageNameTag

script

Jenkins-specific: Used for proper environment setup.

The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

back to overview

Scope Details
Aliases -
Type Jenkins Script
Mandatory yes
Default
Secret no
Configuration scope
  • ☐ parameter
  • ☐ general
  • ☐ steps
  • ☐ stages
Resource references none

serverUrl

The URL to the Protecode backend

back to overview

Scope Details
Aliases protecodeServerUrl
Type string
Mandatory yes
Default $PIPER_serverUrl (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

timeoutMinutes

The timeout to wait for the scan to finish

back to overview

Scope Details
Aliases protecodeTimeoutMinutes
Type string
Mandatory no
Default 60
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

userAPIKey

User API key which is used for API calls. Replacement for username and password / basic authentication.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_userAPIKey (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: protecodeApiKeyCredentialsId
  reference to: userAPIKey

Vault resource:
  name: protecodeApiKeyVaultSecretName
  default value: protecode

Vault paths:
  • $(vaultPath)/protecode
  • $(vaultBasePath)/$(vaultPipelineName)/protecode
  • $(vaultBasePath)/GROUP-SECRETS/protecode

username

User which is used for the protecode scan

back to overview

Scope Details
Aliases user (deprecated)
Type string
Mandatory yes
Default $PIPER_username (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: protecodeCredentialsId
  reference to: username

Vault resource:
  name: protecodeVaultSecretName
  default value: protecode

Vault paths:
  • $(vaultPath)/protecode
  • $(vaultBasePath)/$(vaultPipelineName)/protecode
  • $(vaultBasePath)/GROUP-SECRETS/protecode

verbose

verbose output

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

verifyOnly

Whether the step shall only apply verification checks or whether it does a full scan and check cycle

back to overview

Scope Details
Aliases reuseExisting (deprecated)
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

version

The version of the artifact to allow identification in protecode backend

back to overview

Scope Details
Aliases artifactVersion (deprecated)
Type string
Mandatory no
Default $PIPER_version (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: artifactVersion

versioningModel

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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default major
Possible values - major
- major-minor
- semantic
- full
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

protecodeCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Username with password' credentials ID containing username and password to authenticate to the Protecode system.

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

protecodeApiKeyCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret text' credentials ID containing API Key/token to authenticate to BDBA server.

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

dockerConfigJsonCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret file' credentials ID containing Docker config.json (with registry credential(s)). You can create it like explained in Prerequisites.

back to overview

Scope Details
Aliases dockerCredentialsId (deprecated)
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

Details

  • The Protecode scan step is able to send a file addressed via parameter filePath to the backend for scanning it for known vulnerabilities.
  • Alternatively an HTTP URL can be specified via fetchUrl. Protecode will then download the artifact from there and scan it.
  • To support docker image scanning please provide scanImage with a docker like URL poiting to the image tag within the docker registry being used.
  • To receive the result it polls until the job completes.
  • Once the job has completed a PDF report is pulled from the backend and archived in the build
  • Finally the scan result is being analysed for critical findings with a CVSS v3 score >= 7.0 and if such findings are detected the build is failed based on the configuration setting failOnSevereVulnerabilities.
  • During the analysis all CVEs which are triaged are ignored and will not provoke the build to fail.