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) | reference to Jenkins main pipeline script |
token | (yes) | pass via ENV, Vault or Jenkins credentials (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¶
Jenkins-specific: Used for proper environment setup.
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¶
Jenkins-specific: Used for proper environment setup.
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¶
Jenkins-specific: Used for proper environment setup.
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¶
Jenkins-specific: Used for proper environment setup.
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¶
Jenkins-specific: Used for proper environment setup.
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¶
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 |
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-specific: Used for proper environment setup. See using credentials for details.
Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|