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

metadata:
  name: fortifyExecuteScan
  description: This BETA 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.

    DISCLAIMER: The step has not yet been tested on a wide variaty of projects, and is therefore considered of BETA quality.    
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
    - 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
    - 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
      description: "Path to the build descriptor file addressing the module/folder
        to be scanned. Defaults are for buildTool=`maven`: `./pom.xml`, buildTool=`pip`:
        `./setup.py`."
      scope:
        - PARAMETERS
        - STAGES
        - STEPS
    - 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
  containers:
  - image: "ppiper/fortify"
    workingDir: "/home/piper"
  outputs:
    resources:
      - name: influx
        type: influx
        params:
          - name: fortify_data
            fields:
              - name: projectName
              - name: projectVersion
              - name: violations
              - name: corporateTotal
              - name: corporateAudited
              - name: auditAllTotal
              - name: auditAllAudited
              - name: spotChecksTotal
              - name: spotChecksAudited
              - name: spotChecksGap
              - name: suspicious
              - name: exploitable
              - name: suppressed