/firewall-manager

name: firewall-manager
description: Manage UniFi firewall policies using natural language — create, modify, and review firewall rules, content filters, and traffic policies. Use when asked to block traffic, create firewall rules, manage content filtering, set up time-based access controls, or review firewall configuration.

Firewall Manager

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 manage firewall policies on a UniFi network. Translate the user's intent into the right MCP tool calls, always preview before executing, and snapshot state around every mutation as a manual reconstruction reference.

There are no helper scripts in this skill — only references and tools. You drive the workflow:

• The MCP server provides tools to read, create, update, and toggle policies.
• `references/firewall-schema.md` is the V2 schema reference.
• `references/policy-templates.yaml` is a small library of common-scenario payloads you read directly.
• `references/dpi-categories.md` maps app names to DPI category groups.

---

1. Setup check

Before doing anything else:

• Discover tools and check required read responses; server credentials may be supplied outside the agent's environment. Stop if required reads fail.
• Verify the server responds by calling `unifi_tool_index`.

---

2. Snapshot before every mutation

You **always** snapshot the current firewall state before any create / update / delete. The snapshot is your rollback reference and the input to the post-change diff.

Gather state via three parallel tool calls:

• `unifi_list_firewall_policies`
• `unifi_list_firewall_zones`
• `unifi_list_firewall_groups`

Combine the results into one JSON document and write it to disk:

STATE_DIR="${UNIFI_SKILLS_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/unifi-mcp/skills}/firewall-snapshots"
mkdir -p "$STATE_DIR"
SNAPSHOT="$STATE_DIR/firewall_$(date -u +%Y%m%dT%H%M%SZ).json"
# Write the combined JSON ($SNAPSHOT_JSON below is what you composed from the three tool results):
printf '%s\n' "$SNAPSHOT_JSON" > "$SNAPSHOT"
echo "Snapshot saved to $SNAPSHOT"

Tell the user the snapshot path. They may want it for manual restore if something goes wrong.

---

3. Use templates when one fits

Read `references/policy-templates.yaml` directly — do not invent new templates. The file lists every template's `params`, `tool`, `payload`, and `notes`. Walk the user's request against the template list:

| Template | Use when | |----------|----------| | `iot-isolation` | "block IoT from reaching the LAN" / "isolate smart devices" | | `guest-lockdown` | "lock down guest WiFi to internet only" | | `kids-content-filter` | "block apps after bedtime" / time-based filtering | | `block-bittorrent` | "block torrents / P2P" | | `work-vpn-split-tunnel` | "VPN but keep printer access" | | `camera-isolation` | "lock cameras to NVR only" |

To apply a template:

1. Read `policy-templates.yaml` and locate the matching entry. 2. Resolve every `params` value:

• Zone IDs come from `unifi_list_firewall_zones`.
• Network IDs come from `unifi_list_networks`.
• Confirm any free-form parameter (times, days, network names) with the user.

3. Substitute the params into the template's `payload` block. Substitution is literal: `"{iot_zone_id}"` → `"<actual ID>"`. 4. Call the template's `tool` with the resolved payload — first **without** `confirm=true` to get the preview. 5. Show the preview to the user, get explicit confirmation, then call again with `confirm=true`.

Do not skip the preview step even when the template is well-known. Templates are starting points, not blanket approval.

---

4. Custom rules (when no template fits)

Consult `references/firewall-schema.md` before constructing any V2 payload. It is the authoritative reference for:

• Zones, actions (`ALLOW` / `BLOCK` / `REJECT`)
• `matching_target` / `matching_target_type` combinations
• Port matching, protocols, connection states
• Schedule format

For app-aware rules (TikTok, YouTube, Steam, BitTorrent, etc.), consult `references/dpi-categories.md` to identify the category group, then call `unifi_get_dpi_s