FortiGate

Clarity Transform reads firewall policy from a FortiGate over the FortiOS REST API and uses it to infer which discovered devices are permitted to communicate. Read-only throughout; nothing is written to the appliance.

Where to find it

Go to Discover → Integrations, then select the FortiGate card. The card's category label is Security. The integration's page has the Endpoints and History tabs; Integrations describes the page, its grid and its row actions.

Why we do this

Firewall policy is a complementary axis to observed traffic, and the pair is worth more than either alone. Firewall policy describes every conversation that is permitted to happen.

What we collect

• Firewall policies, with source, destination, service and action
• Address objects and address groups
• Service objects and service groups, so a promoted relationship carries a real port rather than a service name
• Inferred device-to-device relationships where both ends resolve

A group with an exclude list is reported, not expanded

FortiOS allows an address group to carry an exclude-member list. Such a group is not the union of its members, so expanding it would overstate what the policy covers. Clarity reports it and moves on rather than guessing.

What it adds

On an estate where FortiGates are managed centrally, this integration is the device half of the picture: what is actually installed and running, as against what FortiManager holds as authored intent.

Device and manager are not the same thing, and where both exist we read both

Reading only the device would miss centrally authored intent; reading only the manager would miss anything configured locally.

What is deliberately not inferred

• No traffic content, packet captures or firewall logs. Configuration only.
• Nothing is written back to the appliance at any point, and the account used has no permission to do so.
• A rule is not a dependency. A rule is promoted to a CMDB relationship only where both its source and destination resolve to a device or network already discovered, and where it is specific enough to describe a dependency rather than a broad policy.

Rule order is not evaluated

Firewall evidence means "a rule names this pair and port", not "this traffic would pass". A rule shadowed by a preceding deny still produces evidence. Deny, disabled, negated-address, negated-service and port-less rules are refused before they reach inference, so shadowing is the one case that is not detected. Treat a permitted-only finding as a lead to verify rather than a conclusion.

What we require

The requirement below is read from rb-pautol-fortigate-connect.ps1 in the Runbooks repository, which is where it is maintained. If it is wrong, the runbook is what gets corrected and this page follows on the next build.

Access profile required: a custom profile named clarity-readonly, with read on the system, network, firewall, log, VPN and security-profile groups, and none set to read-write. Discovery reads configuration only; it never writes to the device, and a write attempt as this account is rejected by the device itself.

Connectivity: the FortiOS REST API over HTTPS on TCP 443 from Clarity to the management interface.

If the account carries a trusted-hosts list it must include the Clarity host. FortiOS rejects an untrusted source using the same message it gives for a wrong password, so this failure is routinely diagnosed as a bad credential. Test from the Clarity virtual machine itself rather than from a workstation.

FortiOS calls every named login - full-privilege or not - an "administrator", configured under config system admin. There is no separate lightweight object for a read-only integration account (config system api-user exists but is a different, token-based mechanism this integration does not use). "Administrator" here describes where the account lives, not what it can do: do not let it read as "privileged" in anything derived from this file.

Verification before handover

1. Confirm the account authenticates from the Clarity host specifically. If the account carries a trusted-hosts list it must include the Clarity host, because FortiOS rejects an untrusted source using the same message it gives for a wrong password.
2. Confirm the policy table is readable. Read the firewall policy collection. A populated result confirms the access profile covers the firewall group.
3. Confirm the object tables are readable. Read the address and service collections too.

Configuring the endpoint

On the integration's Endpoints tab, select the add icon (Create New Integration Endpoints). The Create new entry form opens with these fields, in this order:

Field	Value
Name	A name for the endpoint
End Point	The FortiGate management FQDN or IP address
Credential	The stored credential for the read-only administrator
Job Schedule	A five-field cron expression. Daily (0 2 * * *) is ample; weekly (0 2 * * 0) is defensible on a stable estate
Enabled	Ticked. The box is unticked when the form opens

The help texts: End Point "FQDN or IP Address of management system for technology e.g. vCenter, Nutanix Prism"; Credential "Credentials can be configured under Settings/Identity and Access Management/Credentials."; Job Schedule "Cron schedule – Use five fields: 〈mm〉 〈hh〉 〈day-of-month〉 〈month〉 〈weekday〉".

The Credential list offers the credentials stored under Settings → Identity & Access Management → Credentials, so create the credential there first.

No field is marked as required. Technology is set by the card and is hidden in the form. Select Save to create the endpoint, or Cancel to close the form. The edit icon opens the same fields as Edit entry.

Removing the access

Delete the account on the appliance. Then, in Clarity, remove the endpoint (select its row on the Endpoints tab, then Remove selected) or clear its Enabled box, and remove the credential under Settings → Identity & Access Management → Credentials.

Troubleshooting

Symptom	Cause
Authentication fails with a credential you believe is correct	A trusted-hosts list on the account that does not include the Clarity host. FortiOS reports this identically to a wrong password.
Policies read but objects missing	The access profile grants read on the firewall group but not on the address or service groups.
An address group reported rather than expanded	It carries an exclude-member list. Expected behaviour, not a fault.
Policies read but no relationships created	Endpoints do not resolve to discovered devices. Run the hypervisor and operating system integrations first.