zscaler

name: zscaler description: > Answer questions about the Zscaler portfolio — full operational depth (T1, with SDK / TF / OneAPI exposure) on ZIA, ZPA (including AppProtection inline WAF/IPS sub-component and Browser Access), ZCC (Client Connector), ZDX (Digital Experience — T1 borderline, observability layer per 2026-05-04 verification gate), ZIdentity (unified identity + OneAPI authentication + step-up auth), and Cloud & Branch Connector (ZTW/ZTC — VM-based traffic forwarding for cloud workloads and branch offices); programmable-but-shallow (T2) on ZBI (Zero Trust Browser / Cloud Browser Isolation) and ZWA (Workflow Automation — DLP incident lifecycle); plus extended awareness with reasoning docs (T3, portal-only / no SDK) on Deception (decoys/honeypots for post-perimeter detection), Risk360 (cyber risk quantification / Monte Carlo / CISO board reporting), the AI Security family (AI Guard runtime guardrails for LLM prompt-injection / jailbreak / sensitive-data / toxicity / refusal detection plus AI Red Teaming / AI Guardrails / four-pillar governance), ZMS (workload microsegmentation east-west, host-agent + WFP/nftables enforcement), ZSDK, AEM, DSPM, ITDR, UVM, Zscaler Cellular, Experience Center, Breach Predictor, Business Insights, SOC Workbench, and Zero Trust Branch; plus paragraph-level awareness (T4) of Resilience, BCC, CTEM, Cloud Protection, Posture Control, M365 Copilot, Red Canary MDR, MTH, B2B, ZINS (shadow-IT NSS Collector), EASM, and Federal Cloud variants. Covers URL category coverage, URL filtering rule precedence, wildcard matching semantics, SSL inspection ordering, cloud app control interaction with URL filtering, DLP three-layer model, sandbox / malware / ATP, firewall filtering, ZPA app-segment matching and policy evaluation order, AppProtection profiles / paranoia levels, Browser Access wildcard certificate rules, ZCC forwarding-profile / trusted-network decisions (which decide whether traffic reaches ZIA or ZPA in the first place), ZDX score / probe / diagnostic-session questions about user experience, browser isolation (Isolate action, Smart Browser Isolation, isolation profiles), Cloud Connector provisioning and activation, and Zscaler portfolio breadth ("what is X?", "does Zscaler do Y?"). Use whenever the user mentions Zscaler, ZIA, ZPA, ZCC, ZDX, ZBI, ZWA, ZTW, ZTC, CBC, Zero Trust Browser, Cloud Browser Isolation, Client Connector, AppProtection, Browser Access, Deception, Risk360, AI Guard, AI Guardrails, AI Red Teaming, AI Security, ZMS, microsegmentation, east-west traffic, ZINS, EASM, URL categories, URL filtering, cloud app control, SSL inspection, DLP, sandbox, app segments, forwarding profiles, trusted networks, ZDX score, probes, diagnostic sessions / deeptraces, isolation profiles, prompt injection, jailbreak detection, LLM guardrails, or asks "is $URL covered / blocked / allowed". Also use for "why does this rule win", "what happens when these policies overlap", "why is this user's app slow", "what happens when traffic gets isolated", "what is $product", or "does Zscaler have something for $use-case" questions, even if the user does not explicitly name Zscaler.

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 a _data/snapshot/ populated by the refresh scripts. Public upstream does not track _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 for a snapshot first

Before answering tenant-specific questions, check whether _data/snapshot/ has any runtime data:

find _data/snapshot -mindepth 1 -type f -print -quit

If empty, say so explicitly (see When to decline) and still answer the general case where possible. If populated, read the relevant JSON (_data/snapshot/<cloud>/zia/url-categories.json, _data/snapshot/<cloud>/zia/url-filtering-rules.json, _data/snapshot/<cloud>/zpa/app-segments.json, etc.) and cite the specific rule IDs you used.

_data/schemas/ is a separate cache for log-schema decompositions, query skeletons, and script-generated reports (gitignored; 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 _data/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 _data/iac/ for env-specific answers and cite the reference for context.

find _data/iac -mindepth 1 -type f -print -quit   # check before assuming vendor source reflects this fork's deployment

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. Only read more than one if the question genuinely spans them.

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.

If you are an AI agent, prefer references/_meta/agent-patterns.md over the prose runbooks below. It contains typed Python functions for the same diagnostic / recovery flows in copy-pasteable form: detect_cloud(), is_gov_cloud(), detect_auth_framework(), smoke_test_creds(), enumerate_endpoints(), interpret_error(), plus a composite diagnose_tenant(). The canonical implementation lives at scripts/agent_patterns.py. Lift functions verbatim or import agent_patterns as ap.

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, check references/_meta/clarifications.md for the question's domain — zia-*, zpa-*, shared-*, log-*. Summaries distil the doc; clarifications flag where the doc's cheerful prose hides an unresolved ambiguity. Cite the clarification ID in your answer when one applies 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, snapshot empty — say so directly, and still answer the general case if there is one.
• 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 — architecture, policy integration, isolation profiles) and ZWA (Workflow Automation — DLP incident lifecycle). Reference docs cover the SDK surface, but coverage is thin compared to T1. Answer at confidence: medium-to-high for documented surface; flag gaps explicitly when the question pushes beyond what the reference covers.
• T3 — extended awareness, no SDK (reasoning doc or portfolio-map entry, portal-only) — Deception, Risk360, AI Security family (AI Guard / AI Guardrails / AI Red Teaming), ZMS (microsegmentation), ZSDK, AEM, DSPM, ITDR, UVM, Zscaler Cellular, Experience Center, Breach Predictor, Business Insights, SOC Workbench, and Zero Trust Branch. The reasoning docs at references/deception/, references/risk360/, references/ai-security/, and references/zms/ cover architecture, capabilities, and edge cases for those four; the rest are portfolio-map entries only. None of these products are configurable via SDK / TF. Answer at confidence: medium and explicitly note "portal-only configuration, no SDK module". Do NOT fabricate field names, API endpoints, or programmatic config patterns. Concepts and behaviors yes; API specifics no.
• 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), EASM, 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.