Zia Look Up Rule Targets

ZIA: Look Up Rule Targets

Why this skill exists

Every ZIA rule resource (Cloud Firewall, DNS, IPS, URL Filtering, SSL Inspection, Web DLP, File Type Control, Sandbox, Cloud App Control) scopes by the same set of "who/where/when/what-device" target fields:

• users, groups, departments — who the rule applies to
• locations, location_groups — where the user is connecting from
• url_categories — which URL category the request hits
• devices, device_groups — which managed device the user is on
• workload_groups — which workload (cloud-asset) the connection is to/from
• labels — admin-assigned tags for organisation/reporting
• time_windows — which time-of-day schedule the rule honours

Every one of those fields takes IDs (or, for url_categories, canonical UPPER_SNAKE strings), not display names. The admin will almost always name them by display name. This skill is the single source of truth for "given a name, find the ID."

Centralising it here means every rule skill (zia-create-firewall-filtering-rule, zia-create-cloud-app-control-rule, etc.) can chain to this one instead of repeating — and re-decaying — the same lookup table.

Hard rules (apply to every lookup)

These rules are non-negotiable and override anything a rule skill might say in passing:

1. Read-before-write. For every rule target the admin names, run one lookup with the appropriate zia_list_* tool before assembling the rule payload.
2. Empty list is authoritative. If the list call returns no match for an exact-name lookup, the named target does not exist. Stop the rule create. Tell the admin plainly. Do not retry with split keywords, broader filters, larger page_size, unfiltered listings, or "let me also try without the filter to double-check." One call, one answer.
3. Never invent IDs. If a lookup returns nothing, never substitute a similar-looking ID, never skip the field that the admin named, never silently drop it from the payload. The rule payload must reflect the admin's intent verbatim or the workflow stops.
4. Never narrate the lookup. Don't tell the admin "I'm searching for the user group Engineering…" — just resolve, build the payload, and report what was applied. If you have to retry quietly (e.g. one retry with a different known-good knob, see the name= vs search= notes), retry quietly and report only the final outcome.
5. Don't pre-list targets the admin didn't name. If the admin says "create a rule for users in Engineering," resolve only Engineering. Don't dump the full user-group list as context, don't enumerate departments, don't list time intervals "in case they want one."
6. One target kind per call. Don't try to bundle a user lookup and a location lookup into one tool call.

Rule-target catalogue

The table below is the authoritative mapping for ZIA rule-target fields. Each row gives:

• the canonical field name on the rule payload
• the type the rule expects (list of int IDs, or list of str UPPER_SNAKE)
• the lookup tool to use, with the correct tool name (the project has a few legacy multiplexed tools — those are called out)
• which rule resources accept the field
• known quirks worth remembering at lookup time

Lookup pattern (apply to every row)

For every rule target the admin names:

1. Pick the row from the table above.
2. Make exactly one call to the listed tool, with the listed knob, using the admin's literal name.
3. Examine the response:
   • One match → take its id (or, for url_categories, take its id field for Web DLP / its canonical string field for everything else). Move on to the next target.
   • Multiple matches → ask the admin once which one they meant. Do not auto-pick.
   • No match → stop the rule create. Report which target could not be resolved. Suggest either correcting the name or creating the missing resource first (with the appropriate sub-skill if one exists — e.g. zia-onboard-location for new locations, zia-manage-time-interval for new time intervals).

After all named targets are resolved, hand the IDs back to the calling rule skill so it can build the rule payload.

Creating URL categories on the fly

url_categories is the one rule-target field where create-on-demand is part of the normal flow. ZIA exposes two flavours of URL categories that share the same API surface but have very different lifecycle rules:

• Predefined (Zscaler-curated) — FINANCE, NEWS_AND_MEDIA, OTHER_ADULT_MATERIAL, SHAREWARE_DOWNLOAD, etc. Cannot be created or deleted. Can be modified in two narrow ways: incremental URL/IP add/remove (preserves Zscaler's curated list) or full PUT of the keyword/IP fields.
• Custom (admin-owned) — created by the admin. Full CRUD lifecycle. Used when the rule scope is "block these specific 12 domains" rather than "block this whole category."

The toolset cleanly separates the two:

The custom-only tools (zia_update_url_category, zia_delete_url_category) refuse predefined IDs at the safety-guard layer — calling them against FINANCE raises a ValueError pointing at the right predefined-flavoured tool. Trust those guards; do not work around them.

Decision tree when the admin names a URL category in a rule scope:

1. The admin named a built-in category by canonical name (e.g. "block OTHER_ADULT_MATERIAL"). Use it as-is in the rule payload — no lookup needed beyond verifying it exists via zia_list_url_categories(search=...) or zia_get_url_category_predefined(name=...).
2. The admin named a category by a recognisable description (e.g. "block adult material"). Run zia_list_url_categories(search="<keyword>") and confirm the canonical string with the admin if more than one matches. Pick from results where custom_category matches the admin's intent.
3. The admin named a custom category that already exists. zia_list_url_categories(search="<name>") will return it with custom_category=True. Use its id (Web DLP) or canonical string (every other rule type).
4. The admin named a custom category that doesn't exist and gave you URLs ("create a rule that blocks these URLs: example.com, foo.com"). Treat this as a custom URL category create. Call zia_create_url_category(configured_name=..., super_category=..., urls=[...]) first, then use the returned ID/canonical string in the rule payload.
5. The admin named a custom category that doesn't exist and gave no URLs. Stop. Ask for the URL list (or which existing category they meant). Don't substitute a similarly-named built-in category.
6. The admin asked to add/remove URLs on a predefined category ("add bad-site.com to FINANCE"). This is a separate workflow from rule creation — call zia_add_urls_to_category(category_id="FINANCE", urls=[...]) (or zia_remove_urls_from_category with HMAC confirmation). Both work transparently on predefined IDs because they use the SDK's ?action=ADD_TO_LIST / ?action=REMOVE_FROM_LIST endpoints, which preserve Zscaler's curated list.
7. The admin asked to fully replace fields on a predefined category (e.g. "set the keywords on FINANCE to exactly these 5"). Use zia_update_url_category_predefined(name="FINANCE", keywords=[...]). Calling zia_update_url_category against a predefined ID is rejected by the safety guard — that's intentional, because a full-PUT against a predefined category would obliterate Zscaler's curated URL list.

Important: Web DLP is the only rule type whose url_categories field takes numeric IDs. Every other rule type takes the canonical UPPER_SNAKE string. The list/get/create tools return both fields on each entry — pick the right one based on which rule you're building.

Rule-target × Rule-type coverage matrix

This is the same table as above, restated as a coverage matrix so the calling rule skill can quickly check which rule-target fields its rule type supports.

Legend: CFW = Cloud Firewall, DNS = Cloud Firewall DNS, IPS = Cloud Firewall IPS, URL = URL Filtering, SSL = SSL Inspection, DLP = Web DLP, FTC = File Type Control, SBX = Sandbox, CAC = Cloud App Control.

If the admin names a rule-target field that the rule type doesn't support (e.g. time_windows on SSL Inspection, departments on IPS, url_categories on Cloud Firewall), stop and explain — do not silently drop the field. Suggest the correct rule type if it's a clear mismatch.

Naming-knob cheat sheet

A few of the lookup tools have non-obvious knob preferences. The defaults below match what the tool descriptions document.

What this skill does NOT cover

This skill is intentionally narrow. The following lookups are rule-type-specific and are handled inside their respective rule skills, not here:

• The cloud-app catalog field (canonical ZIA app names like DROPBOX, ONEDRIVE, SHAREPOINT_ONLINE, CLOUDFLARE_DOH). Exposed as cloud_applications on SSL Inspection, Web DLP, File Type Control, and Cloud App Control, and as applications on Cloud Firewall DNS rules — same catalog, different field name (an inconsistency in the underlying ZIA API). Not used by Cloud Firewall (non-DNS), IPS, or Sandbox. → always chain to zia-look-up-cloud-app-name to translate friendly names to canonical names. SSL Inspection, File Type Control, Cloud App Control, and DNS auto-resolve friendly names in their tools; Web DLP does not yet.
• Cloud App Control's actions and rule_type fields (the category-scoped action enum set and the category itself). → zia-create-cloud-app-control-rule plus zia_list_cloud_app_control_actions for action discovery.
• Cloud Firewall-specific fields: src_ips, dest_addresses, source_countries, dest_countries, dest_ip_categories, dest_ip_groups, dest_ipv6_groups, device_trust_levels, nw_applications, nw_application_groups, nw_services, nw_service_groups, app_services, app_service_groups. → zia-create-firewall-filtering-rule.
• SSL Inspection-specific fields: ZPA app segments, platforms, the action dict (with sub-actions). → zia-create-ssl-inspection-rule.
• DLP-specific fields: DLP engines, DLP dictionaries, ICAP server, notification template, auditor, file types, content scopes. → handled inside the Web DLP rule skill (when written) or directly in zscaler_mcp/tools/zia/web_dlp_rules.py.
• Sandbox-specific fields: file types, ba_rule_action, ba_policy_categories. → zia-create-sandbox-rule (if/when written).
• The Time Interval object itself. Finding or creating a time_windows ID is delegated to zia-manage-time-interval. This skill just tells you that time_windows is the field name and that you should chain.

How a rule skill chains to this one

In practice, every rule skill's "Step 2: Resolve every named resource (read-before-write)" should look like this — and nothing more for the shared rule-target fields:

Step 2 — Look up shared 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 strings, for url_categories). Stop and report if any lookup is empty — never invent IDs, never substitute. Then resolve any rule-type-specific fields (listed below) before assembling the payload.

The rule-type-specific lookups (e.g. firewall's IP source/destination/network-service-group resolution, SSL's cloud-app + URL-category resolution, CAC's app-enum + actions discovery) stay in the rule skill itself, because they don't apply to other rule types.

Quick Reference

Read-only lookup tools (in the order of the rule-target table):

• zia_users_manager(action="read", search=...)
• zia_user_group_manager(action="read", name=...)
• zia_user_department_manager(action="read", search=...)
• zia_list_locations(query_params={"search": ...})
• zia_list_location_groups(name=..., search=..., group_type=...)
• zia_list_url_categories(search=...) — discovery for both flavours
• Custom-category lifecycle: zia_get_url_category / zia_create_url_category / zia_update_url_category (full PUT, custom only) / zia_delete_url_category (custom only, HMAC)
• Predefined-category lifecycle: zia_get_url_category_predefined(name=...) / zia_update_url_category_predefined(name=..., ...) (full PUT, predefined only)
• Incremental URL/IP edits (work transparently on both flavours): zia_add_urls_to_category(category_id=..., urls=[...]) / zia_remove_urls_from_category(category_id=..., urls=[...])
• zia_list_devices(name=...) / zia_list_devices_lite / zia_list_device_groups(search=...)
• zia_list_workload_groups(query="[?name=='...']")
• zia_list_rule_labels(search=...)
• zia-manage-time-interval (sub-skill, not a tool)

Sub-skills referenced from here:

• zia-manage-time-interval — find-or-create a Time Interval and return its ID for the time_windows field.
• zia-onboard-location — create a new location (with its static IP / VPN credential prerequisites) when the admin named one that doesn't exist.

Skills that chain INTO this one:

• zia-create-firewall-filtering-rule
• zia-create-cloud-app-control-rule
• zia-create-ssl-inspection-rule
• zia-create-url-filtering-rule
• (and any future ZIA rule create/update skill — DLP, sandbox, file type control, DNS, IPS)

Each of those skills delegates the shared rule-target lookups to this skill and keeps only the rule-type-specific logic locally.