Introduction
-The fcli utility can be used to interact with various Fortify products, like Fortify on Demand (FoD), Software Security Center (SSC), ScanCentral SAST and ScanCentral DAST. This document describes installation and general usage of fcli. For a full listing of fcli commands and corresponding command line options, please see the -man-pages as listed in the Manual Pages section.
-Some of the fcli highlights:
--
-
-
-
Interact with many different Fortify products with just a single command-line utility
-
- -
-
Both plain Java and native platform binaries for Windows, Linux and Mac available
-
- -
-
Modular command structure, making it easy to focus on particular tasks
-
- -
-
Rich output formats; save command output in JSON, CSV, XML or plain-text formats
-
- -
-
Session-based; no need to pass URL’s and credentials on every individual fcli invocation
-
- -
-
Support for configuring option values through environment variables
-
- -
-
Support for fcli variables; pass data between fcli commands
-
-
The following Fortify products are currently supported by fcli:
--
-
-
-
Software Security Center (SSC)
----
-
-
-
Includes virtually all functionality provided by the legacy FortifyClient utility
-
- -
-
Includes virtually all functionality provided by the ssc-client sample shipped with SSC
-
- -
-
Adds a wide range of other functionalities not previously included in any Fortify client-side utilities
-
-
- -
-
-
-
ScanCentral SAST
----
-
-
-
Support for starting and managing ScanCentral SAST scans
-
-
- -
-
-
-
ScanCentral DAST
----
-
-
-
Support for starting and managing ScanCentral DAST scans
-
- -
-
Support for listing scan policies and settings
-
- -
-
Support for listing and managing sensors
-
-
- -
-
-
-
Fortify on Demand (FoD)
----
-
-
-
Support for creating and managing applications, microservices and releases
-
- -
-
Support for starting and managing SAST & OSS scans
-
- -
-
Support for importing/downloading SAST/DAST/MAST & OSS results
-
- -
-
Partial/preview support for starting and managing DAST & MAST scans
-
- -
-
Partial/preview support for managing users, groups and their assignments
-
-
- -
-
Some commands and options are either hidden or marked as PREVIEW or LEGACY; these may change at any time, even between minor fcli versions. Any fcli invocations using these commands or options may break when upgrading to a future fcli 2.x version, so if possible you should refrain from using these in pipelines for example. Most notably, this includes the following functionalities:
-
-
-
-
Commands for configuring and running FoD DAST & MAST scans will change significantly, based on upcoming FoD API changes & improvements
-
- -
-
Commands and options for managing and assigning users and groups for both FoD and SSC will likely change; see https://github.com/fortify/fcli/issues/369 for details.
-
-
Hidden commands are not listed in fcli help output and not included in the Manual Pages. If needed, you can view the list of hidden commands using the fcli util all-commands list -q hidden command.
Installation
-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:
--
-
-
-
-docs-html.zip&docs-manpage.zip: Manual pages in either HTML or manpage format
- -
-
-fcli-linux.tgz,fcli-mac.tgz&fcli-windows.zip: Native binaries for each of the mentioned platforms---
-
-
-
Note that some browsers by default will disallow downloading of
-fcli-windows.zip; please bypass the warning
- -
-
Linux and Mac downloads include an
-auto-completionscript that makes interactive fcli usage easier
-
- -
-
-
-
-fcli.jar: Java version of fcli, which should be runnable on any platform that has Java 11+ installed---
-
-
-
Note that in general, the native binaries are easier to invoke, offer better performance, and have the benefit of auto-completion capabilities on Linux & Mac
-
- -
-
If you experience any unexpected behavior with native binaries, like commands or command line options not being listed or recognized, or technical error messages about methods, constructors or serializers not being -found, please try with the Java version as it may be an issue specific to the native binaries. See the Troubleshooting section for details.
-
-
- -
-
-
-
-fcli-thirdparty.zip: Third-party licenses and sources for license purposes; usually no need to download
- -
-
-LICENSE.TXT&README.md: Some generic information and license for fcli
-
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:
--
-
-
-
Download the appropriate binary archive for your platform
-
- -
-
Extract the archive contents to a directory of your choosing
-
- -
-
For ease of use, add this directory to your operating system or shell PATH environment variable, or move the
-fcli/fcli.exebinary to a directory that is already on the PATH
- -
-
Linux/Mac only: Run the following command to install fcli auto command completion, allowing for use of the
-<tab>to get suggestions for fcli command and option names. You may want to add this to your shell startup script, such that fcli auto-completion is readily available in every shell.
-source <extraction-dir>/fcli_completion
-Note: Please ensure that the version of the completion script matches the fcli version that you’re using, as otherwise the completion script may provide incorrect suggestions.
-
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.
Command Structure
-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.
Note that the --help option must be specified after the sub-command for which you want view usage instructions, i.e. fcli ssc --help and not fcli --help ssc. A listing of all available fcli commands can be viewed using the fcli util all-commands list command.
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.
-Common Options
-The following sections describe common options that are available on (most) fcli commands.
--h | --help
-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.
---env-prefix
-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.
--log-level
-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.
--log-file
-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.
--o | --output
-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:
--
-
-
-
--o 'expr=Text with {expression1} or {expression2}\n'
-Formats the output data based on the given template expression, which is a combination of (optional) plain text and SpEL expressions; see Option Expressions for details. In most cases, expressions will be simple property references, i.e.,{property.subProperty}. This can be used for a variety of purposes, for example generating output in a human-readable format, or for generating a list of commands to be run at a later stage. Note that by default, no newline character will be inserted after evaluating the given expression. If necessary, the expression should explicitly include\nto output a newline character. Also note that depending on your shell, theexproption must be properly quoted. For most shells, theexpr=...value should be enclosed in single or double quotes. To demonstrate the power of this output format, following are two examples of how-o exprcan be used to generate a script that purges all application versions matching certain criteria:---
-
-
-
-fcli ssc appversion list -q 'createdBy=="admin"' -o 'expr=fcli ssc appversion purge-artifacts --older-than 30d {id}\n'
- -
-
-for id in $(fcli ssc appversion list -q 'createdBy=="admin"' -o 'expr={id} '); do echo "fcli ssc appversion purge-artifacts –older-than 30d ${id}'"; done
-
- -
-
-
-
--o json-properties
-List all JSON properties returned by the current command, which can be used on options that take JSON properties as input, like output expressions (-o expr={prop}), properties to include in the output (-o table=prop1,prop2), queries (-q 'prop1=="value1"'), and fcli variables (--store var:prop1,prop2&::var::prop1}). Two important notes about this output format:---
-
-
-
The command will be executed as specified, so be careful when using this output option on any command -that changes state (delete/update/create/…). In most cases, the
-getorlistoperations will return a similar set of properties, so you can use those commands to view available properties.
- -
-
On some commands, the list of available JSON properties may vary depending on command line options. For example, when a query returns no records, then
--o json-propertieswill not output any properties. Likewise, a command may provide options for including additional data for each record; the corresponding JSON properties will only be shown if-o json-propertiesis used in combination with these options that load additional data.
-
- -
-
--output-to-file
-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.
--progress
-Various commands offer a --progress option to specify how to output progress messages. This option supports the following values:
-
-
-
-
-auto: Automatically select betweenansi,single-lineandsimpledepending on console capabilities.
- -
-
-none: Don’t output any progress messages.
- -
-
-simple: Output every progress message on a separate line, effectively leaving older progress messages visible. This will be used by default if no console is available, for example during pipeline runs. Supports multi-line progress messages.
- -
-
-single-line: Uses the\r(carriage return) character to overwrite previous progress message. This will be used by default if a non-ANSI console is detected. Supports single-line progress messages only.
- -
-
-ansi: Uses ANSI escape sequences to overwrite previous progress messages. This will be used by default if ANSI capabilities are detected. Supports multi-line progress messages.
-
--store
-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.
--q | --query
-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:
-
-
-
-
--q 'p1=="v1"'
-Only output records if the value of propertyp1equalsv1
- -
-
--q 'p1=="v1" || p1=="v2"'
-Only output records if the value of propertyp1equals eitherv1orv2
- -
-
--q '{"v1","v2"}.contains(p1)'
-Same as previous, but more concise if matching against many different values
- -
-
--q 'name matches "val1|val2"'
-Similar as above, but using regex-based OR matching
- -
-
--q 'p2==25 || p2<5'
-Only output records if the value of propertyp2either equals 25 or is less than 5
- -
-
--q 'p1=="v1" && (p2=="v2" || p3=="v2")'
-Only output records if the value of propertyp1equalsv1and the value of either propertyp2orp3isv2
- -
-
-fcli ssc artifact list --appversion MyApp:main -q 'scanTypes matches "\bSCA\b"'
-Only output artifacts containing a Fortify SCA scan (matching the whole wordSCAagainstscanTypesproperty)
- -
-
-fcli ssc artifact list --appversion MyApp:main -q '_embed.scans.![buildLabel].contains("myLabel")'
-Only output artifacts for which any of the scans included in the artifact has abuildLabelthat equalsmyLabel
- -
-
-fcli ssc artifact list --appversion MyApp:main -q '#now("-90d") < #date(uploadDate)'
-Only output artifacts that were uploaded less than 90 days ago.
-
Server-side queries
-In general, queries specified using the -q / --query option are evaluated on the client. Some commands will analyze the given query and generate corresponding server-side query parameters to minimize the amount of data that needs to be transferred from server to client. Generated queries can be viewed in the log file if --log-level is set to DEBUG level.
All commands that automatically generate server-side queries also provide a dedicated option for overriding the automatically generated server-side query, for example to further optimize the query or in case the automatically generated query is causing any issues. Following bullet points provide details on server-side queries for the various product modules:
--
-
-
-
FoD:
-
-All commands that automatically generate server-side queries provide the--filters-paramoption to override the automatically generated query. Server-side queries are automatically generated for the following SpEL expressions:---
-
-
-
-prop1=='value'(simple equals expressions)
- -
-
-prop1=='val1' || prop1=='val2'(or-expressions on a single property)
- -
-
-{'value1','value2'}.contains(prop1)(or-expression on a single property)
- -
-
-prop1 matches 'literalValue1|literalValue2'(or-expression on a single property)
- -
-
-prop1=='value' && prop2 matches 'val1|val2'(and-expression containing any of the above)
-
- -
-
-
-
ScanCentral SAST:
-
-No server-side queries are automatically being generated.
- -
-
ScanCentral DAST:
-
-No server-side queries are automatically being generated. Some commands provide the--server-queryoption to explicitly pass query parameters to the server.
- -
-
SSC:
-
-All commands that automatically generate server-side queries provide the--q-paramoption to override the automatically generated query. Server-side queries are automatically generated for the following SpEL expressions:---
-
-
-
-prop1=='value'(simple equals expressions)
- -
-
-prop1=='value' && prop2=='val2'(and-expression containing simple equals expressions)
-
- -
-
--session
-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.
-Option Expressions
-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:
--
-
-
-
Top-level properties:
-
-fcli ... list -q '(has("property2") && property2=="value2")'
- -
-
Nested properties:
-
-fcli ... list -q 'nestedObject!=null && get("nestedObject").has("stringValue") && nestedObject.stringValue=="nestedObjectValue1"'
- -
-
Nested array properties:
-
-fcli ... list -q 'nestedObjectArray !=null && !(nestedObjectArray.isEmpty()) && get("nestedObjectArray").get(0).has("stringValue") && nestedObjectArray.get(0).stringValue=="nestedArrayValue1"'
-
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:
-
-
-
-
-fcli ... list -q 'prop1 matches "value1|value2"'
-
Such errors can be avoided using one of the following approaches:
--
-
-
-
Rewrite the expression to not use the
-matchesoperator, for example:
-fcli ... list -q '{"value1","value2"}.contains(prop1)'
- -
-
Add null-check (include all records for which
-propisnull):
-fcli ... list -q 'prop1==null || prop1 matches "value1|value2"'
- -
-
Add null-check (exclude all records for which
-propisnull):
-fcli ... list -q 'prop1!=null && prop1 matches "value1|value2"'
-
Fcli provides some utility functions that may be used in expressions. Note that these functions calls are preceded by a # character.
-
-
-
-
-#date(string): Convert the given date/time in string format to a proper date/time representation, allowing for date/time-based comparison operations. This can be used on property references or literal strings.
- -
-
-#now(): Get the current date/time, allowing for date/time-based comparison operations.
- -
-
-#now(period): Get the current date/time plus or minus the given period. The given period must start with either a+or-, followed by a number and the time unit. Some examples:-90d(now minus 90 days),+15m(now plus 15 minutes) and-90s(now minus 90 seconds).
- -
-
-#var(name): Get fcli variable contents; variable properties can be accessed as usual, i.e.#var("myVar")?.rootProp?.subProp.
- -
-
-#env(name): Get the value of an environment variable.
-
Note that for date comparisons, both sides of the comparison operator need to be explicitly defined as date/time objects. For example:
--
-
-
-
Invalid comparison:
-#date(myprop) < '2023-01-01'
- -
-
Valid comparison:
-#date(myprop) < #date('2023-01-01')
- -
-
Valid comparison:
-#date(myprop) < #now('-90d')
-
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:
-
-
-
-
--q '... "literal SpEL string" ...'(single quotes for shell, double quotes for SpEL literals)
- -
-
--q "... 'literal SpEL string' ..."(double quotes for shell, single quotes for SpEL literals)
-
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.
Session Management
-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:
fcli ssc session login --url https://my.ssc.org/ssc --user <user> --password <password>
-fcli ssc appversion list
-fcli ssc session logout --user <user> --password <password>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.
Named Sessions
-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:
-
-
-
-
Run fcli commands against multiple instances of the same product, like DEV and PROD instances or an on-premise instance and a Fortify Hosted instance, without having to continuously login and logout from one instance to switch to another instance
-
- -
-
Run fcli commands against a single instance of a product, but with alternating credentials, for example with one session providing admin rights and another session providing limited user rights
-
- -
-
Run one session with username/password credentials to allow access to all fcli functionality (based on user permissions), and another session with token-based authentication with access to only a subset of fcli functionality
-
- -
-
Run multiple pipelines or automation scripts simultaneously, each with their own session name, to reduce chances of these pipelines and scripts affecting each other (see Fcli Data Folder though for a potentially better solution for this scenario)
-
-
Session Storage
-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.
Fcli Data Folder
-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:
--
-
-
-
-FCLI_STATE_DIR: Location of fcli state like session and variable data.
-Default:<FCLI_DATA_DIR>/state
- -
-
-FCLI_CONFIG_DIR: Location of fcli configuration data like proxy and trust store settings.
-Default:<FCLI_DATA_DIR>/config
- -
-
-FCLI_DATA_DIR: Default base directory for the two directories listed above.
-Default:<FORTIFY_DATA_DIR>/fcli
- -
-
-FORTIFY_DATA_DIR: Default base directory for the directories listed above.
-Default:<user home directory>/.fortify
-
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.
Environment Variables
-Apart from the special-purpose environment variables described in other sections, like the Fcli Data 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 --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:
--
-
-
-
-FCLI_DEFAULT_SSC_APPVERSION_CREATE_ISSUE_TEMPLATE
- -
-
-FCLI_DEFAULT_SSC_APPVERSION_ISSUE_TEMPLATE
- -
-
-FCLI_DEFAULT_SSC_ISSUE_TEMPLATE
- -
-
-FCLI_DEFAULT_ISSUE_TEMPLATE
-
Environment variable lookups are based on the following rules:
--
-
-
-
Command aliases are not taken into account when looking for environment variables; suppose we have a
-deletecommand with aliasrm, you will need to useFCLI_DEFAULT_..._DELETE_...and notFCLI_DEFAULT_..._RM_...
- -
-
For options, fcli will use the longest option name when looking for environment variables; suppose we have an option with names
--a,--aband--abc, you will need to useFCLI_DEFAULT_..._ABCand notFCLI_DEFAULT_..._ABorFCLI_DEFAULT_..._A
- -
-
For positional parameters, the environment variable name will be based on the parameter label, converted to
-SNAKE_CASEwith all special characters replaced by an underscore. For example,<attributeDefinitionId>will becomeATTRIBUTE_DEFINITION_ID, andHOST:PORTwill becomeHOST_PORT.
-
Although powerful, these environment variables for providing default option and parameter values should be used with some care to avoid unexpected results:
--
-
-
-
Obviously command option requirements should be respected; supplying default values for exclusive options may result in errors or unexpected behavior
-
- -
-
Preferably, you should use the most specific environment variable name, like
-FCLI_DEFAULT_SSC_APPVERSION_CREATE_ISSUE_TEMPLATEfrom the example above, to avoid accidentally supplying default values to a similarly named option on other commands
-
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 variable value will be used as a default value for all
---urloptions in the SSC module
- -
-
This variable value will be used as a default value for all
---ssc-urloptions in other product modules
-
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 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 artifact upload command.
Variables can be stored using the --store myVarName[:prop1,prop2] option on data output commands. If property names are specified, then only these property names will be stored. If no property names are provided, all available JSON properties will be stored.
Variables can be referenced in subsequent fcli commands using the ::myVarName::prop syntax anywhere on the command line; such occurrences will be substituted with the value of the given property name.
Many (but not all) fcli commands will also store an entity-specific default property name when using the --store option. Whether a default property name has been stored can be seen in the output of the fcli util variable list command. If a default property name was stored, the ::myVarName:: syntax can be used to reference the value of the default property name, thereby avoiding the need to manually specify the appropriate property name.
Following are some examples, assuming the necessary login sessions are available:
-fcli ssc appversion create myApp:1.0 --auto-required-attrs --skip-if-exists --store myVersion
-fcli ssc artifact upload myScan.fpr --appversion ::myVersion::
-
-fcli ssc appversion create myApp:1.0 --auto-required --skip-if-exists --store myVersion:id,name
-fcli ssc artifact upload myScan.fpr --appversion ::myVersion::id
-
-fcli sc-sast scan start -p package.zip -v 22.2 --appversion test:1.0 --store x
-fcli sc-sast scan wait-for ::x::
-
-fcli sc-sast scan start -p package.zip -v 22.2 --appversion test:1.0 --store x
-fcli sc-sast scan wait-for ::x::jobTokenFcli provides the regular get, list and delete operations on the +fcli util variable command tree, and actual variable contents can be retrieved using the fcli util variable contents command. Please see help output or manual pages for more information on these commands.
The fcli util variable contents command supports the regular fcli output options and query capabilities. This allows for advanced us cases, like retrieving server data once and then outputting it in multiple formats, potentially even applying separate filters. As an example:
fcli ssc appversion list --store myVersions
-fcli util variable contents myVersions -o csv --output-to-file myVersions.csv
-fcli util variable contents myVersions -o json -q createdBy=admin --output-to-file myAdminVersions.json
-fcli util variable contents myVersions -o 'expr={id}\n' --output-to-file myVersionIds.txtNote: variable-related syntax and behavior was changed in fcli version 2.0.0. If you are using an older fcli version, please refer to the documentation for that version. When upgrading from 1.x.x to 2.x.x, you may need to update your fcli invocations to match the new syntax. See Issue 160 for information on why syntax and behavior was changed.
-Manual Pages
-Manual pages are automatically generated and contain the same information as fcli help output. Manual pages in HTML and Linux man-page formats can be downloaded for offline use from the fcli releases page at https://github.com/fortify/fcli/releases, or can be viewed online at https://fortify.github.io/fcli.
-Please select the proper fcli version from the links above to access the corresponding manual pages. When using the offline HTML documentation bundle, please make sure to extract the full documentation archive to allow for hyperlinks to work correctly.
-The manual pages for the currently selected fcli release can be found here: fcli (1).
-Troubleshooting
-Native Binaries
-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:
-
-
-
-
Commands and/or option listed in manual pages are not listed by the help output of a native binary
-
- -
-
Trying to use commands and/or options listed in the manual pages result in errors stating that the command or option is not recognized
-
- -
-
Some commands and/or options result in technical error messages about classes, constructors or methods not being found or not being accessible
-
-
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.
Submitting a Bug Report
-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:
--
-
-
-
Fcli version, as shown by the
-fcli --versioncommand
- -
-
Which fcli variant you are using; one of the native binaries or the
-.jarvariant invoked usingjava -jar fcli.jar
- -
-
If you are experiencing an issue with the native binaries, please confirm whether the
-.jarversion of fcli exhibits the same behavior
- -
-
Operating system and any other relevant environment details, for example:
----
-
-
-
Interactive or pipeline/automation use
-
- -
-
If pipeline use, what CI/CD system are you running fcli on (Jenkins, GitHub, GitLab, …)
-
- -
-
What FCLI environment variables have been set
-
-
- -
-
-
-
Steps to reproduce
-
- -
-
Any other information that may be relevant
-
-