sap-jenkins-library/resources/metadata/fortify.yaml

metadata:
  name: 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.
  longDescription: |-
    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.    

spec:
  inputs:
    secrets:
      - name: fortifyCredentialsId
        description: Jenkins 'Secret text' credentials ID containing token to authenticate to Fortify SSC.
        type: jenkins
      - name: githubTokenCredentialsId
        description: Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.
        type: jenkins
    resources:
      - name: commonPipelineEnvironment
        resourceSpec:
          type: piperEnvironment
      - name: buildDescriptor
        type: stash
      - name: deployDescriptor
        type: stash
      - name: tests
        type: stash
      - name: opensourceConfiguration
        type: stash
    params:
      - name: authToken
        type: string
        description: "The FortifyToken to use for authentication"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        mandatory: true
        secret: true
        resourceRef:
          - name: fortifyCredentialsId
            type: secret
          - type: vaultSecret
            paths:
              - $(vaultPath)/fortify
              - $(vaultBasePath)/$(vaultPipelineName)/fortify
              - $(vaultBasePath)/GROUP-SECRETS/fortify
      - name: githubToken
        description: "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:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        type: string
        secret: true
        resourceRef:
          - name: githubTokenCredentialsId
            type: secret
      - name: autoCreate
        type: bool
        description:
          "Whether Fortify project and project version shall be implicitly auto created in case they
          cannot be found in the backend"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: modulePath
        type: string
        description: "Allows providing the path for the module to scan"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "./"
      - name: pythonRequirementsFile
        type: string
        description:
          "The requirements file used in `buildTool: 'pip'` to populate
          the build environment with the necessary dependencies"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: autodetectClasspath
        type: bool
        description: "Whether the classpath is automatically determined via build tool i.e. maven or pip or not at all"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: mustAuditIssueGroups
        type: string
        description: "Comma separated list of issue groups that must be audited completely"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "Corporate Security Requirements, Audit All"
      - name: spotAuditIssueGroups
        type: string
        description:
          "Comma separated list of issue groups that are spot checked and for which `spotCheckMinimum`
          audited issues are enforced"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "Spot Checks of Each Category"
      - name: pythonRequirementsInstallSuffix
        type: string
        description:
          "The suffix for the command used to install the requirements file in `buildTool: 'pip'` to populate
          the build environment with the necessary dependencies"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: pythonVersion
        type: string
        description: "Python version to be used in `buildTool: 'pip'`"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: python3
      - name: uploadResults
        type: bool
        description: "Whether results shall be uploaded or not"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: buildDescriptorFile
        type: string
        conditions:
          - conditionRef: strings-equal
            params:
              - name: buildTool
                value: maven
        description: "Path to the build descriptor file addressing the module/folder to be scanned."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: ./pom.xml
      - name: buildDescriptorFile
        type: string
        conditions:
          - conditionRef: strings-equal
            params:
              - name: buildTool
                value: pip
        description: "Path to the build descriptor file addressing the module/folder to be scanned."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: ./setup.py
      - name: commitId
        description: "Set the Git commit ID for identifying artifacts throughout the scan."
        resourceRef:
          - name: commonPipelineEnvironment
            param: git/commitId
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        type: string
      - name: commitMessage
        description: "Set the Git commit message for identifying pull request merges throughout the scan."
        resourceRef:
          - name: commonPipelineEnvironment
            param: git/commitMessage
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        type: string
      - name: githubApiUrl
        description: "Set the GitHub API URL."
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        type: string
        default: "https://api.github.com"
      - name: owner
        aliases:
          - name: githubOrg
        description: "Set the GitHub organization."
        resourceRef:
          - name: commonPipelineEnvironment
            param: github/owner
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        type: string
      - name: repository
        aliases:
          - name: githubRepo
        description: "Set the GitHub repository."
        resourceRef:
          - name: commonPipelineEnvironment
            param: github/repository
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        type: string
      - name: memory
        type: string
        description: "The amount of memory granted to the translate/scan executions"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "-Xmx4G -Xms512M"
      - name: updateRulePack
        type: bool
        description: "Whether the rule pack shall be updated and pulled from Fortify SSC before scanning or not"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: reportDownloadEndpoint
        aliases:
          - name: fortifyReportDownloadEndpoint
        type: string
        description: "Fortify SSC endpoint for Report downloads"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: "/transfer/reportDownload.html"
      - name: pollingMinutes
        type: int
        description:
          "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"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 30
      - name: quickScan
        type: bool
        description:
          "Whether a quick scan should be performed, please consult the related Fortify documentation on
          JAM on the impact of this setting"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: false
      - name: translate
        type: string
        description:
          "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'`"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: src
        type: "[]string"
        description:
          "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 `['./**/*']`."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: exclude
        type: "[]string"
        description:
          "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."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: apiEndpoint
        aliases:
          - name: fortifyApiEndpoint
        type: string
        description: "Fortify SSC endpoint used for uploading the scan results and checking the audit state"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: "/api/v1"
      - name: reportType
        type: string
        description: The type of report to be generated
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "PDF"
      - name: pythonAdditionalPath
        type: "[]string"
        description: "A list of additional paths which can be used in `buildTool: 'pip'` for customization purposes"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: ["./lib", "."]
        deprecated: true
      - name: artifactUrl
        type: string
        description:
          "Path/URL pointing to an additional artifact repository for resolution of additional
          artifacts during the build"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: considerSuspicious
        type: bool
        description: "Whether suspicious issues should trigger the check to fail or not"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: fprUploadEndpoint
        aliases:
          - name: fortifyFprUploadEndpoint
        type: string
        description: "Fortify SSC endpoint for FPR uploads"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: "/upload/resultFileUpload.html"
      - name: projectName
        aliases:
          - name: fortifyProjectName
        type: string
        description: "The project used for reporting results in SSC"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: '{{list .GroupID .ArtifactID | join "-" | trimAll "-"}}'
      - name: reporting
        type: bool
        description: Influences whether a report is generated or not
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: false
      - name: serverUrl
        aliases:
          - name: fortifyServerUrl
          - name: sscUrl
            deprecated: true
        type: string
        description: "Fortify SSC Url to be used for accessing the APIs"
        mandatory: true
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: pullRequestMessageRegexGroup
        type: int
        description: "The group number for extracting the pull request id in `'pullRequestMessageRegex'`"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 1
      - name: deltaMinutes
        type: int
        description:
          "The number of minutes for which an uploaded FPR artifact is considered to be recent and
          healthy, if exceeded an error will be thrown"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 5
      - name: spotCheckMinimum
        type: int
        description:
          "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"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 1
      - name: fprDownloadEndpoint
        aliases:
          - name: fortifyFprDownloadEndpoint
        type: string
        description: "Fortify SSC endpoint for FPR downloads"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: "/download/currentStateFprDownload.html"
      - name: versioningModel
        aliases:
          - name: defaultVersioningModel
            deprecated: true
        type: string
        description:
          "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'`"
        scope:
          - PARAMETERS
          - GENERAL
          - STAGES
          - STEPS
        default: "major"
        possibleValues:
          - major
          - major-minor
          - semantic
          - full
      - name: pythonInstallCommand
        type: string
        description:
          "Additional install command that can be run when `buildTool: 'pip'`
          is used which allows further customizing the execution environment of the scan"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "{{.Pip}} install --user ."
      - name: reportTemplateId
        type: int
        description: "Report template ID to be used for generating the Fortify report"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 18
      - name: filterSetTitle
        type: string
        description: "Title of the filter set to use for analysing the results"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: "SAP"
      - name: pullRequestName
        type: string
        description:
          "The name of the pull request branch which will trigger creation of a new version in Fortify
          SSC based on the master branch version"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: pullRequestMessageRegex
        type: string
        description: "Regex used to identify the PR-XXX reference within the merge commit message"
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: '.*Merge pull request #(\\d+) from.*'
      - name: buildTool
        type: string
        description: "Scan type used for the step which can be `'maven'`, `'pip'`"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        default: maven
      # Global maven settings, should be added to all maven steps
      - name: projectSettingsFile
        type: string
        description: Path to the mvn settings file that should be used as project settings file.
        scope:
          - GENERAL
          - STEPS
          - STAGES
          - PARAMETERS
        aliases:
          - name: maven/projectSettingsFile
      - name: globalSettingsFile
        type: string
        description: Path to the mvn settings file that should be used as global settings file.
        scope:
          - GENERAL
          - STEPS
          - STAGES
          - PARAMETERS
        aliases:
          - name: maven/globalSettingsFile
      - name: m2Path
        type: string
        description: Path to the location of the local repository that should be used.
        scope:
          - GENERAL
          - STEPS
          - STAGES
          - PARAMETERS
        aliases:
          - name: maven/m2Path
      - name: verifyOnly
        type: bool
        description: Whether the step shall only apply verification checks or whether it does a full scan and check cycle
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: false
  containers:
    - image: "<<please bring your own fortify image>>"
      workingDir: "/home/piper"
  outputs:
    resources:
      - name: influx
        type: influx
        params:
          - name: fortify_data
            fields:
              - name: projectName
              - name: projectVersion
              - name: violations
                type: int
              - name: corporateTotal
                type: int
              - name: corporateAudited
                type: int
              - name: auditAllTotal
                type: int
              - name: auditAllAudited
                type: int
              - name: spotChecksTotal
                type: int
              - name: spotChecksAudited
                type: int
              - name: spotChecksGap
                type: int
              - name: suspicious
                type: int
              - name: exploitable
                type: int
              - name: suppressed
                type: int