zia-create-firewall-filtering-rule

What this skill does

# ZIA: Create Cloud Firewall Filtering Rule

## How to talk to the admin

- Don't narrate tool calls, search filters, or internal lookup logic. Just confirm what was created and which scoping was applied.
- Empty list responses are authoritative. If a `zia_list_*` lookup returns no match for an exact-name search, treat the resource as "does not exist." Do not retry with split keywords or unfiltered listings.
- Don't claim a tool doesn't exist without checking. If `zia_create_*` and `zia_get_*` are visible for a resource, the matching `zia_list_*` exists too.
- Don't narrate strategy pivots. If you have to retry quietly, retry quietly and report only the final outcome.
- After every successful create, **mention the activation step explicitly** — ZIA changes are staged until activated. The agent must call `zia_activate_configuration()` and tell the admin the change is now live.

## Scope of this skill

This skill creates **one** Cloud Firewall Filtering rule per invocation. Anything outside that scope is a hard stop:

- **It does not create** the auxiliary objects the rule references (IP source/destination groups, network service groups, network app groups, location groups, label IDs, group/department/user IDs). If those don't exist, this skill stops and points the admin at the right place to create them — it does not improvise.
- **It does not modify SSL Inspection, URL Filtering, DLP, or any other ZIA rule type.** Those are separate resource types and have their own skills (`zia-create-ssl-inspection-rule` for SSL Inspection).
- **It does not enforce DNS or IPS rules.** Cloud Firewall DNS rules and IPS rules are separate APIs (`cloud_firewall_dns_rules`, `cloud_firewall_ips_rules`) — not what this skill creates.

## Hard stop conditions

Stop and report plainly when:

- **The admin's stated IP groups, network services, network app groups, location names, or user/group IDs cannot be resolved.** Resolve once via the appropriate `zia_list_*` tool; if empty, say so and stop. Do not skip the field, do not invent IDs.
- **A recurring schedule was requested but no schedule details were provided.** Don't guess. Ask once for `start_time`, `end_time`, and `days_of_week`, then chain to `zia-manage-time-interval`.
- **An action was requested that doesn't exist on this rule type.** Valid actions are exactly: `ALLOW`, `BLOCK_DROP`, `BLOCK_RESET`, `BLOCK_ICMP`, `EVAL_NWAPP`. Plain `BLOCK` is not a valid value — pick one of the three block variants based on the desired client-visible behaviour. SSL-inspection-style actions (`DO_NOT_DECRYPT`, `DO_NOT_INSPECT`, `INSPECT`, `BYPASS`) belong to other rule types and are a hard stop here.
- **The admin is trying to modify the predefined Default Cloud IPS Rule** by name. Predefined/default rules cannot be deleted, and changes to them require admin rank 7. Confirm intent before proceeding.
- **The admin asked for a country-based rule but only gave a country name.** ZIA expects ISO 3166 Alpha-2 codes (`US`, `CA`, `BR`, etc.). Resolve common phrasings to the canonical code; if ambiguous, ask once.
- **`rank` is outside the inclusive range `0..7`.** ZIA's Cloud Firewall rank is a 0-7 integer; the tool will reject any other value before the API call. See [admin rank documentation](https://help.zscaler.com/zia/about-admin-rank).

Never improvise around a missing dependency — hand off or stop.

## Action types (what each does)

| Action | Effect on matched traffic | Common reasons to choose this |
|---|---|---|
| `ALLOW` | Permit the traffic. Other downstream policies (URL filtering, DLP, SSL inspection, etc.) may still apply. | Explicit allowlist for known-good destinations or services. |
| `BLOCK_DROP` | Silently drop the packet. The client gets no signal — the connection just times out. | Quietly block disallowed traffic without revealing that a firewall is in the path; reduces information leakage to attackers. |
| `BLOCK_RESET` | Drop the packet and send a TCP RST back to the source. The client's connection fails immediately with a reset. | Fast-fail block for end-user-facing traffic where a quick error is preferable to a hung connection. TCP only. |
| `BLOCK_ICMP` | Drop the packet and return an ICMP unreachable to the source. | Make the block visible at the network layer — useful for traceroutes and diagnostic tooling, or where applications expect a network-level error. Works for non-TCP protocols too. |
| `EVAL_NWAPP` | Defer the action: evaluate the connection against the Network Application rules instead of taking a final action here. | Use when the rule should hand off to `nw_applications` / `nw_application_groups` based filtering downstream. Pair this action with rules that have a populated network-application scope. |

**Picking between the three BLOCK variants:**

- Plain `BLOCK` does **not** exist on this API. Always pick the variant that matches the desired client-visible behaviour.
- Default to `BLOCK_DROP` unless the admin specifically wants the client to see a fast failure (`BLOCK_RESET`) or a network-level error (`BLOCK_ICMP`).
- `BLOCK_RESET` is TCP-only by definition (RST is a TCP flag). For UDP/ICMP, use `BLOCK_DROP` or `BLOCK_ICMP`.

## Workflow

### Step 1: Gather requirements from the admin

Required:

- **Rule name**
- **Action** — one of `ALLOW`, `BLOCK_DROP`, `BLOCK_RESET`, `BLOCK_ICMP`, `EVAL_NWAPP` (see the action table above for which variant to pick)
- **`order`** — 1-based position in the evaluation sequence. ZIA's Cloud Firewall API rejects create payloads without `order`. Pick the position deliberately based on the desired rule ordering (e.g. ALLOW above BLOCK when both target overlapping traffic). The tool defaults to `1` (top) when omitted, but the agent should set it explicitly whenever creating more than one rule in a session.
- **`rank`** — admin rank, integer in the inclusive range `0..7`. ZIA's Cloud Firewall API rejects create payloads without `rank`. The tool defaults to `7` (highest) when omitted; this matches ZIA's documented default. See [admin rank documentation](https://help.zscaler.com/zia/about-admin-rank) for what each level controls.

At least one matching criterion (otherwise the rule is too broad to be useful):

- Source IPs / source IP groups / source countries
- Destination addresses / destination IP groups / destination IPv6 groups / destination countries / destination IP categories
- Network applications / network application groups
- Network services / network service groups / app services / app service groups
- Users / groups / departments
- Locations / location groups
- Device trust levels
- Devices / device groups
- A time-of-day window (Time Interval)

Optional:

- Description, rank (1-7), order (defaults to bottom of list), `enable_full_logging`, `exclude_src_countries`

### Step 2: Resolve every named resource (read-before-write)

**Shared rule targets — delegate to `zia-look-up-rule-targets`.** For every user, group, department, location, location group, device, device group, workload group, label, or time interval the admin named, follow `zia-look-up-rule-targets` to get the IDs. Stop and report if any lookup is empty — never invent IDs, never substitute, never narrate the lookup. (Cloud Firewall accepts every shared rule-target field listed in that skill.)

**Firewall-specific fields — resolve here.** The fields below are unique to Cloud Firewall and not covered by `zia-look-up-rule-targets`. For each one the admin named, run **one** lookup using the knob below. Empty result = does not exist. Don't retry with broader filters.

| Admin named | Resolution tool | Lookup knob | Returns |
|---|---|---|---|
| Network service name | `zia_list_network_services` | **`name="<literal>"`** (case-insensitive substring; client-side) | network service ID |
| Source IP group name | `zia_list_ip_source_groups` | `search="<exact>"` | source group ID |
| Destination IP group name | `zia_list_ip_destination_groups` | `search="<exact>"` | destination group ID |
| Network service g