FortifyVulnerabilityExporter

Generic Usage

Invocation

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.

Plugins

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 ...

Configuration Sources

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.

Configuration Format

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.

Configuration Expressions

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():{}]

Configuration Properties

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.

Raw or Audited results

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.

FoD considerations

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 considerations

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.

CI/CD Integration

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.

FoD CI/CD workflow

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

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

SSC CI/CD workflow

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

Check out source code
Scan source code, either:
- Locally using Fortify SCA, optionally utilizing one of the Fortify CI/CD integrations
- Remotely on a ScanCentral environment
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
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.

GitHub Integration

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.

GitHub Action

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.

Docker Image

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.

FoD to 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 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.

SSC to 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.

GitHub Configuration

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.

GitLab Integration

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.

Docker Image

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

FoD to 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 FoD to GitLab.

Note that to avoid GitLab passing sh as an argument to FortifyVulnerabilityExporter (which will fail, as FortifyVulnerabilityExporter will interpret sh as the name of a configuration file), we need to override the image entrypoint and manually invoke the utility in the script section.

fortify_scanning:
  image: 
    name: fortifydocker/fortify-vulnerability-exporter
    entrypoint: [""]
  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: 
  - java -DpopulateContainerDirs=true -cp "/app/classpath/*:app/libs/*" com.fortify.vulnexport.FortifyVulnerabilityExporter
  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 Debricked or 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.

SSC To 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.

Note that to avoid GitLab passing sh as an argument to FortifyVulnerabilityExporter (which will fail, as FortifyVulnerabilityExporter will interpret sh as the name of a configuration file), we need to override the image entrypoint and manually invoke the utility in the script section.

fortify_scanning:
  image: 
    name: fortifydocker/fortify-vulnerability-exporter
    entrypoint: [""]
  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: 
  - java -DpopulateContainerDirs=true -cp "/app/classpath/*:app/libs/*" com.fortify.vulnexport.FortifyVulnerabilityExporter
  when: manual
  allow_failure: true
  artifacts:
    reports:
      sast: gl-fortify-sast.json
      dependency_scanning: gl-fortify-debricked-depscan.json
      # Or for Sonatype Nexus IQ use: gl-fortify-sonatype-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, /config/SSCToGitLabDebricked.yml or /config/SSCToGitLabSonatype.yml to output only a SAST, DAST, Debricked SCA or Sonatype SCA 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.

GitLab Configuration

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.

BitBucket Integration

FortifyVulnerabilityExporter allows for exporting vulnerabilities from Fortify on Demand (FoD) and Fortify Software Security Center (SSC) to BitBucket Code Insights.

BitBucket Pipe

The easiest way to integrate a Fortify scan and FortifyVulnerabilityExporter into a BitBucket pipeline is to utilize the dedicated BitBucket Fortify Pipe, which is available here: https://bitbucket.org/fortifysoftware/fortify-scan.

Manual integration

If the Fortify Pipe described above doesn't fit your needs, for example because your pipelines run outside of BitBucket or if you require a custom scan configuration, you can use FortifyVulnerabilityExporter to generate the BitBucket Code Insights report and annotation files as described in the following sections.

FoD to BitBucket

To export FoD vulnerability data to a BitBucket Code Insights report and annotations file, you will need to run FortifyVulnerabilityExporter using the FoDToBitBucket configuration, using one of the invocation approaches as described in the Invocation section. This section also displays sample FoD connection properties; a full list of properties is available in the FoD Configuration section. Once the Code Insights report and annotations files have been generated, you will need to upload these files to BitBucket as described in the Upload BitBucket Code Insights Report section.

SSC to BitBucket

To export SSC vulnerability data to a BitBucket Code Insights report and annotations file, you will need to run FortifyVulnerabilityExporter using the SSCToBitBucket configuration, using one of the invocation approaches as described in the Invocation section. This section also displays sample SSC connection properties; a full list of properties is available in the SSC Configuration section. Once the Code Insights report and annotations files have been generated, you will need to upload these files to BitBucket as described in the Upload BitBucket Code Insights Report section.

Upload BitBucket Code Insights Report

The previous sections described how to generate a BitBucket Code Insights report and annotation files. Once generated, these files will need to be uploaded to BitBucket using the BitBucket REST API:

To upload the report file, perform a PUT request to https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG/commit/$BITBUCKET_COMMIT/reports/<unique report id>
- See https://developer.atlassian.com/cloud/bitbucket/rest/api-group-reports/#api-repositories-workspace-repo-slug-commit-commit-reports-reportid-put for endpoint details
To upload the annotations file, perform a POST request to https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG/commit/$BITBUCKET_COMMIT/reports/<unique report id>/annotations
- See https://developer.atlassian.com/cloud/bitbucket/rest/api-group-reports/#api-repositories-workspace-repo-slug-commit-commit-reports-reportid-annotations-post for endpoint details

When performing these uploads from a BitBucket pipeline, you can invoke these endpoints without authentication by utilizing a standard BitBucket proxy; see the Authentication section at https://support.atlassian.com/bitbucket-cloud/docs/code-insights/ for details. When performing these uploads from any other location, like another CI/CD system, you will need to authenticate with the BitBucket REST API as described here: https://developer.atlassian.com/cloud/bitbucket/rest/intro/#authentication.

DefectDojo Integration

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 Debricked results to a GitLab Dependency Scanning 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

SonarQube Integration

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.

FoD to SonarQube

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, 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

SSC to SonarQube

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

SonarQube Configuration

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.

CSV Export

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.

CSV Export Invocation

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.

CSV Configuration

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

JSON Export

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.

JSON Export Invocation

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:

FoD	SSC	Description
`FoDToJsonRaw.yml`	`SSCToJsonRaw.yml`	Output raw application release/version and vulnerability data to standard output, useful for understanding what properties are available for use in (template) expressions
`FoDToJsonCustom.yml`	`SSCToJsonCustom.yml`	Examples on how to map vulnerability data to various JSON structures, outputting to both standard output and a JSON file

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.

JSON Configuration

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

JSON format definition

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.

FoD

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.

FoD Configuration

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.

Loading additional data from FoD

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.

FoD Expressions

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.

SSC

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.

SSC Configuration

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.

Loading additional data from SSC

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.

SSC Expressions

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

Future Plans

Bug tracker integrations

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

This document was auto-generated from USAGE.template.md; do not edit by hand

Files

USAGE.md

Latest commit

History

USAGE.md

File metadata and controls

FortifyVulnerabilityExporter

Generic Usage

Invocation

Plugins

Configuration Sources

Configuration Format

Configuration Expressions

Configuration Properties

Raw or Audited results

FoD considerations

SSC considerations

CI/CD Integration

FoD CI/CD workflow

SSC CI/CD workflow

GitHub Integration

GitHub Action

Docker Image

FoD to GitHub

SSC to GitHub

GitHub Configuration

GitLab Integration

Docker Image

FoD to GitLab

SSC To GitLab

GitLab Configuration

BitBucket Integration

BitBucket Pipe

Manual integration

FoD to BitBucket

SSC to BitBucket

Upload BitBucket Code Insights Report

DefectDojo Integration

SonarQube Integration

FoD to SonarQube

SSC to SonarQube

SonarQube Configuration

CSV Export

CSV Export Invocation

CSV Configuration

JSON Export

JSON Export Invocation

JSON Configuration

JSON format definition

FoD

FoD Configuration

Loading additional data from FoD

FoD Expressions

SSC

SSC Configuration

Loading additional data from SSC

SSC Expressions

Future Plans

Bug tracker integrations