zscaler/zscaler-mcp-server/create-firewall-filtering-rule

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.

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

Action types (what each does)

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 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.

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

Why `name=` and not `search=` for network services: ZIA's canonical names are uppercase enums (HTTP, FTP, DNS, ...). Server-side search="http" does NOT match HTTP. The tool's name= parameter normalizes casing client-side, so name="http" reliably finds the predefined HTTP service. (The same caveat applies to user groups; zia-look-up-rule-targets documents it for that field.)

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 this country at night", 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>] value on the firewall rule.

If the admin did not mention a schedule, leave time_windows unset. Don't invent a default.

Do not call zia_activate_configuration() from within zia-manage-time-interval when chaining — defer activation to the end of this skill so a single activation flushes both the new Time Interval and the new firewall rule.

Step 4: Build the payload

Map admin language to canonical fields:

• "block country X" → dest_countries=["XX"] with rule_action="BLOCK_DROP" (or BLOCK_RESET / BLOCK_ICMP if the admin wants a visible error)
• "block traffic FROM country X" → source_countries=["XX"] with a block action
• "exception for these source countries" → source_countries=[...] plus exclude_src_countries=True
• "block IP range A.B.C.D/24" → src_ips=["A.B.C.D/24"] (raw CIDR, no group needed) or source_ip_groups=[<id>] if a named group is preferred
• "block traffic to bad-IP-list-1" → dest_ip_groups=[<id>] after resolving the group name
• "block but make sure clients see a fast failure" → rule_action="BLOCK_RESET" (TCP only)
• "block silently / fail closed without telling the client" → rule_action="BLOCK_DROP"
• "block but return a network-layer error" → rule_action="BLOCK_ICMP"
• "evaluate against the network-app rules" / "let the nw-app catalog decide" → rule_action="EVAL_NWAPP"
• "log everything" → enable_full_logging=True

Step 5: Create the rule

Call:

zia_create_cloud_firewall_rule(
    name=<name>,
    rule_action="ALLOW" | "BLOCK_DROP" | "BLOCK_RESET" | "BLOCK_ICMP" | "EVAL_NWAPP",
    description=<optional>,
    enabled=True,
    rank=<0-7, default 7>,                     # always send; tool defaults to 7
    order=<1-based position, default 1>,       # always send; tool defaults to 1 (top)
    src_ips=[...],
    dest_addresses=[...],
    source_countries=[...],          # ISO 3166 Alpha-2 codes
    dest_countries=[...],
    exclude_src_countries=<bool>,
    dest_ip_categories=[...],
    device_trust_levels=[...],
    nw_applications=[...],
    enable_full_logging=<bool>,
    app_services=[...],
    app_service_groups=[...],
    departments=[...],
    dest_ip_groups=[...],
    dest_ipv6_groups=[...],
    devices=[...],
    device_groups=[...],
    groups=[...],
    labels=[...],
    locations=[...],
    location_groups=[...],
    nw_application_groups=[...],
    nw_services=[...],
    nw_service_groups=[...],
    time_windows=[<interval_id>],    # only if schedule was requested
    users=[...],
)

Capture the returned id.

Step 6: Activate the configuration