/firewall-auditor

name: firewall-auditor
description: Audit UniFi firewall policies for conflicts, redundancies, security gaps, and best practices. Use when asked to review firewall rules, check for security issues, audit network policies, or optimize firewall configuration.

Firewall Policy Auditor

Dependencies

Requires: network Optional: none

Verify required tools through MCP discovery before collecting data; discovery alone does not prove controller connectivity or authorization. If a required server/tool is missing or a required read fails, stop and report it unavailable. Optional sources may be skipped only when the report visibly names the missing source and resulting coverage limits. Verify Network tool discovery with `unifi_tool_index`; if it is unavailable, stop and use `unifi-network-setup` for connection help. Never request secrets.

Coverage and Limitations

Every report must include a **Coverage and Limitations** section: name each requested source and its status (available, unavailable, partial, or capped), requested time window/timezone or current-state collection time, actual filters, returned counts, limits, pagination, and any failed calls or unknown fields. Counts describe retrieved records, not totals unless completeness is established. A successful empty query is an observation; a failed or missing source is unavailable, never an empty result. If a limit is reached, label the source capped unless further bounded reads establish coverage. If completeness cannot be established, label it partial. Do not claim complete coverage, all-clear, or overall health from unavailable, partial, or capped data; say “No concerning activity found in the retrieved records” when appropriate.

Separate **Observations** (cite source/tool, record ID and timestamp when available), **Hypotheses** (correlations and alternative explanations), and **Identity** (only explicit source-backed credential/account attribution, with its limits). Timing, similar names, proximity, or absence of a matching event alone proves neither identity nor cause. A credential event identifies the recorded account, not who physically used it. Missing mappings or clock uncertainty limit correlations.

You audit the firewall configuration on a UniFi network. Your job is to dispatch the right MCP tool calls, evaluate the results against a documented rubric, score the audit deterministically, and present prioritised findings.

The work is split between you and one tiny CLI:

• **You** gather data via the `unifi-network` MCP tools, evaluate each benchmark, and write findings.
• **`scripts/unifi-firewall-score`** turns those findings into the canonical score. This is the only deterministic boundary — running it on the same findings always produces the same score, which is what makes audit history meaningful.

There is no Python script doing the audit for you. There is no HTTP sidecar. You drive the audit; the CLI does the math.

---

Procedure

1. Gather data in parallel

Dispatch these tool calls in **a single batch** (multiple tool uses in one assistant turn — they are independent and you should not serialise them):

• `unifi_list_firewall_policies`
• `unifi_list_firewall_zones`
• `unifi_list_legacy_firewall_rules`
• `unifi_list_networks`
• `unifi_list_firewall_groups`
• `unifi_list_devices`
• `unifi_get_dpi_stats` *(optional but useful for HYG-05 / EGR-03 context)*

If a required tool returns `success=false`, stop scoring and report the unavailable source in Coverage and Limitations. Optional DPI failure limits only the affected benchmarks. Do not turn missing evidence into a passing benchmark.

For richer per-policy detail (needed by HYG-02 conflict detection and HYG-05 shadowing), follow up with `unifi_get_firewall_policy_details` for each policy returned by `unifi_list_firewall_policies`. Batch these calls in parallel as well.

1a. Determine which firewall engine the site runs

**Do this before evaluating any benchmark.** UniFi has two firewall engines and a site runs exactly one:

| Signal | Engine | |---|---| | `unifi_list_firewall_policies` and `unifi_list_firewall_zones` return entries | **zone-based** (V2, UniFi Network 9.0+ after migration) | | Both return zero entries and `unifi_list_legacy_firewall_rules` returns entries | **legacy** (pre-zone-based) | | All three return zero entries | **indeterminate** — see below |

The zone-based tools do not error on a legacy site. They return empty, which is indistinguishable from "no firewall rules configured" unless you check the legacy tool too. Both list tools also return a `note` field when the controller reports nothing; treat its presence as a prompt to check the legacy engine, not as a finding in itself.

Record the detected engine and state it in the report header, so a reader knows which ruleset was actually examined.

**Never score segmentation from an engine you did not read.** If the site is legacy, evaluate SEG-01 through SEG-04 against the legacy rules, not against the empty zone-based result. Reporting "no VLAN segmentation enforced" because the zone-based endpoints were empty is a false critical — it is the specific failure this step exists to prevent.

If the engine is **indeterminate** (all three empty), do not emit segmentation criticals. Emit a single `info` finding stating that no firewall configuration could be retrieved and that segmentation could not be assessed, and continue with the non-segmentation benchmarks as partial coverage. Withhold the overall score/status and history entry when any benchmark cannot be assessed; report only supported findings. An audit that cannot see the rules must say so rather than score them as absent.

2. Evaluate the 16 benchmarks

Walk through each benchmark in `references/security-benchmarks.md` in order: **SEG-01 → SEG-04, EGR-01 → EGR-03, HYG-01 → HYG-05, TOP-01 → TOP-04**. For each benchmark, the reference document specifies:

• The exact condition to verify
• Which tool output to read
• The d