Firewall AIops MCP server

<!-- mcp-name: io.github.AIops-tools/firewall-aiops -->

Firewall AIops

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.

Why this exists

through identical tool names. Adding a third firewall later is a new platform descriptor, not a rewrite.

• One server, both firewalls — OPNsense and pfSense in a mixed estate, spoken to

(with hit counts and state table), NAT (port-forward / outbound / 1:1), aliases, VPN (WireGuard / OpenVPN / IPsec), DHCP leases & reservations, and the firewall log.

• Read the whole firewall — firmware/health, interfaces & gateways, filter rules

black-box verdict: gatewayhealthrca (WAN loss/latency/down → cause + action), rulehitandshadowanalysis (never-hit + shadowed/redundant rules), and blockedtrafficrca (top blocked sources/ports → scan / brute-force / probe).

• Flagship RCA analyses — transparent heuristics that show their numbers, never a

undo-recorded from the fetched before-state), flush states, restart a service, and the "make it live" commit (applychanges / reconfigure) and reboot at risk=high** with a dry-run preview. Every write, reversible or not, lands an audit row.

• Governed writes — toggle a rule, add/remove an alias entry (reversible,

What this tool does, and does not, decide

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.

Tool inventory (35 tools)

Shortened. The full README is on GitHub.