{
  "markdown": "<!-- mcp-name: io.github.AIops-tools/firewall-aiops -->\n\n# Firewall AIops\n\nGoverned, audited AI-ops for **OPNsense** and **pfSense** firewalls — for AI agents (via MCP) and humans (via CLI).\n\n> **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.\n\nfirewall-aiops speaks to two firewall platforms behind one MCP server — **OPNsense**\n(REST API under `/api/...`, API key+secret via HTTP Basic auth) and **pfSense**\n(REST API v2 under `/api/v2/...` from the pfSense-pkg-RESTAPI package, API key via\nan `X-API-Key` header) — with the **same tools working on both**. Each target in the\nconfig names its own `platform`; a name-keyed platform registry selects the API shape\n(auth + resource paths), so an agent never has to know which firewall it is talking to.\n\nEvery tool runs through a **built-in governance harness** (vendored, zero external\ndependency): audit log, token/call budget with runaway circuit-breaker, descriptive\nrisk-tier labelling, undo-token recording, and prompt-injection sanitisation.\n\n## Why this exists\n\n- **One server, both firewalls** — OPNsense and pfSense in a mixed estate, spoken to\n  through identical tool names. Adding a third firewall later is a new platform\n  descriptor, not a rewrite.\n- **Read the whole firewall** — firmware/health, interfaces & gateways, filter rules\n  (with hit counts and state table), NAT (port-forward / outbound / 1:1), aliases,\n  VPN (WireGuard / OpenVPN / IPsec), DHCP leases & reservations, and the firewall log.\n- **Flagship RCA analyses** — transparent heuristics that show their numbers, never a\n  black-box verdict: `gateway_health_rca` (WAN loss/latency/down → cause + action),\n  `rule_hit_and_shadow_analysis` (never-hit + shadowed/redundant rules), and\n  `blocked_traffic_rca` (top blocked sources/ports → scan / brute-force / probe).\n- **Governed writes** — toggle a rule, add/remove an alias entry (reversible,\n  undo-recorded from the fetched before-state), flush states, restart a service, and\n  the \"make it live\" commit (`apply_changes` / `reconfigure`) and `reboot` at\n  **risk=high** with a dry-run preview. Every write, reversible or not, lands an\n  audit row.\n\n## What this tool does, and does not, decide\n\nIt delivers firewall operations — reads and writes — accurately and efficiently,\nand records every one of them. It does **not** decide whether a write is allowed\nto happen. That is the agent's judgement, or the permission of the account you\nconnect it with: give the OPNsense/pfSense API user a read-only role, and the\nwrites fail at the server — the place that actually owns the permission.\n\nSo there is no read-only switch, no policy file, no approval gate to configure.\nThe one thing the tool guarantees is that nothing is silent: **every call, over\nMCP and over the CLI alike, lands an audit row** in `~/.firewall-aiops/audit.db`,\nand reversible writes still capture their before-state and record an inverse\nwhere one exists.\n\n> Each tool declares a `risk_level`, matched to its `[READ]`/`[WRITE]`\n> documentation tag, and carried into the audit row as a descriptive tier — so a\n> reviewer can see at a glance that a row was a high-risk write. It is a label,\n> not a gate.\n\nRunning a smaller / local model? See\n[agent-guardrails.md](skills/firewall-aiops/references/agent-guardrails.md) — it lists\nthe guardrails this tool now enforces for you (so you don't spend prompt budget\nrestating them) and gives a ready-made system prompt for what's left.\n\n## Tool inventory (35 tools)\n\n| Domain | Tools | # | Kind |\n|--------|-------|:-:|------|\n| **System** | `firmware_status`, `health_status`, `interface_status`, `gateway_status` | 4 | read |\n| **Rules** | `list_rules`, `rule_detail`, `rule_stats`, `rule_states` | 4 | read |\n| **NAT** | `nat_port_forwards`, `nat_outbound`, `nat_one_to_one` | 3 | read |\n| **Aliases** | `list_aliases`, `alias_entries` | 2 | read |\n| **VPN** | `wireguard_status`, `openvpn_sessions`, `ipsec_sas` | 3 | read |\n| **DHCP** | `dhcp_leases`, `dhcp_static_mappings` | 2 | read |\n| **Diagnostics** | `firewall_log`, `states_table`, `top_talkers` | 3 | read |\n| **Flagship analyses** | `gateway_health_rca`, `rule_hit_and_shadow_analysis`, `blocked_traffic_rca` | 3 | read |\n| **Writes** | `toggle_rule`, `add_alias_entry`, `remove_alias_entry`, `kill_states`, `restart_service` | 5 | write (**med**) |\n| **Writes** | `apply_changes`, `reconfigure`, `reboot` | 3 | write (**high**) |\n| **Undo** | `undo_list`, `undo_apply` | 2 | read / write |\n\nReversible writes record an inverse **undo descriptor** built from the real fetched\nbefore-state (`toggle_rule` restores the rule's prior enabled flag; alias add/remove\ninvert). `apply_changes` / `reconfigure` / `reboot` are high-risk with `dry_run`;\n`reboot` is irreversible (audit only).\n\n## Install\n\n```bash\nuv tool install firewall-aiops        # or: pipx install firewall-aiops\n```\n\n## Quick start\n\n### As a Claude Code plugin\n\nOne install gives an agent both the skill and the MCP server:\n\n```\n/plugin marketplace add AIops-tools/marketplace\n/plugin install firewall-aiops@aiops-tools\n```\n\nThe MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the\npackage version this plugin declares, so an audit row can be traced back to the\ncode that wrote it. Credentials are still configured with `firewall-aiops init` — see below.\n\n### As a CLI or standalone MCP server\n\n```bash\nfirewall-aiops init                     # wizard: pick platform (opnsense/pfsense) + store the secret (encrypted)\nfirewall-aiops doctor                   # verify config, secrets, and connectivity\nfirewall-aiops overview                 # one-shot: version + gateway/interface health + rule count\nfirewall-aiops rules list               # list filter rules\nfirewall-aiops rules toggle <uuid> --disable   # dry-run + double-confirm governed write\nfirewall-aiops log --action block -n 50 # recent blocked traffic\n```\n\nRun the MCP server (stdio) for an agent:\n\n```bash\nfirewall-aiops mcp                      # or: firewall-aiops-mcp\n```\n\n### MCP client config\n\n```json\n{\n  \"mcpServers\": {\n    \"firewall-aiops\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"firewall-aiops\", \"firewall-aiops-mcp\"],\n      \"env\": { \"FIREWALL_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n    }\n  }\n}\n```\n\n## Configuration\n\n`~/.firewall-aiops/config.yaml` (non-secret connection details only):\n\n```yaml\ntargets:\n  - name: fw1\n    platform: opnsense       # opnsense | pfsense\n    host: 192.0.2.1\n    port: 443\n    username: <opnsense-api-key>   # OPNsense API key (unused for pfSense)\n    verify_ssl: false        # false for self-signed lab certs\n  - name: edge\n    platform: pfsense\n    host: 192.0.2.2\n    verify_ssl: false\n    scheme: http             # https (default) | http — for a GUI behind a TLS-terminating proxy\n```\n\nThe **secret** — the OPNsense API *secret* (paired with the key for HTTP Basic auth)\nor the pfSense **API key** — is stored **encrypted** in `~/.firewall-aiops/secrets.enc`\n(Fernet + scrypt-derived key), never plaintext on disk. Set it with\n`firewall-aiops secret set <target>` or the `init` wizard. The store is unlocked by a\nmaster password from `FIREWALL_AIOPS_MASTER_PASSWORD` (non-interactive/MCP/CI) or an\ninteractive prompt (CLI on a TTY). A legacy plaintext env var\n`FIREWALL_<TARGET>_SECRET` is honoured as a fallback (migrate with\n`firewall-aiops secret migrate`).\n\n## Governance\n\nEvery MCP tool is wrapped by `@governed_tool`:\n\n- **Audit** — every call is logged to `~/.firewall-aiops/audit.db` (tool, params with\n  secrets redacted, status, duration, risk tier, approver, rationale).\n- **Budget / runaway guard** — per-process token/call caps and a repeat-call circuit\n  breaker (`FIREWALL_MAX_TOOL_CALLS`, `FIREWALL_RUNAWAY_MAX`, …).\n- **Risk-tier labelling** — each tool's declared `risk_level` is recorded on its\n  audit row as a descriptive tier (a label, not a gate); there is no read-only\n  switch, policy file, or approval gate. `FIREWALL_AUDIT_APPROVED_BY` and\n  `FIREWALL_AUDIT_RATIONALE` are optional audit annotations, recorded when set but\n  never required.\n- **Undo recording** — reversible writes record an inverse descriptor to\n  `~/.firewall-aiops/undo.db` from the fetched before-state (recording only; an\n  external orchestrator executes it).\n- **Sanitisation** — all firewall-returned text is bounded + injection-sanitised\n  before it reaches the agent.\n\n## Platform support & verification status\n\n- **Platforms**: OPNsense (REST API) and pfSense (REST API v2, pfSense-pkg-RESTAPI).\n- **Test coverage**: behaviour is validated against mocked OPNsense/pfSense JSON\n  responses — every module imports, every MCP tool carries the governance marker, the\n  RCA heuristics are unit-tested against synthetic telemetry, and reversible writes are\n  asserted to record the correct inverse undo descriptor. The concrete REST paths are\n  modelled from each project's public API and have not yet been exercised against a\n  live firewall. See [docs/VERIFICATION.md](docs/VERIFICATION.md) for the checklist a\n  live run must satisfy; `firewall-aiops doctor` (a firmware/version query on both\n  platforms) is the fastest connectivity check. Both platforms are free and\n  self-hostable (OPNsense is fully open-source; pfSense CE is free), so a home lab is\n  the easiest place to run it.\n- **Missing a capability?** Open an issue or PR at\n  [github.com/AIops-tools/Firewall-AIops](https://github.com/AIops-tools/Firewall-AIops)\n  — contributions and feedback welcome.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 9702,
  "sha": "ce1aa733cc82a6e6ac23fd860578af7c176c88967a1506c88083993312adcc7f",
  "repo_slug": "aiops-tools/firewall-aiops",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiops_tools_firewall_aiops_a9c26bf4/readme"
}