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.

JenkinsCommand 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)	pass via ENV, Vault or Jenkins credentials (protecodeCredentialsId)
script	(yes)	reference to Jenkins main pipeline script
serverUrl	yes
username	(yes)	pass via ENV, Vault or Jenkins credentials (protecodeCredentialsId)
cleanupMode	no
customDataJSONMap	no
customScanVersion	no
dockerConfigJSON	no	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	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

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