credentialdiggerScan¶
Scan a repository on GitHub with Credential Digger
Description¶
This step allows you to scan a repository on Github using Credential Digger.
It can for example be used for DevSecOps scenarios to verify the source code does not contain hard-coded credentials before being merged or released for production. It supports several scan flavors, i.e., full scans of a repo, scan of a snapshot, or scan of a pull request.
Usage¶
We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.
library('piper-lib-os')
credentialdiggerScan script: this
piper credentialdiggerScan
Outputs¶
Output type | Details |
---|---|
Parameters¶
Overview - Step¶
Name | Mandatory | Additional information |
---|---|---|
script | (yes) | |
token | (yes) | githubTokenCredentialsId ) |
apiUrl | no | |
debug | no | |
exportAll | no | |
models | no | |
prNumber | no | |
repository | no | |
rulesDownloadUrl | no | |
rulesFile | no | |
snapshot | no | |
verbose | no | activates debug output |
Overview - Execution Environment¶
Orchestrator-specific only
These parameters are relevant for orchestrator usage and not considered when using the command line option.
Name | Mandatory | Additional information |
---|---|---|
containerCommand | no | |
containerShell | no | |
dockerEnvVars | no | |
dockerImage | no | |
dockerName | no | |
dockerOptions | no | |
dockerPullImage | no | |
dockerVolumeBind | no | |
dockerWorkspace | no |
Details¶
apiUrl¶
Set the GitHub API url. Needed for scanning a pull request.
Scope | Details |
---|---|
Aliases | githubApiUrl |
Type | string |
Mandatory | no |
Default | https://api.github.com |
Secret | no |
Configuration scope |
|
Resource references | none |
containerCommand¶
Jenkins-specific: Used for proper environment setup.
Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
containerShell¶
Jenkins-specific: Used for proper environment setup.
Allows to specify the shell to be executed for container with containerName.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
debug¶
Execute the scans in debug mode (i.e., print logs).
Scope | Details |
---|---|
Aliases | verbose |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerEnvVars¶
Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerImage¶
Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | saposs/credentialdigger:4.14.0 |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerName¶
Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerOptions¶
Docker options to be set when starting the container.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerPullImage¶
Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerVolumeBind¶
Jenkins-specific: Used for proper environment setup.
Volumes that should be mounted into the docker container.
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerWorkspace¶
Jenkins-specific: Used for proper environment setup.
Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
exportAll¶
Export all the findings, i.e., including non-leaks.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
models¶
Machine learning models to automatically verify the findings.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_models (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
prNumber¶
If set, scan the pull request open with this number.
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 0 |
Secret | no |
Configuration scope |
|
Resource references | none |
repository¶
URL of the GitHub repository (was name, but we need the url). In case it's missing, use the URL of the current repository.
Scope | Details |
---|---|
Aliases | githubRepo |
Type | string |
Mandatory | no |
Default | $PIPER_repository (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
rulesDownloadUrl¶
URL where to download custom rules. The file published at this URL must be formatted as the default ruleset https://raw.githubusercontent.com/SAP/credential-digger/main/ui/backend/rules.yml
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_rulesDownloadUrl (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
rulesFile¶
Name of the rules file used locally within the step. If a remote files for rules is declared as rulesDownloadUrl
, the stashed file is ignored. If you change the file's name make sure your stashing configuration also reflects this.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | inputs/rules.yml |
Secret | no |
Configuration scope |
|
Resource references | none |
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
snapshot¶
If set, scan the snapshot of the repository at this commit_id/branch.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_snapshot (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
token¶
GitHub personal access token as per https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line
Scope | Details |
---|---|
Aliases | - githubToken - access_token |
Type | string |
Mandatory | yes |
Default | $PIPER_token (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: githubTokenCredentialsId Vault resource: name: githubVaultSecretName default value: github 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 |
githubTokenCredentialsId¶
Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|