Overview

The Fortify AST Scan component provides seamless integration of OpenText Core Application Security (Fortify on Demand) for automated Application Security Testing (AST) into your GitLab CI/CD pipelines. The component leverages the Fortify/components/fcli component to set up fcli, then executes the fcli ci action to run the requested scans and related tasks, providing a unified yet customizable experience across your AST scan workflows on GitLab and other CI systems.

The GitLab integration consists of two components:

  • Fortify fcli component - Provides fcli installation and setup functionality. This component allows for setting up fcli for use in custom CI/CD workflows.

  • Fortify AST Scan component - Provides complete AST scanning workflow by including the fcli component and adding scan execution jobs.

The ast-scan component provides the following runnable jobs:

  • Inherited from the fcli component:

    • <job-name>-prepare: Download and install fcli

    • <job-name>: Run the Fortify AST scan

  • Provided by the ast-scan component:

    • <job-name>-publish-debug-output: Optionally publish debugging output

    • <job-name>-publish-sast: Publish SAST report to GitLab security dashboard

In addition, several hidden jobs are defined by the component which may be used to implement advanced use cases but should not be directly customized.

Quick Start Example

Minimal configuration for running OpenText Fortify AST scans.

include:
  - component: $CI_SERVER_FQDN/Fortify/components/ast-scan/linux@1
    inputs:
      job-name: fortify-ast-scan
      stage: test
      fcli-version: v3

stages: [test]

fortify-ast-scan:
  image: maven:3-openjdk-17   # Docker image with build tools
  variables:
    FOD_URL: ${FOD_URL}                         # From GitLab CI/CD variables
    FOD_CLIENT_ID: ${FOD_CLIENT_ID}             # From GitLab CI/CD variables
    FOD_CLIENT_SECRET: ${FOD_CLIENT_SECRET}     # From GitLab CI/CD variables
    # FOD_RELEASE: MyApp:main                   # Optional: defaults to repo:branch

Tips & Recommendations

Centralized Configuration Management

For enterprise environments with multiple repositories, consider creating custom GitLab components or pipeline templates to wrap the Fortify integration. This approach provides:

  • Version stability: Pin specific component versions (e.g., @1.0.1 instead of @1) and fcli versions across all pipelines

  • Consistent configuration: Centrally manage common settings like tool versions and scan parameters

  • Controlled upgrades: Test new versions centrally before rolling out to all repositories

Example custom component or template structure:

# In your organization's shared component/template repository
include:
  - component: $CI_SERVER_FQDN/Fortify/components/ast-scan/linux@1.0.1  # Pinned version
    inputs:
      job-name: fortify-ast-scan
      stage: security
      fcli-version: v3.15.0  # Pinned fcli version

fortify-ast-scan:
  variables:
    FOD_URL: ${FOD_URL}
    FOD_CLIENT_ID: ${FOD_CLIENT_ID}
    FOD_CLIENT_SECRET: ${FOD_CLIENT_SECRET}
  extends: .my-shared-config  # Additional organization-wide settings

Air-Gapped Environments

For air-gapped or restricted network environments, host custom tool definitions and tool bundles in an internal SCM repository or artifact registry. Configure the integration to use these internal resources:

  • Set TOOL_DEFINITIONS to point to your internally hosted tool definitions file

  • Set FCLI_TGZ_URL to download fcli from your internal mirror

This ensures all required tools are accessible without external internet access.

Configuration

Component Inputs

The following component inputs can be specified when including the ast-scan component:

Input Description Default

job-name

Job name for the Fortify AST scan. This must be a valid file system path name and will be used to name the component-provided jobs.

fortify-ast-scan

stage

GitLab CI/CD stage in which to run the AST scan jobs. This stage must be defined in your pipeline’s stages: list.

test

fcli-version

Fcli version to use for running the AST scan. Note that not all fcli versions may be compatible with this component, so avoid overriding unless necessary.

v3

reports-access

GitLab access level required for accessing scan reports. Allowed values: all, developer, none.

developer

logs-access

GitLab access level required for accessing debug logs. Allowed values: all, developer, none.

developer

logs-expire-in

GitLab artifacts:expire_in value for log artifacts. As logs may contain sensitive data, they should be cleaned up promptly.

1 day

debug

Whether to generate and collect debug logs. Note that these may contain sensitive data like access tokens or credentials.

false

alpine-image

Allows for overriding the default Alpine image used by various jobs, for example to use an image from a custom registry.

alpine:latest

Configuration is accomplished through environment variables set on the main scan job (see following sections). Unlike GitHub Actions which use action inputs for some configuration, the GitLab components use environment variables exclusively for scan configuration, following GitLab CI/CD conventions.

Setup & Bootstrap

The environment variables in this section allow you to customize bootstrapping behavior of fcli and supporting tools like ScanCentral Client. These variables can be configured on the <job-name>-prepare job as needed.

Note
 This GitLab Component requires a recent fcli v3.x.y version to function properly.
Note
 Environment variables listed in the subsequent sections are for fcli 3.15.0; if your bootstrap settings install another fcli version, please refer to to the fcli ci action documentation for that version.

Environment Variable

Description

FCLI_TGZ_URL

By default, fcli is downloaded from the official GitHub releases page at https://github.com/fortify/fcli/releases/download//fcli-linux.tgz, where FCLI_VERSION is set based on the fcli-version component input. This environment variable allows you to specify a custom URL, for example pointing to an internal mirror in air-gapped environments. The URL can use the ` variable to reference the value of the `fcli-version component input. In air-gapped environments, you’ll likely also want to set TOOL_DEFINITIONS to point to a custom tool definitions file to allow for downloading supporting tools like ScanCentral Client from the internal mirror.

FCLI_RSA_SHA256_URL

URL for the fcli RSA SHA256 signature file. Defaults to /fcli-linux.tgz.rsa_sha256 where FCLI_BASE_URL is https://github.com/fortify/fcli/releases/download/, and FCLI_VERSION is set based on the fcli-version component input. Set to blank to skip signature verification (not recommended).

FCLI

Path to a pre-installed fcli executable. When set on the <job-name>-prepare job, fcli bootstrapping will skip downloading and installing fcli, and will use this binary instead. This may be useful for environments without internet access, if a self-hosted shell-based runner already has fcli pre-installed, or if the Docker image in which <job-name> is being run already provides the fcli executable. Note that the <job-name>-prepare and main <job-name> jobs usually run inside different images, so the prepare job doesn’t explicitly check or fail if the given fcli executable is not accessible from the prepare job.

TOOL_DEFINITIONS

Supporting tools like ScanCentral Client or Debricked CLI are by default downloaded from the URLs defined in the default Fortify tool definitions. For airgapped environments, point this environment variable to an internally hosted custom tool definitions zip file to download these tools from an internal mirror.

PREINSTALLED

Set to true to require that all supporting tools (e.g., ScanCentral Client, Debricked CLI) invoked by the fcli ci action are already installed, preventing tool definitions from being updated or tools from being automatically installed. This is useful for environments where pre-installed tools must be used, or where automatic tool installation is not permitted.

Authentication & Connection

Configure credentials and connection details for OpenText Core Application Security (Fortify on Demand).

Environment Variable

Description

FOD_URL

OpenText Core Application Security (Fortify on Demand) URL, for example https://ams.fortify.com. This must be rendered by the CI/CD system as plain text, not as a masked secret/variable.

FOD_CLIENT_ID
FOD_CLIENT_SECRET

Required when authenticating with an API key: OpenText Core Application Security (Fortify on Demand) Client ID (API key) and Secret (API secret).

FOD_TENANT
FOD_USER
FOD_PASSWORD

Required when authenticating with user credentials: OpenText Core Application Security (Fortify on Demand) tenant, user and password. It is recommended to use a Personal Access Token instead of an actual user password.

FOD_LOGIN_EXTRA_OPTS

Extra login options, for example for disabling SSL checks or changing connection time-outs; see fcli fod session login documentation.

Release Management

Configure OpenText Core Application Security (Fortify on Demand) release settings, including automatic creation and setup of applications and releases if they don’t exist.

Environment Variable

Description

FOD_RELEASE

OpenText Core Application Security (Fortify on Demand) release to use with this action. This should be specified as <app-name>:<release-name> (for non-microservices applications) or <app-name>:<microservice-name>:<release-name> (for microservices applications). Default value is based on repository and branch name, for example myOrg/myRepo:myBranch. Note that you’ll need to explicitly configure FOD_RELEASE for microservices applications, as the default value lacks a microservice name.

DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS
OVERRIDE_SAST_SETTINGS

If DO_SETUP is set not set to false, the application and/or release will be created if they do not yet exist, and static scan settings will be configured if necessary. By default, static scan settings will only be configured if no settings have been previously configured for the release; set OVERRIDE_SAST_SETTINGS to true to override existing static scan settings. The setup will be performed using the fcli-provided fcli-provided setup-release action, or, the custom fcli action specified through SETUP_ACTION. Extra options for the fcli action can be passed through the SETUP_EXTRA_OPTS environment variable, but also see below for some convenience environment variables.

COPY_FROM_RELEASE

Depending on your Git workflow, when a new release is created, it is recommended to copy state from the release representing your default branch by either setting this environment variable or by passing the --copy-from option through SETUP_EXTRA_OPTS.

SAST_ASSESSMENT_TYPE

By default, when setting up a release for SAST scanning, the SAST scan will be configured with the Static Assessment assessment type. You can choose a different assement type by either setting this environment variable or by passing the --assessment-type option through SETUP_EXTRA_OPTS. Note that this won’t update the assessment type if SAST scan settings have already been configured for the release, unless you set OVERRIDE_SAST_SETTINGS to true.

DO_AVIATOR_AUDIT

To enable Aviator audits, set this environment variable to true or pass --use-aviator through SETUP_EXTRA_OPTS. Note that Aviator avaliablility depends on tenant and scan policy configuration, and may consume additional entitlement units. Also note that this setting will be ignored if SAST scan settings have already been configured for the release, unless you set OVERRIDE_SAST_SETTINGS to true.

DO_SCA_SCAN

To enable Software Composition Analysis in your SAST scans, set this environment variable to true or pass --oss through SETUP_EXTRA_OPTS. Note that Debricked or Sonatype availability depends on tenant and scan policy configuration, and may consume additional entitlement units. Also note that this option will be ignored if SAST scan settings have already been configured for the release, unless you set OVERRIDE_SAST_SETTINGS to true.

Package Configuration

Configure source code packaging behavior for SAST scans. Control whether to use custom packaging actions, specify pre-built packages, or customize ScanCentral Client usage.

Environment Variable

Description

PACKAGE_ACTION
PACKAGE_ACTION_EXTRA_OPTS

By default, when running a SAST scan, the fcli package action is used to (optionally) package the source code to be scanned; see next entry for information on how to configure the default package action. If the standard fcli package action doesn’t meet your needs, for example if you want to perform a local translation using Fortify Static Code Analyzer, you can use PACKAGE_ACTION to use a custom action for packaging, optionally providing extra options to this custom action through the PACKAGE_ACTION_EXTRA_OPTS environment variable. Note that any custom action must set the global.package.output action variable, pointing to the package or MBS file to be scanned.

USE_PACKAGE
PACKAGE_EXTRA_OPTS
SC_CLIENT_VERSION
SC_CLIENT_HOME
SOURCE_DIR

These environment variables define packaging behavior. If USE_PACKAGE is specified, packaging will be skipped and the given package or MBS file (which must already exist) will be used. To pass additional options to the scancentral package command like -bt or -bf, use PACKAGE_EXTRA_OPTS. Note that the -oss option will be automatically added if Software Composition Analysis in enabled in FoD SAST scan settings.

By default:
* If SC_CLIENT_HOME is specified, the pre-installed ScanCentral Client at that location will be registered and used, skipping automatic installation. The path should point to the installation directory or binary.
* SC_CLIENT_VERSION may be specified to request a specific ScanCentral Client version to be used. Allowed values:
* An explicit version number (e.g. 25.2 or 25.2.0)
* Path to a specific ScanCentral Client installation
* latest to use the latest available ScanCentral Client version
* auto (default) to use a pre-installed version if available, otherwise installs latest
* If neither SC_CLIENT_VERSION nor SC_CLIENT_HOME are set, defaults to auto behavior.
* Current working directory will be packaged; use SOURCE_DIR to package a different directory.
* Debug logging for Scancentral Client is disabled; pass --debug on the fcli invocation to enable debug logging.

Scan Execution

Configure SAST scan execution and waiting behavior for OpenText Core Application Security (Fortify on Demand).

Environment Variable

Description

DO_SAST_SCAN
SAST_SCAN_EXTRA_OPTS

The fcli ci action currently only supports running a SAST scan, which is enabled by default. The SAST_SCAN_EXTRA_OPTS environment variable can be used to provide additional options to the fcli fod sast-scan start command, for example to specify scan notes. Note that these environment variables only control the submission of the scan request; see the information below for details on waiting for the scan to complete.

DO_WAIT
DO_SAST_WAIT
SAST_WAIT_EXTRA_OPTS

By default, the fcli ci action will wait for all started scans to complete; set DO_WAIT to false to just kick off any configured scans without waiting for completion. Note that doing so will skip any post-scan tasks. The SAST_WAIT_EXTRA_OPTS environment variable can be used to pass extra options to the fcli fod sast-scan wait-for command.

Post-Scan Actions

Configure post-scan tasks including release summaries, policy checks, pull request comments, and vulnerability data exports for OpenText Core Application Security (Fortify on Demand). NOTE: Availability and behavior of post-scan tasks may vary across CI/CD systems and fcli versions.

Environment Variable

Description

DO_RELEASE_SUMMARY
RELEASE_SUMMARY_ACTION
RELEASE_SUMMARY_EXTRA_OPTS

If DO_RELEASE_SUMMARY is not set to false, a release summary will be generated using the fcli-provided release-summary action or, if specified, the custom fcli action specified through RELEASE_SUMMARY_ACTION. Extra options for the fcli action can be specified through the RELEASE_SUMMARY_EXTRA_OPTS environment variable, which may include fcli options to allow unsigned custom actions to be used.

DO_CHECK_POLICY
CHECK_POLICY_ACTION
CHECK_POLICY_EXTRA_OPTS

If DO_CHECK_POLICY is set to true (implied if any of the other two CHECK_POLICY_* variables are set), a policy check will be run after scan completion using the fcli-provided check-policy action or, if specified, the custom fcli action specified through CHECK_POLICY_ACTION. Extra options for a custom fcli action can be passed through the CHECK_POLICY_EXTRA_OPTS environment variable, which may include fcli options to allow unsigned custom actions to be used.

DO_PR_COMMENT
PR_COMMENT_ACTION
PR_COMMENT_EXTRA_OPTS

(PREVIEW) If DO_PR_COMMENT is set to true (implied if any of the other two PR_COMMENT_* variables are set), a Pull Request or Merge Request comment will be generated using an fcli-provided action matching the current CI system like github-pr-comment or, if specified, the custom fcli action specified through PR_COMMENT_ACTION. Extra options for the fcli action can be specified through the PR_COMMENT_EXTRA_OPTS environment variable, which may include fcli options to allow unsigned custom actions to be used.

DO_SAST_EXPORT
SAST_EXPORT_ACTION
SAST_EXPORT_EXTRA_OPTS

If DO_SAST_EXPORT is not set to false and a SAST scan was completed, the SAST vulnerability data will be exported into a CI-specific format using an fcli-provided action matching the current CI system like github-sast-report or gitlab-sast-report, or, if specified, the custom fcli action specified through SAST_EXPORT_ACTION. Extra options for the fcli action can be specified through the SAST_EXPORT_EXTRA_OPTS environment variable, which may include fcli options to allow unsigned custom actions to be used.

Advanced Customization

Customizing the <job-name> Job

The main <job-name> job can be customized to specify the Docker image providing build tools, additional environment variables, and other job properties:

<job-name>:
  image: golang:latest          # Required: Docker image with build tools
  extends:
    - .<job-name>-vars-ci       # Required: inherit component variables
    - .my-custom-vars           # Optional: inherit additional variables
  variables:
    FOD_URL: https://ams.fortify.com
    FOD_CLIENT_ID: ${FOD_CLIENT_ID}     # From GitLab CI/CD variables
    FOD_CLIENT_SECRET: ${FOD_CLIENT_SECRET}
    # Additional scan configuration...

If you override needs or extends, make sure to keep the original contents to ensure the component functions correctly.

Customizing Report Publication

The component automatically publishes SAST reports to GitLab’s security dashboard through the <job-name>-publish-sast job. You can customize the access level for these reports through the reports-access component input.

Debug output publication is controlled by the debug component input. When enabled, the <job-name>-publish-debug-output job will collect and publish logs, package files, and FPR files as GitLab artifacts.