Network Firewall (Appliance) Check Reference

Configuration fields, vendor-specific API surfaces, alert codes, and platform support for the Network Firewall check in octoja.

Written By Stefan Steuer

Last updated 26 days ago

Network Firewall (Appliance) Check Reference

Configuration options and alert behaviour for the Network Firewall (Appliance) check.

The Network Firewall check probes a perimeter firewall appliance for reachability, firmware up-to-date status, license / feature-key expiry, and security signals. Default interval: 15 minutes. The check supports seven vendor surfaces (FortiGate REST API, FortiGate SNMP, OPNsense, Sophos XG / XGS, WatchGuard REST, WatchGuard SNMP, and SonicWall SNMP); fields visible in the UI depend on the selected vendor. The two FortiGate surfaces are distinct: the REST API surface reports firmware and FortiGuard license status, while the SNMP surface reads live measurements (CPU, memory, disk, sessions, VPN tunnels, HA cluster members, and interfaces). The SNMP surfaces vary by vendor: WatchGuard (SNMP) adds CPU, interfaces, and HA; SonicWall (SNMP) adds CPU, RAM, interfaces, and VPN tunnels.

Vendor matrix

Vendor	API surface	Auth	Reachability target
FortiGate (REST API)	FortiOS REST API over HTTPS (default port 443)	REST API token (`Authorization: Bearer`)	Appliance directly
FortiGate (SNMP)	SNMP v2c / v3 (default UDP port 161; FORTINET-FORTIGATE-MIB + IF-MIB)	v2c community string, or SNMPv3 user with auth + privacy	Appliance directly
OPNsense	OPNsense REST (`/api/core/firmware/*`)	HTTP Basic with API key + secret	Appliance directly
Sophos XG / XGS	Sophos XML API (`/webconsole/APIController`, port 4444)	Username + password in the XML request body	Appliance directly
WatchGuard (REST)	WatchGuard Cloud REST (`/rest/platform/allocation/v2/`, `/rest/threatsync/management/v1/`)	OAuth2 client_credentials + `WatchGuard-API-Key` header	WatchGuard Cloud regional endpoint
WatchGuard (SNMP)	SNMP v2c / v3 (default UDP port 161)	v2c community string, or SNMPv3 user with auth + privacy	Appliance directly
SonicWall (SNMP)	SNMP v2c / v3 (default UDP port 161)	v2c community string, or SNMPv3 user with auth + privacy	Appliance directly

Configuration fields

Common fields apply across vendors; the rest are revealed when the matching vendor is selected.

Common

Field	Type	Required	Default	Description
Vendor	select	Yes	OPNsense	Selects which appliance surface to probe. Drives which fields are shown. Options: FortiGate (REST API), FortiGate (SNMP), OPNsense, Sophos XG / XGS (local), WatchGuard (REST), WatchGuard (SNMP), SonicWall (SNMP)
Verify TLS certificate	boolean	No	false	Validate the appliance TLS certificate. Off by default because appliances typically present a self-signed certificate. Not shown for WatchGuard (REST), WatchGuard (SNMP), FortiGate (SNMP), or SonicWall (SNMP) — those cloud and SNMP connections do not use TLS in this way

OPNsense

Field	Type	Required	Default	Description
Host / IP	string	Yes	—	Management hostname or IP (no scheme)
API port	number	No	443	HTTPS management / API port. OPNsense allows moving the GUI off 443. Range 1–65535
API key	password	Yes	—	OPNsense API key
API secret	password	Yes	—	OPNsense API secret

WatchGuard (REST)

Field	Type	Required	Default	Description
Region base URL	string	No	https://api.deu.cloud.watchguard.com	Regional WatchGuard Cloud base URL. EU = `deu`, USA = `usa`
WatchGuard API key	password	Yes	—	API key from WatchGuard Cloud Managed Access
Client ID (read-only access)	string	Yes	—	OAuth2 client ID
Client secret	password	Yes	—	OAuth2 client secret
Account ID	string	Yes	—	Account identifier in WatchGuard API paths (`WGC-1-…` or `ACC-…`)
Target Fireware version	string	No	—	Set to evaluate up-to-date status. Empty = skip the up-to-date dimension (the Cloud API does not expose latest reliably)
License warning (days)	number	No	30	Feature-key / license expiring within this many days raises a warning. Range 1–365

Sophos XG / XGS

Field	Type	Required	Default	Description
Host / IP	string	Yes	—	Hostname or IP of the appliance
API port	number	No	4444	Sophos XML API port. Range 1–65535
Admin username	string	Yes	—	Sophos admin user with API access
Admin password	password	Yes	—	Password for the admin user
Target firmware version	string	No	—	Compare against this version (e.g. `21.0.0 GA`). Empty = skip up-to-date dimension. The local Sophos API does not report latest available

FortiGate (REST API)

Field	Type	Required	Default	Description
Host / IP	string	Yes	—	Hostname or IP of the appliance
Management port	number	No	443	HTTPS management port. FortiGate admin access is frequently moved off 443. Range 1–65535
REST API token	password	Yes	—	Token of a read-only REST API administrator (System > Administrators), sent as `Authorization: Bearer`
License warning (days)	number	No	30	Feature-key / license expiring within this many days raises a warning. Range 1–365

FortiGate (SNMP)

The SNMP surface polls the FortiGate over SNMP for live measurements. Threshold, interface, VPN, and HA fields below are visible only for this vendor.

Field	Type	Required	Default	Description
Host / IP	string	Yes	—	Hostname or IP of the appliance
SNMP version	select	No	v2c	SNMP protocol version. Options: `v2c`, `v3`
SNMP port	number	No	161	UDP port for SNMP. Range 1–65535
Community (v2c)	string	No	public	Read community string. Shown when SNMP version is `v2c`
SNMPv3 user	string	No	—	SNMPv3 username. Shown when SNMP version is `v3`
Auth protocol (v3)	select	No	SHA-1	SNMPv3 authentication protocol. Options: `None`, `SHA-1`, `SHA-256`. Shown when SNMP version is `v3`
Auth password (v3)	password	No	—	Authentication password. Shown when the auth protocol is not `None`
Privacy protocol (v3)	select	No	AES-128	SNMPv3 encryption protocol. Options: `None`, `AES-128`, `AES-192`, `AES-256`. Shown when the auth protocol is not `None`
Privacy password (v3)	password	No	—	Privacy password. Shown when the privacy protocol is not `None`
CPU warning (%)	number	No	85	CPU usage at or above this raises a warning
CPU critical (%)	number	No	95	CPU usage at or above this raises Critical
RAM warning (%)	number	No	85	Memory usage at or above this raises a warning
RAM critical (%)	number	No	95	Memory usage at or above this raises Critical
Disk warning (%)	number	No	85	Disk usage at or above this raises a warning
Disk critical (%)	number	No	95	Disk usage at or above this raises Critical
Include interfaces (IF-MIB)	boolean	No	true	Collect interface status and in/out error counters
Interfaces that must be up	array	No	—	Names selected from interfaces discovered on the last run. Any operationally down raises Critical. Shown when interfaces are included
Warn if any interface down	boolean	No	false	Warn when any admin-up interface is operationally down. Shown when interfaces are included
Include VPN tunnels	boolean	No	true	Collect VPN tunnel status
VPN tunnels that must be up	array	No	—	Names selected from tunnels discovered on the last run. Any down / missing raises Critical. Shown when VPN tunnels are included
Warn if any VPN tunnel down	boolean	No	false	Warn when any discovered tunnel is down. Shown when VPN tunnels are included
Include HA	boolean	No	true	Collect HA cluster member information
HA expected cluster members (0 = off)	number	No	0	Critical when fewer HA cluster members are visible than this value (failed peer). 0 disables the HA alarm. Shown when HA is included

WatchGuard (SNMP)

The SNMP surface polls a WatchGuard Firebox directly over SNMP. It reuses the same SNMP connection fields as FortiGate (SNMP), plus the CPU, interface, and HA fields below. RAM, disk, and VPN measurements are not collected on this surface.

Field	Type	Required	Default	Description
Host / IP	string	Yes	—	Hostname or IP of the appliance
SNMP version / port / credentials	group	No	v2c, 161	Same SNMP connection fields as FortiGate (SNMP): version (`v2c` / `v3`), port, v2c community, and the SNMPv3 user / auth protocol / auth password / privacy protocol / privacy password
CPU warning (%)	number	No	85	CPU usage at or above this raises a warning
CPU critical (%)	number	No	95	CPU usage at or above this raises Critical
Include interfaces (IF-MIB)	boolean	No	true	Collect interface status and in/out error counters
Interfaces that must be up	array	No	—	Names selected from interfaces discovered on the last run. Any operationally down raises Critical. Shown when interfaces are included
Warn if any interface down	boolean	No	false	Warn when any admin-up interface is operationally down. Shown when interfaces are included
Include HA	boolean	No	true	Collect HA cluster member information
HA expected cluster members (0 = off)	number	No	0	Critical when fewer HA cluster members are visible than this value. 0 disables the HA alarm. Shown when HA is included
Target Fireware version	string	No	—	Set to evaluate up-to-date status against this version. Empty = skip the up-to-date dimension
License warning (days)	number	No	30	Feature-key / license expiring within this many days raises a warning. Range 1–365

SonicWall (SNMP)

The SNMP surface polls a SonicWall appliance directly over SNMP. It reuses the same SNMP connection fields as FortiGate (SNMP), plus the CPU, RAM, interface, and VPN fields below. Disk and HA measurements are not collected on this surface.

Field	Type	Required	Default	Description
Host / IP	string	Yes	—	Hostname or IP of the appliance
SNMP version / port / credentials	group	No	v2c, 161	Same SNMP connection fields as FortiGate (SNMP): version (`v2c` / `v3`), port, v2c community, and the SNMPv3 user / auth protocol / auth password / privacy protocol / privacy password
CPU warning (%)	number	No	85	CPU usage at or above this raises a warning
CPU critical (%)	number	No	95	CPU usage at or above this raises Critical
RAM warning (%)	number	No	85	Memory usage at or above this raises a warning
RAM critical (%)	number	No	95	Memory usage at or above this raises Critical
Include interfaces (IF-MIB)	boolean	No	true	Collect interface status and in/out error counters
Interfaces that must be up	array	No	—	Names selected from interfaces discovered on the last run. Any operationally down raises Critical. Shown when interfaces are included
Warn if any interface down	boolean	No	false	Warn when any admin-up interface is operationally down. Shown when interfaces are included
Include VPN tunnels	boolean	No	true	Collect VPN tunnel status
VPN tunnels that must be up	array	No	—	Names selected from tunnels discovered on the last run. Any down / missing raises Critical. Shown when VPN tunnels are included
Target SonicOS version	string	No	—	Set to evaluate up-to-date status against this version. Empty = skip the up-to-date dimension

Issue codes

The check reports a list of issue rows; the worst severity becomes the overall result.

Code	Vendor	Severity	Meaning
`offline`	All	Critical	Appliance unreachable, or one Firebox in the account is disconnected
`outdated`	OPNsense, Sophos, WatchGuard*, FortiGate	Warning	Current firmware does not match latest / target. Detail = `current → target`
`pending-updates`	OPNsense	Warning	Up-to-date but the upgrade mirror has pending package updates. Detail = count
`needs-reboot`	OPNsense	Warning	OPNsense flagged a pending reboot
`update-check-unavailable`	OPNsense	Warning	Upgrade mirror unreachable; up-to-date verdict above is unreliable. Detail = connection status
`gateway-down`	Sophos	Warning	Sophos device-info gateway status is not True. Detail = reported status
`no-devices`	WatchGuard	Warning	WatchGuard Cloud inventory returned no Fireboxes for the account
`license-expired`	WatchGuard, FortiGate	Critical	Soonest feature-key / subscription expiry is in the past. Detail = days past expiry
`license-expiring`	WatchGuard, FortiGate	Warning	Soonest feature-key / subscription expiry is within the warning window. Detail = days remaining
`open-incidents`	WatchGuard	Critical	ThreatSync reports open threat incidents. Detail = count
`cpu-high`	FortiGate (SNMP)	Warning / Critical	CPU usage reached the warning or critical threshold. Detail = `value% / threshold%`
`ram-high`	FortiGate (SNMP)	Warning / Critical	Memory usage reached the warning or critical threshold. Detail = `value% / threshold%`
`disk-high`	FortiGate (SNMP)	Warning / Critical	Disk usage reached the warning or critical threshold. Detail = `value% / threshold%`
`vpn-required-down`	FortiGate (SNMP)	Critical	A tunnel listed in VPN tunnels that must be up is down. Detail = tunnel name
`vpn-required-missing`	FortiGate (SNMP)	Critical	A tunnel listed in VPN tunnels that must be up was not found. Detail = tunnel name
`vpn-any-down`	FortiGate (SNMP)	Warning	One or more discovered tunnels are down (when Warn if any VPN tunnel down is on). Detail = tunnel names
`if-required-down`	FortiGate (SNMP)	Critical	An interface listed in Interfaces that must be up is operationally down. Detail = interface name
`if-required-missing`	FortiGate (SNMP)	Critical	An interface listed in Interfaces that must be up was not found. Detail = interface name
`if-any-down`	FortiGate (SNMP)	Warning	One or more admin-up interfaces are operationally down (when Warn if any interface down is on). Detail = interface names
`ha-degraded`	FortiGate (SNMP)	Critical	Fewer HA cluster members are visible than the expected count. Detail = `visible/expected`

*WatchGuard outdated only fires when a Target Fireware version is configured. FortiGate (REST API) needs no target version — the appliance itself reports available upgrades via FortiGuard.

Error codes

When the check itself cannot run (bad configuration, authentication failure, unreachable API), it reports one of the following error codes instead of issue rows. The check detail view shows the matching message.

Code	Meaning
`invalid-vendor`	Unknown or unconfigured vendor
`check-failed`	Unexpected error while running the check
`opnsense-config-required`	OPNsense requires host, API key and API secret
`opnsense-auth-failed`	OPNsense authentication failed (check API key/secret)
`sophos-config-required`	Sophos requires host, username and password
`sophos-auth-failed`	Sophos authentication failed (check username/password)
`sophos-unparseable`	Sophos returned an unparseable response
`sophos-no-deviceinfo`	Sophos response did not contain DeviceInfo (API user may lack access)
`watchguard-config-required`	WatchGuard requires base URL, API key, client ID/secret and account ID
`watchguard-token-failed`	WatchGuard token request failed
`watchguard-no-access-token`	WatchGuard token response did not contain an access token
`watchguard-unreachable`	WatchGuard Cloud unreachable
`watchguard-auth-failed`	WatchGuard authorization failed (check API key / account ID)
`watchguard-listing-failed`	WatchGuard device listing failed
`fortigate-config-required`	FortiGate requires host and a REST API token
`fortigate-auth-failed`	FortiGate authentication failed (check API token)
`fortigate-snmp-config-required`	FortiGate (SNMP) requires a host
`watchguard-snmp-config-required`	WatchGuard (SNMP) requires a host
`sonicwall-snmp-config-required`	SonicWall (SNMP) requires a host

Metrics collected

vendor — the vendor string echoed back for the renderer
online — appliance is reachable / at least one Firebox is connected
firmwareCurrent — currently installed firmware version (best-effort across vendor JSON shapes)
firmwareLatest — latest version reported by OPNsense / FortiGate, or the configured target string for Sophos / WatchGuard
upToDate — true / false / null (null when the up-to-date dimension was not evaluated)
licenseExpiresAt — soonest feature-key / subscription expiry (WatchGuard and FortiGate), ISO-8601
openAlerts — ThreatSync open-incident count when available (WatchGuard only)
issues — list of {severity, code, detail} entries that contributed to the result

FortiGate (SNMP) additionally returns the live measurements below.

sysName / model / fortiOsVersion / uptimeDays — appliance identity and uptime
cpuPercent / memPercent / diskPercent — CPU, memory, and disk usage in percent
memTotalMB / diskTotalMB — total memory and disk capacity
sessionCount — active session count
vpnTunnels plus vpnTunnelsTotal / vpnTunnelsUp / vpnTunnelsDown — per-tunnel status and totals
haMode / haGroup / haNodes / haNodeCount — HA mode, group, and per-node CPU / memory
interfaces plus ifTotal / ifUp / ifDown and ifInErrors / ifOutErrors — interface status and aggregate error counters

Platform support

The check runs on the octoja agent; the agent platform is irrelevant — what matters is reachability to the appliance or cloud.

Agent platform	Supported
Windows	Yes
macOS	Yes
Linux	Yes

Notes

The check runs every 15 minutes on the agent. The interval is not user-configurable.
HTTP timeout per API call is 30 seconds.
The OPNsense flow triggers a fresh firmware-check before reading status, then waits 4 seconds — the OPNsense API serves a cached status until a check is explicitly triggered.
The WatchGuard parser is tolerant of field-name variations across tenants: connectionStatus / status, fireboxVersion / osVersion, featureKeyExpiration / expirationDate, and so on.
Version comparison is lower-case prefix matching (e.g. 12.7 matches 12.7.1). Set Target firmware version to a prefix to allow patch revisions through.
OPNsense and Sophos feature-key / license expiry is currently not surfaced. The license dimension applies to WatchGuard and FortiGate only.
The Sophos XML API requires the credentials in the request body, not headers — octoja escapes user input via the XML serializer before posting.
FortiGate (SNMP) thresholds are normalised so that the warning value is never higher than the critical value — if entered the wrong way round, octoja swaps them.
FortiGate (SNMP) VPN tunnel status is aggregated by tunnel name: a tunnel counts as up when any of its selectors is up.
FortiGate (SNMP) interface collection skips software loopback interfaces. A required interface that is admin-up but operationally down is reported as down.