/manage-firewall

name: manage-firewall
description: >-
  Inspects and configures the web application firewall (WAF) in front of a
  Power Pages production site. Lists the current state, recommends enabling
  protection when it is off, and walks the user through adding, updating,
  or removing custom rules — IP blocks, country blocks, path blocks, and
  rate limits. Use when the user wants to turn on WAF, block traffic by
  IP or country, rate-limit login or signup pages, protect pages from
  brute-force attempts, restrict access to specific paths, review the
  current firewall configuration, or asks "is my site protected against
  bots / common web attacks?" — even if they say "add rate limit" or
  "protect login page" without mentioning "firewall" or "WAF".
user-invocable: true
argument-hint: "[optional: --review <out-dir>]"
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Manage Web Application Firewall

Configure the firewall for a Power Pages production site. The firewall is only available on production sites and in supported regions — the scripts detect and report eligibility issues. After rule changes, edge propagation takes up to one hour.

**Initial request:** $ARGUMENTS

Gotchas

• **Website record id vs portal id.** `.powerpages-site/website.yml` stores the website record id, not the portal id. Every script takes `--portalId`. Resolve once via `website.js --websiteId` during prerequisites.
• **Never resolve by name.** Site names can duplicate; only the website record id is safe.
• **Async operations.** `enable.js` and `disable.js` poll until the status reaches the target value (or timeout). `delete-rules.js` returns immediately (202) — verify via `get-rules.js`.
• **Concurrent-operation guard.** `B003` means another enable/disable is in flight. Poll status until it settles, then retry.
• **False-positive managed rule:** disable via a rule override (`EnabledState: "Disabled"` inside `RuleGroupOverrides` — managed rule fields use PascalCase).
• **First-match-wins.** Rules evaluate in priority order. A geo-allow-then-default-deny pattern requires an explicit default-deny rule AFTER the allow.
• **Custom rule priority range: 11–65000.** Values 1–10 are reserved for platform-managed rules.
• **`set-rules.js` is additive / update-only.** Send only rules being created or modified. The service merges them; existing rules not in the payload are untouched.
• **Use `delete-rules.js` to remove rules.** `set-rules.js` cannot remove. Always use `delete-rules.js --names`.
• **WAF state semantics — `Created` is the only "enabled" state.** `get-status.js` returns `value: "Created"` when the firewall is enabled and actively filtering (counter-intuitive — the API does NOT use `"Enabled"`). Any other value (`Disabled`, `None`, `Enabling`, `Disabling`, `Failed`) means no active policy exists. **MUST** call `get-status.js` first and only invoke `get-rules.js` when `value` is `Created` — otherwise the rules endpoint returns a 500 and the whole firewall section gets skipped in the report.

Workflow

1. **Prerequisites** — Locate project, confirm sign-in, identify site, check eligibility 2. **Check firewall state** — Capture status and rules 3. **Choose an action** — Context-aware recommendation or question 4. **Apply the change** — Run the matching script, verify 5. **Summarize and next steps** — Present result, record usage, offer follow-ups

Task Tracking

Create tasks in three groups. Mark each `in_progress` when starting, `completed` when done.

| Group | When to create | Tasks | |-------|----------------|-------| | 1 | At start | Check prerequisites | | 2 | After prerequisites pass | Check firewall state · Choose an action (skip in review mode) | | 3 | After user confirms an action | Apply the change (skip in review mode OR no change action was chosen) · Summarize and next steps (always) |

---

1. Prerequisites

1.1 Locate the project, detect review mode

Use `Glob` to find `**/powerpages.config.json`. If `$ARGUMENTS` contains `--review <out-dir>`, remember the output directory — Steps 3–4 are skipped and Step 5 writes JSON only.

1.2 Resolve site identifiers

Read `.powerpages-site/website.yml` → extract `id` field → that is `<WEBSITE_ID>`.

If missing, the site has not been deployed. Tell the user and recommend `/deploy-site`. Stop. Do **not** resolve by name or URL.

Resolve to portalId:

node "${PLUGIN_ROOT}/scripts/website.js" --websiteId "<WEBSITE_ID>"

Capture `Id` (portalId), `Type`, `Name`, `WebsiteUrl`. If exit code `2` → sign-in required (`pac auth create` or `az login`). If `null` → site not found in this environment. Stop in either case.

1.3 Eligibility

Check the `Type` field and the script responses for eligibility. The scripts return specific error codes for ineligible sites (non-production, unsupported region, restricted feature). Read `references/commands.md` § "Common error catalogue" and § "Regional availability" for the full list.

If the site is ineligible, tell the user in plain language what the limitation is and stop.

---

2. Check firewall state

2.1 Get status (always run first)

node "${PLUGIN_ROOT}/skills/manage-firewall/scripts/get-status.js" --portalId "<PORTAL_ID>"

The response shape is `{ "status": "ok", "value": "<state>" }`.

• `Created` — WAF is enabled and filtering. Proceed to **2.2** to fetch rules.
• Any other value (`Disabled`, `None`, `Enabling`, `Disabling`, `Failed`, etc.) — **WAF is not enabled**. **MUST NOT** call `get-rules.js` — the rules endpoint will return a 500 because no active policy exists to read. Skip **2.2** and treat the rules payload as empty: `{ "status": "ok", "body": { "CustomRules": [], "ManagedRules": [] } }`.

If the status response is `"status": "unsupported"`, tell the user the fire