

protecodeExecuteScan

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

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.

Auditing findings (Triaging)

Triaging is now supported by the Protecode backend and also Piper does consider this information during the analysis of the scan results though product versions are not supported by 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 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 config.yml file. In this case, calling the step is reduced to one simple line.
Calling the step can be done either via the Jenkins library step or on the command line.

Jenkins Pipeline

library('piper-lib-os')

protecodeExecuteScan script: this

Command Line

piper protecodeExecuteScan

Outputs

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

Prerequisites

1. Create a Username / Password credential with the Protecode user in your Jenkins credential store
2. Lookup 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 create it like explained in the Docker Success Center in the article about how to generate a new auth in the config.json file.

Parameters

Overview

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)
artifactVersion	no
cleanupMode	no
dockerConfigJSON	no	pass via ENV or Jenkins credentials (dockerConfigJsonCredentialsId)
dockerRegistryUrl	no
excludeCVEs	no
failOnSevereVulnerabilities	no
fetchUrl	no
filePath	no
includeLayers	no
pullRequestName	no
reportFileName	no
reuseExisting	no
scanImage	no
timeoutMinutes	no
verbose	no	activates debug output

Details

artifactVersion

The version of the artifact to allow identification in protecode backend

back to overview

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

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

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	Jenkins credential id:   id: dockerConfigJsonCredentialsId

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 job 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 to scan with Protecode which must be accessible via public HTTP GET request

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

includeLayers

Flag if the docker layers should be included

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

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

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

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

reuseExisting

Whether to reuse an existing product instead of creating a new one

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

scanImage

The reference to the docker image to scan with Protecode

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

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

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

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

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 the Docker Success Center in the article about how to generate a new auth in the config.json file.

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.