Fortify CLI (fcli) Installation & Usage

Managed installation is only available on internet-connected systems, or if your company hosts the various Fortify tools (including fcli) internally and provides a corresponding custom tool definitions bundle. Advantages of a managed installation:

The steps below describe how to perform a managed fcli installation. The syntax for invoking the various commands depends on the fcli variant that you downloaded. If you downloaded fcli.jar, fcli can be invoked using java -jar /path/to/fcli.jar. If you downloaded a native binary, fcli can be invoked using /path/to/fcli (Linux/Mac) or C:\path\to\fcli.exe (Windows). Any use of fcli in the commands below should be replaced by the appropriate command for invoking fcli on your system.

This option can be used on every fcli (sub-)command to view usage information for that command. Usage information usually shows the command synopsis, a description of the functionality provided by the command, and a description of each command line option or parameter accepted by the command.

As described in the Environment Variables section, default option and parameter values can be retrieved from environment variables starting with FCLI_DEFAULT. This option allows for configuring a different environment variable prefix. This may be useful if, for example, you want to login to multiple instances of the same system using environment variables. For example, when running fcli ssc session login --env-prefix PROD, fcli will look for environment variables like PROD_SSC_URL instead of FCLI_DEFAULT_SSC_URL.

Note that a default value for the --env-prefix option itself can be specified through an FCLI_DEFAULT_ENV_PREFIX environment variable, for example if you want to globally override the FCLI_DEFAULT prefix.

This option can be used on every fcli (sub-)command to specify the fcli log level; see the help output for a list of allowed levels. Note that this option also requires the --log-file option to be specified, otherwise no log will be written.

This option can be used on every fcli (sub-)command to specify the file to which to output log data. If not specified, currently no log data will be written, although future versions may specify a default log file location in the fcli data folder.

Available on virtually all (leaf) commands that output data, this option can be used to specify the output format. Fcli supports a wide variety of output formats, like table, csv, json, xml, and tree formats, allowing for both human-readable output or output suitable for automations. The csv-plain and table-plain output formats produce CSV or table output without headers. The *-flat output formats produce a flattened view of the output data, potentially making it easier to process that data without having to navigate through an object tree. For a full list of output formats supported by your fcli version, please refer to the help output or Manual Pages.

Most output formats allow for specifying the JSON properties to be included in the output, for example -o csv=id,name. If no JSON properties are specified, most output formats will output all available JSON properties, except for table output, which usually outputs a predefined set of JSON properties.

There are two output formats that are somewhat special:

Available on virtually all (leaf) commands that output data, this option can be used to write the command output data to a file, in the format specified by the --output option listed above. In some cases, this may be more convenient than redirecting the output to a file. For example, although currently not implemented, fcli could potentially skip creating the output file if there is no output data or if an error occurs. Also, for commands that output status updates, like wait-for commands, the --output-to-file option allows for status updates to be written to standard output while the final output of the command will be written to the file specified.

Various commands offer a --progress option to specify how to output progress messages. This option supports the following values:

Available on virtually all (leaf) commands that output data, this option can be used to store command output data in an fcli variable. For more details, see the Fcli Variables section.

Available on most list commands and some other commands, this option allows for querying the output data, outputting only records that match the given Spring Expression Language (SpEL) expression. See the Option Expressions section for details.

Expressions are evaluated on individual records; record properties can be accessed as shown in the SpEL documentation. The list of properties that can be queried can be obtained by executing the current command with the -o json-properties option; see -o | –output for details.

Following are some examples using bash syntax, assuming the record contains p1, p2, …​ properties:

Available on virtually all commands that interact with a target system, this option allows for specifying a session name. For more details, see the Session Management section.

Various fcli options take either plain expressions, like -q | --query, or template expressions (plain text combined with expressions embedded between curly braces), like -o | –output expr=…​. These expressions use Spring Expression Language (SpEL); general information on syntax, supported operators and more can be found in the SpEL Documentation.

When evaluating expressions, fcli configures SpEL for 'data binding and condition evaluation', meaning that not all SpEL features are available. In particular, query expressions cannot invoke constructors nor static methods, and write access is mostly disabled. Attempts to access non-existing JSON properties will result in an error, which, although uncommon, may be an issue if the server doesn’t consistently return all expected properties. You’ll need to explicitly check for property existence in such cases, for example:

Some SpEL operators like matches may throw an exception if any of the operands is null. For example, the following will result in an error if the prop1 propery is null for any of the records returned by the list command:

Such errors can be avoided using one of the following approaches:

Fcli provides some utility functions that may be used in expressions. Note that these functions calls are preceded by a # character.

Note that for date comparisons, both sides of the comparison operator need to be explicitly defined as date/time objects. For example:

SpEL expressions may contain various characters that will be interpreted by some shells, like the # character for calling functions, and either single or double quotes around literal string values. As such, with most shells you should enclose the full expression in single or double quotes, and use the other quotes in the expression, for example:

Which one to choose depends on any other characters appearing in the expression. For example, in bash you’d usually use single quotes to have everything in-between passed to fcli as-is, unless you want to use specific shell features inside the expression. Note that you can use the #env function to retrieve environment variable contents, so you don’t need to use shell syntax to insert environment variable contents into expressions.

Fcli supports named sessions, allowing you to have multiple open sessions for a single product. When issuing a session login command, you can optionally provide a session name as in fcli ssc session login mySession ..., and then use that session in other commands using the --session mySession command line option. If no session name is specified, a session named default will be created/used. Named sessions allow for a variety of use cases, for example:

To keep session state between fcli invocations, fcli stores session data like URL and authentication tokens in the Fcli Data Folder. To reduce the risk of unauthorized access to this sensitive data, fcli encrypts the session data files. However, this is not bullet-proof, as the default encryption key and algorithm can be easily viewed in fcli source code. As such, it is recommended to ensure file permissions on the fcli data folder are properly configured to disallow access by other users. Being stored in the user’s home directory by default, the correct file permissions should usually already be in place. For enhanced security, you may also consider setting the FCLI_ENCRYPT_KEY environment variable; see the Fcli Data Folder section for details.

By default, fcli will use the home directory of the current user for various operations, like storing fcli state and configuration (see next section) or for tool installations (see fcli tool manual pages). These locations can be individually overridden through environment variables or command-line options, but in some cases you may want to just specify an alternative 'user home directory' to have all fcli operations use this alternative directory by default, instead of having to override multiple individual directories.

For this purpose, fcli will check for an environment variable named FCLI_USER_HOME; if defined, the value of this environment variable will be used instead of the actual user home directory for any fcli command that reads or writes data from/to the user home directory.

Of course, even if this environment variable is set, you can still override individual directories through the applicable environment variables or command-line options. For example, if you set both FCLI_USER_HOME and FCLI_CONFIG_DIR (but not any of the other environment variables listed in the next section), then fcli configuration data will be stored in the directory specified through FCLI_CONFIG_DIR, whereas fcli state data will be stored in <FCLI_USER_HOME>/.fortify/fcli/state.

By default, fcli stores configuration and state data like session files (see Session Management), fcli variable contents (see Fcli Variables) and proxy settings in its data folder. Future versions of fcli may also automatically generated log files in this data directory, if no --log-file option is provided.

The locations of these files can be controlled through the following environment variables:

If none of these environment variables have been set, then state data will be stored in <user home directory>/.fortify/fcli/state, and configuration data will be stored in <user home directory>/.fortify/fcli/config.

Note: earlier versions of fcli used different environment variable names, but this was causing issues (see Issue 248). If you are using an older fcli version, please refer to the corresponding documentation. When upgrading fcli from an older version, you may need to adjust the environment variable names.

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 have each pipeline use a separate fcli state directory, to avoid those pipelines from sharing session data, variables and other persistent fcli state data. This will avoid issues like different pipelines overwriting each others session data (for example with different URLs or credentials), or one pipeline logging out of a session while another pipeline is still using the session.

Depending on the situation, pipelines can either share fcli configuration data, or be configured to have different configuration data directories. When sharing the configuration data, it is recommended that these pipelines do not update any configuration data during pipeline execution, but rather use pre-configured settings. For example, you could pre-configure fcli with proxy and trust store settings.

On containerized systems, like pipelines running in GitLab or GitHub, the default folders will usually be stored inside the individual pipeline containers and thus will not interfere with each others state.

Note that some files stored in the fcli data 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 data 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 custom encryption key.

Apart from the special-purpose environment variables described in the sections above, 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 --issue-template option of the +fcli ssc appversion create 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.

Fci comes with various built-in actions, currently focused on providing the following functionality:

Documentation for built-in actions can be found here:

Future fcli versions may introduce new built-in actions, enhance existing built-in actions, or provide enhanced action syntax, for example to allow for running pipeline-style actions that run a set of commands to package source code, submit a scan request, wait for scan completion, and perform post-scan activities like data export or policy checks.

Action support is centralized into the action entity of the various product modules. For now, fcli supports fcli fod action * and fcli ssc action * commands. Based on user feedback, we may consider adding action support on other modules like sc-sast or sc-dast as well. The following commands may be used to manage and run built-in actions:

Apart from built-in actions, users can also develop and run custom actions, which could be customized versions of built-in actions or completely new actions. Note that the ability to run custom actions is currently considered PREVIEW functionality; as fcli actions are a new functionality, we are collecting user feedback regarding action syntax, which could potentially result in breaking action syntax changes across minor fcli releases (although we’ll try to avoid this as much as possible).

As such, custom actions that run fine on the current fcli version may fail to run on any other fcli version. Fcli does perform action version checks based on action schema version (see below), but supported schema versions may change between minor or patch releases of fcli. Once we are comfortable with moving custom actions out of PREVIEW status, breaking schema/action syntax changes will be allowed only on major fcli releases, for example when moving from fcli 2.x to fcli 3.x.

Custom actions can be loaded from various sources, like a local or remote YAML file, optionally embedded in a zip-file that contains multiple actions. Each of the fcli commands listed in the previous section also support custom actions:

To allow for easy access, custom actions can also be imported into fcli using the fcli * action import command, which allows for importing either a single action YAML file or all action YAML files from a local or remote zip-file. Once imported, these actions can be accessed in the same way as built-in actions. Note that imported custom actions will override built-in actions if they have the same name. You can use the fcli * action reset command to remove all previously imported custom actions.

There are several resources available to help you developing custom actions. To start with, you can use the fcli * action get <action> command to view the contents of any built-in action as a basis for developing your own custom actions. Fcli provides a built-in __sample__ action that explains various concepts and lists many of the supported action YAML elements together with a description. To view the sample action, use the fcli ssc action get __sample__ or fcli fod action get __sample__ command.

Fcli also provides an action schema, which allows YAML editors and IDEs to provide code completion, documentation and validation for fcli action YAML documents. You may need to install a plugin to enable proper YAML editing and schema support. Following are some commonly used IDE plugins that are known to work with one of the schema associations listed below:

For optimal compatibility with various IDEs and YAML editors, fcli allows the schema to be declared in two ways:

Fcli requires at least one of these statements to be provided in action YAML files. You may also provide both, in which case the schema URL must be identical in both statements. Once you’ve added one of these statements to your action YAML file, your IDE or YAML editor may automatically provide support for editing and validating action YAML files. If not, try closing and re-opening the YAML file, or consult the documentation of your IDE or YAML editor.

As shown in the sample schema statements above, the current fcli version 2.7.0 supports schema version 1.1.0. Other fcli versions may support different schema versions. In general, fcli also provides backward compatibility for earlier schema versions with the same schema major version range, and forward compatibility for later schema patch versions within the same schema minor version range.

As actions can potentially perform dangerous operations, like sending confidential data to third-party systems, or updating or deleting data in Fortify or third-party systems, you should only run trusted actions. If you wish to run any actions provided by a third party, you could potentially review action contents, and potentially in the future we may provide functionality for performing a security analysis on action contents (either as a new fcli command or through Fortify rules).

However, this won’t be sufficient for actions that are dynamically loaded from a remote location, as action contents could change at any time. For example, a legitimate action can easily be replaced by some malicious action.

For this reason, fcli by default requires custom actions to be signed. Organizations, teams or individuals can sign actions with their own private key using the fcli * action sign command, the corresponding public key can be imported into fcli using the fcli config public-key import command. Most action commands also allow for explicitly passing a public key through the --pubkey option.

Public keys can be loaded from a local file, URL, string or environment variable, see command help or next section for details. Obviously, you should only use trusted public keys; loading a public key from a third-party URL may be dangerous for the same reasons as explained above.

Fcli is commonly used in CI/CD pipelines to perform all sorts of Fortify-related operations, and fcli actions allow for even more advanced use cases. This section provides some hints as to how to integrate actions into CI/CD pipelines, considering deployment and security aspects.

Publishing

Fcli actions can be loaded from any URL, but for CI/CD integration you could consider hosting fcli actions in a shared source code repository like https://some-scm.our.org/repositories/shared-ci-tools/fcli/actions. This allows for easy sharing and maintainance of fcli actions that are used across many CI/CD pipelines. This even allows for automatically signing those action using CI/CD pipelines on this shared repository.

Public & private key management

Of course, those actions should be signed using an organization-specific private key. For example, this could be either an existing private key that’s used throughout the organization, or a private key that’s managed by the CI/CD team. There are several ways to pass the corresponding public key to fcli from within CI/CD pipelines:

With each of these approaches, the public key can be be loaded from:

Design considerations

Given that actions can define and process arbitrary parameters, it may be tempting to implement generic, highly configurable actions. For example, you could implement a highly configurable action for checking all kinds of security policy criteria, with the actual criteria to be checked being passed as action parameters.

However, from a CI/CD perspective, this means that every pipeline must properly set these action parameters. Pipeline authors may copy existing pipelines or use pipeline templates to have these action parameters set to predefined values, but what if those parameters need to updated globally? Potentially, this means that you’d need to update thousands of pipelines to adjust action parameters.

This is exactly the reason why we don’t provide a highly configurable check-policy action, but instead just provide an example that can be customized according to organization requirements. Instead of passing fine-grained pass/fail criteria as action parameters, those criteria are hard-coded into the action. If there is a need to apply different criteria for different types of applications, for example based on business risk, multiple approaches are possible:

The examples above or based on actions that perform policy checks, but the same principles and considerations (may) apply to other types of actions.

Native binaries require some special source code annotations for proper operation, which are not required for the plain Java .jar version of fcli. If fcli developers forgot to include any of these annotations, you may experience any of the following behavior:

If you encounter any of these issues, please submit a bug report as described in Submitting a Bug Report. As described in that section, please include information on whether the .jar version of fcli exhibits the same erroneous behavior. While fcli developers are working on fixing the issue, you can temporarily use the .jar version of fcli until the issue is resolved.

After confirming that an issue cannot be resolved based on the information above, and is not caused by user error, please consider submitting a bug report on the fcli issue tracker. Before doing so, please verify that there is not already a bug report open for the issue that you are experiencing; in that case, feel free to leave a comment on the existing bug report to confirm the issue and/or provide additional details.

When opening a bug report, please include the following information: