Skip to main content

Connect a FortiGate firewall

FortiGate firewalls are on-prem, so Retrievy scans them through the Retrievy Agent for Docker running on a Linux host that has network reach to the FortiGate management interface. You register each FortiGate as a data source in Retrievy, the SaaS hands the agent an encrypted device manifest, and scans run nightly.

This page covers the FortiGate side (creating the read-only admin and registering the device) and the Retrievy side (wizard, encryption, scan triggers).

Before you start​

You need:

  • A FortiGate firewall running a supported FortiOS version (6.4 or later for full CIS coverage).
  • A Linux host with Docker where the Retrievy Agent Docker container is already installed and showing as Online in Settings → Fleet → Agents.
  • Network reach from the agent host to each FortiGate's management interface on SSH (port 22 by default).
  • The manage-cloud-accounts permission in Retrievy (the same permission gates cloud and on-prem data sources).
  • One free data-source slot on your plan per FortiGate.

How the connection works​

The agent pulls every FortiGate's running config over SSH on a nightly schedule. The exact command is show full-configuration and nothing else. The agent never modifies the device, never runs admin commands, and never opens an SSH session outside the scheduled scan window.

Credentials never live on the agent's disk. The flow:

  1. You enter the SSH username and password in Retrievy's wizard.
  2. The SaaS encrypts the password with the agent's RSA public key (a key the agent generated at install time and shared during pairing).
  3. The encrypted blob is added to the agent's device manifest.
  4. At scan time, the agent decrypts the password in memory using its private key, opens SSH, runs the command, and discards the cleartext as soon as the scan completes.

That model means rotating the credential is a single field update in Retrievy with no agent reconfiguration.

Step 1. Create a read-only admin on FortiGate​

A read-only admin is the safest credential set. Standard admin rights are not required.

On the FortiGate, either via the GUI or CLI:

GUI​

  1. Open System → Administrators → Create New → Administrator.
  2. Username: retrievy-readonly (or anything you like).
  3. Type: Local User.
  4. Password: a strong unique password. You'll paste it into Retrievy in step 3 and not need it again.
  5. Administrator profile: pick the built-in prof_admin_readonly profile if present; otherwise create a custom profile granting Read on every section and None on Write.
  6. Save.

CLI equivalent​

config system admin
  edit retrievy-readonly
    set password ENC <your-password>
    set accprofile prof_admin_readonly
    set trusthost1 <agent-host-ip> 255.255.255.255
  next
end

The trusthost line restricts the account to logins from the agent host's IP, which is a sensible extra hardening step.

Step 2. Confirm SSH is reachable from the agent host​

From the Docker agent's host:

ssh retrievy-readonly@<fortigate-ip> "show full-configuration | grep \"\""

If you see a long config dump, you're good. If you see Permission denied, re-check the password and the admin profile. If you see Connection refused, SSH is disabled on that interface (in System → Settings → Administrative Access, tick SSH for the management interface).

Step 3. Add the FortiGate in Retrievy​

In Retrievy:

  1. Open Settings → Cloud Integrations. The same page that lists cloud accounts also lists FortiGate devices.
  2. Click Add Cloud Account in the top-right.
  3. On the IDENTIFY TARGET step, pick FortiGate from the provider tiles. Click Next.
  4. The INGEST CREDENTIALS step asks for the device details:
FieldWhat to fill in
Device nameFriendly name shown in the dashboard, for example fg-edge-01.
HostFortiGate management IP or hostname reachable from the agent.
PortHTTPS port for the optional REST API. Default 443.
VDOMVirtual domain to scan. Default root.
SSH portSSH port. Default 22.
SSH usernameThe read-only admin you created in step 1.
SSH passwordThe password for that admin. Masked.
Assign to agentDropdown listing your online Docker agents. Pick the one that can reach this FortiGate.
  1. Click Next. Retrievy adds the FortiGate to the selected agent's manifest. The agent picks up the new device on its next heartbeat.

The optional REST API token​

A second field set lets you provide a FortiOS API token for the optional Policy Hygiene scan (separate from the CIS configuration scan). Without the API token, you still get the full CIS scan; you just don't get the hygiene findings (shadow rules, unused policies, rule-order drift). To create the token, in FortiOS go to System → Admin Profiles → API User and follow the FortiOS docs for token generation. Paste the token into the API Token field on the wizard.

Step 4. First scan​

The agent runs FortiGate scans on a nightly schedule (around 02:00 server-local time). To see findings now:

  1. Open Settings → Fleet → Agents, expand the agent you assigned the device to.
  2. The Devices list shows the new FortiGate. Click Scan Now on its row.
  3. The agent picks up the command within a minute. The scan typically takes a few minutes for a single device.

Findings land in the SCM FortiGate dashboard. You'll see two finding groups: CIS findings (always present) and Policies findings (only if you provided the API token).

Multiple FortiGates per agent​

One Docker agent scans as many FortiGates as you assign to it. Repeat Step 3 for each device, assigning them all to the same agent (or distributing across multiple agents if you have firewalls in isolated network segments).

Each FortiGate counts as one data-source slot on your plan. See plan feature matrix for slot counts per tier.

Rotating the SSH password​

  1. On the FortiGate, set a new password for the read-only admin.
  2. In Retrievy, open the FortiGate row in Settings → Cloud Integrations → Update credentials. Paste the new password.
  3. Click Save. The SaaS re-encrypts with the agent's public key and ships the new manifest on the next heartbeat.

The old password stops working as soon as you change it on the FortiGate side; there's no overlap window in Retrievy.

Revoking access​

  1. In Retrievy, click Deactivate on the device card to pause scans, or remove it entirely to release the data-source slot.
  2. On the FortiGate, disable or delete the read-only admin.

Troubleshooting​

Symptom: Wizard saves the device but the first scan reports SSH authentication failed. → Fix: Re-check the SSH username and password by hand from the agent's host (the ssh command shown in step 2). Most often the password was pasted with a trailing space, or the admin's trusthost field doesn't include the agent's IP.

Symptom: Scan reports Connection timed out. → Fix: The agent host can't reach the FortiGate's SSH port. From the agent host, run nc -zv <fortigate-ip> 22. If it fails, there's a firewall in between or the management interface doesn't have SSH enabled. Allow SSH from the agent host's IP on the FortiGate's management interface (Network → Interfaces → [mgmt] → Administrative Access).

Symptom: CIS findings appear but every Policies finding is empty. → Fix: You haven't provided a FortiOS API token, so the hygiene scan is skipped. Create the token in FortiOS (System → Admin Profiles → API User) and add it to the device in Settings → Cloud Integrations → Update credentials.

Symptom: A FortiGate I added doesn't show up in the agent's Devices list. → Fix: The agent hasn't fetched the updated manifest yet. Wait one heartbeat (typically under a minute) and refresh. If it still doesn't appear after 5 minutes, check that the agent is Online in Settings → Fleet → Agents.

Symptom: I want to scan a VDOM other than root. → Fix: Change the VDOM field in Update credentials to the VDOM name (case sensitive). The agent runs config vdom / edit <vdom> before the show command on the next scan.

Symptom: Scan succeeds but findings reference a config that doesn't match my current FortiGate. → Fix: The agent caches the last successful manifest. If you changed the device's host or credentials and the previous scan ran against the old values, trigger a new scan to refresh. If the issue persists, restart the agent container.