CONTRIBUTING.md

Contributing to FortifyVulnerabilityExporter

Contribution Agreement

Contributions like bug fixes and enhancements may be submitted through Pull Requests on this repository. Before we can accept 3^rd-party pull requests, you will first need to sign and submit the Contribution Agreement. Please make sure to mention your GitHub username when submitting the form, to allow us to verify that the author of a pull request has accepted this agreement.

Information for Developers

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

Conventional commits & versioning

Versioning is handled automatically by release-please-action based on Conventional Commits. Every commit to the main branch should follow the Conventional Commits convention. Following are some examples; these can be combined in a single commit message (separated by empty lines), or you can have commit messages describing just a single fix or feature.

chore: Won't show up in changelog

ci: Change to GitHub Actions workflow; won't show up in changelog

docs: Change to documentation; won't show up in changelog

fix: Some fix (#2)

feat: New feature (#3)

feat!: Some feature that breaks backward compatibility

feat: Some feature
  BREAKING-CHANGE: No longer supports xyz

See the output of git log to view some sample commit messages.

release-please-action invoked from the GitHub CI workflow generates pull requests containing updated CHANGELOG.md and version.txt files based on these commit messages. Merging the pull request will result in a new release version being published; this includes publishing the image to Docker Hub, and creating a GitHub release describing the changes.

Lombok

This project uses Lombok. Gradle builds will automatically handle Lombok annotations, but 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.

Gradle Wrapper

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/shared-gradle-helpers; please refer to the documentation and comments in included scripts for more information.

Common Commands

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

Plugin Development

FortifyVulnerabilityExporter provides a plugin framework that 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 document was auto-generated from CONTRIBUTING.template.md; do not edit by hand