[READ] All firewall aliases (name, type, description, member count).

Args: target: Firewall target name from config; omit for the default.

[READ] The member entries (hosts/networks/ports) of one alias.

Args: name: Alias name (from list_aliases). target: Firewall target name from config; omit for the default.

[READ] Rank gateways by loss + latency, map each down/degraded one to cause + action.

The flagship WAN RCA: pulls gateway status, flags each gateway that is down (status down/offline or 100% loss) or degraded (loss/latency over threshold), ranks worst-first, and attaches a likely cause and a recommended action. Every ranking carries its numbers, not a black-box verdict. Pass 'gateways' for pure analysis, or a target to pull live.

Args: loss_pct: Loss %% at/above which a gateway is degraded (default 5.0). latency_ms: RTT ms at/above which a gateway is degraded (default 150). gateways: Injected rows {name, address, status, lossPercent, rttMs}; skips the live pull. target: Firewall target name from config; omit for the default.

Returns dict: {gatewaysEvaluated, downCount, degradedCount, thresholds, worst:[{name, address, status, lossPercent, rttMs, down, degraded, cause, action}], note}.

[READ] Flag never-hit enabled rules and shadowed/redundant rules.

Finds enabled rules with zero evaluations (dead or misordered), rules fully covered by an earlier terminating rule (shadowed), and rules identical to an earlier one (redundant). Rules are compared in list order, top-down, exactly as pf evaluates them; every finding names the offending/covering rule uuid. Pass 'rules' for pure analysis, or a target to pull live.

Args: rules: Injected rows {uuid, sequence, enabled, action, interface, protocol, source, destination, destinationPort, evaluations}. interface: Optional interface filter when pulling live. target: Firewall target name from config; omit for the default.

Returns dict: {rulesEvaluated, unusedCount, shadowedCount, redundantCount, unusedRules, shadowedRules, redundantRules, note}.

[READ] Rank the noisiest blocked sources and classify cause + action.

Keeps only blocked firewall-log entries, aggregates by source (hit count, distinct destination ports, busiest port), ranks the noisiest sources, and classifies each as a port scan, a service probe/brute-force on a sensitive port, or generic — with a recommended action. Every entry carries its numbers. Pass 'log_entries' for pure analysis, or a target to pull live.

Args: top: How many source rows to return, noisiest first (default 20). limit: How many recent log rows to pull when live (default 500). log_entries: Injected rows {action, source, destination, destinationPort, protocol}; skips the live pull. target: Firewall target name from config; omit for the default.

Returns dict: {blocksEvaluated, distinctSources, topSources:[{source, hits, distinctPorts, topPort, topPortHits, cause, action}], note}.

[READ] Active DHCP leases (IP, MAC, hostname, state).

Args: online_only: If True, return only leases marked online. target: Firewall target name from config; omit for the default.

[READ] DHCP static (reserved) mappings (MAC ↔ IP).

Args: target: Firewall target name from config; omit for the default.

[READ] Recent firewall-log entries, optionally filtered to pass/block.

Args: action: Optional filter — one of pass, block, reject, rdr, nat. limit: Max entries to return (default 200). target: Firewall target name from config; omit for the default.

Returns an envelope: {"entries": [...], "returned": N, "limit": L, "truncated": bool}. When "truncated" is true there are more entries than were returned — re-run with a higher limit rather than treating the result as the complete log.

[READ] Active pf state-table entries (connections currently tracked).

Args: top: How many state entries to return (default 100). target: Firewall target name from config; omit for the default.

Returns an envelope: {"states": [...], "returned": N, "limit": L, "truncated": bool, "total": T}. "truncated" is true when the state table holds more entries than were returned.

[READ] Busiest source hosts, aggregated from the state table by bytes.

Args: top: How many talkers to return (default 20). target: Firewall target name from config; omit for the default.

Returns an envelope: {"topTalkers": [...], "returned": N, "limit": L, "truncated": bool, "total": T}. "truncated" is true when more distinct sources were seen than were returned.

[READ] Inbound port-forward (DNAT) rules, normalized.

Args: target: Firewall target name from config; omit for the default.

[READ] Outbound (source) NAT mappings, normalized.

Args: target: Firewall target name from config; omit for the default.

[READ] 1:1 NAT mappings (external ↔ internal), normalized.

Args: target: Firewall target name from config; omit for the default.

[READ] List filter rules (optionally on one interface), normalized.

Args: interface: Optional interface name to filter by (e.g. wan, lan). target: Firewall target name from config; omit for the default.

[READ] One rule's full detail by uuid/id.

Args: uuid: Rule uuid (OPNsense) or id (pfSense), from list_rules. target: Firewall target name from config; omit for the default.

[READ] Per-rule hit counts / evaluations, busiest first (top-N).

Args: top: How many rules to return, busiest first (default 20). target: Firewall target name from config; omit for the default.

[READ] Active pf state-table entries associated with rules (top-N).

Args: top: How many state entries to return (default 50). target: Firewall target name from config; omit for the default.

[READ] The staged rule set apply_changes would commit, with lockout risk.

Run this BEFORE apply_changes. It reports whether committing the staged rules would cut the endpoint this tool manages the firewall through — a disabled 'pass' rule that permits management access, or an enabled 'block' rule that covers it. Findings are ranked worst-first and carry a certain flag: certain ones make apply_changes refuse, uncertain ones (alias destinations, 'any', interface groups) are warnings only and never block.

basis states what this is: the staged rule STATE, not a diff against the running config — neither platform exposes a per-rule dirty flag over REST.

Args: target: Firewall target name from config; omit for the default.

[READ] Firmware / OS version and whether updates are available.

Args: target: Firewall target name from config; omit for the default.

[READ] System health snapshot: hostname, uptime, CPU, memory, load.

Args: target: Firewall target name from config; omit for the default.

[READ] Interfaces with link status + address, down interfaces first.

Args: target: Firewall target name from config; omit for the default.

[READ] WAN/LAN gateways with status, loss %, and RTT latency.

Args: target: Firewall target name from config; omit for the default.

[READ] List recorded, not-yet-applied undo tokens (most recent first).

Each entry names the original tool, the inverse tool that undo_apply would run, and a human note. Use the undoId with undo_apply.

Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra row is fetched), not guessed from a length coincidence: when it is true there are MORE tokens than shown, so re-run with a higher limit rather than reporting the list as complete.

Each entry carries effectVerified. False means the original write lost its response, so the change it reverses is PROBABLE, not confirmed — check the live state before applying, and do not report the result as a restore of a state that may never have been reached.

Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.

[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.

The inverse runs through its own governed tool, so it is audited and labelled with its own risk tier there. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.

Args: undo_id: The undoId from undo_list (or an _undo_id in a write result). dry_run: If True, preview the inverse tool + params without running it. target: Passed through to the inverse tool when it accepts a target.

[READ] WireGuard peers with connected state, last handshake, transfer.

Args: target: Firewall target name from config; omit for the default.

[READ] OpenVPN sessions / connected clients (name, address, bytes).

Args: target: Firewall target name from config; omit for the default.

[READ] IPsec security associations (phase-1/phase-2) with state.

Args: target: Firewall target name from config; omit for the default.

[WRITE][risk=medium] Enable/disable a filter rule; reversible.

Reads the rule first so the harness records an undo that restores its prior enabled state. Staged only — run apply_changes to make it live. Pass dry_run=True to preview.

Args: uuid: Rule uuid (OPNsense) or id (pfSense), from list_rules. enable: True to enable the rule, False to disable. dry_run: If True, preview without changing. target: Firewall target name from config; omit for the default.

[WRITE][risk=medium] Add one entry to an alias; reversible (undo removes it).

Captures the alias' prior entries before the change. Pass dry_run=True to preview.

Args: name: Alias name (from list_aliases). entry: The host/network/port to add. dry_run: If True, preview without changing. target: Firewall target name from config; omit for the default.

[WRITE][risk=medium] Remove one entry from an alias; reversible (undo adds it back).

Captures the alias' prior entries before the change. Pass dry_run=True to preview.

Args: name: Alias name (from list_aliases). entry: The host/network/port to remove. dry_run: If True, preview without changing. target: Firewall target name from config; omit for the default.

[WRITE][risk=high] Commit staged firewall config — makes edits live.

This is the "make it live" step after staged edits (e.g. toggle_rule).

Reads the staged rule set first and REFUSES when committing it would provably cut the endpoint this tool manages the firewall through — disabling the 'pass' rule that permits management access, or enabling a 'block' rule that covers it, locks out this tool and the undo that would reverse it. Uncertain cases (alias destinations, 'any', interface groups) warn and proceed.

dry_run=True returns the full staged change set and its assessment, not just an acknowledgement — use it before every apply.

Args: dry_run: If True, return the staged change set + lockout assessment without applying. override: Proceed despite a certain lockout finding. Only for operators with console / out-of-band access who mean it. target: Firewall target name from config; omit for the default.

[WRITE][risk=high] Reload/commit a subsystem's config (filter/nat/aliases).

Reloading the 'filter' subsystem commits the staged rule set just as apply_changes does, so it carries the same lockout guard and the same override.

Args: subsystem: Config subsystem to reload (filter, nat, aliases). dry_run: If True, preview without reconfiguring. override: Proceed despite a certain lockout finding (filter subsystem). target: Firewall target name from config; omit for the default.

[WRITE][risk=medium] Flush pf state-table entries (optionally one source IP).

Drops tracked connections; they re-establish on the next packet. This includes THIS tool's own connection state, so the call may appear to fail even though the flush ran — that is a lost response, not a lockout, and a blind retry is the wrong reaction. Access is not lost: the permitting rule is untouched. Pass dry_run=True to preview.

Args: filter_ip: Optional source IP to scope the flush to (blank = all states). dry_run: If True, preview without flushing. target: Firewall target name from config; omit for the default.

[WRITE][risk=medium] Restart a firewall service (unbound, dhcpd, openvpn, ...).

REFUSES the service that answers this appliance's own management API (nginx / lighttpd / configd / webgui and friends): restarting it kills the connection this tool is using, so the restart cannot be observed and the undo cannot run. Restart those from the console instead. Pass dry_run=True to preview.

Args: service: Service name to restart. dry_run: If True, preview without restarting. target: Firewall target name from config; omit for the default.

[WRITE][risk=high] Reboot the firewall. IRREVERSIBLE — audit only, no undo.

Pass dry_run=True to preview.

Args: dry_run: If True, preview without rebooting. target: Firewall target name from config; omit for the default.