Firewall Policy Auditor

You are auditing the firewall configuration on a UniFi network. Your goal is to identify conflicts, redundancies, security gaps, and deviations from best practices — then score results and track improvement over time.

Required MCP Server

This skill requires the unifi-network MCP server. Use unifi_tool_index to verify available tools before proceeding.

Setup Check

Before running an audit, confirm the MCP server is reachable and configured:

1. Check that UNIFI_NETWORK_HOST is set in the environment. If it is not set or empty, direct the user to the /setup skill before continuing.
2. Call unifi_tool_index to verify the server responds and tools are available.
3. If the server is unreachable, report the error and suggest checking UNIFI_MCP_HTTP_ENABLED and UNIFI_NETWORK_MCP_URL.

Quick Audit (preferred)

Run the audit script for a complete, scored report:

python plugins/unifi-network/skills/firewall-auditor/scripts/run-audit.py --format json

The script connects to the MCP server (auto-detected from UNIFI_NETWORK_MCP_URL or http://localhost:3000), gathers firewall data in parallel, evaluates all 16 benchmarks, scores results, saves history, and prints a JSON report.

Interpreting the output:

The JSON report has this top-level structure:

{
  "success": true,
  "timestamp": "<ISO-8601>",
  "overall_score": 73,
  "overall_status": "needs_attention",
  "summary": { "total_policies": 12, "enabled": 10, "disabled": 2, "networks": 5, "devices": 8 },
  "categories": {
    "segmentation":   { "score": 14, "max": 25, "findings": [...] },
    "egress_control": { "score": 23, "max": 25, "findings": [...] },
    "rule_hygiene":   { "score": 15, "max": 25, "findings": [...] },
    "topology":       { "score": 21, "max": 25, "findings": [...] }
  },
  "critical_findings": [...],
  "recommendations": ["[SEG-01] No rule blocking IoT VLAN traffic... — use unifi_create_simple_firewall_policy."],
  "trend": { "previous_score": 68, "change": "+5" }
}

Read overall_score and overall_status first, then walk through critical_findings before the per-category detail. Findings include a benchmark_id, severity, message, and — when applicable — a fix block with the exact MCP tool and parameters to resolve it.

For a human-readable summary instead of JSON:

python plugins/unifi-network/skills/firewall-auditor/scripts/run-audit.py --format human

Understanding Results

Score thresholds (from references/scoring-rubric.md)

Each of the four categories (Segmentation, Egress Control, Rule Hygiene, Topology) contributes up to 25 points. Deductions are applied per finding instance:

• critical finding: -5 points per instance
• warning: -2 points per instance
• informational: -1 point per instance

The category floor is 0 — a total segmentation failure does not obscure good hygiene scores.

What each benchmark means (from references/security-benchmarks.md)

Consult references/security-benchmarks.md for the full check definition, the MCP tools each benchmark uses, and the exact remediation command for each ID.

Acting on Findings

Each finding in the report includes a fix block when an automated remedy is available:

{
  "benchmark_id": "SEG-01",
  "severity": "critical",
  "message": "No rule blocking IoT VLAN traffic to private networks.",
  "fix": {
    "tool": "unifi_create_simple_firewall_policy",
    "params": { "name": "Block IoT to Private", "ruleset": "LAN_IN", "action": "drop", ... }
  }
}

For each finding:

1. Explain what the finding means in plain language and why it matters.
2. Show the fix.tool and fix.params from the report so the user knows exactly what will change.
3. Defer actual execution to the firewall-manager skill. Tell the user: "To apply this fix, switch to the firewall-manager skill, which will preview the change and wait for your confirmation before modifying the controller."

Never call mutating tools directly from within this skill. The auditor reads; the firewall-manager writes.

Priority order for acting: address critical findings first (SEG-01, SEG-02, SEG-03, HYG-02, TOP-01), then warnings, then informational items.

Tracking Trends

The script automatically records every audit result in audit-history.json (stored in .claude/unifi-skills/ by default, or the path in UNIFI_SKILLS_STATE_DIR). Up to 50 entries are retained.

The trend field in each report shows the score change since the previous run:

"trend": { "previous_score": 68, "change": "+5" }

To compare audits over time, read the history file directly:

cat .claude/unifi-skills/audit-history.json

Each entry contains a timestamp and overall_score. Share this with the user to show improvement (or regression) after applying fixes. A healthy cadence is one audit per week or after any firewall change.

Manual Procedure (fallback)

Use this procedure when the run-audit.py script is unavailable or the MCP server is not accessible via HTTP.

Step 1: Gather data (batch all together)

Call via unifi_batch:

• unifi_list_firewall_policies — all policies
• unifi_list_firewall_zones — zone definitions
• unifi_list_networks — all networks/VLANs
• unifi_list_firewall_groups — Firewall groups (address/port) referenced by rules
• unifi_get_dpi_stats — DPI data (shows what traffic is actually flowing)

Step 2: Policy analysis

For each policy, extract and analyze:

• Source/destination zones and networks
• Action (ALLOW, REJECT, DROP)
• Protocol/port specificity
• Enabled/disabled state
• Rule ordering (higher priority rules shadow lower ones)

Step 3: Check for issues

Conflicts:

• Two rules matching the same traffic with different actions
• A broad ALLOW that undermines a specific REJECT (or vice versa, depending on order)

Redundancies:

• Rules that are strict subsets of other rules with the same action
• Disabled rules that duplicate enabled rules
• Rules targeting networks or groups that no longer exist

Security gaps:

• Inter-VLAN traffic allowed without explicit rules (check IoT → main network, guest → private)
• No egress filtering on high-risk VLANs (IoT devices should not reach everything)
• Missing rules for common best practices:
  • IoT VLAN should not access private networks
  • Guest VLAN should only access internet (not local resources)
  • Management VLAN should be restricted

Unused rules:

• Rules targeting IP groups with no members
• Rules for networks that have been deleted
• Rules that have been disabled for extended periods

Step 4: Report

Present findings in this format:

## Firewall Audit Report

**Total Policies:** [count] ([enabled] enabled, [disabled] disabled)
**Zones:** [list]
**Networks:** [count]

### Critical Issues
[Issues that create security vulnerabilities]

### Warnings
[Redundancies, conflicts, or best practice violations]

### Recommendations
1. [Specific, actionable recommendation with which tool to use]
2. [...]

### Policy Summary Table
| # | Name | Action | Source | Destination | Status | Notes |
|---|------|--------|--------|-------------|--------|-------|

Tips

• Prefer the script. run-audit.py --format json is faster, deterministic, and tracks history automatically. The manual procedure is a fallback only.
• Consult the benchmarks doc. references/security-benchmarks.md has the authoritative definition for every check ID (SEG-, EGR-, HYG-, TOP-). When a finding is unclear, look up the benchmark there.
• Use the scoring rubric to set expectations. references/scoring-rubric.md explains exactly how deductions are calculated. Show users their score in context: a 73/100 is "Needs Attention", not a failing grade.
• Track scores over time. A single audit is a snapshot. The real value is the trend — run an audit after every batch of firewall changes to confirm the score improved.
• Focus on actionable findings. Do not report "everything is fine" items. Surface critical issues first, then warnings.
• Defer writes to firewall-manager. When recommending changes, name the specific tool and parameters (from the fix block), then hand off to the firewall-manager skill for execution.