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
|
Prerequisites¶
- Create a Username / Password credential with the Protecode user in your Jenkins credential store
- 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 | protecodeCredentialsId ) |
script | yes | |
serverUrl | yes | |
username | yes | protecodeCredentialsId ) |
artifactVersion | no | |
cleanupMode | no | |
dockerConfigJSON | no | 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
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_artifactVersion (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: artifactVersion |
cleanupMode¶
Decides which parts are removed from the Protecode backend after the scan
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | binary |
Possible values | - none - binary - complete |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_dockerConfigJSON (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: dockerConfigJsonCredentialsId |
dockerRegistryUrl¶
The reference to the docker registry to scan with Protecode
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_dockerRegistryUrl (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: container/registryUrl |
excludeCVEs¶
DEPRECATED: Do use triaging within the Protecode UI instead
Scope | Details |
---|---|
Aliases | protecodeExcludeCVEs |
Type | string |
Mandatory | no |
Default | '' |
Secret | no |
Configuration scope |
|
Resource references | none |
failOnSevereVulnerabilities¶
Whether to fail the job on severe vulnerabilties or not
Scope | Details |
---|---|
Aliases | protecodeFailOnSevereVulnerabilities |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
fetchUrl¶
The URL to fetch the file to scan with Protecode which must be accessible via public HTTP GET request
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_fetchUrl (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
filePath¶
The path to the file from local workspace to scan with Protecode
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_filePath (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
group¶
The Protecode group ID of your team
Scope | Details |
---|---|
Aliases | protecodeGroup |
Type | string |
Mandatory | yes |
Default | $PIPER_group (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
includeLayers¶
Flag if the docker layers should be included
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
password¶
Password which is used for the user
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_password (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: protecodeCredentialsId reference to: password Vault paths:
|
pullRequestName¶
The name of the pull request
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_pullRequestName (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
reportFileName¶
The file name of the report to be created
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | protecode_report.pdf |
Secret | no |
Configuration scope |
|
Resource references | none |
reuseExisting¶
Whether to reuse an existing product instead of creating a new one
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
scanImage¶
The reference to the docker image to scan with Protecode
Scope | Details |
---|---|
Aliases | dockerImage |
Type | string |
Mandatory | no |
Default | $PIPER_scanImage (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
serverUrl¶
The URL to the Protecode backend
Scope | Details |
---|---|
Aliases | protecodeServerUrl |
Type | string |
Mandatory | yes |
Default | $PIPER_serverUrl (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
timeoutMinutes¶
The timeout to wait for the scan to finish
Scope | Details |
---|---|
Aliases | protecodeTimeoutMinutes |
Type | string |
Mandatory | no |
Default | 60 |
Secret | no |
Configuration scope |
|
Resource references | none |
username¶
User which is used for the protecode scan
Scope | Details |
---|---|
Aliases | user (deprecated) |
Type | string |
Mandatory | yes |
Default | $PIPER_username (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: protecodeCredentialsId reference to: username Vault paths:
|
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | dockerCredentialsId (deprecated) |
Type | string |
Configuration scope |
|
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.