Imported from dvmrry/zscaler-skill (SKILL.md). Install upstream with npx skills add dvmrry/zscaler-skill. Copyright stays with the author.

Zscaler

A skill for reasoning about Zscaler ZIA and ZPA configuration — what gets matched, what wins, and why.

What this skill knows

This skill encodes how Zscaler actually behaves — rule precedence, wildcard semantics, SSL inspection ordering, and policy evaluation across ZIA and ZPA. That knowledge is the product; live API access alone will give confidently wrong answers about precedence.

Two kinds of question this skill handles:

• General behavior — "how do wildcards match?", "what happens when URL filtering and cloud app control both apply?". Answerable anywhere, sourced from references/.
• Tenant-specific lookups — "is reddit.com in a URL category in our tenant?". Requires observed tenant state: either a configured runtime-data snapshot (_data/snapshot/ by default), explicit user-provided command output, or — when available — read-only zscalerctl output. Public upstream does not track runtime data; tenant snapshots live only in private runtime-data mounts or forks.

Structured troubleshooting with a symptom, affected scope, and timeframe should use the portable zscaler-investigator skill or the /z-investigator runtime adapter. This broad zscaler entrypoint is for ad-hoc Q&A and lightweight lookups, not discovery-journal investigations.

Check tenant observation first

Before answering tenant-specific questions, resolve the configured mount and check whether its snapshot/ directory has any runtime data:

RUNTIME_DATA="$(node scripts/runtime-data-path.mjs)"
find "$RUNTIME_DATA/snapshot" -mindepth 1 -type f -print -quit

If populated, read the relevant JSON (<mount>/snapshot/<cloud>/zia/url-categories.json, <mount>/snapshot/<cloud>/zia/url-filtering-rules.json, <mount>/snapshot/<cloud>/zpa/app-segments.json, etc.) and cite the specific rule IDs you used. If the overlay records that the snapshot or diff was produced by zscalerctl, treat it as the fast local cache of read-only tenant observation.

If <mount>/snapshot/ is empty or stale and the question is tenant-specific, do not invent tenant truth. When the optional @zscalerctl companion is available, hand off or draft a bounded read-only command (zscalerctl --format json ...) for the operator to run, then apply this skill's policy semantics to the returned JSON. Until zscalerctl is officially adopted, use soft language: "if installed", "when available", or "I can draft the read-only command." See references/_meta/tooling.md.

<mount>/schemas/ is a separate cache for log-schema decompositions, query skeletons, and script-generated reports (gitignored in the default public layout; populated by scripts such as splunk-query.sh, issue-watch.py, and find-asymmetries.py). Raw logs are a validation layer, not a primary source — see When to consult logs below.

Vendor source vs production IaC

The skill ships with Zscaler Terraform provider source under vendor/terraform-provider-{zia,zpa,zcc,ztc}/. Those repositories are useful for resource schemas, validation rules, provider coverage, and field-level shapes. Deployment examples or modules, when vendored, live separately under vendor/terraform-*-modules/. Provider source and example modules are reference material, not production truth.

If a fork has populated <mount>/iac/ (empty in upstream), treat that as production truth for "how is X actually deployed in our environment" questions. The source under vendor/ remains useful for "what's possible" / "what fields exist" / "what defaults Zscaler ships." Where the two diverge for a specific deployment, prefer the configured runtime IaC for env-specific answers and cite the reference for context.

RUNTIME_DATA="$(node scripts/runtime-data-path.mjs)"
find "$RUNTIME_DATA/iac" -mindepth 1 -type f -print -quit

See docs/data-contract/iac.md for the precedence rules and structure.

Question routing

Go straight to the reference file that covers the question shape. Treat this table as a resolver, not a preload list: select one row, read the named file, then stop unless the question genuinely spans multiple products or policies.

If the question shape isn't here, start with references/shared/policy-evaluation.md and follow its cross-links.

For breadth questions ("does Zscaler have a product for X?", "what is Risk360?", "is AppProtection part of ZPA?", "what's the difference between Cloud Connector and Posture Control?"), start with references/_meta/portfolio-map.md — single-page index of every Zscaler product with deep-dive / awareness / out-of-scope tier. Tells the skill what coverage depth to claim before answering.

For prerequisite-knowledge questions ("what's a proxy?", "what's the difference between SAML and OIDC?", "what does zero trust actually mean?", "how does NAT work?"), start with references/_meta/primer/ — five primer docs covering generic networking, forwarding paradigms, zero-trust philosophy, identity protocols, and the Zscaler platform shape. Use this when the asker is non-networking-background or when you need to set up conceptual scaffolding before diving into a product-specific answer.

For meta-questions about the skill itself ("where does general Zscaler knowledge end and tenant-specific data begin?", "how should this skill combine doc knowledge with what we know operationally?"), see references/_meta/layering-model.md — the three-layer framing (general / tenant / SME tribal) with anti-patterns and operational implications for fine-tune training. For the pre-release zscalerctl companion boundary, see references/_meta/tooling.md: zscalerctl observes tenant state; this skill reasons over it.

If you are an AI agent, prefer references/_meta/agent-patterns.md over the prose runbooks below. It contains pure typed Python functions for cloud classification, auth-framework detection, and error interpretation: detect_cloud(), is_gov_cloud(), detect_auth_framework(), and interpret_error(). The canonical implementation lives at scripts/agent_patterns.py. It performs no tenant or SDK calls; use snapshots, supplied command output, or the read-only zscalerctl companion for observation.

For actionable / procedural questions — "which auth path should I use?", "how do I detect if this is a gov cloud?", "I'm getting 401 / rule isn't applying / 429 rate-limited / EDIT_LOCK / activation stuck — what do I do?", "how do I rotate credentials safely?", "how do I round-trip a config without hitting the read/write asymmetry?" — start at references/_meta/runbooks.md. The runbook contains: (1) authentication selection decision tree with concrete diagnostic checks, (2) diagnostic procedures for cloud detection / OneAPI-vs-legacy detection / migration status, (3) troubleshooting flows for the six most common failure modes, (4) credential lifecycle patterns including rotation, fallback, OneAPI ↔ legacy coexistence, gov-cloud forced-legacy. This is the home for "what should I DO?" questions — the rest of the skill is reference (how things work); the runbook is procedural (what steps to take). Each product api.md cross-links here, and each api.md also has a "Common SDK patterns" subsection with inline code so you don't have to switch docs to find the call signature you need.

For verifying a finding before threading it into the skill — i.e., any time a user reports behavior that's not yet documented — apply references/_meta/verification-protocol.md. The four-tier model (source-verified / behavior-verified / operator-reported / inferred) governs what language is permitted, where the finding can land, and how user assertions get treated when they conflict with sources. This is binding for assistant behavior: treat user-reported behavior as a tier-C candidate by default, run the source-check sequence before threading, never use "verified" language for unverified content, and hold the line on tier C/D when users push for tier-A treatment without producing evidence.

Before quoting any reference summary, do a targeted clarification lookup — search references/_meta/clarifications.md by the selected product prefix, cited clarification ID, or the specific field/behavior in question. Do not load the entire clarification ledger for routine answers. When a matching entry applies, cite the clarification ID and adjust confidence accordingly.

Answer format

Return every non-trivial answer in this shape. It keeps answers grounded, makes uncertainty visible, and gives a future trainer a consistent structure to learn from.

## Answer
<direct answer in 1–3 sentences; lead with the conclusion>

## Reasoning
<why, citing the specific mechanics — rule order, match type, evaluation stage>

## Sources
- references/zia/url-filtering.md (§ section you used)
- _data/snapshot/<cloud>/zia/url-filtering-rules.json (rule IDs 42, 47 — only if snapshot was consulted)

## Confidence
high | medium | low — <one-line reason; e.g. "stub reference, inferred from Zscaler KB">

For trivial factual questions ("what's a URL category?") you can drop Reasoning and Confidence, but keep Sources.

Confidence rule when sources disagree

When two vendored sources describe the same behavior in different — even subtly different — ways:

1. Do not silently pick one. Report Confidence: medium at most, sometimes low depending on severity.
2. Cite both sources in the ## Sources section.
3. Name the divergence explicitly in ## Reasoning — one sentence identifying what the two sources say and why it matters for the answer.
4. If the divergence overlaps an open clarification in references/_meta/clarifications.md, cite the clarification ID.

Concrete example: Understanding Application Access p.1 describes the port-mismatch outcome two ways ("bypasses ZPA and sends traffic directly" vs "client connection request is dropped by ZPA"). Those are two perspectives on the same event — reconciled in references/zpa/app-segments.md § Worked example. An answer using this material should cite the reconciled section, not either single quote, and report Confidence: medium if the user's question hinges on what happens to the traffic after the bypass.

A claim derived by inference — extrapolating a stated rule beyond its documented scope — gets Confidence: low and an explicit note in Reasoning calling out that it's an extrapolation. Do not dress inferences as quoted fact.

When to consult logs

Default: answer from config (_data/snapshot/) and reference docs. Logs are the validation layer, not the first stop — they add latency and cost.

Consult logs when any of:

• The user pushes back on a config-derived answer.
• Config is ambiguous (multiple rules could match, wildcard could go either way, segments overlap).
• The question is inherently observational ("when did this start breaking?", "how often does Y happen?").
• You suspect config/reality drift — rules recently changed, or the answer smells wrong.

Do not consult logs for pure semantic questions ("how do wildcards match?") — reasoning docs handle those. See references/shared/log-correlation.md for the full decision rule.

When you do query, cite the SPL pattern by name from references/shared/splunk-queries.md rather than inlining it. If logs contradict config, call that drift out explicitly in the Answer — it's the high-signal finding.

When to decline

• Tenant state needed, no observation available — say so directly, and still answer the general case if there is one. If @zscalerctl is available, offer or draft a bounded read-only command; otherwise ask for a snapshot or sanitized command output.
• Relevant reference is still a stub (author-status: stub, no body yet) — say the skill hasn't written this down yet, describe what you know from the file's TODO headings, and mark Confidence: low.
• Question maps to a known open clarification — if a reference doc cross-links an entry in references/_meta/clarifications.md that covers the user's question, cite the clarification ID (e.g. "this hits zia-03 — wildcard tokenization is unresolved in our public material"), answer what you can, and flag the gap rather than hallucinating the rest.
• T1 — operational deep-dive (SDK / TF / API + multi-component coverage) — ZIA, ZPA (including AppProtection inline WAF/IPS sub-component and Browser Access), ZCC (forwarding profiles, trusted networks, fail-open), ZIdentity (unified identity, OneAPI auth, step-up authentication), Cloud & Branch Connector (ZTW/ZTC — Cloud Connector VM architecture, traffic forwarding rules, SDK/TF surface), and ZDX (score, probes, diagnostic sessions, alerts — T1 borderline: observability layer rather than enforcement, per 2026-05-04 verification gate). Answer with full confidence and cite specific reference sections including API endpoints, rule semantics, and policy evaluation order.
• T2 — programmable but shallow (SDK / API exposure, narrow surface) — ZBI (Cloud Browser Isolation / Zero Trust Browser), ZWA (Workflow Automation), AI Guard, ZMS, EASM, Zscaler Cellular / ZCell, and Business Insights. The surface is not uniformly writable: ZMS and the Python EASM client are read-only/query-only, while AI Guard, ZCell, and the Business Insights custom-app/report-config families include writes. Answer at confidence: medium-to-high for the documented surface; flag the precise client/parity gap when the question pushes beyond it.
• T3 — extended reasoning, no verified SDK / TF management surface — Deception, Risk360, AI Security family surfaces beyond AI Guard, ZSDK, AEM, DSPM, ITDR, UVM, Experience Center, Breach Predictor, SOC Workbench, and Zero Trust Branch. Route to the product reasoning doc or portfolio entry, answer at confidence: medium, and state the exact captured coverage boundary instead of applying a blanket portal-only claim to a neighboring Tier 2 product. Do NOT fabricate field names, API endpoints, or programmatic config patterns.
• T4 — paragraph-only routing (one-paragraph framing in portfolio map) — Resilience, BCC, CTEM, Cloud Protection, Posture Control, M365 Copilot, Red Canary MDR, MTH, B2B, ZINS (shadow-IT NSS Collector), Federal Cloud variants (zscalergov, zscalerten, ZPA GOV/GOVUS), or any other Zscaler-marketed product not in the T1 / T2 / T3 lists. Start at references/_meta/portfolio-map.md for the one-paragraph framing. Give the conceptual answer and point to the Zscaler help site / TAM for operational depth — do NOT fabricate API details or rule behaviors. Confidence: medium at most.
• T5 — truly out of scope — currently empty. Reserved for deprecated / internal / unshipped products. If a user question lands here, decline outright.
• Partial scope within T1 — ZCC device-posture rules and on-device web policy are partially in scope (see references/zcc/index.md for gaps). ZDX's application-specific call-quality integrations (Microsoft Teams, Zoom deep-dives) are partially in scope — references/zdx/index.md lists the gaps. ZIdentity's IdP-specific configurations (Entra, AD FS, Okta) and MFA method configs are partially in scope — references/zidentity/index.md lists the gaps. (Note: ZBI moved to T2; see references/zbi/index.md for that product's documented gaps including Votiro CDR integration, Sandbox+Isolation, Local Browser Rendering, and end-user UX features.)

Do not guess precedence, matching semantics, or evaluation order from first principles. These are exactly the places Zscaler's real behavior diverges from intuition — wrong confident answers here are the failure mode this skill exists to prevent.

Recognizing a deferred topic from frontmatter

Before answering with high confidence, check the relevant reference doc's frontmatter:

Topics this skill cannot answer without tenant access (load-bearing list — when asked about these without _data/snapshot/ populated, decline with a pointer rather than guess):

• The tz / country write-side current behavior on ZIA Location Management (read returns unprefixed; write accepted-form is unverified post-API change)
• Whether VMSS upgrade window behavior on Cloud Connector matches the documented Sunday-midnight-local pattern in your deployment
• Whether the Python SDK Server Group servers[] model gap affects you (TF works fine; Python explicit-server-mode does not)
• Default zsroot password for new Cloud Connector / Branch Connector deployments
• Whether the ZIA showEunatp wire-casing asymmetry (mixed-case on read, uppercase on write) is current API behavior
• Specific cipher / TLS-version posture Zscaler presents at the SSL inspection edge
• Anything labeled confidence: medium + source-tier: code where the SDK is the only source — runtime divergence is possible

This list expands as the skill grows; references/_meta/clarifications.md is the canonical index. When in doubt, prefer "I don't know without your tenant" over a confident guess.

Known open questions

references/_meta/clarifications.md is the canonical index of unresolved questions across the skill — each with a stable ID (zia-03, shared-02, etc.), what resolves it, and which reference doc raised it. When a user's question overlaps a known gap, cite the ID and be explicit that the answer is bounded by that gap.