zscaler/zscaler-mcp-server/create-cloud-app-control-rule

ZIA: Create Cloud App Control Rule

How to talk to the admin

• Don't narrate tool calls, search filters, JMESPath expressions, 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 or more Cloud App Control rules per invocation. When the admin names multiple cloud apps in one request, the skill creates one rule per app (see "Multi-app handling" below) — that is intentional, not a violation of scope. Anything outside that scope is a hard stop:

• It does not create the auxiliary objects the rule references (location IDs, label IDs, group/department/user IDs, device groups, time intervals). 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, URL Filtering, DLP, File Type Control, 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, zia-create-url-filtering-rule). Cloud App Control is not the same as URL Filtering — URL Filtering blocks at the URL/category level; Cloud App Control allows or blocks specific operations (upload, share, edit, comment, attach) inside an application.
• It does not bypass SSL inspection. Cloud App Control needs the traffic to be decrypted to enforce action-level decisions. If the traffic is in a DO_NOT_DECRYPT SSL Inspection rule, the action enforcement will not happen — surface this as a known limitation if the admin asks why a rule isn't taking effect.

Hard stop conditions

Stop and report plainly when:

• The admin's stated cloud app cannot be resolved to a canonical ZIA name after one targeted lookup. Do not invent canonical names, do not silently substitute a similar app. Hand off to zia-look-up-cloud-app-name if the admin needs help finding the right canonical name.
• The admin asked for an action that doesn't exist on this app's category. Cloud App Control actions are category-scoped. BLOCK_FILE_SHARE_UPLOAD works for DROPBOX (category FILE_SHARE) but not for GMAIL (category WEBMAIL, where the equivalent is BLOCK_WEBMAIL_ATTACH). Always discover the valid actions for the target app's category first — do not guess action enums.
• The admin asked for plain "BLOCK" or "ALLOW". Cloud App Control does not have a connection-level block/allow. Pick the right granular action (e.g. BLOCK_FILE_SHARE_UPLOAD, ALLOW_FILE_SHARE_VIEW). If the admin really wants a connection-level block of an entire application, that's a Cloud Firewall rule (zia-create-firewall-filtering-rule) or URL Filtering rule, not Cloud App Control.
• The admin's stated location names, user/group/department IDs, label names, or time-interval 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.
• `rank` is outside the inclusive range `0..7`. ZIA's admin rank is a 0-7 integer; the tool will reject any other value before the API call. See admin rank documentation.
• The rule name is longer than 31 characters. ZIA enforces a hard 31-character maximum on the Cloud App Control rule name. The API rejects longer names with {"code": "INVALID_INPUT_ARGUMENT", "message": "Name exceeds the max length 31 characters"}. Abbreviate the verb ("Blk" for Block, "Allw" for Allow, "Iso" for Isolate) before truncating the app name — see Step 7 for the worked pattern. This counts bytes, not Unicode grapheme clusters; emoji and most accented characters in the name will consume more than one slot.
• 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.

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

How Cloud App Control differs from other rule types

Multi-app handling (one rule per cloud application)

Pattern: when the admin's request names more than one cloud application — even apps in the same category — create one rule per app, not a single rule with all apps in `cloud_applications`.

Why. Cloud App Control's action enums are surfaced at the category level, but the API validates per `(rule_type, application, action)` tuple. Two apps in the same category can each accept a slightly different subset of the category's action enums. A rule combining multiple apps with a shared action list frequently fails the create call with:

{
    "code": "INVALID_INPUT_ARGUMENT",
    "message": "Invalid action provided for selected applications"
}

The error is total — the create fails for all apps in the call, not just the rejected one. There is no API surface that enumerates per-app action validity up front, so the only safe pattern is to split.

Loop the workflow once per app. Each iteration reuses the same scoping (users / groups / locations / schedule / device trust), the same rule_type, and the same admin intent — only name, cloud_applications, and actions change per iteration. Rule names must be unique and ≤ 31 characters (ZIA hard limit), so suffix each with the app's friendly name and abbreviate the verb if needed (e.g. "Blk upload - Dropbox", "Blk upload - GDrive", "Blk upload - OneDrive"). Step 7 has the full abbreviation pattern.

Why not one rule per category instead? Tempting, but every app added to cloud_applications re-runs the per-app validation on the server. The first incompatible (app, action) pair fails the entire create. One rule per app removes the ambiguity entirely and makes each rule individually auditable in the ZIA UI.

After all rules in the loop have been created, activate once at the end (Step 8) — a single activation flushes them all.

Action vocabulary (a few illustrative examples)

The exact enums vary per category — always discover them via zia_list_cloud_app_control_actions(cloud_app=<app>) before creating a rule. For reference, here are typical patterns:

Action prefixes mean:

• ALLOW_* — permit the operation.
• BLOCK_* / DENY_* — deny the operation outright.
• CAUTION_* — show the user a warning page; they can proceed by acknowledging.
• ISOLATE_* — hand the session to Browser Isolation (requires Isolation entitlement).
• *_CONDITIONAL_ACCESS — apply Conditional Access policy logic.

The treatment of "view-only" mode is typically ALLOW_*_VIEW paired with BLOCK_*_UPLOAD / BLOCK_*_DOWNLOAD / BLOCK_*_SHARE in the same rule.

Workflow

Step 1: Gather requirements from the admin

Required: