Firewall Sync
A gateway asset often sits behind a firewall that separates it from the networks it fronts: the virtual assets and subnets it provides access to live on the far side of that firewall. Every policy that grants access to such a destination then needs a matching rule on the firewall, and every policy change needs the rule changed.
Firewall sync lets the gateway asset do that itself. For each policy that grants access to a virtual asset or subnet behind the gateway, the asset creates the address objects, the service and one allow rule on the firewall, keeps them in step with the policy, and removes them when the policy goes. The asset talks to the firewall over its own LAN; the firewall's management API is never exposed to the internet, and its API key is never stored on the XplicitTrust servers.
Supported firewalls: Fortinet FortiGate (FortiOS REST API).
How it works
The gateway asset receives, with its configuration, the list of destinations behind it that policies grant access to, together with the services of those policies. From that it maintains on the firewall:
- an address object for each destination (a host or a network) and one for the gateway's own address toward it,
- a service object for each service definition a policy uses, reusing the
firewall's predefined services (such as
HTTPS) where they match, - one allow rule per policy and destination, from the gateway's address to the destination for that service, with NAT disabled.
The firewall's own routing decides the interfaces of a rule: the asset asks the firewall which interface reaches the gateway and which reaches the destination. A destination that the firewall reaches through the same interface as the gateway is on the gateway's own segment; the firewall is not in that path, and the rule is skipped unless you choose to create such rules anyway.
Every object the asset creates carries an ownership marker in its comment and
a name starting with the configured prefix (xt- by default). Rules are
grouped under one section label in the firewall's rule view and placed either
before or after your own rules, as configured. The asset never touches
objects it does not own, and on removal it deletes exactly the objects it
created. Drift introduced on the firewall is repaired every 15 minutes.
Prerequisites
Gateway asset. A Linux asset running agent 1.136 or newer that reaches the firewall's management interface over the LAN.
FortiGate. A REST API administrator for the asset. Use a dedicated administrator with the least privilege the sync needs: read-write on firewall addresses, services and policies, read on the system, network and router tables, no GUI or SSH access, and the trusted host limited to the gateway asset's address. On the FortiGate CLI:
config system accprofile
edit "xt-sync"
set sysgrp read
set netgrp read
set fwgrp custom
config fwgrp-permission
set policy read-write
set address read-write
set service read-write
set schedule read
set others read
end
next
end
config system api-user
edit "xt-sync"
set accprofile "xt-sync"
config trusthost
edit 1
set ipv4-trusthost <gateway asset address> 255.255.255.255
next
end
next
end
execute api-user generate-key xt-sync
The key is shown once; copy it for the console. Firewall sync is validated on FortiOS 8.0.2 and uses the REST API paths that exist since FortiOS 6.4. Earlier releases have not been tested.
Routing. The destinations must be routed through the firewall. In an HA cluster, use the cluster's management address; each member presents its own certificate, so pin one fingerprint per member (see below).
Setting it up
- Open the gateway asset on the Assets page and switch to the Firewall sync tab.
- Choose the firewall vendor and enter the Management URL of the
firewall (
https://hostorhttps://host:port, as reachable from the asset). Leave VDOM empty unless the API administrator is not bound to a VDOM and the gateway's VDOM is not the one you want; the asset detects the VDOM the gateway sits in. - Review the object name prefix, the rule placement (before or after your own rules), what to do with destinations on the asset's own segment, the section label and whether the rules should log all traffic. Save.
- Enter the device API key and choose Hand over to asset. The asset must be online: the key is encrypted for that asset's own certificate, kept for two minutes for it to collect, and discarded. The status moves from waiting for the asset to delivered, verifying.
- On its first contact the asset refuses the firewall's management certificate, which is normally self-signed: the status shows The device presented a certificate that is not pinned with the fingerprint it saw. Compare it with the certificate on the firewall (System → Certificates) and choose Pin the certificate the device presented, then save. The next run verifies the key against the device and creates the rules.
The side panel shows the state of the API key, the last sync, the device the asset found (hostname, firmware, serial number, VDOM, operation mode, high availability) and how many rules were applied, skipped or failed. The sync report lists every rule with its outcome and the interfaces it was placed on.
Pinning the certificate up front
If you have the SHA-256 fingerprint of the management certificate at hand, add it under Pinned certificate fingerprints before handing over the key. Without a pin the certificate has to chain to a public certificate authority.
Turning it off
Turning the sync off makes the asset remove the rules and objects it created and forget the API key; the settings stay, so it can be turned on again with a new key. Remove firewall sync deletes the settings too.
Troubleshooting
| What you see | What it means |
|---|---|
| API key: not handed over yet | Settings saved, no key handed over. |
| API key: waiting for the asset | The asset has not collected the key yet. It needs to be online; the handoff expires after two minutes. |
| API key: handoff expired, hand it over again | The asset did not collect the key in time. Check that the asset is online and its agent is 1.136 or newer, then hand the key over again. |
| API key: delivered, verifying | The asset holds the key and has not reached the device yet, or the device's certificate is not pinned. Look at the last sync message. |
| API key: rejected by the device | The firewall refused the key. Generate a new key for the API administrator and hand it over again. |
| The device presented a certificate that is not pinned | Normal on first contact and after a certificate rotation or a failover. Pin the fingerprint shown after checking it on the firewall. |
| The API user may not read: | The API administrator's profile lacks read access to the listed tables. Facts from those tables show as unknown; widen the profile as in the prerequisites. |
| Rules skipped | The destination is on the gateway's own segment, or a hostname-defined virtual asset has not resolved yet. Choose Create rules anyway for hosts that are routed through the firewall although they share the gateway's prefix. |
| Rules failed | The sync report carries the firewall's error for each rule. Common causes are the policy limit of a FortiGate-VM trial license and an API administrator without write access to policies. |
Security notes
- The API key is encrypted for the gateway asset's certificate before it leaves the console, is held by the asset only and never stored on the XplicitTrust servers. Nothing is written to the device until the key and the device's certificate have been verified.
- The gateway asset holds a key that can change firewall rules within the API administrator's profile. Keep that profile to the permissions above, limit the trusted host to the asset, and treat the gateway asset as the sensitive host it is.
- There is no way to skip certificate verification. The management certificate is pinned by fingerprint, or it has to chain to a public certificate authority.