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:

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.

1. Substitute the params into the template's payload block. Substitution is literal: "{iot_zone_id}" → "<actual ID>".
2. Call the template's tool with the resolved payload — first without confirm=true to get the preview.
3. 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_stats to confirm the exact category ID on this controller before building the rule.

Tool selection:

• unifi_create_firewall_policy — V2 zone-based create. Wraps the payload in policy_data. Pre-resolve zone IDs (unifi_list_firewall_zones) and network IDs (unifi_list_networks) before constructing it.
• unifi_update_firewall_policy — partial update via fetch-merge-put. Pass only the fields you want to change in update_data (e.g., {"enabled": true}). This is the canonical way to enable/disable a policy because it preserves all other fields.
• unifi_toggle_firewall_policy — convenience wrapper for flipping enabled. Prefer unifi_update_firewall_policy with update_data={"enabled": …} — it's the canonical fetch-merge-put path and produces the same result with no special casing.
• unifi_get_firewall_policy_ordering — read the user-defined policy ordering for a source/destination zone pair. Use this when rule placement matters; do not infer editable order from index.
• unifi_reorder_firewall_policies — reorder user-defined policies for a source/destination zone pair. Pass the complete orderedFirewallPolicyIds object from the read response as ordered_firewall_policy_ids, with only the intended movement applied. These IDs belong to the Integration API ordering family; do not substitute V2 policy IDs. Read the ordering tool schema before calling. Preview first, then confirm.

Policy ordering uses UniFi's official integration API and requires an API key (UNIFI_API_KEY or UNIFI_NETWORK_API_KEY). Local username/password controller sessions can read policies and zones, but they cannot call the ordering endpoint. The ordering endpoint uses integration API zone UUIDs internally. The local MCP manager accepts the normal unifi_list_firewall_zones IDs and translates them by zone name before calling the ordering endpoint.

5. Verify after every mutation

Take a fresh snapshot using the same procedure as Step 2, then compare to the pre-change snapshot:

diff -u "$BEFORE" "$AFTER" | head -200

For a structural (key-aware) diff that ignores ordering, fall back to:

python3 - "$BEFORE" "$AFTER" <<'PY'
import json, sys
a, b = (json.load(open(p)) for p in sys.argv[1:])
def keyed(items):
    # list output uses 'id', detail output uses '_id' — accept either
    out = {}
    for i, x in enumerate(items):
        k = x.get('id') or x.get('_id') or f'__idx_{i}'
        out[k] = x
    return out
ap, bp = keyed(a.get('policies', [])), keyed(b.get('policies', []))
added   = [bp[k] for k in bp.keys() - ap.keys()]
removed = [ap[k] for k in ap.keys() - bp.keys()]
changed = [(ap[k], bp[k]) for k in ap.keys() & bp.keys() if ap[k] != bp[k]]
print(json.dumps({'added': added, 'removed': removed, 'changed': changed}, indent=2))
PY

Read the diff. If it does not match the change you intended (e.g., extra unintended modifications, wrong field touched), stop and report to the user. Do not proceed with further mutations until the unexpected change is understood.

6. Safety rules

1. Always preview first. Every mutating tool returns a preview when called without confirm=true. Show the preview verbatim before executing.
2. Never auto-confirm. Wait for explicit user approval before calling with confirm=true. "Sounds good, do it" counts. Silence does not.
3. Snapshot before, diff after. No exceptions. The snapshot path is the rollback reference.
4. Check policy gates on permission errors. If a mutation fails with a permission error, surface the relevant env var:

• Create: UNIFI_POLICY_NETWORK_FIREWALL_POLICIES_CREATE=true
• Update: UNIFI_POLICY_NETWORK_FIREWALL_POLICIES_UPDATE=true
• Delete: UNIFI_POLICY_NETWORK_FIREWALL_POLICIES_DELETE=true (off by default)

1. Understand impact before acting. Call unifi_list_firewall_policies before creating new rules to detect conflicts and redundancy.
2. One change at a time. When the user asks for several changes, do them sequentially with snapshot/preview/confirm/diff per change. Batching mutations makes rollback impossible.

7. Common scenarios

"Block [app/service] on [network/VLAN]"

1. Snapshot (Step 2).
2. Identify the DPI category from references/dpi-categories.md, then confirm the ID with unifi_get_dpi_stats.
3. If a template matches (e.g., block-bittorrent), use it (Step 3).
4. Otherwise: gather zone + network IDs, build a V2 payload with action="REJECT" per references/firewall-schema.md.
5. Preview → confirm → execute.
6. Diff (Step 5).

"Block [app] after [time] on [days]"

1. Snapshot.
2. If kids-content-filter applies, use it with block_days, block_start, block_end.
3. Otherwise: consult the schedule format in references/firewall-schema.md and build the rule.
4. Preview → confirm → diff.

"Show me all rules affecting [network/VLAN]"

1. unifi_list_firewall_policies.
2. Filter to policies whose source or destination references the target network or its zone.
3. Present as a table: name, action, source → destination, enabled, ruleset.

No mutation, no snapshot needed.

"Are there any conflicting or redundant rules?"

1. unifi_list_firewall_policies.
2. For deeper analysis, also fetch per-policy details via unifi_get_firewall_policy_details.
3. Look for: same source/destination but different actions (conflict), strict subsets with the same action (redundant), disabled rules duplicating enabled ones (clutter), broad ALLOW rules indexed before specific REJECT rules (shadowing).
4. Report findings with prioritised recommendations. Hand off to the firewall-auditor skill for a scored audit.

"Set up IoT isolation / guest lockdown / camera isolation"

1. Snapshot.
2. Locate the matching template in policy-templates.yaml.
3. Resolve params (zone IDs from unifi_list_firewall_zones, network IDs from unifi_list_networks).
4. Apply (Step 3).
5. Diff.

"Clean up / optimize firewall rules"

1. unifi_list_firewall_policies.
2. Snapshot.
3. Identify quick wins: disabled duplicates → delete (if delete policy gate is on), shadowed rules → re-order, stale references → remove.
4. Propose changes one at a time with previews.
5. Diff after each change.

For a comprehensive scored audit, use the firewall-auditor skill instead.

8. Manual fallback

When you cannot reach the MCP server (network issue, server crash), there is no fallback that mutates the controller — there's nothing to mutate against. Tell the user the server is unreachable and direct them to the unifi-network-setup skill for diagnosis.

The "manual procedure" sections of older versions of this skill assumed a separate HTTP transport that no longer exists. Removed for simplicity.

9. Tips

• unifi_create_firewall_policy is the canonical create tool. Pre-resolve zone IDs and network IDs before constructing the V2 payload.
• index is controller-assigned on zone-based policies. Do not try to move policies by updating index; use the dedicated ordering tools.
• Users say "block" loosely — clarify whether they want REJECT (sends RST/ICMP unreachable, faster client failure) or BLOCK (silent discard, less informative to the client). REJECT is usually right for internal traffic, BLOCK for external-facing rules. The action comparison table is in references/firewall-schema.md.
• DPI rules are bypassable by VPNs. When blocking social media or gaming, also consider blocking the VPN/Proxy DPI category. See references/dpi-categories.md.
• Rule order matters for camera-isolation and other multi-rule templates. Confirm ordering with unifi_list_firewall_policies after creation.
• A snapshot is just a JSON file. If a change goes wrong, the user can reconstruct the prior state by hand from the snapshot — share the path.