Skip to content

detectExecuteScan

Executes Synopsys Detect scan

Description

This step executes Synopsys Detect scans. Synopsys Detect command line utlity can be used to run various scans including BlackDuck and Polaris scans. This step allows users to run BlackDuck scans by default. Please configure your BlackDuck server Url using the serverUrl parameter and the API token of your user using the apiToken parameter for this step.

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')

detectExecuteScan script: this

Command Line

piper detectExecuteScan

Prerequisites

You need to store the API token for the Detect service as 'Secret text' credential in your Jenkins system.

Parameters

Overview

Name Mandatory Additional information
projectName yes
script yes Jenkins only reference to Jenkins main pipeline script
serverUrl yes
token yes Vault Secret pass via ENV, Vault or Jenkins credentials (detectTokenCredentialsId)
codeLocation no
containerCommand no Jenkins only
containerShell no Jenkins only
customEnvironmentVariables no
customScanVersion no
dependencyPath no
detectTools no
dockerEnvVars no Jenkins only
dockerImage no Jenkins only
dockerName no Jenkins only
dockerOptions no Jenkins only
dockerPullImage no Jenkins only
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only
excludedPackageManagers no
failOn no
globalSettingsFile no
groups no
includedPackageManagers no
installArtifacts no
m2Path no
mavenExcludedScopes no
projectSettingsFile no
scanOnChanges no
scanPaths no
scanProperties no
scanners no
stashContent no Jenkins only
unmap no
verbose no activates debug output
version no
versioningModel no

Details

codeLocation

An override for the name Detect will use for the scan file it creates.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_codeLocation (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
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).

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

containerShell

Jenkins-specific: Used for proper environment setup.

Allows to specify the shell to be executed for container with containerName.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

customEnvironmentVariables

A list of environment variables which can be set to prepare the environment to run a BlackDuck scan.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default $PIPER_customEnvironmentVariables (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

customScanVersion

Defines a custom version for the Detect scan which deviates from the typical versioning pattern using version and versioningModel. It allows to set non-numeric versions as well and supersedes the value of version which is calculated automatically. The parameter is also used by other scan steps (e.g. Fortify, Sonar, WhiteSource) and thus allows a common custom version across scan tools.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_customScanVersion (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dependencyPath

Absolute Path of the dependency management file of the project. This path represents the folder which contains the pom file, package.json etc. If the project contains multiple pom files, provide the path to the parent pom file or the base folder of the project

back to overview

Scope Details
Aliases detect/dependencyPath
Type string
Mandatory no
Default .
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

detectTools

The type of BlackDuck scanners to include while running the BlackDuck scan. By default All scanners are included. For the complete list of possible values, Please refer Synopsys detect documentation

back to overview

Scope Details
Aliases detect/detectTools
Type []string
Mandatory no
Default $PIPER_detectTools (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerEnvVars

Jenkins-specific: Used for proper environment setup.

Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].

back to overview

Scope Details
Aliases -
Type map[string]string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerOptions

Jenkins-specific: Used for proper environment setup.

Docker options to be set when starting the container.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
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.

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

dockerVolumeBind

Jenkins-specific: Used for proper environment setup.

Volumes that should be mounted into the docker container.

back to overview

Scope Details
Aliases -
Type map[string]string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

excludedPackageManagers

The package managers that need to be excluded for this scan. Providing the package manager names with this parameter will ensure that the build descriptor file of that package manager will be ignored in the scan folder For the complete list of possible values for this parameter, please refer Synopsys detect documentation

back to overview

Scope Details
Aliases detect/excludedPackageManagers
Type []string
Mandatory no
Default $PIPER_excludedPackageManagers (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

failOn

A list of policies can be provided which will be applied after the scan is completed. These policies if violated will mark the build/scan result as failed. The list of accepted values can be found at Synopsys detect documentation

back to overview

Scope Details
Aliases detect/failOn
Type []string
Mandatory no
Default - BLOCKER
Possible values - ALL
- BLOCKER
- CRITICAL
- MAJOR
- MINOR
- NONE
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

globalSettingsFile

Path or url to the mvn settings file that should be used as global settings file

back to overview

Scope Details
Aliases maven/globalSettingsFile
Type string
Mandatory no
Default $PIPER_globalSettingsFile (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

groups

Users groups to be assigned for the Project

back to overview

Scope Details
Aliases detect/groups
Type []string
Mandatory no
Default $PIPER_groups (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

includedPackageManagers

The package managers that need to be included for this scan. Providing the package manager names with this parameter will ensure that the build descriptor file of that package manager will be searched in the scan folder For the complete list of possible values for this parameter, please refer Synopsys detect documentation

back to overview

Scope Details
Aliases detect/includedPackageManagers
Type []string
Mandatory no
Default $PIPER_includedPackageManagers (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

installArtifacts

If enabled, it will install all artifacts to the local maven repository to make them available before running detect. This is required if any maven module has dependencies to other modules in the repository and they were not installed before.

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

m2Path

Path to the location of the local repository that should be used.

back to overview

Scope Details
Aliases maven/m2Path
Type string
Mandatory no
Default $PIPER_m2Path (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

mavenExcludedScopes

The maven scopes that need to be excluded from the scan. For example, setting the value 'test' will exclude all components which are defined with a test scope in maven

back to overview

Scope Details
Aliases detect/mavenExcludedScopes
Type []string
Mandatory no
Default $PIPER_mavenExcludedScopes (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

projectName

Name of the Synopsis Detect (formerly BlackDuck) project.

back to overview

Scope Details
Aliases detect/projectName
Type string
Mandatory yes
Default $PIPER_projectName (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

projectSettingsFile

Path or url to the mvn settings file that should be used as project settings file.

back to overview

Scope Details
Aliases maven/projectSettingsFile
Type string
Mandatory no
Default $PIPER_projectSettingsFile (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

scanOnChanges

This flag determines if the scan is submitted to the server. If set to true, then the scan request is submitted to the server only when changes are detected in the Open Source Bill of Materials If the flag is set to false, then the scan request is submitted to server regardless of any changes. For more details please refer to the documentation

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

scanPaths

List of paths which should be scanned by the Synopsis Detect (formerly BlackDuck) scan.

back to overview

Scope Details
Aliases detect/scanPaths
Type []string
Mandatory no
Default - .
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

scanProperties

Properties passed to the Synopsis Detect (formerly BlackDuck) scan. You can find details in the Synopsis Detect documentation

back to overview

Scope Details
Aliases detect/scanProperties
Type []string
Mandatory no
Default - --blackduck.signature.scanner.memory=4096
- --detect.timeout=6000
- --blackduck.trust.cert=true
- --logging.level.com.synopsys.integration=DEBUG
- --detect.maven.excluded.scopes=test
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

scanners

List of scanners to be used for Synopsis Detect (formerly BlackDuck) scan.

back to overview

Scope Details
Aliases detect/scanners
Type []string
Mandatory no
Default - signature
Possible values - signature
- source
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
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.

back to overview

Scope Details
Aliases -
Type Jenkins Script
Mandatory yes
Default
Secret no
Configuration scope
  • ☐ parameter
  • ☐ general
  • ☐ steps
  • ☐ stages
Resource references none

serverUrl

Server URL to the Synopsis Detect (formerly BlackDuck) Server.

back to overview

Scope Details
Aliases detect/serverUrl
Type string
Mandatory yes
Default $PIPER_serverUrl (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

stashContent

Jenkins-specific: Used for proper environment setup.

Specific stashes that should be considered for the step execution.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default - buildDescriptor
- checkmarx
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

token

Api token to be used for connectivity with Synopsis Detect server.

back to overview

Scope Details
Aliases - blackduckToken
- detectToken
- apiToken (deprecated)
- detect/apiToken (deprecated)
Type string
Mandatory yes
Default $PIPER_token (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: detectTokenCredentialsId

Vault paths:
  • $(vaultPath)/detect

unmap

Unmap flag will unmap all previous code locations and keep only the current scan results in the specified project version. Set this parameter to true, when the project version needs to store only the latest scan results.

back to overview

Scope Details
Aliases detect/unmap
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

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

version

Defines the version number of the artifact being build in the pipeline. It is used for build version creation and as source for the Detect version. Typically it is available through the pipeline run. The project version of the Detect project is calculated using the versioningModel.

back to overview

Scope Details
Aliases - projectVersion
- detect/projectVersion
Type string
Mandatory no
Default $PIPER_version (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: artifactVersion

versioningModel

The versioning model used for result reporting (based on the artifact version). For example: the version 1.2.3 of the artifact will result in a version 1 to report into, when versioningModel: major is used and will result in a version 1.2 when versioningModel: major-minor is used. Recommendation for a Continuous Delivery process is to use versioningModel: major.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default major
Possible values - major
- major-minor
- semantic
- full
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

detectTokenCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret text' credentials ID containing the API token used to authenticate with the Synopsis Detect (formerly BlackDuck) Server.

back to overview

Scope Details
Aliases apiTokenCredentialsId
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages