Skip to content

protecodeExecuteScan

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.

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

name mandatory default possible values
addSideBarLink No true true, false
artifactVersion No
cleanupMode No binary none, binary, complete
dockerCredentialsId Yes
dockerRegistryUrl No
excludeCVEs No []
failOnSevereVulnerabilities No true true, false
fetchUrl No
filePath No
group Yes
includeLayers No false true, false
password Yes
protecodeCredentialsId Yes
pullRequestName No
reportFileName No protecode_report.pdf
reuseExisting No false true, false
scanImage No
script Yes
serverUrl Yes
timeoutMinutes No 60
username Yes
verbose No false true, false
  • addSideBarLink: Whether to create a side bar link pointing to the report produced by Protecode or not
  • artifactVersion: The version of the artifact to allow identification in protecode backend
  • cleanupMode: Decides which parts are removed from the Protecode backend after the scan
  • dockerRegistryUrl: The reference to the docker registry to scan with Protecode
  • excludeCVEs: DEPRECATED: Do use triaging within the Protecode UI instead
  • failOnSevereVulnerabilities: Whether to fail the job on severe vulnerabilties or not
  • fetchUrl: The URL to fetch the file to scan with Protecode which must be accessible via public HTTP GET request
  • filePath: The path to the file from local workspace to scan with Protecode
  • group: The Protecode group ID of your team
  • includeLayers: Flag if the docker layers should be included
  • password: Password which is used for the user
  • pullRequestName: The name of the pull request
  • reportFileName: The file name of the report to be created
  • reuseExisting: Whether to reuse an existing product instead of creating a new one
  • scanImage: The reference to the docker image to scan with Protecode
  • script: 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.
  • serverUrl: The URL to the Protecode backend
  • timeoutMinutes: The timeout to wait for the scan to finish
  • username: User which is used for the protecode scan
  • verbose: verbose output

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.

Step Configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter general step/stage
addSideBarLink X
artifactVersion X
cleanupMode X
dockerRegistryUrl X X
excludeCVEs X
failOnSevereVulnerabilities X
fetchUrl X
filePath X
group X
includeLayers X
password X
pullRequestName X
reportFileName X
reuseExisting X
scanImage X X
serverUrl X X
timeoutMinutes X
username X
verbose X