Firewall Aiops

Use this skill whenever the user needs to operate an OPNsense or pfSense firewall — a one-shot overview, firmware/health, interfaces and gateways, firewall rules with hit-counts and shadow analysis, NAT (port-forward/outbound/1:1), aliases and their entries, VPN (WireGuard/OpenVPN/IPsec), DHCP leases and static mappings, the firewall log and state table, three flagship RCAs (gateway health, rule hit/shadow, blocked traffic), and governed writes (toggle a rule, add/remove an alias entry, kill states, restart a service, apply/reconfigure to make edits live, reboot). Always use this skill for "OPNsense", "pfSense", "firewall rule", "port forward", "NAT", "alias", "WireGuard", "OpenVPN", "IPsec", "DHCP lease", "firewall log", "blocked traffic", "why is my WAN down", "gateway loss/latency", "unused / shadowed rules", "apply firewall changes", "reboot the firewall" when the context is an OPNsense/pfSense firewall. Do NOT use when the target is something other than an OPNsense/pfSense firewall (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Cloud security groups and vendor firewall appliances are out of scope. Preview — governed firewall operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Mock-validated only, not run against a live firewall; both OPNsense and pfSense are free/self-hostable, so a home lab is the easiest live check.

Firewall AIops (preview)

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by the OPNsense project, Deciso, Netgate, or the pfSense project. OPNsense, pfSense and Netgate are trademarks of their respective owners. Source at github.com/AIops-tools/Firewall-AIops under the MIT license.

Governed firewall operations — 32 MCP tools across OPNsense (REST /api/...) and pfSense (REST v2 /api/v2/...), every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.firewall-aiops/, policy engine, token/runaway budget guard, undo-token recording, and graduated-autonomy risk tiers. A per-target platform field selects the API shape, so the same tools work on both firewalls and one config can span a mixed estate. The OPNsense API secret / pfSense API key is stored encrypted (~/.firewall-aiops/secrets.enc, Fernet + scrypt) — never plaintext on disk.

Standalone: the governance harness is bundled in the package (firewall_aiops.governance) — no external skill-family dependency. Preview / mock-only: not run against a live firewall; both platforms are free/self-hostable, so a home lab is the easiest live check.

What This Skill Does

Group	Tools	Count	R/W
System	firmware_status, health_status, interface_status, gateway_status	4	read
Rules	list_rules, rule_detail, rule_stats, rule_states	4	read
NAT	nat_port_forwards, nat_outbound, nat_one_to_one	3	read
Aliases	list_aliases, alias_entries	2	read
VPN	wireguard_status, openvpn_sessions, ipsec_sas	3	read
DHCP	dhcp_leases, dhcp_static_mappings	2	read
Diagnostics	firewall_log, states_table, top_talkers	3	read
Flagship analyses	gateway_health_rca, rule_hit_and_shadow_analysis, blocked_traffic_rca	3	read
Writes	toggle_rule, add_alias_entry, remove_alias_entry, kill_states, restart_service	5	write (med)
Writes	apply_changes, reconfigure, reboot	3	write (high)

The three flagship analyses are transparent heuristics that report their numbers, never a black-box verdict: gateway_health_rca ranks gateways by loss + latency and maps each down/degraded one to a cause + action; rule_hit_and_shadow_analysis finds never-hit and shadowed/redundant rules; blocked_traffic_rca classifies the noisiest blocked sources as scan / brute-force / probe.

Quick Install

bash

uv tool install firewall-aiops
firewall-aiops init       # wizard: pick platform (opnsense/pfsense) + encrypted secret
firewall-aiops doctor

When to Use This Skill

• Get a one-shot snapshot (overview / firmware_status / gateway_status)
• Investigate a down/degraded WAN (gateway_health_rca) → cause + action
• Audit the ruleset (rule_stats hit counts, rule_hit_and_shadow_analysis for never-hit / shadowed / redundant rules)
• Triage hostile traffic (firewall_log --action block, blocked_traffic_rca, top_talkers)
• Inspect NAT, aliases, VPN tunnels (WireGuard/OpenVPN/IPsec), and DHCP leases
• Safely toggle a rule or edit an alias (toggle_rule / add_alias_entry / remove_alias_entry, reversible + undo-recorded), then make it live with apply_changes (dry-run + approver)

Do NOT use when the target is not an OPNsense/pfSense firewall — route hypervisor, storage, backup, cluster, multi-vendor router/switch config, or OT/industrial work to the appropriate other AIops-tools skill.

Related Skills — Skill Routing

If the user wants…	Use
OPNsense / pfSense firewall ops	firewall-aiops (this skill)
A non-firewall platform (hypervisor, storage, backup, cluster, network config, OT edge)	the appropriate other AIops-tools skill
Cloud security groups / vendor firewall appliances	out of scope for this tool

Common Workflows

WAN is down / flaky

1. gateway_status → see which gateways report loss/latency/down
2. gateway_health_rca → ranked worst-first with a likely cause + recommended action (last-mile loss, congestion, latency, or a hard down)

Clean up the ruleset

1. rule_stats → busiest rules by hit count/evaluations
2. rule_hit_and_shadow_analysis → enabled rules with 0 evaluations (dead/misordered), rules shadowed by an earlier terminating rule, and exact duplicates — each names the offending/covering rule uuid

Triage blocked traffic

1. firewall_log --action block (or firewall_log(action="block"))
2. blocked_traffic_rca → noisiest sources ranked, each classified (port scan, service brute-force on 22/3389/…, or generic) with an action; cross-reference top_talkers

Toggle a rule and make it live (reversible)

1. list_rules → find the rule uuid/id
2. toggle_rule <uuid> --disable --dry-run → preview
3. Re-run without --dry-run (double-confirm) — it captures the rule's prior enabled state and records an inverse undo descriptor
4. apply_changes (risk=high; set FIREWALL_AUDIT_APPROVED_BY +

• Secure by default (v0.2.0+): with no ~/.firewall-aiops/rules.yaml, high/critical operations are denied unless FIREWALL_AUDIT_APPROVED_BY names an approver (set FIREWALL_AUDIT_RATIONALE too). firewall-aiops init seeds a starter rules.yaml; an operator-authored rules file is honoured as-is. FIREWALL_AUDIT_RATIONALE) to commit staged config

Governance & Safety

• Every tool is audited to ~/.firewall-aiops/audit.db (relocatable via FIREWALL_AIOPS_HOME).
• High-risk ops (apply_changes, reconfigure, reboot) can require a named approver: set FIREWALL_AUDIT_APPROVED_BY and FIREWALL_AUDIT_RATIONALE.
• Writes support --dry-run and double confirmation at the CLI. reboot is irreversible (audit only).
• Reversible writes capture the real fetched before-state and record an inverse descriptor (toggle→toggle-back, add-alias↔remove-alias).

References

• references/capabilities.md — full tool + platform + API-path reference
• references/cli-reference.md — CLI command reference
• references/setup-guide.md — onboarding, credentials, and connectivity