Skip to content

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 Secret pass via ENV or Jenkins credentials (protecodeCredentialsId)
script yes Jenkins only reference to Jenkins main pipeline script
serverUrl yes
username yes Secret pass via ENV or Jenkins credentials (protecodeCredentialsId)
artifactVersion no
cleanupMode no
dockerConfigJSON no Secret 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
  reference to: ``

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

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

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.