Upgrading from fcli v2.x to v3.x may require some changes to existing fcli command invocations, as some commands, options, or accepted option values have changed. This document describes those changes for each of the affected fcli modules. Note that this document only describes breaking changes, it doesn’t describe any new functionality. Please see the fcli change log for an overview of new features.
Configuration & state data
Configuration and state data for fcli 2.x was stored in <user home>/.fortify/fcli/config
and <user home>/.fortify/fcli/state
by default. As there have been some incompatible changes to the contents of some of these files, fcli 3.x uses <user home>/.fortify/fcli/v3/config
and <user home>/.fortify/fcli/v3/state
by default instead. This means that fcli 3.x will not be aware of any configuration or state data generated through fcli 2.x, like proxy or trust store configuration, sessions, or tool installations.
This allows for running fcli 2.x and 3.x side by side without any conflicts, but also means that you’ll need to run fcli config
commands again for fcli 3.x, use the session login
commands to recreate any sessions, and/or re-do tool installations to make fcli 3.x aware of these installations.
You may attempt to copy fcli 2.x configuration and state data to the fcli 3.x configuration and state directories to make fcli 3.x aware of this data; this will likely work for configuration data like proxy & trust store settings and tool installation state, but is not officially supported. You shouldn’t copy SSC session state from fcli 2.x to the fcli 3.x state directory, as this is known to cause errors.
FCLI_DEFAULT_*
environment variables
If you were previously using FCLI_DEFAULT_*
environment variables, the environment variable names may need to be updated to reflect the updated fcli command structure and option names.
As an example, with fcli 2.x, the environment variable FCLI_DEFAULT_SC_SAST_CLIENT_AUTH_TOKEN
environment variable would define a default value for all --client-auth-token
options within the sc-sast
module, effectively specifying a default value for the --client-auth-token
option on the fcli sc-sast session login
command. Given that the fcli sc-sast session
commands have been removed in fcli 3.x, and the --client-auth-token
option now needs to be specified on the fcli ssc session login
command, the environment variable name will need to be changed from FCLI_DEFAULT_SC_SAST_CLIENT_AUTH_TOKEN
to FCLI_DEFAULT_SSC_CLIENT_AUTH_TOKEN
.
Another example is the FCLI_DEFAULT_SSC_CI_TOKEN
environment variable; as the fcli ssc session login
command now only supports a --token
option and no longer a --ci-token
option, this environment variable will need to be renamed to FCLI_DEFAULT_SSC_TOKEN
.
--output
option
Breaking changes:
-
The following formats are no longer accepted by the
-o
/--output
option:-
json-properties
; to view available properties, please usejson
format instead. -
tree
&tree-flat
; to get tree-like output, please useyaml
format instead. -
csv-plain
&table-plain
; please use the new--style=no-headers
option instead. -
json-flat
,xml-flat
&yaml-flat
; please use the new--style=flat
option instead.
-
-
There may be subtle differences in the output produced by the various output formats. For example:
-
csv
output will now by default use the original JSON property names as headers, instead of attempting to format these as human-readable text. -
Similarly, when specifying what properties to include in the
table
output, for example with-o table=p1,p2
, the original property names will be used as table headers. -
Optionally, you can specify alternative header names, for example with
-o table=p1:First Property,p2:Second Property
or-o csv=p3:Property 3,p4:Property 4
-
fcli fod
Breaking changes:
-
The
--session
option has been renamed to--fod-session
, to be more explicit and consistent with other fcli modules. -
The fcli action syntax has changed significantly; custom fcli actions developed for fcli 2.x will require changes to allow them to run on fcli 3.x. Please review the Fcli Actions section for details.
fcli sc-sast
Breaking changes:
-
The
fcli sc-sast session
commands have been removed; please usefcli ssc session
commands instead to manage sessions that are shared acrossfcli ssc
,fcli sc-sast
,fcli sc-dast
, and the newfcli aviator
module. The ScanCentral SAST client-auth-token will now need to be passed to thefcli ssc session login
command. -
The
--session
option has been replaced with--ssc-session
to explicitly refer to sessions managed through thefcli ssc session
commands. -
The options accepted by the
fcli sc-sast scan start
command have changed significantly:-
The
-m
,--mbs-file
,-p
, and--package-file
have been replaced by the new--file
/-f
option, which will auto-detect whether the given file is an MBS file or package file. -
For packages generated by ScanCentral Client 24.2 or above, it is recommended to remove the
--sensor-version
/-v
option as fcli will now auto-detect the proper sensor version to be used for the scan. For packages generated by ScanCentral Client 24.1 or below, the--sensor-version
option is still required.
-
fcli sc-dast
Breaking changes:
-
The
fcli sc-dast session
commands have been removed; please usefcli ssc session
commands instead to manage sessions that are shared acrossfcli ssc
,fcli sc-sast
,fcli sc-dast
, and the newfcli aviator
module. -
The
--session
option has been replaced with--ssc-session
to explicitly refer to sessions managed through thefcli ssc session
commands.
fcli ssc
Breaking changes:
-
Sessions managed by
fcli ssc session
commands are now being shared acrossfcli ssc
,fcli sc-sast
,fcli sc-dast
, and the newfcli aviator
module. As a result, the--client-auth-token
option will now need to be specified on thefcli ssc session login
command if the session is to be used for invokingfcli sc-sast
commands. -
The
--session
option has been renamed to--ssc-session
, to be more explicit and consistent with other fcli modules. -
Deprecated option values for the
--copy
option onfcli ssc appversion create
have been removed; any references toAnalysisProcessingRules
will need to be replaced withprocessing-rules
, and any references toBugTrackerConfiguration
will need to be replaced withbugtracker
. -
The fcli action syntax has changed significantly; custom fcli actions developed for fcli 2.x will require changes to allow them to run on fcli 3.x. Please review the Fcli Actions section for details.
Fcli actions
There have been significant changes to the fcli action yaml syntax, both to make the syntax easier to use and understand, and to allow for new features. Built-in actions have been updated to the new syntax, so if you are running built-in actions only, these changes shouldn’t have any impact when upgrading from fcli v2.x to v3.x.
However, any custom actions developed for fcli v2.x will not run on fcli v3.x (and vice versa). To allow custom actions developed for fcli v2.x to run on fcli v3.x, they will need to be updated to use the new fcli action yaml syntax. Given that the ability to run custom actions was documented as being preview functionality in fcli v2.x, this shouldn’t come as too much of a surprise.
If, despite the preview warning, the updated fcli action yaml syntax poses major issues for your business, please discuss this with your OpenText Fortify representative to investigate options for assistance on migrating your fcli v2.x custom actions to fcli v3.x. Based on customer feedback, we may also investigate feasibility of providing an automated migration tool. Note though that even if we choose to do so, automatically migrated actions may still require manual review and changes to cater for any migration tasks that cannot be automated.
To assist you with updating your fcli v2.x custom actions to allow them to run on fcli v3.x, the following table provides a summary of fcli v2.x action instructions and their fcli v3.x equivalents. Please note that the syntax for many of these instructions have changed, for example now taking a map instead of a list, with map keys defining identifiers. Please see the schema definition or the various built-in fcli actions for details and examples on new syntax. It is recommended to use IDE-provided schema-based code assistance when updating your custom actions.
fcli 2.x |
fcli 3.x |
Notes |
|
|
Now takes map instead of list, moved to |
|
|
Moved to new |
|
|
Now takes map instead of list, some property changes |
|
|
Use variable name with trailing |
|
|
Properties have been renamed for better consistency |
|
|
Renamed for better consistency |
|
|
Now takes map instead of list, some property changes |
|
|
Renamed, some property changes |
|
|
Renamed for better consistency |
|
|
Now takes map instead of list, many properties have been renamed for better consistency |
|
|
Now takes map instead of list, new syntax for variable names to allow for composite & array-style variables |
|
|
Renamed for better consistency |
|
|
Renamed for better consistency |
|
|
Now takes map instead of list, with new syntax for map values |
|
|
Renamed for better consistency |