Fortify CLI (fcli) Installation & Usage

Download bundles for fcli are available on the Releases page, containing both development releases (named Development Release - <branch> branch) and final releases. In general, the use of a final release is recommended, unless you want to use any functionality that hasn’t made it into a final release yet.

Each release comes with a list of assets:

Please note that when publishing a new release, it may take up to 30-60 minutes before release assets are posted. If the latest release doesn’t show any of the assets listed above, please check again in 30-60 minutes. If you encounter a release without these assets after waiting for 60 minutes, please consider submitting an issue on the fcli issue tracker.

To install one of the binary distributions of fcli:

To install the .jar version of fcli, simply download fcli.jar and put in in a directory of your choosing, after which it can be executed using java -jar path/to/fcli.jar. You may want to set up a simple wrapper script/batch file or shell alias to make it slightly easier to invoke fcli.jar.

Fcli provides a product-oriented command structure, with each product represented by a separate tree of subcommands. For example, the fcli fod command tree can be used to interact with Fortify on Demand (FoD), and the fcli ssc command tree can be used to interact with Fortify Software Security Center (SSC). There are also some non product-related command trees, like the fcli config command tree to manage fcli configuration.

To see what top-level fcli commands are available, you can use the fcli --help command. You can drill down into the command tree to see what sub-commands are available within a particular parent command, for example by running fcli ssc --help to see all fcli ssc sub-commands, or fcli ssc session --help to see all SSC session management commands.

If you don’t have fcli up and running yet, you can also refer to the downloadable or online manual pages; refer to the Manual Pages section for more information.

The following sections describe common options that are available on (most) fcli commands.

Most fcli product modules are session-based, meaning that you need to run a session login command before you can use most of the other commands provided by a product module, and run a session logout command when finished, for example:

For interactive use, you can choose to keep the session open until it expires (expiration period depends on target system and login method). For pipeline use or other automation scenarios, it is highly recommended to issue a session logout command when no further interaction with the target system is required, to allow for any client-side and server-side cleanup to be performed. For example, upon logging in to SSC with user credentials, fcli will generate a UnifiedLoginToken, which will be invalidated when the ssc session logout is being run. If you have many (frequently executed) pipelines that interact with SSC, and you don’t run the ssc session logout command when the pipeline finishes, you risk exhausting SSC’s limit on active tokens. In addition, the logout commands will perform client-side cleanup, like removing session details like URL and authentication tokens from the client system.

For product modules that support it, like SSC or ScanCentral DAST, it is also highly recommended to use token-based authentication rather than username/password-based authentication when incorporating fcli into pipelines or other automation tasks. This will avoid creation of a temporary token as described above, but also allows for better access control based on token permissions. Similarly, for systems that support Personal Access tokens, like FoD, it is highly recommended to utilize a Personal Access Token rather than user password. Note however that depending on (personal access) token permissions, not all fcli functionality may be available. In particular, even the least restrictive SSC CIToken may not provide access to all endpoints covered by fcli. If you need access to functionality not covered by CIToken, you may need to define a custom token definition, but this can only be done on self-hosted SSC environments, not on Fortify Hosted. If all else fails, you may need to revert to username/password-based authentication to utilize the short-lived UnifiedLoginToken.

Fcli stores various files in its home directory, like session files (see Session Management) and fcli variable contents (see Fcli Variables). Future versions of fcli may also automatically generated log files in this home directory, if no --log-file option is provided.

By default, the fcli home directory is located at <user home directory>/.fortify/fcli, but this can be overridden through the FORTIFY_HOME or FCLI_HOME environment variables. If the FCLI_HOME environment variable is set, then this will be used as the fcli home directory. If the FORTIFY_HOME environment variable is set (and FCLI_HOME is not set), then fcli will use <FORTIFY_HOME>/fcli as its home directory.

When utilizing fcli in pipelines or automation scripts, especially when multiple pipelines or scripts may be running simultaneously on a single, non-containerized system, it is highly recommended to set the FCLI_HOME or FORTIFY_HOME environment variables to a dedicated directory for each individual pipeline/script run. Failure to do so may cause these runs to share session data, variables and other persistent fcli data, which will likely cause issues. For example, both pipelines may try to login with the same session name but with different URL’s or credentials, or even when using the same session configuration, one pipeline may log out of the session while the other pipeline is still using that session. Or, both pipelines may be updating the same fcli variable but with different contents, causing unexpected results when accessing those fcli variables. On containerized systems, like pipelines running in GitLab or GitHub, the fcli home folder will usually be stored inside the individual pipeline containers, so in this case it shouldn’t be necessary to set the FCLI_HOME or FORTIFY_HOME variables.

Note that some files stored in the fcli home directory may contain sensitive data, like authentication tokens generated by login commands, or proxy credentials configured through the fcli config proxy commands. Fcli encrypts any sensitive files, but since the encryption key and algorithm are hardcoded, these files can be decrypted fairly easily. You should ensure proper file access permissions on the fcli home folder. In addition, you can consider setting the FCLI_ENCRYPT_KEY environment variable to configure an alternative encryption key. That way, the sensitive files can only be decrypted if someone has access to this customer encryption key.

Apart from the special-purpose environment variables described in other sections, like the Fcli Home Folder section, fcli allows for specifying default option and parameter values through environment variables. This is particularly useful for specifying product URL’s and credentials through pipeline secrets, but also allows for preventing having to manually supply command line options if you frequently invoke a particular command with the same option value(s). For example, you could define a default value for the fcli ssc appversion create --issue-template option, to avoid having to remember the issue template name every time you invoke this command.

Fcli walks the command tree to find an environment variable that matches a particular option, starting with the most detailed command prefix first. For the issue-template example above, fcli would look for the following environment variable names, in this order:

Environment variable lookups are based on the following rules:

Although powerful, these environment variables for providing default option and parameter values should be used with some care to avoid unexpected results:

Despite #2 above, in some cases it may be useful to use less specific environment names, in particular if the same default values should be applied to multiple commands. As an example, consider an environment variable named FCLI_DEFAULT_SSC_URL:

This means that defining a single FCLI_DEFAULT_SSC_URL environment variable, together with for example FCLI_DEFAULT_SSC_USER and FCLI_DEFAULT_SSC_PASSWORD environment variables, allows for applying these default values to all of the fcli ssc session login, fcli sc-sast session login, fcli sc-dast session login, and corresponding logout commands.

Note that as described in the –env-prefix section, you can override the FCLI_DEFAULT prefix. For example, with --env-prefix MYPREFIX, fcli will look for MYPREFIX_* environment variables instead of FCLI_DEFAULT_* environment variables.

Fcli allows for storing fcli output data in fcli variables for use by subsequent fcli commands. This is a powerful feature that prevents users from having to use shell features to parse fcli output when needing to provide output from one command as input to another command. For example, this feature allows for starting a scan, and then passing the scan id to a corresponding wait-for command, or for creating an SSC application version, and passing the SSC application version id to the appversion-artifact upload command.

Fcli supports two types of variables:

Predefined variables are easier to use; they are more concise and you do not need to remember JSON property names. However, as indicated, they are more limited in use; they only store a predefined JSON property, and are only available on a subset of commands and options.

Following are some examples, assuming the necessary login sessions are available:

Fcli provides dedicated commands for managing variables and variable contents through the following commands; please see help output or manual pages for available sub-commands:

Note that the fcli config variable contents get and list commands support the regular fcli output options, and the list command also provides query capabilities. This allows for advanced use cases, like retrieving server data once and then outputting it in multiple formats, potentially even applying separate filters. As an example:

The manual pages for this fcli release can be found here: fcli (1). If you are viewing this documentation offline, please make sure that you have fully extracted the docs-html.zip file to access the manual pages.

Manual pages for each fcli release are automatically generated as new fcli releases are being built, and are available in HTML and Linux man-page formats. The manual pages in man-page format can be downloaded from the fcli releases page at https://github.com/fortify/fcli/releases. The HTML-formatted manual pages, including this documentation page, can also be downloaded from the fcli release page or viewed online at https://fortify.github.io/fcli.