Overview

The Fortify fcli component allows for setting up fcli for use in custom CI/CD workflows in GitLab. This allows you to implement fully customized AST scan workflows or other automation workflows that interact with Fortify products.

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 fcli component provides the following runnable jobs:

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

  • <job-name>: Run arbitrary fcli commands from the job script section

In addition, several hidden jobs are defined (e.g., .<job-name>-vars-shared, .<job-name>-vars, .<job-name>-vars-prepare, .fcli-install) which may be used to implement advanced use cases but should not be directly customized.

Quick Start Example

Basic setup for custom workflows with fcli version pinning.

include:
  - component: $CI_SERVER_FQDN/Fortify/components/fcli/linux@2
    inputs:
      job-name: fcli
      fcli-version: v3       # Use latest fcli 3.x.y release
      stage: test

stages: [test]

fcli:
  image: my-build-tools:v1   # Optional: specify build environment
  script:
    - ${FCLI} -V             # Verify fcli installation
    - ${FCLI} fod session login ...
    - # Your custom fcli commands here
    - ${FCLI} fod session logout ...

Tips & Recommendations

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 fcli component:

Input Description Default

job-name

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

fcli

stage

GitLab CI/CD stage in which to run the jobs provided by this component. This stage must be defined in your pipeline’s stages: list.

Required, no default

fcli-version

Fcli version to install/use. Supports semantic versioning (e.g., v3 for latest v3.x.y, v3.15 for latest v3.15.y).

v3

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.

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.

Advanced Customization

Customizing the <job-name> Job

By default, <job-name> will just run ${FCLI} -V to verify the fcli installation. You’ll typically want to define a custom script section that runs fcli and other commands as needed. For Docker-based runners, you’ll usually also want to define the image in which the script section is executed:

<job-name>:
  image: my-build-tools:v1     # Optional: specify Docker image
  script:
    - ${FCLI} fod session login ...
    - # Your custom fcli commands here
    - ${FCLI} fod session logout ...

If needed, you can also customize the needs, variables, and/or extends instructions. If you override needs or extends, make sure to keep the original contents:

<job-name>:
  extends:
    - .<job-name>-vars       # Required: inherit fcli-related variables
    - .my-custom-vars        # Optional: inherit additional variables
  variables:
    MY_VAR: value            # Optional: define extra variables
  needs:
    - <job-name>-prepare     # Required: wait for fcli installation
    - some-other-job         # Optional: wait for other jobs
  script:
    - # Your commands here

Customizing the <job-name>-prepare Job

The <job-name>-prepare job can be customized to perform additional preparation tasks beyond fcli installation. You can define additional script steps, optionally based on additional variables:

<job-name>-prepare:
  extends:
    - .<job-name>-vars-prepare  # Required: inherit fcli installation variables
    - .my-custom-vars           # Optional: inherit additional variables
  variables:
    MY_VAR: value               # Optional: define extra variables
  script:
    - !reference [ .fcli-install, script ]  # Required: install fcli
    - echo "Additional preparation steps"   # Optional: your custom steps

Any artifacts that need to be shared with the main <job-name> job must be stored under the directory identified by the ${FORTIFY_DIR} environment variable.

You can also customize the Docker image used for the preparation job. By default, alpine:latest is used:

<job-name>-prepare:
  image: my.registry/alpine:latest  # Use custom registry or different image

Using Multiple Component Configurations

You can include the fcli component multiple times with different configurations, as long as each include specifies a different job-name. This allows for using multiple fcli versions within a single pipeline. Each include must use the same component version to avoid conflicts.

include:
  - component: $CI_SERVER_FQDN/Fortify/components/fcli/linux@2
    inputs:
      job-name: fcli-stable
      fcli-version: v3.15.0
      stage: test
  - component: $CI_SERVER_FQDN/Fortify/components/fcli/linux@2
    inputs:
      job-name: fcli-dev
      fcli-version: dev_v3.x
      stage: test

fcli-stable:
  script:
    - ${FCLI} -V

fcli-dev:
  script:
    - ${FCLI} -V