FireSight docs

The FortiManager export script

fmg-export.py exports a FortiManager for an offline review when FireSight can't reach it, or when a backup can't be read (FortiManager 7.4 backups currently can't). You run it on any PC that can reach the FortiManager's web interface, then upload the file it writes as an offline snapshot.

The export holds policies, objects, devices, interfaces, routes and hit counters. It never holds a password, session or token.

Get the script

  1. In FireSight, open Settings, Connections, Add offline snapshot.
  2. Choose Config files or export.
  3. Click Download export script. It saves one file, fmg-export.py.

Downloading the script needs the Administrator role.

What it needs

  • Python 3.8 or later on Windows, macOS or Linux. Nothing else: no extra packages.
  • HTTPS access from that PC to FortiManager.
  • A FortiManager administrator with JSON API access (Read is enough), or an API token.

Run it

It asks for the password, which isn't shown or saved:

python fmg-export.py --host fmg.corp.example --user admin

On Windows use py fmg-export.py ....

Only some ADOMs (management domains):

python fmg-export.py --host 10.0.0.5 --user admin --adom EMEA --adom APAC

With an API token instead of a password:

FMG_TOKEN=<api-token> python fmg-export.py --host fmg.corp.example --token-env FMG_TOKEN

On Windows, set FMG_TOKEN=<api-token> first, then py fmg-export.py --host <fmg> --token-env FMG_TOKEN.

When it finishes it prints how many ADOMs, devices, packages and policies it exported, the file name and size, and any items it couldn't read (FireSight shows these as warnings).

Options

Option Default Meaning
--host required FortiManager address or name.
--port 443 HTTPS port.
--user asked for Administrator user name. You're asked for the password.
--password-env NAME Read the password from this environment variable instead of asking. Useful on Windows, where pasting into the hidden prompt can fail.
--token-env NAME Use an API token from this environment variable instead of a user name and password.
--adom NAME every ADOM Export only this ADOM. Repeat for several.
--out FILE see below Output file. A name ending in .gz is compressed with gzip; any other name is written as plain JSON.
--ca-file FILE A CA certificate (PEM) that signed FortiManager's certificate, if the PC doesn't trust it.
--insecure off Don't verify the TLS certificate. Labs only.
--use-proxy off Go through the system's HTTPS proxy. By default the script connects directly.
--quiet off Print only the summary.
--diagnose off Show FortiManager's answers to the sign-in and check the password arrived intact (its length and whether it contains spaces, control characters or non-ASCII characters; never the password itself).

The output file

By default the file is called fmg-export-<host>-<date>.json.gz, with the date and time as YYYYMMDD-HHMM in the PC's local time. With --adom, the ADOM names are in the name too, for example fmg-export-<host>-EMEA_APAC-<date>.json.gz; a list of more than three is shortened to the first three and and-N-more.

The file is compressed with gzip. Upload it as it is: FireSight accepts it compressed. Uploads are accepted up to 200 MB (1 GB once expanded); the script warns you if the file is larger. For a very large FortiManager, export a few ADOMs at a time with --adom and load each as its own snapshot.

To upload: Settings, Connections, Add offline snapshot, Config files or export.

Why it is read-only

The script only reads, and that is enforced in its code:

  • Every request passes a check before it leaves the PC. It may send reads (get) and exactly three other calls: sign in, sign out, and FortiManager's device proxy, and the proxy only with a GET to a FortiGate's monitor API. Anything else (set, add, update, delete, move, clone, install, scripts) is refused with refused: … isn't a read, and this script only reads, and nothing is sent.
  • It sends one request at a time.
  • It signs out when it's done.

For a second guarantee, sign in with an admin whose FortiManager profile is read-only, so FortiManager itself refuses changes.

If the sign-in is refused

FortiManager doesn't say why it refused a sign-in. The script lists the usual causes:

  1. The admin is an API user (REST API admin). Those can't sign in with a password: use its API key with --token-env.
  2. The admin's trusted hosts don't include this PC's address.
  3. The password didn't arrive as typed. On Windows, pasting into the hidden prompt can fail: type it, or use set FMG_PW=<password> and --password-env FMG_PW.
  4. The admin signs in through RADIUS, LDAP, TACACS+ or SAML, or has two-factor sign-in, a password that must be changed, or is locked out.
  5. JSON API Access is None in the admin's settings (Read is enough).

Run it again with --diagnose to see FortiManager's full answer. FortiManager's Event Log (System Settings > Event Log) shows the exact reason.

The most reliable fix is a read-only API administrator. On the FortiManager CLI:

config system admin user
  edit firesight-export
    set user_type api
    set profileid Restricted_User
    set rpc-permit read
    set trusthost1 <pc-ip> 255.255.255.255
  next
end
execute api-user generate-key firesight-export

Then set FMG_TOKEN=<api-token> and py fmg-export.py --host <fmg> --token-env FMG_TOKEN.

Exit codes

Code Meaning
0 Exported.
1 The export failed, for example a refused sign-in or a connection error.
2 Missing input: no password, the token variable isn't set, or an --adom that doesn't exist.
130 Stopped with Ctrl+C. Nothing was written.
← Offline snapshots Create a rule request →