

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 pipelines

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. Request creation of a team for your development group as described here and in addition request creation of a technical Protecode user through OS3 team
2. Create a Username / Password credential with the Protecode technical user in your Jenkins credential store
3. Supply the credential ID either via config.yml or on the step via parameter protecodeCredentialsId
4. Supply the group ID of the Protecode group via parameter protecodeGroup. You can either inquire this value from OS3 upon creation of the group or look it up yourself via REST API using curl -u <place your user here> "https://<protecode host>/api/groups/".

Example

Usage of pipeline step:

Workspace based:

executeProtecodeScan script: this, filePath: 'dockerImage.tar'

Fetch URL:

executeProtecodeScan script: this, fetchUrl: 'https://nexusrel.wdf.sap.corp:8443/nexus/service/local/repositories/build.releases.3rd-party.proxy.2018.04.13/content/org/alfresco/surf/spring-cmis-framework/6.11/spring-cmis-framework-6.11.jar'

Docker image:

executeProtecodeScan script: this, dockerRegistryUrl: 'https://docker.wdf.sap.corp:50000', dockerImage: 'piper/yeoman:1.0-20180321110554'

Parameters

Overview

Name	Mandatory	Additional information
dockerCredentialsId	yes	id of credentials (using credentials)
group	yes
password	yes	pass via ENV or Jenkins credentials
protecodeCredentialsId	yes	id of credentials (using credentials)
script	yes	reference to Jenkins main pipeline script
serverUrl	yes
username	yes	pass via ENV or Jenkins credentials
addSideBarLink	no
artifactVersion	no
cleanupMode	no
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

addSideBarLink

Whether to create a side bar link pointing to the report produced by Protecode or not

back to overview

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

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

dockerCredentialsId

Jenkins-specific: Used for proper environment setup.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

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	none

protecodeCredentialsId

Jenkins-specific: Used for proper environment setup.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

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	none

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

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 dockerImage with a docker like URL poiting to the image tag within the docker registry being used. Our step uses skopeo to download the image and sends it to Protecode for scanning.
• 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 protecodeFailOnSevereVulnerabilities.
• During the analysis all CVEs which are either triaged in the Protecode backend or which are excluded via configuration parameter protecodeExcludeCVEs are ignored and will not provoke the build to fail.

FAQs:

• In case of dockerImage and the step still tries to pull and save it via docker daemon, please make sure your JaaS environment has the variable ON_K8S declared and set to true.