zia-create-url-filtering-rule

What this skill does

# ZIA: Create URL Filtering Rule

## How to talk to the admin

- Don't narrate tool calls, JMESPath filters, search keys, 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** URL Filtering rule per invocation. Anything outside that scope is a hard stop:

- **It does not create** the auxiliary objects the rule references (URL categories, label IDs, group/department/user IDs, location groups). 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, Cloud Firewall, DLP, or any other ZIA rule type.** Those are separate resource types and have their own skills (`zia-create-ssl-inspection-rule`, `zia-create-firewall-filtering-rule`).
- **It does not classify URLs.** If the admin gives a literal URL, look up its category via `zia_url_lookup` first, then scope the rule by the resulting category names — URL Filtering rules match on `url_categories`, not on raw URLs.

## Hard stop conditions

Stop and report plainly when:

- **The admin's stated URL categories, label/group IDs, or location names 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`, `CAUTION`, `ISOLATE`. Anything else (e.g. `DECRYPT`, `INSPECT`, `BYPASS`, `BLOCK_DROP`) belongs to other rule types and is a hard stop here.
- **`ISOLATE` was requested without Browser Isolation entitlement.** ISOLATE requires a Browser Isolation subscription. If the admin asks for it on a tenant without entitlement, the API will reject the rule. Confirm the admin has the entitlement before proceeding; if unsure, suggest `CAUTION` as the closest non-isolation alternative.
- **`block_override=True` was requested without `rule_action="BLOCK"`.** Override only applies to BLOCK actions. Reject combinations that don't match.
- **`enforce_time_validity=True` was requested without start/end timestamps.** When validity windows are enforced, `validity_start_time`, `validity_end_time`, and `validity_time_zone_id` are required. Don't guess the dates.

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

## Action types (what each does)

| Action | Effect on matched URL traffic | Common reasons to choose this |
|---|---|---|
| `ALLOW` | Permit the request. Other downstream policies (DLP, SSL inspection, etc.) may still apply. | Explicit allowlist for known-good URL categories or for an exception that overrides a broader BLOCK rule above. |
| `BLOCK` | Deny the request and show a BLOCK page to the user. | Block disallowed categories outright (adult content, gambling, malware, etc.). Often paired with `block_override=True` plus `override_users` / `override_groups` for managed exceptions. |
| `CAUTION` | Show the user a warning interstitial; the user may click through and continue. | Soft enforcement for risky-but-not-banned categories where awareness matters more than a hard block. |
| `ISOLATE` | Render the page in a remote isolated browser session — pixels stream to the user; the local browser never touches the site. | High-risk categories where data exfiltration / drive-by malware is the concern but a hard BLOCK is too disruptive. **Requires Browser Isolation entitlement.** |

## Two kinds of "time" on this rule type

URL Filtering exposes two different time controls — they solve different problems:

1. **`time_windows` — recurring schedule.** Attach one or more Time Interval IDs to enforce the rule on a recurring time-of-day / day-of-week pattern (e.g. "block social media 09:00-17:00 Mon-Fri"). Use `zia-manage-time-interval` to find or create the interval. Idempotent on name.

2. **`enforce_time_validity` + `validity_start_time` / `validity_end_time` / `validity_time_zone_id` — one-shot date range.** A non-recurring window during which the rule is active (e.g. "this exception is valid from Mar 1 to Mar 15 only"). Outside the window, the rule has no effect.

The two are independent and can be combined (e.g. "valid from Mar 1 to Mar 31, and only during business hours within that window"). If the admin's request implies one or the other, pick the right field — don't conflate them. If the admin says "between 9am and 5pm Mon-Fri" → that's `time_windows`. If they say "until end of March" → that's `enforce_time_validity`.

## Workflow

### Step 1: Gather requirements from the admin

Required:

- **Rule name**
- **Action** — one of `ALLOW`, `BLOCK`, `CAUTION`, `ISOLATE`

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

- **URL categories** (most common scope on this rule type)
- Protocols (e.g. `["HTTP_RULE", "HTTPS_RULE"]`)
- Request methods (`GET`, `POST`, `CONNECT`, etc.)
- User agent types (`CHROME`, `FIREFOX`, etc.)
- Users / groups / departments
- Locations / location groups
- Devices / device groups / device trust levels
- A time-of-day window (`time_windows`) and/or a one-shot validity range (`enforce_time_validity`)

Optional:

- Description, rank (1-7), order (defaults to bottom)
- `block_override=True` plus `override_users` / `override_groups` (BLOCK action only — lets specified users override)
- `end_user_notification_url` — custom block-page URL
- `size_quota`, `time_quota` — bandwidth / time budgets per session
- `ciparule=True` — flags the rule as a CIPA-compliance rule

### 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, URL category, device, device group, workload group, label, or time interval the admin named, follow `zia-look-up-rule-targets` to get the IDs (or canonical UPPER_SNAKE strings, for `url_categories` — URL Filtering takes the string form, not numeric IDs). Stop and report if any lookup is empty — never invent IDs, never substitute. (URL Filtering accepts every shared rule-target field in that skill, including `time_windows` and `workload_groups`.)

**URL-filtering-specific helpers — use here.** The shared skill handles named URL categories. Use the tool below when the admin gives you a literal URL instead of a category name.

| Admin named | Resolution tool | Lookup knob | Returns |
|---|---|---|---|
| Literal URL ("can users access foo.com?") | `zia_url_lookup` | (URL list) | category names — feed those into `url_categories=[...]` |

Don't skip a field that the admin named because lookup failed — the skill stops, the admin fixes the naming or creates the missing object first.

### Step 3: Resolve the schedule (only if the admin asked for time-of-day scoping)

If the admin's request includes any time-of-day language ("during business hours", "after hours", "weekends only", "between 8am-5pm Mon-Fri", "block social media at work", etc.), **chain to `zia-manage-time-interval`** to find or create the Time Interval and obtain its `interval_id`. That ID becomes the `time_windows=[<id>]