Configure the Network Firewall (Appliance) Check

Set up the Network Firewall check to monitor OPNsense, WatchGuard, Sophos XG / XGS, FortiGate, or SonicWall appliances over REST or SNMP.

Written By Stefan Steuer

Last updated 26 days ago

Configure a Network Firewall (Appliance) Check

The Network Firewall (Appliance) check monitors a perimeter firewall — its reachability, firmware level, license / feature-key status, and security signals. octoja reaches it through one of seven vendor surfaces: FortiGate (REST API), FortiGate (SNMP), OPNsense, Sophos XG / XGS (local), WatchGuard (REST), WatchGuard (SNMP), and SonicWall (SNMP). The REST and local-API surfaces track firmware and license status; the SNMP surfaces read live measurements — CPU, sessions, and interface status, plus (depending on vendor) memory, disk, VPN tunnels, and HA cluster members.

Which vendor surface?

Vendor	How octoja reaches it	Agent placement
FortiGate (REST API)	FortiOS REST API on the appliance (HTTPS, Bearer token, default port 443)	octoja agent on a host that can reach the appliance's management port
FortiGate (SNMP)	SNMP v2c or v3 on the appliance (default UDP port 161, FortiGate + interface MIBs)	octoja agent on a host that can reach the appliance over SNMP
OPNsense	OPNsense REST API on the appliance (HTTPS, HTTP Basic with API key + secret)	octoja agent on a host that can reach the OPNsense management address
Sophos XG / XGS (local)	Sophos XML API on the appliance (HTTPS, default port 4444)	octoja agent on a host that can reach the appliance's API port
WatchGuard (REST)	WatchGuard Cloud REST API (OAuth2 client credentials + API key)	octoja agent on any internet-connected device — the appliance does not need to be local
WatchGuard (SNMP)	SNMP v2c or v3 on the Firebox (default UDP port 161)	octoja agent on a host that can reach the appliance over SNMP
SonicWall (SNMP)	SNMP v2c or v3 on the appliance (default UDP port 161)	octoja agent on a host that can reach the appliance over SNMP

Requirements

A managed OPNsense, WatchGuard, Sophos XG / XGS, FortiGate, or SonicWall appliance
The octoja agent installed on a device that can reach the appliance (FortiGate/OPNsense/Sophos/SonicWall and the SNMP surfaces) or the WatchGuard Cloud (WatchGuard REST)
API credentials for the chosen vendor, or — for any SNMP surface — an SNMP community string or SNMPv3 user (see the vendor sections below)

Steps

Go to Devices and open the device where the octoja agent is installed.
Click the Checks tab → Add Check → Network Firewall (Appliance).
Pick a Vendor. The form rearranges to show the relevant fields.
Fill in the vendor-specific fields (see below).
Adjust License warning (days) if 30 days is not enough lead time for your renewal workflow (WatchGuard and FortiGate).
Leave Verify TLS certificate off unless your appliance presents a certificate signed by a trusted CA — most perimeter firewalls do not.
Click Add Check.

OPNsense

Field	What to enter
Host / IP	Management hostname or IP of the appliance (no scheme), e.g. `192.168.1.1`
API port	Management API port. Default `443` matches a stock OPNsense install
API key	API key from the OPNsense user that owns the credentials
API secret	API secret paired with the key

Where do I get an OPNsense API key/secret? octoja needs an API key and matching secret from an OPNsense user with read access to status and firmware information. Generate the key/secret pair in the OPNsense web UI and paste both into the fields above — see your firewall vendor's documentation for the exact steps.

WatchGuard (REST)

Field	What to enter
Region base URL	Base URL from the WatchGuard Cloud Managed Access page. EU customers use `https://api.deu.cloud.watchguard.com` (default); US customers use the corresponding `usa` URL
WatchGuard API key	API key issued to your MSP account from Administration → Managed Access
Client ID (read-only access) / Client secret	OAuth2 client credentials from the same Managed Access page — request a read-only client
Account ID	Account identifier that appears in WatchGuard Cloud API paths, e.g. `WGC-1-XXXXXXXX` or `ACC-XXXXXXXX`
Target Fireware version	Optional. Set to the Fireware version you want appliances to be on. Leave empty to skip up-to-date evaluation (the WatchGuard Cloud API does not expose a reliable "latest" version)

Sophos XG / XGS

Field	What to enter
Host / IP	Hostname or IP of the appliance (no scheme)
API port	XML API port. Default `4444` matches the Sophos default. Sophos exposes a different port if you have moved the WebAdmin port
Admin username	An admin user with API access on the appliance. See your firewall vendor's documentation for enabling API access
Admin password	Password for the admin user
Target firmware version	Optional. Set to the Sophos firmware version you want the device to be on (e.g. `21.0.0 GA`). Leave empty to skip up-to-date evaluation — the local Sophos XML API does not know about released versions

FortiGate (REST API)

The REST API surface tracks firmware level and FortiGuard license status. Pick it when you want firmware and license monitoring.

Field	What to enter
Host / IP	Hostname or IP of the appliance (no scheme)
REST API token	Token of a read-only REST API administrator on the appliance. See your firewall vendor's documentation for creating one
Management port	HTTPS management port. Default `443` matches a stock FortiGate install

FortiGate (SNMP)

The SNMP surface reads live measurements over SNMP: CPU, memory and disk usage (each with its own warning and critical thresholds), the active session count, VPN tunnels, HA cluster members, and interface status with error counters. Before you configure the check, enable SNMP on the appliance and create a v2c community string or an SNMPv3 user with read access — see your firewall vendor's documentation.

Field	What to enter
Host / IP	Hostname or IP of the appliance (no scheme)
SNMP version	`v2c` or `v3`. Default `v2c`
SNMP port	UDP port the FortiGate listens on for SNMP. Default `161`
Community (v2c)	The read community string. Default `public`. Shown only when SNMP version is `v2c`
SNMPv3 user	The SNMPv3 username. Shown only when SNMP version is `v3`
Auth protocol (v3)	Authentication protocol for SNMPv3: `None`, `SHA-1`, or `SHA-256`. Default `SHA-1`
Auth password (v3)	Authentication password. Shown when an auth protocol other than `None` is selected
Privacy protocol (v3)	Encryption protocol for SNMPv3: `None`, `AES-128`, `AES-192`, or `AES-256`. Default `AES-128`
Privacy password (v3)	Privacy password. Shown when a privacy protocol other than `None` is selected
CPU warning (%) / CPU critical (%)	Thresholds for CPU usage. Defaults `85` / `95`
RAM warning (%) / RAM critical (%)	Thresholds for memory usage. Defaults `85` / `95`
Disk warning (%) / Disk critical (%)	Thresholds for disk usage. Defaults `85` / `95`
Include interfaces (IF-MIB)	Collect interface status and error counters. On by default
Interfaces that must be up	Pick from interfaces discovered on the last run. Any selected interface that is operationally down raises Critical
Warn if any interface down	Raise a Warning when any interface that should be up is operationally down. Off by default
Include VPN tunnels	Collect VPN tunnel status. On by default
VPN tunnels that must be up	Pick from tunnels discovered on the last run. Any selected tunnel that is down or missing raises Critical
Warn if any VPN tunnel down	Raise a Warning when any discovered tunnel is down. Off by default
Include HA	Collect HA cluster member information. On by default
HA expected cluster members (0 = off)	Raise Critical when fewer HA members are visible than this number (a failed peer). `0` turns the HA alarm off

WatchGuard (SNMP)

The WatchGuard SNMP surface reads live measurements from the Firebox over SNMP: CPU usage, the active session count, interface status, and HA cluster members. It also tracks the feature-key expiry and firmware level. Enable SNMP on the Firebox and create a v2c community string or an SNMPv3 user with read access first — see your firewall vendor's documentation.

Field	What to enter
Host / IP	Hostname or IP of the Firebox (no scheme)
SNMP version	`v2c` or `v3`. Default `v2c`
SNMP port	UDP port the appliance listens on for SNMP. Default `161`
Community (v2c)	The read community string. Default `public`. Shown only when SNMP version is `v2c`
SNMPv3 user	The SNMPv3 username. Shown only when SNMP version is `v3`
Auth protocol (v3)	Authentication protocol for SNMPv3: `None`, `SHA-1`, or `SHA-256`. Default `SHA-1`
Auth password (v3)	Authentication password. Shown when an auth protocol other than `None` is selected
Privacy protocol (v3)	Encryption protocol for SNMPv3: `None`, `AES-128`, `AES-192`, or `AES-256`. Default `AES-128`
Privacy password (v3)	Privacy password. Shown when a privacy protocol other than `None` is selected
CPU warning (%) / CPU critical (%)	Thresholds for CPU usage. Defaults `85` / `95`
Include interfaces (IF-MIB)	Collect interface status and error counters. On by default
Interfaces that must be up	Pick from interfaces discovered on the last run. Any selected interface that is operationally down raises Critical
Warn if any interface down	Raise a Warning when any interface that should be up is operationally down. Off by default
Include HA	Collect HA cluster member information. On by default
HA expected cluster members (0 = off)	Raise Critical when fewer HA members are visible than this number (a failed peer). `0` turns the HA alarm off
Target Fireware version	Optional. Set to evaluate up-to-date status against this Fireware version. Leave empty to skip
License warning (days)	A feature key expiring within this many days raises a Warning. Default `30`

SonicWall (SNMP)

The SonicWall SNMP surface reads live measurements from the appliance over SNMP: CPU and memory usage, the active session count, interface status, and VPN tunnels. Enable SNMP on the appliance and create a v2c community string or an SNMPv3 user with read access first — see your firewall vendor's documentation.

Field	What to enter
Host / IP	Hostname or IP of the appliance (no scheme)
SNMP version	`v2c` or `v3`. Default `v2c`
SNMP port	UDP port the appliance listens on for SNMP. Default `161`
Community (v2c)	The read community string. Default `public`. Shown only when SNMP version is `v2c`
SNMPv3 user	The SNMPv3 username. Shown only when SNMP version is `v3`
Auth protocol (v3)	Authentication protocol for SNMPv3: `None`, `SHA-1`, or `SHA-256`. Default `SHA-1`
Auth password (v3)	Authentication password. Shown when an auth protocol other than `None` is selected
Privacy protocol (v3)	Encryption protocol for SNMPv3: `None`, `AES-128`, `AES-192`, or `AES-256`. Default `AES-128`
Privacy password (v3)	Privacy password. Shown when a privacy protocol other than `None` is selected
CPU warning (%) / CPU critical (%)	Thresholds for CPU usage. Defaults `85` / `95`
RAM warning (%) / RAM critical (%)	Thresholds for memory usage. Defaults `85` / `95`
Include interfaces (IF-MIB)	Collect interface status and error counters. On by default
Interfaces that must be up	Pick from interfaces discovered on the last run. Any selected interface that is operationally down raises Critical
Warn if any interface down	Raise a Warning when any interface that should be up is operationally down. Off by default
Include VPN tunnels	Collect VPN tunnel status. On by default
VPN tunnels that must be up	Pick from tunnels discovered on the last run. Any selected tunnel that is down or missing raises Critical
Target SonicOS version	Optional. Set to evaluate up-to-date status against this SonicOS version. Leave empty to skip

What triggers an alert?

Condition	Severity
Configuration is incomplete (missing host, credentials, or account fields)	Failure
Authentication failed against the appliance / cloud	Failure
Appliance is unreachable	Critical (with code `offline`)
Firmware does not match the latest / target version (OPNsense, Sophos, FortiGate, WatchGuard, or SonicWall)	Warning (`outdated`)
OPNsense has pending package upgrades after the upgrade check	Warning (`pending-updates`)
OPNsense reports needs reboot	Warning (`needs-reboot`)
OPNsense update mirror unreachable (up-to-date verdict unreliable)	Warning (`update-check-unavailable`)
Sophos gateway is down	Warning (`gateway-down`)
WatchGuard inventory returns no Fireboxes	Warning (`no-devices`)
WatchGuard feature key / FortiGate license already expired	Critical (`license-expired`)
WatchGuard feature key / FortiGate license expires within the warning window	Warning (`license-expiring`)
WatchGuard ThreatSync reports open incidents	Critical (`open-incidents`)
An SNMP surface reports CPU, memory, or disk usage at or above its critical threshold	Critical (`cpu-high` / `ram-high` / `disk-high`)
An SNMP surface reports CPU, memory, or disk usage at or above its warning threshold	Warning (`cpu-high` / `ram-high` / `disk-high`)
An SNMP surface: a required VPN tunnel is down or not found	Critical (`vpn-required-down` / `vpn-required-missing`)
FortiGate (SNMP): any discovered VPN tunnel is down (when the warning is enabled)	Warning (`vpn-any-down`)
An SNMP surface: a required interface is down or not found	Critical (`if-required-down` / `if-required-missing`)
An SNMP surface: any interface that should be up is down (when the warning is enabled)	Warning (`if-any-down`)
FortiGate (SNMP) or WatchGuard (SNMP): fewer HA cluster members are visible than expected	Critical (`ha-degraded`)
All dimensions clean	OK

Tips

The check runs every 15 minutes by default — short enough to catch a perimeter going offline quickly without overwhelming the appliance management plane.
Use a dedicated read-only API user where the vendor allows it. The OPNsense and Sophos APIs accept credentials with browse-only permissions for status and firmware queries.
For WatchGuard, the ThreatSync incident check is best-effort — accounts without a ThreatSync subscription return a non-success code and octoja silently skips that dimension.
For a FortiGate, pick the surface that matches what you want to watch: FortiGate (REST API) for firmware and FortiGuard license status, or FortiGate (SNMP) for live CPU, memory, disk, sessions, VPN, HA, and interface measurements. You can configure both checks against the same appliance if you want each set of signals.
The Interfaces that must be up and VPN tunnels that must be up pickers populate from what the previous SNMP run discovered. Run the check once, then come back to select the names you want to require.
If you protect multiple appliances of the same vendor, configure one check per appliance. All the local-API and SNMP surfaces are appliance-local; only the WatchGuard (REST) surface is account-wide (one check covers every Firebox in the account).

After the first check interval, the result appears in the device's Checks tab with online status, firmware level, license expiry (WatchGuard), open incidents (WatchGuard), and an issue list.