The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Firewall AIops listing page.
Governed, audited AI-ops for OPNsense and pfSense firewalls — for AI agents (via MCP) and humans (via CLI).
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. MIT licensed.
firewall-aiops speaks to two firewall platforms behind one MCP server — OPNsense
(REST API under /api/..., API key+secret via HTTP Basic auth) and pfSense
(REST API v2 under /api/v2/... from the pfSense-pkg-RESTAPI package, API key via
an X-API-Key header) — with the same tools working on both. Each target in the
config names its own platform; a name-keyed platform registry selects the API shape
(auth + resource paths), so an agent never has to know which firewall it is talking to.
Every tool runs through a built-in governance harness (vendored, zero external dependency): audit log, token/call budget with runaway circuit-breaker, descriptive risk-tier labelling, undo-token recording, and prompt-injection sanitisation.
gateway_health_rca (WAN loss/latency/down → cause + action),
rule_hit_and_shadow_analysis (never-hit + shadowed/redundant rules), and
blocked_traffic_rca (top blocked sources/ports → scan / brute-force / probe).apply_changes / reconfigure) and reboot at
risk=high with a dry-run preview. Every write, reversible or not, lands an
audit row.It delivers firewall operations — reads and writes — accurately and efficiently, and records every one of them. It does not decide whether a write is allowed to happen. That is the agent's judgement, or the permission of the account you connect it with: give the OPNsense/pfSense API user a read-only role, and the writes fail at the server — the place that actually owns the permission.
So there is no read-only switch, no policy file, no approval gate to configure.
The one thing the tool guarantees is that nothing is silent: every call, over
MCP and over the CLI alike, lands an audit row in ~/.firewall-aiops/audit.db,
and reversible writes still capture their before-state and record an inverse
where one exists.
Each tool declares a
risk_level, matched to its[READ]/[WRITE]documentation tag, and carried into the audit row as a descriptive tier — so a reviewer can see at a glance that a row was a high-risk write. It is a label, not a gate.
Running a smaller / local model? See agent-guardrails.md — it lists the guardrails this tool now enforces for you (so you don't spend prompt budget restating them) and gives a ready-made system prompt for what's left.
| Domain | Tools | # | Kind |
|---|---|---|---|
| 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) |
| Undo | undo_list, undo_apply | 2 | read / write |
Reversible writes record an inverse undo descriptor built from the real fetched
before-state (toggle_rule restores the rule's prior enabled flag; alias add/remove
invert). apply_changes / reconfigure / reboot are high-risk with dry_run;
reboot is irreversible (audit only).
One install gives an agent both the skill and the MCP server:
The MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with firewall-aiops init — see below.
The same bundle is published on ClawHub, where one install delivers the skill and its MCP server together:
Restart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is
fetched with uv, pinned to this exact release, so
uvx has to be on PATH — without it the skill still installs but reports
Visible to model: no. Credentials are configured exactly as below.
Run the MCP server (stdio) for an agent:
~/.firewall-aiops/config.yaml (non-secret connection details only):
The secret — the OPNsense API secret (paired with the key for HTTP Basic auth)
or the pfSense API key — is stored encrypted in ~/.firewall-aiops/secrets.enc
(Fernet + scrypt-derived key), never plaintext on disk. Set it with
firewall-aiops secret set <target> or the init wizard. The store is unlocked by a
master password from FIREWALL_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an
interactive prompt (CLI on a TTY). A legacy plaintext env var
FIREWALL_<TARGET>_SECRET is honoured as a fallback (migrate with
firewall-aiops secret migrate).
Every MCP tool is wrapped by @governed_tool:
~/.firewall-aiops/audit.db (tool, params with
secrets redacted, status, duration, risk tier, approver, rationale).FIREWALL_MAX_TOOL_CALLS, FIREWALL_RUNAWAY_MAX, …).risk_level is recorded on its
audit row as a descriptive tier (a label, not a gate); there is no read-only
switch, policy file, or approval gate. FIREWALL_AUDIT_APPROVED_BY and
FIREWALL_AUDIT_RATIONALE are optional audit annotations, recorded when set but
never required.~/.firewall-aiops/undo.db from the fetched before-state (recording only; an
external orchestrator executes it).firewall-aiops doctor (a firmware/version query on both
platforms) is the fastest connectivity check. Both platforms are free and
self-hostable (OPNsense is fully open-source; pfSense CE is free), so a home lab is
the easiest place to run it.MIT — see LICENSE.