Build secure software fast with Fortify. Fortify offers end-to-end application security solutions with the flexibility of testing on-premises and on-demand to scale and cover the entire software development lifecycle. With Fortify, find security issues early and fix at the speed of DevOps.

FortifyVulnerabilityExporter allows for exporting vulnerabilities from Fortify on Demand and Fortify Software Security Center to the following third-party products and output formats:

• GitHub Integration
• GitLab Integration
• DefectDojo Integration
• SonarQube Integration
• CSV Export
• JSON Export

Please review the information in the following sections before integrating FortifyVulnerabilityExporter into your SDLC:

• Raw or Audited Results
• Generic Usage
• CI/CD Integration

• Downloads: https://github.com/fortify/FortifyVulnerabilityExporter/releases
  • Development releases may be unstable or non-functional. The *-thirdparty.zip file is for informational purposes only and does not need to be downloaded.
• Docker images: https://hub.docker.com/repository/docker/fortifydocker/fortify-vulnerability-exporter
  • latest and stable tags point to the latest production release
  • vX.Y.Z and X.Y.Z tags point to the given patch release
  • vX.Y and X.Y tags point to the latest patch release of the given minor release
  • vX and X tags point to the latest minor and patch release of the given major release
  • dev_<branch> tags point to the latest development release for a given branch
  • latest_rc tag points to the latest development release on the main branch
• Source code: https://github.com/fortify/FortifyVulnerabilityExporter
• Automated builds: https://github.com/fortify/FortifyVulnerabilityExporter/actions

Before deploying FortifyVulnerabilityExporter in a production environment, you should consider whether the utility should export all vulnerabilities, or vulnerabilities should be audited first to filter out any false positives and other non-interesting findings. This is an important decision to make and depends on how the exported data will be used.

The main risk with exporting all vulnerabilities without auditing them first is that users, for example developers, will get overwhelmed by the sheer number of issues. This may result in users simply ignoring the results, causing critical vulnerabilities not being acted upon, or users actively complaining about the solution. Of course, in other situations it may be perfectly valid to simply export all vulnerabilities independent of whether they have been audited first, as long as expectations are set right.

Obviously, requiring manual reviews of scan results will have an impact on how to integrate FortifyVulnerabilityExporter into your workflows; you cannot have a fully automated scan-and-export workflow if a manual review is required between scan and export. The sections below provide some considerations for FoD and SSC, and the CI/CD Integration section provides more details on the various automation approaches.

Fortify Professional Services can assist you in properly designing a solution that suits your requirements.

Exporting only actionable items is less of an issue with Fortify on Demand, as by default the first scan will be manually audited by the FoD team, and non-interesting results are filtered out using machine learning. However for larger projects you may want to perform additional manual reviews on the initial scan results before enabling Fortify Vulnerability Exporter, or perform regular manual reviews before running FortifyVulnerabilityExporter.

SSC provides various options for managing scan results, however by default scan results will need to be manually audited in order to filter out any false positives and other non-interesting findings. In order to produce a list of actionable items to be exported by FortifyVulnerabilityExporter, a combination of any of the following can be considered:

• Have FortifyVulnerabilityExporter export issues for which the Analysis tag has been set to Exploitable through manual review or auto-applied by Audit Assistant
• Have FortifyVulnerabilityExporter export issues based on Audit Assistant prediction tags
• Have FortifyVulnerabilityExporter export issues for which some dedicated custom tag has been set, for example Export to System1 is set to Yes
• Have FortifyVulnerabilityExporter export issues for which a custom tag Baseline is not set to Yes; assuming all issues have been marked as Baseline after the first scan, this will result in only newly introduced vulnerabilities being exported, not overwhelming users with previously existing issues
• Have FortifyVulnerabilityExporter export high-risk issues only based on static filters, by selecting only high risk issues like critical injection/data flow vulnerabilities (white list approach), or by filtering out less interesting issues, like issues in categories related to code quality (black list approach)

Filtering can be done using the various filtering options provided by FortifyVulnerabilityExporter, however utilizing SSC's Issue Templates functionality to provide dedicated views on vulnerabilities to be exported may prove a more manageable solution. For example, you could have an 'Export to System1' filter set and another 'Export to System2' filter set, each with their own selection criteria for the respective systems.

Similar to Fortify on Demand, the manual review can take place after the first scan only, or after every scan. When doing the manual review after the first scan only, you can either rely on Audit Assistant to filter out any newly introduced non-interesting findings, or you can accept the fact that users will see a relatively small number of non-interesting findings in the exported results. Of course you should have a proper process in place to properly handle such non-interesting findings.

FortifyVulnerabilityExporter can be invoked as either a stand-alone Java program, or by using a Docker image. In both cases, configuration and command line arguments are similar. General command line syntax is as follows:

• java -jar FortifyVulnerabilityExporter.jar [configFile] [options]
• docker run --rm fortifydocker/fortify-vulnerability-exporter [configFile] [options]

[configFile] can either be an absolute or relative path to a configuration file, and optionally the file extension can be omitted if the actual configuration file has one of the following extensions: yml, yaml, or properties. If a relative path (or no path) is specified, the utility will look for the configuration file in the following places, in this order:

• . (current working directory)
• ./config
• [JarDir] (directory where FortifyVulnerabilityExporter.jar is installed)
• [JarDir]/config
• /config (used by fortifydocker/fortify-vulnerability-exporter Docker image)

Following are some sample invocations based on the default configuration files that are usually located in [JarDir]/config:

• FoD to GitLab JSON:
  java -jar FortifyVulnerabilityExporter.jar FoDToGitLab --fod.baseUrl=https://emea.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPassword --fod.release.id=100

• SSC to GitHub SARIF:
  java -jar FortifyVulnerabilityExporter.jar SSCToGitHub --ssc.baseUrl=http://localhost:2010/ssc --ssc.user=MyUser --ssc.password=MyPassword --ssc.version.name=webgoat:5.0

• FoD to raw JSON:
  docker run --rm fortifydocker/fortify-vulnerability-exporter FoDToJsonRaw --fod.baseUrl=https://emea.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPassword --fod.release.id=100

• FoD to CSV:
  docker run --rm fortifydocker/fortify-vulnerability-exporter FoDToCSV --fod.baseUrl=https://emea.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPassword --fod.release.id=100

When using Docker-based invocation, you may need to use appropriate volume mappings. For example, you may have the Docker image export vulnerability data to a file on your host system, or have the Docker image read a custom configuration file from your host system. Some CI/CD systems already set up such volume mappings for your. For example, GitHub provides the ${GITHUB_WORKSPACE} environment variable that points to your GitHub workspace (either inside or outside a Docker image). Similarly, GitLab provides the ${CI_PROJECT_DIR} environment variable.

The default GitLab and GitHub configuration files utilize these environment variables to write the exported data to your GitLab project directory or GitHub workspace. Similarly you could utilize these variables to point to a custom configuration file in your workspace, for example ${WORKSPACE_DIR}/MyCustomConfig.yml.

FortifyVulnerabilityExporter utilizes a simple plugin system; plugins are responsible for actually loading vulnerability data and exporting this data to various systems or output formats. For example, the utility ships with plugins for loading data from FoD, loading data from SSC, exporting data to JSON format, and so on. These standard plugins are bundled inside the FortifyVulnerabilityExporter.jar file (within the BOOT-INF/lib directory) and are automatically enabled based on utility configuration, so no further user action is required to use these standard plugins.

The utility can optionally load third-party plugins, allowing third-party developers to provide additional functionality without requiring a custom build of the main FortifyVulnerabilityExporter application. For example, developers may implement custom plugins to add support for other vulnerability sources or targets. Custom plugins should only be obtained from trusted sources, and users should verify that plugins are compatible with the FortifyVulnerabilityExporter version being used.

The utility will by default load plugins from the plugins directory in the current working directory. You can optionally specify the location of the plugins directory by passing the -DpluginDir=/path/to/plugins Java command line option. For example, if you have installed custom plugins to /opt/FortifyVulnerabilityExporter/plugins, you may need to use a command like the following in order to have the utility load these plugins. Note that the -DpluginDir option must come before the -jar option.

java -DpluginDir=/opt/fortify-vulnerability-exporter/plugins -jar /opt/fortify-vulnerability-exporter/FortifyVulnerabilityExporter.jar ...

FortifyVulnerabilityExporter configuration is done through configuration properties that can be specified through:

• YAML configuration files
• Environment variables
• Java system properties
• Command line options prefixed with --

If a property is defined in multiple places, then values from lower items in this list override values from earlier ones. For example, command line options can override properties defined in environment variables or configuration files.

FortifyVulnerabilityExporter loads YAML configuration files from the following locations, again with properties defined in lower items overriding properties defined in earlier items in this list:

• application.yml provided in the main FortifyVulnerabilityExporter jar file
• Configuration files provided by plugins (from their pluginConfig directory)
• An optional, local configuration file specified through the --export.config=<path/to/config.yml> command line option
  • Note that usually you will not specify the --export.config option directly when running FortifyVulnerabilityExporter from the command line, but rather you would specify a plain configuration file name as the first command line parameter to FortifyVulnerabilityExporter as described in the Invocation section. FortifyVulnerabilityExporter will look up the appropriate configuration file as described in that section, and then set the --export.config option for you.

One or more standard configuration files are provided for each of the available integrations and export formats, as described in the relevant sections in this documentation.

In YAML configuration files, properties may be presented in hierarchical YAML format. For example:

some.property.name: value

is equivalent to:

some:
  property:
    name: value

which in turn is equivalent to:

some.property:
  name: value

The various sections in this document that describe configuration properties may do so using any of these formats, whichever is most appropriate.

Configuration trees from different sources are automatically combined. For example, plugins can provide partial predefined configurations in their pluginConfig directory; at runtime these configurations will be combined with the configuration specified through the export.config property and other configuration properties specified on the command line or through environment variables.

Relaxed rules are used when loading configuration properties. This documentation will usually state property names in dot notation like some.property.long-name, however you may use for example an environment variable named SOME_PROPERTY_LONGNAME to set this configuration property. Full rules are explained in the Spring Boot documentation. When running on GitHub, environment variables starting with INPUT_ are also accepted in order to support GitHub Actions with property to set FortifyVulnerabilityExporter configuration properties.

In general, configuration properties in FortifyVulnerabilityExporter support one of the following three types of property values:

• Plain values
• Simple expressions
• Template expressions

The documentation for each property usually explicitly states whether the property is expected to contain either a simple or template expression. Properties for which this is not stated usually expect plain values. In general:

• Plain values are used for basic configuration properties, like file output locations
• Simple expressions are used for decision-making or other logic, like deciding whether a given vulnerability should be included in the output
• Template expressions are used for mapping source data to target data, allowing to combine plain text with source data

Both simple and template expressions are based on Spring Expression Language (SpEL); please see the Spring Expression Language documentation for detailed information on SpEL features and syntax. With simple expressions, the value is simply interpreted as an expression; any string will need to be placed between quotes. Template expressions are plain string values combined with expressions denoted using the $[expression] syntax. Following are some examples to illustrate the difference between simple and template expressions:

• Simple expressions:
  • vuln.engineType=='SCA'
  • vuln.severityString matches 'Critical|High'
• Template expressions:
  • Category is $[vuln.issueName]
  • $[vuln.instanceId]

Although plain values cannot contain any expressions, they may contain property placeholders. These property placeholders, denoted by ${property.name}, can be used to reference existing properties. These property placeholders can reference other configuration properties, but they can also reference properties defined by the plugin that is loading the vulnerability data. For example, both the SSC and FoD plugins allow for accessing application version or release data using property placeholders.

So to summarize:

• Plain properties contain text, possibly combined with property placeholders denoted by ${property.name} to reference application version/release data. As an example, an output file name could be configured as {applicationVersion.project.name}-${applicationVersion.name}.csv to write CSV data to a file named after the SSC application and version name.
• Simple expression properties contain expressions
• Template expression properties contain text, possibly combined with expressions denoted by $[expression] to reference application version/release and vulnerability data

The actual properties that can be referenced in expressions and property placeholders are dependent on where the data is being loaded from; data loaded from FoD has a different structure and uses different property names compared to SSC for example. Please see the following sections for details:

• FoD Expressions
• SSC Expressions

Apart from standard SpEL features, FortifyVulnerabilityExporter provides some additional utility functions for use in expressions. These functions are documented in the JavaDoc for FortifyVulnerabilityExporterExpressionHelper$EvaluationContextFunctions. Following are some real-world examples of utilizing these predefined functions in template expressions:

• Convert HTML to plain text: $[#htmlToText(vuln.recommendations)]
• Extract a specific part from a URL: $[#uriPart(vuln.primaryLocationFull, 'serverUrl')]
  • Other parts that can be requested include protocol, host, port, path, relativePath, query and fragment
• Throw an error if expression is true: $[#check(vulnerabilityMappers.result.get().size()>1000, "GitHub does not support importing more than 1000 vulnerabilities. Please clean the scan results or update vulnerability search criteria.")?vulnerabilityMappers.result.get():{}]

The following configuration properties are supported by FortifyVulnerabilityExporter:

• export.cronSchedule: By default, FortifyVulnerabilityExporter will run the export and then terminate. If the export.cronSchedule property is defined, FortifyVulnerabilityExporter will run the export according to the configured schedule and will not terminate by itself. The format for the cron expression is documented in Spring JavaDoc.
• export.config: Local path to a standard or custom configuration file from which to load configuration properties. As explained in earlier sections, in most cases you don't configure this property directly, but instead pass a configuration file as the first parameter to FortifyVulnerabilityExporter as shown in the Invocation section. Under the hoods, the application.yml file included with FortifyVulnerabilityExporter uses this property to set the spring.config.import property.
• Spring Boot Core Properties, taking into account that FortifyVulnerabilityExporter provides default values (through code or application.yml) for some of these properties.
• Configuration properties supported by the various plugins, as explained in the appropriate plugin-specific sections in this documentation.
• export.from: Specifies the plugin and optional configuration name used to load vulnerability data, for example fod, ssc.instance1 or ssc.instance2.
• export.to: Specifies one or more plugins and optional configuration names used to export vulnerability data, for example json, json.github.sast or json.gitlab.sast, json.gitlab.dast, json.github.sast.

For both export.from and export.to, the part before the optional dot (.) specifies the plugin to be used. For example, both fod and fod.instance1 will use the FoD plugin to load vulnerability data. The optional suffix is used to differentiate between multiple configurations for the same plugin. For example, when setting export.from to fod, then the FoD plugin will look for configuration properties like fod.baseUrl and fod.vulnerability.filterParam. When setting export.from to fod.instance1 however, the FoD plugin will look for configuration properties like fod.instance1.baseUrl and fod.instance1.vulnerability.filterParam.

This approach allows for selecting between multiple predefined configurations. For example, you can have a configuration file that defines multiple FoD or SSC configurations with different base URL's or credentials; users simply need to select the appropriate configuration by pointing the export.from property to one of these predefined configurations.

This functionality is also extensively used by plugins that can export vulnerability data to multiple predefined formats. For example, the JSON Export plugin comes bundled with many predefined JSON output formats, like GitHub SAST, GitLab SAST and GitLab DAST formats. Each of these formats is defined using an appropriate configuration property prefix like json.gitlab.sast. Now if the export.to property contains json.gitlab.sast, this partial predefined configuration will be automatically applied. Other plugin configuration settings, like the actual output file or whether to pretty-print the exported data, are usually loaded from the standard or customized configuration file specified using the export.config option. Alternatively, these settings can also be supplied directly on the command line or through environment variables. These configuration options will also be prefixed with json.gitlab.sast.

FortifyVulnerabilityExporter can be combined with other Fortify tools to integrate Application Security Testing into your CI/CD pipelines and workflows. The following sections provide details on some possible approaches. Before integrating FortifyVulnerabilityExporter into your CI/CD pipeline, please make sure you have read the Raw or Audited results section.

The general CI/CD workflow for Fortify on Demand is as follows:

1. Check out source code
2. Package source code using Fortify ScanCentral Client
3. Use FoDUploader to submit a scan request to FoD, utilizing the option to wait for scan completion
4. Run FortifyVulnerabilityExporter to publish latest scan results to a file or third-party system

The general CI/CD workflow when utilizing Fortify SSC as the scan results repository is as follows:

1. Check out source code
2. Scan source code, either:
   • Locally using Fortify SCA, optionally utilizing one of the Fortify CI/CD integrations
   • Remotely on a ScanCentral environment
3. Wait for scan results to become available
   • Wait for SSC to finish processing scan results if you want to export all vulnerabilities
   • Wait for SSC to finish processing Audit Assistant results if you want to export only actionable vulnerabilities
   • See Raw or Audited results for more information about these two approaches
4. Run FortifyVulnerabilityExporter to publish latest scan results to a file or third-party system

The main difficulty is step 3, as not all Fortify on-premise tools provide functionality for waiting for SSC to finish processing scan results or Audit Assistant results. Some examples:

• The FortifyClient utility returns immediately after uploading the artifact, doesn't wait for the scan to be processed by SSC
• The ScanCentral Client utility allows for blocking until scan completion, but doesn't provide functionality for waiting until the scan has actually been processed on SSC
• The Fortify Jenkins plugin provides options for polling SSC until SSC has finished processing the uploaded scan

So depending on how Fortify is being integrated into your CI/CD pipeline, you may need to think about how and when to run FortifyVulnerabilityExporter in order to have it load the latest scan results. Following are some potential options, in arbitrary order:

• A: After scan completion & upload, wait for a specific amount of time to allow SSC to process the artifact and potentially apply Audit Assistant results, before running FortifyVulnerabilityExporter and any follow-on steps
• B: Utilize the SSC REST API to poll SSC for current scan processing status, waiting until the scan processing status changes to 'processing complete' or until Audit Assistant results have been auto-applied
• C: Run FortifyVulnerabilityExporter on a scheduled basis, for example once per day
• D: Utilize SSC webhooks or JMS events to monitor SSC for 'scan processing completed' events, triggering a run of FortifyVulnerabilityExporter whenever such an event is encountered, using the application version id listed in the event payload

The first two options basically block your CI/CD job until SSC has completed processing the scan. The latter two options allow for better utilization of your CI/CD system; the CI/CD system can run other jobs instead of having the scan job block one of the available slots until scan processing has completed. In particular when utilizing ScanCentral, the scan job can finish as soon as the scan request has been submitted to the ScanCentral environment.

Of the two latter options, option C completely separates FortifyVulnerabilityExporter from your scan jobs. Most recent scan results will be exported at predefined intervals. You can utilize the scheduling functionality provided by FortifyVulnerabilityExporter itself, or you can use your CI/CD system or system scheduler to invoke a single run of the utility. You can have one or more instances that process any number of application versions. For example, you could have a separate instance for processing individual application versions, a separate instance for processing all application versions belonging to an individual business unit, or a single instance for processing all application versions.

With option D, the workflow is basically split into two separate, independent subflows. One subflow is responsible for initiating the scan, and the other subflow is responsible for processing scan results.

At the moment, the webhook or JMS-based approach may require some custom component to listen for the appropriate JMS messages or to receive the SSC webhook invocation. Whenever such an event is received, the custom component could for example trigger a CI/CD job that runs FortifyVulnerabilityExporter to export vulnerabilities to a file, and then runs any subsequent steps to ingest that file into another system.

Customers may work with Fortify Professional Services to implement such custom components, or they may choose to submit a feature requests for allowing SSC to call arbitrary HTTP/REST endpoints with configurable payload on specific system events. With such a feature, SSC could for example automatically call the 'trigger job' endpoint on arbitrary CI/CD systems whenever a scan has been successfully processed.

FortifyVulnerabilityExporter allows for exporting vulnerabilities from Fortify on Demand (FoD) and Fortify Software Security Center (SSC) to a file formatted according to GitHub import specifications. This file can then be uploaded to GitHub using a GitHub-provided action. Once uploaded, Fortify vulnerabilities can be viewed and managed on the GitHub Security dashboard. See GitHub's Code Scanning Alerts documentation for more information about this GitHub feature.

The easiest way to integrate FortifyVulnerabilityExporter into a GitHub Actions workflow is by utilizing a dedicated GitHub Action; please see the gha-export-vulnerabilities documentation for details on how to use this action.

If for any reason you cannot use the dedicated GitHub Action, for example because you need more control over how FortifyVulnerabilityExporter is being invoked, you can use the fortify/fortify-vulnerability-exporter Docker image as described in the sections below.

The following example illustrates how to utilize the fortify/fortify-vulnerability-exporter Docker image to integrate FortifyVulnerabilityExporter into a GitHub workflow for exporting vulnerability data from FoD to GitHub.

name: FoD issues to GitHub using FortifyVulnerabilityExporter

on: [workflow_dispatch]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Optionally you could check out the source code and run a 
      # Fortify scan before invoking FortifyVulnerabilityExporter.
      
      # Run FortifyVulnerabilityExporter with the standard
      # configuration file, credentials provided through GitHub
      # secrets. The standard configuration file outputs the data
      # to standard output (for debugging) and to a file named
      # gh-fortify-sast.sarif in the GitHub workspace directory.
      - uses: docker://fortifydocker/fortify-vulnerability-exporter:latest
        with:
          export_config: /config/FoDToGitHub.yml
          fod_baseUrl: https://ams.fortify.com
          fod_tenant: ${{ secrets.FOD_TENANT }}
          fod_user: ${{ secrets.FOD_USER }}
          fod_password: ${{ secrets.FOD_PAT }}
          fod_release_name: MyApp:MyRelease
          # Or use fod_release_id: 1234 
          
      # Uploaded the generated file containing Fortify vulnerabilities to GitHub.
      - uses: github/codeql-action/upload-sarif@v1
        with:
          sarif_file: ./gh-fortify-sast.sarif
          
      # Optionally store the generated file for troubleshooting purposes.
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: sarif-files
          path: ./gh-fortify-sast.sarif

As described in the CI/CD Integration section, you can optionally combine this with other Fortify tools to create a full workflow that scans your code and makes the results available on GitHub.

The following example illustrates how to utilize the fortify/fortify-vulnerability-exporter Docker image to integrate FortifyVulnerabilityExporter into a GitHub workflow for exporting vulnerability data from SSC to GitHub.

name: SSC issues to GitHub using FortifyVulnerabilityExporter

on: [workflow_dispatch]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Optionally you could check out the source code and run a 
      # Fortify scan before invoking FortifyVulnerabilityExporter.
      
      # Run FortifyVulnerabilityExporter with the standard
      # configuration file, credentials provided through GitHub
      # secrets. The standard configuration file outputs the data
      # to standard output (for debugging) and to a file named
      # gh-fortify-sast.sarif in the GitHub workspace directory.
      - uses: docker://fortifydocker/fortify-vulnerability-exporter:latest
        with:
          export_config: /config/SSCToGitHub.yml
          ssc_baseUrl: ${{ secrets.SSC_BASE_URL }}
          ssc_authToken: ${{ secrets.SSC_CI_TOKEN_DECODED }}
          ssc_version_name: MyApp:MyVersion
          # Or use ssc_version_id: 1234
          
      # Uploaded the generated file containing Fortify vulnerabilities to GitHub.
      - uses: github/codeql-action/upload-sarif@v1
        with:
          sarif_file: ./gh-fortify-sast.sarif
          
      # Optionally store the generated file for troubleshooting purposes.
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: sarif-files
          path: ./gh-fortify-sast.sarif

As described in the CI/CD Integration section, you can optionally combine this with other Fortify tools to create a full workflow that scans your code and makes the results available on GitHub.

The FoDToGitHub.yml and SSCToGitHub.yml configuration files provide standard configurations for loading vulnerability data from FoD or SSC respectively, and exporting this vulnerability data to GitHub SARIF format. Individual configuration options can be overridden using input parameters similar to how we specify the FoD connection information and credentials. Alternatively you can reference an alternative configuration file located in your GitHub workspace, for example:

      - uses: docker://fortifydocker/fortify-vulnerability-exporter:latest
        with:
          export_config: ${GITHUB_WORKSPACE}/MyCustomConfig.yml

The following sections provide more information on the various configuration options:

• Configuration Properties
• FoD Configuration
• SSC Configuration
• JSON Export

Note that the mapping between Fortify vulnerability data and GitHub SARIF format is not specified in the standard configuration files. Instead, the various JSON-based mappings are predefined in the pluginConfig directory inside the FortifyVulnerabilityExporter-plugin-to-json.jar file. You can however override individual properties in these standard mappings, or use the predefined mappings as a basis for defining your own customized export configuration. The JSON Configuration section provides more details on configuring these mappings.

FortifyVulnerabilityExporter allows for exporting vulnerabilities from Fortify on Demand (FoD) and Fortify Software Security Center (SSC) to a file formatted according to GitLab security report specifications. When properly configured in you GitLab CI job, the Fortify vulnerability data can be reviewed on the GitLab Security Dashboard. See GitLab's documentation on Security Scanner Integration for more information about this GitHub feature.

The following sections describe how to use the fortifydocker/fortify-vulnerability-exporter Docker image within a GitLab CI/CD pipeline.

The following example illustrates how to utilize the fortify/fortify-vulnerability-exporter Docker image to integrate FortifyVulnerabilityExporter into a GitLab CI/CD pipeline for exporting vulnerability data from FoD to GitLab.

fortify_scanning:
  image: fortifydocker/fortify-vulnerability-exporter
  variables:
    export_config: /config/FoDToGitLab.yml
    fod_baseUrl: https://ams.fortify.com
    fod_tenant: ${FOD_TENANT}
    fod_user: ${FOD_USER}
    fod_password: ${FOD_PAT}
    fod_release_name: MyApp:MyRelease
    # Or use fod_release_id: 1234
  script: 
  - echo Script entry is required but not used
  when: manual
  allow_failure: true
  artifacts:
    reports:
      sast: gl-fortify-sast.json
      dast: gl-fortify-dast.json

The configuration file /config/FoDToGitLab.yml used in this example outputs all available GitLab reports. Alternatively, you can use /config/FoDToGitLabSAST.yml or /config/FoDToGitLabDAST.yml to output only a SAST or DAST report respectively. Note that contrary to the SSC implementation, outputting Sonatype/dependency scanning results from FoD is not yet supported.

As described in the CI/CD Integration section, you can optionally combine this with other Fortify tools to create a full workflow that scans your code and makes the results available on GitLab.

The following example illustrates how to utilize the fortify/fortify-vulnerability-exporter Docker image to integrate FortifyVulnerabilityExporter into a GitLab CI/CD pipeline for exporting vulnerability data from SSC to GitLab.

fortify_scanning:
  image: fortifydocker/fortify-vulnerability-exporter
  variables:
    export_config: /config/SSCToGitLab.yml
    ssc_baseUrl: ${SSC_BASE_URL}
    ssc_authToken: ${SSC_CI_TOKEN_DECODED}
    ssc_version_name: MyApp:MyVersion
    # Or use ssc_version_id: 1234
  script: 
  - echo Script entry is required but not used
  when: manual
  allow_failure: true
  artifacts:
    reports:
      sast: gl-fortify-sast.json
      dast: gl-fortify-dast.json
      dependency_scanning: gl-fortify-depscan.json

The configuration file /config/SSCToGitLab.yml used in this example outputs all available GitLab reports. Alternatively, you can use /config/SSCToGitLabSAST.yml, /config/SSCToGitLabDAST.yml, or /config/SSCToGitLabSonatype.yml to output only a SAST, DAST or Sonatype report respectively.

As described in the CI/CD Integration section, you can optionally combine this with other Fortify tools to create a full workflow that scans your code and makes the results available on GitLab.

The FoDToGitLab*.yml and SSCToGitLab*.yml configuration files provide standard configurations for loading vulnerability data from FoD or SSC respectively, and exporting this vulnerability data to GitLab JSON format. Individual configuration options can be overridden using input parameters similar to how we specify the FoD connection information and credentials. Alternatively you can reference an alternative configuration file located in your GitLab project directory, for example:

  image: fortifydocker/fortify-vulnerability-exporter
  variables:
    export_config: ${CI_PROJECT_DIR}/MyCustomConfig.yml

The following sections provide more information on the various configuration options:

• Configuration Properties
• FoD Configuration
• SSC Configuration
• JSON Export

Note that the mapping between Fortify vulnerability data and GitLab JSON format is not specified in the standard configuration files. Instead, the various JSON-based mappings are predefined in the pluginConfig directory in the FortifyVulnerabilityExporter-plugin-to-json.jar file. You can however override individual properties in these standard mappings, or use the predefined mappings as a basis for defining your own customized export configuration. The JSON Configuration section provides more details on configuring these mappings.

DefectDojo provides its own Fortify integration module as described here: https://github.com/DefectDojo/sample-scan-files/tree/master/fortify. However this integration has some drawbacks:

• Relatively complicated to set up (DefectDojo documentation doesn't provide detailed instructions)
• Requires a Fortify SCA installation to run ReportGenerator
  • Less suitable for FoD customers
  • Less suitable for ScanCentral SAST environments
• No direct integration with FoD or SSC
  • Requires FPR file to be downloaded if not available locally
  • Doesn't benefit from advanced filtering and suppression functionalities offered by FoD and SSC
• Only legacy FPR files can be processed; some results on FoD or SSC may not be available in legacy FPR file format

As FortifyVulnerabilityExporter allows for exporting vulnerability data to various output formats that are also supported by DefectDojo, it is possible to set up an alternative integration between FoD or SSC and DefectDojo using one of these common output formats. For example, both FortifyVulnerabilityExporter and DefectDojo support CSV and GitLab formats. In particular the GitLab format seems to be a good match between FortifyVulnerabilityExporter and DefectDojo.

At the moment of writing, DefectDojo supports GitLab SAST and GitLab Dependency Scanning reports. DefectDojo does not yet support GitLab DAST reports; potentially you could export DAST results to CSV format and then import these results using DefectDojo's CSV import (untested). To summarize, the following options are available:

• Export FoD SAST results to a GitLab SAST report and import this report into DefectDojo
• Export SSC SAST results to a GitLab SAST report and import this report into DefectDojo
• Export SSC Sonatype results to a GitLab Dependency Scanning report and import this report into DefectDojo
• Export other FoD or SSC results to CSV format and import the CSV file into DefectDojo

FortifyVulnerabilityExporter allows for exporting vulnerabilities from Fortify on Demand (FoD) and Fortify Software Security Center (SSC) to a file formatted according to SonarQube Generic Issue Import Format specifications. This file can then be imported when running a SonarQube scan using the sonar.externalIssuesReportPaths analysis parameter.

Known Limitations:

• SonarQube can only import a short text-only description; no issue details, explanation or recommendations will be available in SonarQube. Users will need to follow the (text-only) link in order to view further details in FoD or SSC. A SonarQube enhancement (see https://community.sonarsource.com/t/generic-issue-data-ad-hoc-rules/9624) or custom plugin like https://github.com/fortify-ps-sandbox/sonarqube-scanner-externalissue-rule would be needed to import additional details.
• SonarQube can only import external issues associated to source files. As such, at the moment only static analysis results can be imported. Potentially a SonarQube enhancement or custom plugin could add support for reporting non-static external issues at SonarQube project level. Alternatively, non-static issues could potentially be reported against a specific source file. For example, all DAST issues could be reported against a source file named dast-issues.txt.
• Related to the above, SonarQube will ignore vulnerabilities for which the source path does not match any of the files currently being scanned by SonarQube. Effectively, if there is some mismatch between file paths in the Fortify results compared to the source file tree being scanned by SonarQube, SonarQube may ignore all vulnerabilities in the external issue report. Chances of this happening can be minimized by running the Fortify and SonarQube scans on the exact same source code tree, starting from the same working directory, and both using the same build integration like Maven. If necessary, you can use the --json.sonarqube.sast.filePathPrefix=E:/absolute/path/to/project/root command line parameter to add E:/absolute/path/to/project/root as a prefix to the vulnerability file path as reported by Fortify, allowing SonarQube to resolve this path as an absolute path.

At the moment there are no plans to develop any of the work-arounds listed above, unless a customer engages with Fortify Professional Services in order to develop such enhancements.

FortifyVulnerabilityExporter comes with a standard configuration file for exporting vulnerabilities from Fortify on Demand to SonarQube Generic Issue Import Format. Following are some examples on how to run FortifyVulnerabilityExporter in combination with the Maven-based SonarQube Scanner. Note that these examples do not actually run an FoD scan; please see the CI/CD Integration for more information on combining FortifyVulnerabilityExporter with various other Fortify tools to run a scan on FoD before exporting the vulnerabilities to a third-party system like SonarQube.

Java-based invocation

After downloading and extracting the FortifyVulnerabilityExporter distribution zip file (see Related Links for download locations), you can import FoD vulnerabilities to SonarQube using one of the example scripts below.

Windows Example

set VULNEXP_JAR=C:\Users\myuser\Downloads\FortifyVulnerabilityExporter\FortifyVulnerabilityExporter.jar
cd \path\to\my\project
java -jar "%VULNEXP_JAR%" FoDToSonarQube --fod.baseUrl=https://ams.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPAT --fod.release.name=MyApp:MyRelease
mvn clean verify sonar:sonar -Dsonar.externalIssuesReportPaths=./sq-fortify-sast.json

Linux/Bash Example

export VULNEXP_JAR=~/Downloads/FortifyVulnerabilityExporter/FortifyVulnerabilityExporter.jar
cd /path/to/my/project
java -jar "${VULNEXP_JAR}" FoDToSonarQube.yml --fod.baseUrl=https://ams.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPAT --fod.release.name=MyApp:MyRelease
mvn clean verify sonar:sonar -Dsonar.externalIssuesReportPaths=./sq-fortify-sast.json

Docker-based invocation

The main advantage of using Docker to run FortifyVulnerabilityExporter is that you do not need to manually download and unpack the distribution zip file, and worry about the paths to the Jar-file. Obviously you will need to have Docker installed locally to use this approach, capable of running Linux-based Docker images.

cd /path/to/my/project
docker run --rm -v ${PWD}:/export fortifydocker/fortify-vulnerability-exporter FoDToSonarQube --fod.baseUrl=https://ams.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPAT --fod.release.name=MyApp:MyRelease
mvn clean verify sonar:sonar -Dsonar.externalIssuesReportPaths=${PWD}/sq-fortify-sast.json

The script below shows a full example on how to run a scan of the Fortify Mavenized EightBall example, upload the results to SSC, and export the vulnerabilities to SonarQube. You will need to adjust this to your situation, like adjusting the environment variables to match your situation.

You will need to download and extract the FortifyVulnerabilityExporter distribution zip file before running this script. Alternatively you can use the Docker-based invocation instead, as demonstrated in the FoD section above. The FoD section also lists examples on how to run FortifyVulnerabilityExporter on Linux rather than Windows.

This example is meant to be run manually; obviously the PAUSE step is not suitable if you want to integrate this into an automated build pipeline. Please see the CI/CD Integration section for more information on how to integrate FortifyVulnerabilityExporter in automated build pipelines.

Windows Example

set VULNEXP_JAR=C:\Users\myuser\Downloads\FortifyVulnerabilityExporter\FortifyVulnerabilityExporter.jar
set EIGHTBALL_DIR=C:\WORK\Programs\_Fortify\SCA\20.1.1\plugins\maven\maven-plugin-bin\samples\EightBall
set SSC_URL=http://localhost:2010/ssc
set SSC_USER=SSCUser
set SSC_PWD=SSCPassword
set SSC_APP=EightBall
set SSC_APPVER=1.0

cd "%EIGHTBALL_DIR%"
direct-invocation.bat
fortifyclient uploadFPR -url "%SSC_URL%" -user "%SSC_USER%" -password "%SSC_PWD%" -file target\fortify\EightBall-1.0.fpr -application "%SSC_APP%" -applicationVersion "%SSC_APPVER%"
echo Please wait until SSC has processed results before continuing
PAUSE
java -jar "%VULNEXP_JAR%" SSCToSonarQube --ssc.baseUrl="%SSC_URL%" --ssc.user="%SSC_USER%" --ssc.password="%SSC_PWD%" --ssc.version.name="%SSC_APP%:%SSC_APPVER%"
mvn clean verify sonar:sonar -Dsonar.externalIssuesReportPaths=.\sq-fortify-sast.json

The FoDToSonarQube.yml and SSCToSonarQube.yml configuration files provide standard configurations for loading vulnerability data from FoD or SSC respectively, and exporting this vulnerability data to SonarQube Generic Issue Import Format. Individual configuration options can be overridden using input parameters similar to how we specify the FoD connection information and credentials, or alternatively you can specify an alternative configuration file on the FortifyVulnerabilityExporter command line. When using Docker-based invocation, obviously you will need to map the appropriate Docker volume to allow the Docker container to access a configuration file on your host system.

The following sections provide more information on the various configuration options:

• Configuration Properties
• FoD Configuration
• SSC Configuration
• JSON Export

Note that the mapping between Fortify vulnerability data and SonarQube JSON format is not specified in the standard configuration files. Instead, the various JSON-based mappings are predefined in the pluginConfig directory in the FortifyVulnerabilityExporter-plugin-to-json.jar file. You can however override individual properties in these standard mappings, or use the predefined mappings as a basis for defining your own customized export configuration. The JSON Configuration section provides more details on configuring these mappings.

The CSV export plugin allows for exporting vulnerability data to CSV format. The sections below describe how to export vulnerability data from FoD or SSC to CSV format, and provide details on how to configure the plugin.

FortifyVulnerabilityExporter comes with standard configuration files for exporting vulnerabilities from Fortify on Demand or SSC to CSV files. The standard configuration files output a couple of sample vulnerability fields; you will likely need to adjust this to your needs as explained in the CSV Configuration section below.

Following are some example invocations:

• FoD to CSV using Docker image, writing CSV files to the ./export directory:
  docker run --rm -v ./export:/export fortifydocker/fortify-vulnerability-exporter FoDToCSV --fod.baseUrl=https://emea.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPassword --fod.release.id=100
• SSC to CSV using local Java invocation, writing CSV files to the current working directory:
  java -jar FortifyVulnerabilityExporter.jar SSCToCSV --ssc.baseUrl=http://localhost:2010/ssc --ssc.user=MyUser --ssc.password=MyPassword --ssc.version.name=webgoat:5.0

Please see the Generic Usage section for more invocation examples and notes about the location of the plugins.

The CSV export plugin supports the following configuration hierarchy:

csv[.config.name]:
  output:
    mkdir:  true|false          # Create output directory if it doesn't exist yet
    stdout: true|false          # Write CSV output to standard output
    stderr: true|false          # Write CSV output to standard error
    header: true|false          # Include column headers in CSV output
    file:   /path/to/output.csv # Write CSV output to given file
  filter:
    expressions:
      - vuln.prop1 matches 'A|B'
      - vuln.prop2=='Value'     # One or more expressions in Spring Expression Language format
                                # that return either true (include vulnerability in CSV output)
                                # or false (exclude vulnerability in CSV output) 
  fields:
    column1: someText           # Define the fields to be written to CSV output for each individual
    column2: $[vuln.prop1]      # vulnerability. Property values can be plain strings combined with
    column3: Hello $[vuln.name] # expressions in Spring Expression Language format using $[expr] syntax. 

As explained in the Configuration Format section, this configuration hierarchy can be used as-is in YAML configuration files, or may be flattened to property names like csv.output.file.

As explained in the Configuration Properties section, the optional [.config.name] corresponds to the optional configuration name specified in the export.to configuration property. For example, you would use csv.output.file if export.to contains plain csv, whereas you would use csv.config.one.output.file if export.to contains csv.config.one.

General information about the expression format is available in the Configuration Expressions section. Depending on whether data is being processed comes from FoD or SSC, the following sections provide more details on available expression properties:

• FoD Expressions
• SSC Expressions

The JSON export plugin allows for exporting vulnerability data to JSON format. The sections below describe how to export vulnerability data from FoD or SSC to JSON format, and provide details on how to configure the plugin.

FortifyVulnerabilityExporter comes with standard configuration files for exporting vulnerabilities from Fortify on Demand or SSC to JSON files. Most of these standard configuration files export vulnerability data to some specific JSON format, for example as described in the GitHub Integration or GitLab Integration sections.

For both FoD and SSC there are two configuration files not related to any specific integration as listed in the following table:

Following are some example invocations with these configuration files:

• Output raw FoD vulnerability data to standard output using Docker image:
  docker run --rm -v ./export:/export fortifydocker/fortify-vulnerability-exporter FoDToJsonRaw --fod.baseUrl=https://emea.fortify.com --fod.tenant=MyTenant --fod.user=MyUser --fod.password=MyPassword --fod.release.id=100
• Output raw SSC vulnerability data to standard output using local Java invocation:
  java -jar FortifyVulnerabilityExporter.jar SSCToJsonRaw --ssc.baseUrl=http://localhost:2010/ssc --ssc.user=MyUser --ssc.password=MyPassword --ssc.version.name=webgoat:5.0

Please see the Generic Usage section for more invocation examples and notes about the location of the plugins.

The JSON export plugin supports the following configuration hierarchy:

json[.config.name]:
  output:
    mkdir:  true|false          # Create output directory if it doesn't exist yet
    stdout: true|false          # Write JSON output to standard output
    stderr: true|false          # Write JSON output to standard error
    pretty: true|false          # Pretty-print JSON output (human-readable formatting)
    file:   /path/to/output.csv # Write JSON output to given file
    encoding: UTF8              # Output file encoding 
  filter:
    expressions:
      - vuln.prop1 matches 'A|B'
      - vuln.prop2=='Value'     # One or more expressions in Spring Expression Language format
                                # that return either true (include vulnerability in JSON output)
                                # or false (exclude vulnerability in JSON output) 
  format:
    fields:
      topLevelField1: someText           # Define the top-level fields to be written to JSON output.
      topLevelField2: $[vuln.prop1]      # Property values can be plain strings combined with expressions
      topLevelField3: Hello $[vuln.name] # in Spring Expression Language format using $[expr] syntax. 
      topLevelField4: $[vulnerabilityMappers.mapper1.get()] # Get mapped vulnerability data from mapper1 defined below
      topLevelField5: $[vulnerabilityMappers.mapper2.get()] # Get mapped vulnerability data from mapper2 defined below
    vulnerabilityMappers:
      mapper1:
        propertyName: $[vuln.instanceId]  # Mapper output will be a JSON object with given property names
                                          # If not defined, output will be a JSON array
        fields:                           # Property value or array entry will be a JSON object with the given fields
          field1: $[vuln.someField]
        # value: $[vuln.instanceId]       # Alternatively, property value or array entry will be generated from the given template expression 
      mapper2:
        

As explained in the Configuration Format section, this configuration hierarchy can be used as-is in YAML configuration files, or may be flattened to property names like json.output.file.

As explained in the Configuration Properties section, the optional [.config.name] corresponds to the optional configuration name specified in the export.to configuration property. For example, you would use json.output.file if export.to contains plain json, whereas you would use json.config.one.output.file if export.to contains json.config.one.

General information about the expression format is available in the Configuration Expressions section. Depending on whether data is being processed comes from FoD or SSC, the following sections provide more details on available expression properties:

• FoD Expressions
• SSC Expressions

The format definition listed in the YAML snippet above may look somewhat daunting, but luckily there are many examples to learn from. Simple examples that illustrate the effects of the various vulnerabilityMappers configuration properties are available in the FoDToJsonCustom.yml and SSCToJsonCustom.yml sample configuration files. The various predefined formats, for example for GitLab or GitHub integrations, provide additional and more advanced format definition examples. You can find these predefined formats in the pluginConfig directory inside the FortifyVulnerabilityExporter-plugin-to-json.jar plugin jar file, which itself is located inside the FortifyVulnerabilityExport.jar file in the BOOT-INF/lib directory.

The sections below provide information about configuring the connection to FoD, and information about FoD data that can be referenced in expressions and property placeholders.

The FoD vulnerability loader plugin supports the following configuration hierarchy:

fod[.config.name]:
  baseUrl: https://ams.fortify.com          # Base URL to connect to FoD
  proxy:                                
    url:      https://proxy.company.com     # Optional proxy URL
    user:     MyProxyUser                   # Optional proxy user name
    password: MyProxyPassword               # Optional proxy password
  tenant:   MyTenant                        # FoD tenant
  user:     MyUser                          # FoD user name
  password: MyPAT                           # FoD Personal Access Token (recommended) or password
  scopes:   view-apps, view-issues          # Scopes to request during authentication, defaults to view-apps and view-issues
  #clientId:                                # Client id, alternative for user-based authentication 
  #clientSecret:                            # Client secret, alternative for user-based authentication
  release:
    name: MyApp:MyRelease                   # Process release(s) with the given name
                                            # Note that FoD performs a 'contains' search rather than 'equals' search,
                                            # so this may match MyRelease, MyRelease1 and MyRelease2 
    regex: .*:master                        # Process release(s) that match the given regex
                                            # This example will process all releases named 'master' for all applications 
    id: 100                                 # Process release with the given id
    filter:
      expressions: releaseName=='master'    # Process releases for which the given SpEL expression returns true                  
    orderBy:
      field: releaseName                    # Request FoD to return releases ordered by the given property 
      direction: ASC                        # Order ascending (ASC) or descending (DESC)
    # embed:                                # See dedicated section on loading additional data from FoD
  vulnerability:
    filterParam: scanType:Static            # Pass the given filter parameter to FoD when loading vulnerability data
    includeFixed: false                     # Whether to include fixed vulnerabilities in the results, defaults to false
    includeSuppressed: false                # Whether to include suppressed vulnerabilities in the results, defaults to false
    # includeAll: false                     # Shortcut for setting both includeFixed and includeSuppressed to the given value
    filter:                                 
      expressions:                          # Client-side filtering of vulnerabilities using SpEL
    orderBy:
      field: instanceId                     # Request FoD to return vulnerabilities ordered by the given property 
      direction: ASC                        # Order ascending (ASC) or descending (DESC)
    # embed:                                # See dedicated section on loading additional data from FoD

As explained in the Configuration Format section, this configuration hierarchy can be used as-is in YAML configuration files, or may be flattened to property names like fod.release.name.

As explained in the Configuration Properties section, the optional [.config.name] corresponds to the optional configuration name specified in the export.from configuration property. For example, you would use fod.release.name if export.from contains plain fod, whereas you would use fod.instance1.release.name if export.from contains fod.instance1.

The FoD configuration tree supports fod.release.embed and fod.vulnerability.embed properties to load additional data from FoD at release or vulnerability level respectively. Both of these properties can be configured with a list of embed configurations as detailed below.

fod.release:
  embed:
    - ...
    - ...
fod.vulnerability:
  embed:
    - propertyName: myPropertyName        # Property name under which to store the embedded data in the release or vulnerability object
      uri: /api/v3/.../{id}/...           # Load additional data from the given uri. Can use {expr} placeholders to reference release
                                          # or vulnerability properties, including previously embedded properties
      subEntity:                          # Shortcut to set the uri property:
                                          # - For releases: /api/v3/releases/{releaseId}/<subEntity>
                                          #   If subEntity==application: /api/v3/application/{applicationId}
                                          # - For vulnerabilities: /api/v3/releases/{releaseId}/vulnerabilities/{vulnId}/<subEntity>
      resultExpression:                   # Only to be used in special circumstances; defines an expression to get the actual results to be 
                                          # embedded. Defaults to 'containsKey('items')?items:#root' to handle either array or object responses
      embedIf: someProperty!=null         # Only load the data if this expression returns true
      onError: FAIL                       # How to behave if there is an error loading the embedded data
                                          #   Possible options: FAIL, LOG_WARN, LOG_INFO, LOG_DEBUG, LOG_IGNORE
      params:                             # Additional request parameters for the REST request
        reqParam1: value1
        reqParam2: value2

Embedding additional data is a powerful feature, however it should be noted that this can have a significant impact on performance. In particular for embed configurations at vulnerability level, FortifyVulnerabilityExporter will call the associated REST endpoint for every individual vulnerability. If you have a release with many vulnerabilities, this will result in many REST calls to FoD. You should always consider the right balance between exporting as much information as possible, versus simply pointing users to FoD using the vuln.deepLink property for more details.

The standard configuration files provide various examples on how to use the embed feature.

As explained in the Configuration Expressions section, expressions can be used to access vulnerability data and other data loaded from the source system. The FoD vulnerability loader plugin provides access to the following data:

• release

  • Scope: expressions and property placeholders in any target plugin configuration property. Examples:
    • Use property placeholder ${release.releaseName} in target output file configuration property
    • Use template expression $[release.deepLink] in vulnerability mapping configuration property
  • Available sub-properties:
    • All properties returned by the FoD /api/v3/releases endpoint, for the release currently being processed
    • All properties as configured through the fod.release.embed configuration property
    • applicationAndReleaseName property containing <application name>:<release name> (mostly used for regex matching)
    • deepLink property providing browser-viewable deep link to release on FoD

• vuln

  • Scope: expressions in target plugin vulnerability processing configuration properties. Examples:
    • Use simple expression vuln.scantype=='Static' in target filter expression
    • Use template expression $[vuln.deepLink] in vulnerability mapping configuration property
  • Available sub-properties:
    • All properties returned by the FoD /api/v3/releases/{releaseId}/vulnerabilities endpoint, for the vulnerability currently being processed
    • All properties as configured through the fod.vulnerability.embed configuration property
    • deepLink property providing browser-viewable deep link to vulnerability on FoD
    • release property as described above; usually you would access release directly though instead of using vuln.release
    • complianceItems property: provides access to details.complianceCategories, converted to a flat array of objects with complianceName and complianceRule properties, if the details sub-entity has been embedded. If the details sub-entity has not been embedded, this property contains an empty array.

The sections below provide information about configuring the connection to SSC, and information about SSC data that can be referenced in expressions and property placeholders.

The SSC vulnerability loader plugin supports the following configuration hierarchy:

ssc[.config.name]:
  baseUrl: https://ssc.host/ssc             # Base URL to connect to SSC
  proxy:                                
    url:      https://proxy.company.com     # Optional proxy URL
    user:     MyProxyUser                   # Optional proxy user name
    password: MyProxyPassword               # Optional proxy password
  user:       MyUser                        # SSC user name
  password:   MyPassword                    # SSC password
  authToken:  4864b811-0095-...             # Alternative for user-based authentication; CIToken should usually be sufficient
  version:
    name: MyApp:MyVersion                   # Process application version with the given name
    regex: .*:master                        # Process application versions(s) that match the given regex
                                            # This example will process all versions named 'master' for all applications 
    id: 100                                 # Process application version with the given id
    filter:
      expressions: name=='master'           # Process application versions for which the given SpEL expression returns true                  
    orderBy:
      field: name                           # Request SSC to return versions ordered by the given property 
      direction: ASC                        # Order ascending (ASC) or descending (DESC)
    # embed:                                # See dedicated section on loading additional data from SSC
  vulnerability:
    filterSetId:                            # Filter set id for which to request vulnerability data from SSC 
    queryParam:                             # 'q' parameter to be passed to SSC when requesting vulnerability data
    filterParam:                            # 'filter' parameter to be passed to SSC when requesting vulnerability data
    includeHidden: false                    # Whether to include hidden vulnerabilities in the results, defaults to false
    includeRemoved: false                   # Whether to include removed vulnerabilities in the results, defaults to false
    includeSuppressed: false                # Whether to include suppressed vulnerabilities in the results, defaults to false
    # includeAll: false                     # Shortcut for setting includeHidden, includeRemoved and includeSuppressed to the given value
    filter:
      expressions:                          # Client-side filtering of vulnerabilities using SpEL
    orderBy:
      field: issueInstanceId                # Request SSC to return vulnerabilities ordered by the given property 
      direction: ASC                        # Order ascending (ASC) or descending (DESC)
    

As explained in the Configuration Format section, this configuration hierarchy can be used as-is in YAML configuration files, or may be flattened to property names like ssc.version.name.

As explained in the Configuration Properties section, the optional [.config.name] corresponds to the optional configuration name specified in the export.from configuration property. For example, you would use ssc.version.name if export.from contains plain ssc, whereas you would use ssc.instance1.version.name if export.from contains ssc.instance1.

The SSC configuration tree supports ssc.version.embed and ssc.vulnerability.embed properties to load additional data from SSC at release or vulnerability level respectively. Both of these properties can be configured with a list of embed configurations as detailed below.

ssc.version:
  embed:
    - ...
    - ...
ssc.vulnerability:
  embed:
    - propertyName: myPropertyName        # Property name under which to store the embedded data in the version or vulnerability object
      uri: /api/v1/.../{id}/...           # Load additional data from the given uri. Can use {expr} placeholders to reference version
                                          # or vulnerability properties, including previously embedded properties
      subEntity:                          # Shortcut to set the uri property:
                                          # - For application versions: /api/v1/projectVersions/{id}/<subEntity>
                                          #   If subEntity==attributeValuesByName: Load application version attribute values indexed by name
                                          #   If subEntity==currentStaticScan: Load /api/v1/scans/{id} for latest static scan id
                                          #   If subEntity==currentDynamicScan: Load /api/v1/scans/{id} for latest dynamic scan id
                                          # - For vulnerabilities: /api/v1/issues/${id}/<subEntity>
                                          #   If subEntity==details: /api/v1/issueDetails/{id}
                                          #   If subEntity==comments: /api/v1/issues/{id}/comments?limit=-1
      resultExpression:                   # Only to be used in special circumstances; defines an expression to get the actual results to be 
                                          # embedded. Defaults to 'containsKey('items')?items:#root' to handle either array or object responses
      embedIf: someProperty!=null         # Only load the data if this expression returns true
      onError: FAIL                       # How to behave if there is an error loading the embedded data
                                          #   Possible options: FAIL, LOG_WARN, LOG_INFO, LOG_DEBUG, LOG_IGNORE
      params:                             # Additional request parameters for the REST request
        reqParam1: value1
        reqParam2: value2

Embedding additional data is a powerful feature, however it should be noted that this can have some impact on performance. Contrary to the FoD implementation though, FortifyVulnerabilityExporter utilizes SSC bulk requests to retrieve embedded data in order to minimize the number of REST calls. For example, while processing a single page of 50 vulnerabilities, FortifyVulnerabilityExporter will issue only a single bulk request to load embedded data for each of these 50 vulnerabilities. Many of these bulk requests could potentially have an impact on SSC performance though.

The standard configuration files provide various examples on how to use the embed feature.

• applicationVersion

  • Scope: expressions and property placeholders in any target plugin configuration property. Examples:
    • Use property placeholder ${applicationVersion.name} in target output file configuration property
    • Use template expression $[applicationVersion.deepLink] in vulnerability mapping configuration property
  • Available sub-properties:
    • All properties returned by the SSC /api/v1/projectVersions endpoint, for the application version currently being processed
    • All properties as configured through the ssc.version.embed configuration property
    • applicationAndVersionName property containing <application name>:<version name> (mostly used for regex matching)
    • deepLink property providing browser-viewable deep link to application version on SSC

• vuln

  • Scope: expressions in target plugin vulnerability processing configuration properties. Examples:
    • Use simple expression vuln.engineType=='SCA' in target filter expression
    • Use template expression $[vuln.deepLink] in vulnerability mapping configuration property
  • Available sub-properties:
    • All properties returned by the SSC /api/v1/projectVersions/{id}/issues endpoint, for the vulnerability currently being processed
    • All properties as configured through the ssc.vulnerability.embed configuration property
    • deepLink property providing browser-viewable deep link to vulnerability on SSC
    • applicationVersion property as described above; usually you would access applicationVersion directly though instead of using vuln.applicationVersion

The plan is to extend FortifyVulnerabilityExporter with bug tracker integration capabilities, thereby replacing FortifyBugTrackerUtility. Once implemented, following would be the main differences between FortifyBugTrackerUtility and FortifyVulnerabilityExporter:

FortifyBugTrackerUtility:

• Is invoked manually for each run, leaving scheduling to the operating system or CI/CD system
• Configuration is done using Spring XML configuration files that required advanced technical knowledge
• Vulnerabilities are loaded in two phases; previously submitted vulnerabilities are loaded separately from new vulnerabilities to be submitted
• Only a single source and single target system is supported within a single configuration file, and within a single run

FortifyVulnerabilityExporter:

• Can either be invoked manually for a single run, or can be run as a long-running process that handles scheduling of individual runs
• Configuration is done using more concise and user-friendly YAML configuration files
• All vulnerabilities are loaded only once from the source system, independent of whether they were previously exported
  • How to differentiate between previously submitted versus new vulnerabilities is now decided in the target configuration
• FortifyVulnerabilityExporter can export vulnerability data to multiple targets at the same time, with each target performing additional filtering

When migrating from FortifyBugTrackerUtility, please verify the following:

• FortifyVulnerabilityExporter can successfully identify vulnerabilities previously exported with FortifyBugTrackerUtility
• Other steps to be added

The following sections provide information that may be useful for developers of this utility.

The Plugin System allows for developing custom plugins that extend the functionality of FortifyVulnerabilityExporter. For example, custom plugins can load vulnerability data from some alternative source, or export vulnerability data to some alternative target.

Instructions for implementing a plugin that can load vulnerability data:

• Provide implementations for the following two interfaces interface defined in FortifyVulnerabilityExporter-api:
  • com.fortify.vulnexport.api.vuln.loader.IVulnerabilityLoaderFactory
  • com.fortify.vulnexport.api.vuln.loader.IVulnerabilityLoader
• Rather than implementing these interfaces directly, implementations usually extend from the following abstract classes defined in FortifyVulnerabilityExporter-spi-from:
  • com.fortify.vulnexport.spi.source.vuln.loader.AbstractVulnerabilityLoaderFactory<C>
  • com.fortify.vulnexport.spi.source.vuln.loader.AbstractVulnerabilityLoader
• The IVulnerabilityLoaderFactory implementation class needs to be annotated with Spring's @Component annotation
• Implementations may re-use functionality and API's provided in both the FortifyVulnerabilityExporter-spi-from and FortifyVulnerabilityExporter-api projects

Instructions for implementing a plugin that can export vulnerability data to another system or output format:

• Provide implementations for the following two interfaces interface defined in FortifyVulnerabilityExporter-api:
  • com.fortify.vulnexport.api.vuln.consumer.IVulnerabilityConsumerFactory
  • com.fortify.vulnexport.api.vuln.consumer.IVulnerabilityConsumer
• Rather than implementing these interfaces directly, implementations usually extend from the following abstract classes defined in FortifyVulnerabilityExporter-spi-to:
  • com.fortify.vulnexport.spi.target.vuln.consumer.AbstractVulnerabilityConsumerFactory<C>
  • com.fortify.vulnexport.spi.source.vuln.consumer.AbstractVulnerabilityConsumer
• The IVulnerabilityConsumerFactory implementation class needs to be annotated with Spring's @Component annotation
• Implementations may re-use functionality and API's provided in both the FortifyVulnerabilityExporter-spi-to and FortifyVulnerabilityExporter-api projects

Plugins may define compileOnly dependencies in their build.gradle file to reference any dependencies that are (directly or transitively) defined as implementation or runtimeOnly dependencies in the main FortifyVulnerabilityExporter build.gradle file, for example the various com.fortify.client.api:common-* dependencies or javax.validation:validation-api dependency.

Plugins may define implementation dependencies in their build.gradle file to reference any dependencies that are not available through the main FortifyVulnerabilityExporter build.gradle file. Care must be taken that such dependencies (including their transitive dependencies) do not conflict with any of the dependencies already provided by FortifyVulnerabilityExporter.

Plugins are added to the Java classpath using Spring Boot's PropertyLauncher feature.

This project uses Lombok. In order to have your IDE compile this project without errors, you may need to add Lombok support to your IDE. Please see https://projectlombok.org/setup/overview for more information.

It is strongly recommended to build this project using the included Gradle Wrapper scripts; using other Gradle versions may result in build errors and other issues.

The Gradle build uses various helper scripts from https://github.com/fortify-ps/gradle-helpers; please refer to the documentation and comments in included scripts for more information.

All commands listed below use Linux/bash notation; adjust accordingly if you are running on a different platform. All commands are to be executed from the main project directory.

• ./gradlew tasks --all: List all available tasks
• Build: (plugin binary will be stored in build/libs)
  • ./gradlew clean build: Clean and build the project
  • ./gradlew build: Build the project without cleaning
  • ./gradlew dist distThirdParty: Build distribution zip and third-party information bundle
• ./fortify-scan.sh: Run a Fortify scan; requires Fortify SCA to be installed

This project uses GitHub Actions workflows to perform automated builds for both development and production releases. All pushes to the main branch qualify for building a production release. Commits on the main branch should use Conventional Commit Messages; it is recommended to also use conventional commit messages on any other branches.

User-facing commits (features or fixes) on the main branch will trigger the release-please-action to automatically create a pull request for publishing a release version. This pull request contains an automatically generated CHANGELOG.md together with a version.txt based on the conventional commit messages on the main branch. Merging such a pull request will automatically publish the production binaries and Docker images to the locations described in the Related Links section.

Every push to a branch in the GitHub repository will also automatically trigger a development release to be built. By default, development releases are only published as build job artifacts. However, if a tag named dev_<branch-name> exists, then development releases are also published to the locations described in the Related Links section. The dev_<branch-name> tag will be automatically updated to the commit that triggered the build.

See LICENSE.TXT