Skip to content

fortifyExecuteScan

Description

This step executes a Fortify scan on the specified project to perform static code analysis and check the source code for security flaws.

The Fortify step triggers a scan locally on your Jenkins within a docker container so finally you have to supply a docker image with a Fortify SCA and Java plus Maven or alternatively Python installed into it for being able to perform any scans.

DISCLAIMER: The step has not yet been tested on a wide variaty of projects, and is therefore considered of BETA quality.

Parameters

name mandatory default possible values
apiEndpoint No /api/v1
artifactUrl No
authToken Yes
autoCreate No false true, false
autodetectClasspath No true true, false
buildDescriptorFile No
buildTool No maven
commitId No
commitMessage No
considerSuspicious No true true, false
defaultVersioningModel No major
deltaMinutes No 5
dockerEnvVars No []
dockerImage No ppiper/fortify
dockerOptions No []
dockerWorkspace No /home/piper
exclude No
filterSetTitle No SAP
fortifyCredentialsId Yes
fprDownloadEndpoint No /download/currentStateFprDownload.html
fprUploadEndpoint No /upload/resultFileUpload.html
githubApiUrl No https://api.github.com
githubToken No
githubTokenCredentialsId Yes
globalSettingsFile No
m2Path No
memory No -Xmx4G -Xms512M
modulePath No ./
mustAuditIssueGroups No Corporate Security Requirements, Audit All
owner No
pollingMinutes No 30
projectName No {{list .GroupID .ArtifactID | join "-" | trimAll "-"}}
projectSettingsFile No
pullRequestMessageRegex No .*Merge pull request #(\\d+) from.*
pullRequestMessageRegexGroup No 1
pullRequestName No
pythonAdditionalPath No [./lib .]
pythonInstallCommand No {{.Pip}} install --user .
pythonRequirementsFile No
pythonRequirementsInstallSuffix No
pythonVersion No python3
quickScan No false true, false
reportDownloadEndpoint No /transfer/reportDownload.html
reportTemplateId No 18
reportType No PDF
reporting No false true, false
repository No
script Yes
serverUrl No
spotAuditIssueGroups No Spot Checks of Each Category
spotCheckMinimum No 1
src No
stashContent No [buildDescriptor, deployDescriptor, tests, opensourceConfiguration]
translate No
updateRulePack No true true, false
uploadResults No true true, false
verbose No false true, false
  • apiEndpoint: Fortify SSC endpoint used for uploading the scan results and checking the audit state
  • artifactUrl: Path/URL pointing to an additional artifact repository for resolution of additional artifacts during the build
  • authToken: The FortifyToken to use for authentication
  • autoCreate: Whether Fortify project and project version shall be implicitly auto created in case they cannot be found in the backend
  • autodetectClasspath: Whether the classpath is automatically determined via build tool i.e. maven or pip or not at all
  • buildDescriptorFile: Path to the build descriptor file addressing the module/folder to be scanned. Defaults are for buildTool=maven: ./pom.xml, buildTool=pip: ./setup.py.
  • buildTool: Scan type used for the step which can be 'maven', 'pip'
  • commitId: Set the Git commit ID for identifying artifacts throughout the scan.
  • commitMessage: Set the Git commit message for identifying pull request merges throughout the scan.
  • considerSuspicious: Whether suspicious issues should trigger the check to fail or not
  • defaultVersioningModel: The default project versioning model used for creating the version based on the build descriptor version to report results in SSC, can be one of 'major', 'major-minor', 'semantic', 'full'
  • deltaMinutes: The number of minutes for which an uploaded FPR artifact is considered to be recent and healthy, if exceeded an error will be thrown
  • dockerEnvVars: Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
  • 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.
  • dockerOptions: Docker options to be set when starting the container.
  • dockerWorkspace: Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.
  • exclude: A list of directories/files to be excluded from the scan. Wildcards can be used, e.g., '**/Test.java'. If translate is set, this will ignored.
  • filterSetTitle: Title of the filter set to use for analysing the results
  • fortifyCredentialsId: Jenkins 'Secret text' credentials ID containing token to authenticate to Fortify SSC.
  • fprDownloadEndpoint: Fortify SSC endpoint for FPR downloads
  • fprUploadEndpoint: Fortify SSC endpoint for FPR uploads
  • githubApiUrl: Set the GitHub API URL.
  • githubToken: GitHub personal access token as per https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line
  • githubTokenCredentialsId: Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.
  • globalSettingsFile: Path to the mvn settings file that should be used as global settings file.
  • m2Path: Path to the location of the local repository that should be used.
  • memory: The amount of memory granted to the translate/scan executions
  • modulePath: Allows providing the path for the module to scan
  • mustAuditIssueGroups: Comma separated list of issue groups that must be audited completely
  • owner: Set the GitHub organization.
  • pollingMinutes: The number of minutes for which an uploaded FPR artifact''s status is being polled to finish queuing/processing, if exceeded polling will be stopped and an error will be thrown
  • projectName: The project used for reporting results in SSC
  • projectSettingsFile: Path to the mvn settings file that should be used as project settings file.
  • pullRequestMessageRegex: Regex used to identify the PR-XXX reference within the merge commit message
  • pullRequestMessageRegexGroup: The group number for extracting the pull request id in 'pullRequestMessageRegex'
  • pullRequestName: The name of the pull request branch which will trigger creation of a new version in Fortify SSC based on the master branch version
  • pythonAdditionalPath: A list of additional paths which can be used in buildTool: 'pip' for customization purposes
  • pythonInstallCommand: Additional install command that can be run when buildTool: 'pip' is used which allows further customizing the execution environment of the scan
  • pythonRequirementsFile: The requirements file used in buildTool: 'pip' to populate the build environment with the necessary dependencies
  • pythonRequirementsInstallSuffix: The suffix for the command used to install the requirements file in buildTool: 'pip' to populate the build environment with the necessary dependencies
  • pythonVersion: Python version to be used in buildTool: 'pip'
  • quickScan: Whether a quick scan should be performed, please consult the related Fortify documentation on JAM on the impact of this setting
  • reportDownloadEndpoint: Fortify SSC endpoint for Report downloads
  • reportTemplateId: Report template ID to be used for generating the Fortify report
  • reportType: The type of report to be generated
  • reporting: Influences whether a report is generated or not
  • repository: Set the GitHub repository.
  • 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: Fortify SSC Url to be used for accessing the APIs
  • spotAuditIssueGroups: Comma separated list of issue groups that are spot checked and for which spotCheckMinimum audited issues are enforced
  • spotCheckMinimum: The minimum number of issues that must be audited per category in the Spot Checks of each Category folder to avoid an error being thrown
  • src: A list of source directories to scan. Wildcards can be used, e.g., 'src/main/java/**/*'. If 'translate' is set, this will ignored. The default value for buildTool: 'maven' is ['/*.xml', '/.html', '/*.jsp', '/.js', '/src/main/resources//', '/src/main/java//'], for buildTool: 'pip' it is ['./*/'].
  • stashContent: Specific stashes that should be considered for the step execution.
  • translate: Options for translate phase of Fortify. Most likely, you do not need to set this parameter. See src, exclude. If 'src' and 'exclude' are set they are automatically used. Technical details: It has to be a JSON string of list of maps with required key 'src', and optional keys 'exclude', 'libDirs', 'aspnetcore', and 'dotNetCoreVersion'
  • updateRulePack: Whether the rule pack shall be updated and pulled from Fortify SSC before scanning or not
  • uploadResults: Whether results shall be uploaded or not
  • verbose: verbose output

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
apiEndpoint X X
artifactUrl X
authToken X
autoCreate X
autodetectClasspath X
buildDescriptorFile X
buildTool X X
commitId X
commitMessage X
considerSuspicious X
defaultVersioningModel X
deltaMinutes X
dockerEnvVars X
dockerImage X
dockerOptions X
dockerWorkspace X
exclude X
filterSetTitle X
fprDownloadEndpoint X X
fprUploadEndpoint X X
githubApiUrl X X
githubToken X X
globalSettingsFile X X
m2Path X X
memory X
modulePath X
mustAuditIssueGroups X
owner X
pollingMinutes X
projectName X
projectSettingsFile X X
pullRequestMessageRegex X
pullRequestMessageRegexGroup X
pullRequestName X
pythonAdditionalPath X
pythonInstallCommand X
pythonRequirementsFile X
pythonRequirementsInstallSuffix X
pythonVersion X X
quickScan X
reportDownloadEndpoint X X
reportTemplateId X
reportType X
reporting X
repository X
serverUrl X X
spotAuditIssueGroups X
spotCheckMinimum X
src X
stashContent X
translate X
updateRulePack X
uploadResults X
verbose X