Zscaler ZIA Data Source Plugin for Grafana

Description

The Zscaler ZIA DataSource Plugin is a Grafana backend datasource plugin that enables on-demand querying and visualization of Zscaler Internet Access (ZIA) security posture data inside Grafana panels.

Zscaler Internet Access (ZIA) is a cloud-native security service edge (SSE) platform that enforces internet access policies, inspects traffic, and protects users from threats regardless of location. The plugin connects to the ZIA API via the official Zscaler Go SDK to retrieve organization health, firewall filtering rules, SSL inspection policies, URL filtering rules, data loss prevention (DLP) rules, location infrastructure, user management data, NSS server health, and sandbox detonation quota.

Features

• Query and visualize Zscaler ZIA security posture data directly within Grafana
• Support for multiple data categories:
  • Organization Health: Organization metadata including org ID, cloud name, domain count, HQ location, industry, employee count, and ZPA tenant information
  • Location Infrastructure: Full location details including bandwidth, SSL scan state, firewall settings, VPN status, IPS control, and IPv6 support
  • Firewall Rules: Filtering rules with order, rank, action, state, source/destination IP counts, locations, and departments
  • SSL Inspection: Inspection rules with TLS version constraints, HTTP/2 support, URL category and cloud app counts
  • URL Filtering: URL filtering policies with categories, protocols, block override, time and size quotas
  • DLP Rules: Web DLP rules with severity, OCR, download scan, ZCC notification, and audit email fields
  • User Management: User records with department, group count, admin status, and account type
  • NSS Server Health: NSS log stream server status and health state, filterable by server type
  • Sandbox Quota: Sandbox detonation quota usage, limit, remaining quota, and utilization percentage
• Server-side and client-side filtering for granular data retrieval
• Time range filtering using the Grafana dashboard time picker for rules and sandbox quota
• Lookup by ID or exact name for rules and locations
• OAuth 2.0 authentication via the Zscaler ZIdentity portal
• Automatic rate-limit retry (up to 3 retries via the Zscaler SDK)

Compatibility

Component	Version / Detail
Grafana	>= 12.3.0
Zscaler SDK	zscaler-sdk-go v3 (latest)
Authentication	OAuth 2.0 (Client ID + Secret)

Visuals

Configuration Editor

Query Editor

Installation

Requirements

• Grafana >= 12.3.0
• A Zscaler ZIA tenant with API access enabled
• OAuth 2.0 credentials (Client ID and Client Secret) from the Zscaler ZIdentity portal
• Network connectivity to the Zscaler cloud API

Obtain ZIA API Credentials

1. Log in to your Zscaler ZIdentity portal.
2. Navigate to Administration > OAuth 2.0 Clients (or the equivalent in your tenant).
3. Create a new OAuth 2.0 client and note the Client ID and Client Secret.
4. Assign the required Functional Scopes for the data categories you intend to query:
   • zia.organization — Organization Health
   • zia.locations — Location Infrastructure, Locations Lite
   • zia.firewall — Firewall Rules
   • zia.sslinspect — SSL Inspection
   • zia.urlfiltering — URL Filtering
   • zia.dlp — DLP Rules
   • zia.users — User Management
   • zia.nss — NSS Server Health
   • zia.sandbox — Sandbox Quota
5. Note your organization vanity domain prefix (e.g., acme from acme-admin.zslogin.net).

Install the Plugin

Install the plugin from the Grafana Plugin Catalog or using the Grafana CLI:

grafana cli plugins install crestdata-zscalerzia-datasource

After installation, restart the Grafana server for the plugin to be loaded.

Configure the Data Source

1. In Grafana, navigate to Connections > Data Sources > Add data source.
2. Search for Zscaler ZIA and select it.
3. Fill in the required configuration fields:

Name	Type	Required	Description
Client ID	String	Yes	OAuth 2.0 Client ID from the Zscaler ZIdentity portal
Client Secret	Secure String	Yes	OAuth 2.0 Client Secret from the Zscaler ZIdentity portal
Vanity Domain	String	Yes	Your organization vanity domain prefix (e.g., acme from acme-admin.zslogin.net)
Cloud	String	No	Zscaler cloud environment (default: zscaler.net). Options: zscaler.net, zscalertwo.net, zscalerthree.net

1. Click Save & Test. The health check will authenticate against the Zscaler API and return the connected organization name.

Usage

Query Editor

Once the data source is configured, you can create panels using the query editor with the following parameters:

Parameter	Type	Options / Notes	Default	Description
Query Type	Dropdown	Organization Health, Location Infrastructure, Firewall Rules, SSL Inspection, URL Filtering, DLP Rules, User Management, NSS Server Health, Sandbox Quota	Organization Health	Select the ZIA data category to query
Rule ID	Number	Integer rule ID	—	Fetch a single rule by ID (SSL Inspection, URL Filtering, DLP Rules only). Takes priority over Rule Name.
Rule Name / Object Filter	String	Exact name or partial match depending on query type	—	Filter by name. Behavior varies per query type (see below).
Location ID	Number	Integer location ID	—	Fetch a single location by ID (Location Infrastructure only). Takes priority over Location Name.
Action	Dropdown	All, Allow, Block Drop, Block Reset, Block ICMP, Evaluate Network App	All	Filter firewall rules by action type (Firewall Rules only).
Rule Order	Number	Integer order position	—	Filter firewall rules by rule order (Firewall Rules only).
Location	Dropdown	Populated from your ZIA tenant	All	Filter firewall rules by assigned location (Firewall Rules only).
Department	Dropdown	Populated from your ZIA tenant	All	Filter firewall rules or users by department (Firewall Rules, User Management).
Server Type	Dropdown	All, NSS for Web, NSS for Firewall, VZEN, VZEN SME, VZEN SMLB, Pinned NSS, ADP, ZIRSVR, NSS for ZPA	All	Filter NSS servers by log stream type (NSS Server Health only).
Use Time Filter	Toggle	On / Off	Off	When enabled, restricts results to items whose last_modified timestamp (rules) or start_time (Sandbox Quota) falls within the dashboard time range. Available for Firewall Rules, SSL Inspection, URL Filtering, DLP Rules, and Sandbox Quota. Has no effect when filtering by Rule ID or Rule Name.
SSL Scan Enabled	Boolean	true / false	false	Filter locations where SSL scanning is enabled (Locations Lite only).
Include Sub-Locations	Boolean	true / false	false	Include sub-locations in results (Locations Lite only).
Include Parent Locations	Boolean	true / false	false	Include parent locations in results (Locations Lite only).
Enable IoT	Boolean	true / false	false	Include IoT discovery fields in results (Locations Lite only).

Available Query Types

Organization Health

Returns a single row with organization metadata retrieved from the ZIA organization details API.

Fields returned: org_id, org_name, cloud_name, domain_count, hq_location, country, city, timezone, language, industry, employee_count, zpa_tenant_id, zpa_tenant_cloud

Location Infrastructure

Returns detailed location records from the ZIA location management API.

• Fetch all locations by leaving filters empty
• Fetch a single location by Location ID (takes priority) or exact Location Name

Fields returned: location_id, name, parent_id, country, state, timezone, ip_count, bandwidth_up_mbps, bandwidth_down_mbps, bandwidth_total_mbps, ssl_scan_enabled, firewall_enabled, auth_required, vpn_enabled, ips_control, aup_enabled, xff_forward_enabled, ofw_enabled, ipv6_enabled, profile, description, child_count

Locations Lite

Returns a lightweight subset of location data optimized for security flag review. Supports server-side filtering by SSL scan state, sub-location/parent inclusion, and IoT.

Fields returned: location_id, name, parent_id, timezone, xff_forward_enabled, aup_enabled, caution_enabled, aup_block_internet, aup_force_ssl_inspection, surrogate_ip, surrogate_ip_known_browsers, firewall_enabled, ips_control, zapp_ssl_scan_enabled, ipv6_enabled

Firewall Rules

Returns ZIA firewall filtering rules. Supports server-side filtering by rule name and action, and client-side filtering by location, department, and rule order. Enable Use Time Filter to restrict results to rules whose last_modified timestamp falls within the dashboard time range.

Fields returned: rule_id, name, order, rank, state, action, full_logging, predefined, default_rule, description, last_modified, src_ip_count, dest_ip_count, locations, departments

SSL Inspection

Returns ZIA SSL inspection rules.

• Fetch all rules by leaving filters empty
• Fetch a single rule by Rule ID (takes priority) or exact Rule Name
• Enable Use Time Filter to restrict results (when fetching all rules) to those whose last_modified timestamp falls within the dashboard time range

Fields returned: rule_id, name, state, action, order, rank, default_rule, predefined, min_client_tls, min_server_tls, http2_enabled, url_category_count, cloud_app_count, last_modified

URL Filtering

Returns ZIA URL filtering policy rules.

• Fetch all rules by leaving filters empty
• Fetch a single rule by Rule ID (takes priority) or exact Rule Name
• Enable Use Time Filter to restrict results (when fetching all rules) to those whose last_modified timestamp falls within the dashboard time range

Fields returned: rule_id, name, state, action, order, url_categories, protocols, block_override, time_quota_min, size_quota_kb, time_validity, last_modified, description

DLP Rules

Returns ZIA web DLP rules.

• Fetch all rules by leaving filters empty
• Fetch a single rule by Rule ID (takes priority) or exact Rule Name
• Enable Use Time Filter to restrict results (when fetching all rules) to those whose last_modified timestamp falls within the dashboard time range

Fields returned: rule_id, name, state, action, severity, order, rank, match_only, ocr_enabled, download_scan, no_content_inspect, zcc_notify, auditor_email, engine_count, location_count, department_count, last_modified

User Management

Returns ZIA user records. Supports filtering by name/email (partial match) and department (prefix match via API).

Fields returned: user_id, name, email, is_admin, user_type, deleted, dept_id, dept_name, group_count, comments

NSS Server Health

Returns ZIA NSS (Nanolog Streaming Service) server records. Supports filtering by server type.

Fields returned: server_id, name, status, health_state, server_type, icap_server_id

Sandbox Quota

Returns the ZIA sandbox detonation quota for the current billing period. Enable Use Time Filter (labelled "Filter by Start Time") to restrict results to quota entries whose start_time falls within the dashboard time range.

Fields returned: quota_allowed, quota_used, quota_unused, scale, period_start, quota_pct

Name vs. ID Lookup Behavior

Query Type	ID Filter	Name / Object Filter
Location Infrastructure	Location ID — exact lookup via GetLocation API	Location Name — exact lookup via GetLocationByName API
SSL Inspection	Rule ID — exact lookup	Rule Name — exact lookup via GetByName API
URL Filtering	Rule ID — exact lookup	Rule Name — exact lookup via GetByName API
DLP Rules	Rule ID — exact lookup	Rule Name — exact lookup via GetByName API
Firewall Rules	—	Rule Name — case-insensitive substring match via API
User Management	—	Email / Name — partial match via API
Locations Lite	—	Search — substring match via API

Error Handling and Retry Strategy

Retries are performed automatically by the Zscaler SDK for transient failures:

• HTTP 429 (rate limited) — retried with backoff
• Network/connection-level errors

Max retry attempts: 3 (configured via WithRateLimitMaxRetries).

Non-retryable errors are returned immediately with a descriptive message:

Status Code	Message
401	Unauthorized — session invalid, expired, or wrong Client ID/Secret
403	Access denied — API client is missing the required Functional Scopes
429	Rate limit exceeded

Resources Reference

Resource	Description	Supported Filters
Organization Health	Organization metadata: ID, cloud, domains, HQ, industry, employee count, ZPA tenant	None
Location Infrastructure	Full location details: bandwidth, SSL, firewall, VPN, IPS, AUP, IPv6	Location ID, Location Name
Firewall Rules	Filtering rules with order, rank, state, action, source/destination IP counts, locations, departments	Rule Name, Action, Time Range (last_modified)
SSL Inspection	Inspection rules with TLS version constraints, HTTP/2, URL categories, cloud apps	Rule ID, Rule Name, Time Range (last_modified)
URL Filtering	URL filtering policies with categories, protocols, time and size quotas	Rule ID, Rule Name, Time Range (last_modified)
DLP Rules	Web DLP rules with severity, OCR, download scan, ZCC notification, audit email	Rule ID, Rule Name, Time Range (last_modified)
User Management	User records with department, group count, admin flag, account type	Name, Department
NSS Server Health	NSS log stream server status and health state	Server Type
Sandbox Quota	Sandbox detonation quota: allowed, used, unused, utilization percentage	Time Range (start_time)

Limitations and Recommendations

API Considerations:

• The plugin uses OAuth 2.0 via the Zscaler ZIdentity portal. Ensure the OAuth client has the correct Functional Scopes for each query type you intend to use. Missing scopes result in HTTP 403 errors.

Performance Tips:

• Use Rule ID or exact name lookups instead of fetching all rules when querying a specific policy in large tenants.
• Use Department and Location filters on Firewall Rules queries to reduce result set size in environments with many rules.
• Use Locations Lite instead of Location Infrastructure when only security flag data is needed — it is faster and returns a smaller payload.

Support

For issues, questions, or feature requests, please open an issue in this repository.

Roadmap

See the open issues for a list of proposed features and known issues.

Contributing

Contributions are welcome! To get started with development:

cd crestdata-zscalerzia-datasource

# Frontend
npm install
npm run dev        # development mode with watch
npm run build      # production build

# Backend
mage -v            # build backend binaries

# Tests
npm run test       # frontend tests (Jest)
npm run test:ci    # CI mode
go test ./...      # backend tests

# Linting
npm run lint
npm run lint:fix

# Local Grafana instance (Docker)
npm run server

# E2E tests (Playwright)
npm run e2e

Before submitting a pull request:

1. Run the linter and ensure all tests pass.
2. Validate the plugin using the Grafana Plugin Validator.
3. Ensure any changes to plugin.json are intentional — a Grafana server restart is required after such changes.

Authors and Acknowledgment

Developed by Crest Data.

License

This plugin is distributed under the EULA License. See the LICENSE file for details.

References

• Zscaler Internet Access Product Page
• Zscaler ZIA API Reference
• Zscaler ZIdentity Portal
• Zscaler Go SDK
• Grafana Plugin Development
• Grafana Plugin Publishing Best Practices