Skip to main content

​
Overview

The Zscaler integration gives Cotool agents access to ZIA (Internet Access), ZPA (Private Access), ZDX (Digital Experience), and Zscaler Client Connector through Zscaler’s OneAPI, and lets Zscaler push alert events into Cotool to trigger response agents. It provides three capabilities:
  1. Agent tools — URL classification and Sandbox verdicts, threat blocklist management, ZIA/ZPA policy inspection, config activation, user directory, admin audit logs, ZDX alerts and device health, and Client Connector device management.
  2. Detection-rule sync — ZIA policy rules, ZIA Security & UEBA alert rules, and ZPA AppProtection profiles are synced weekly into Cotool’s detection-rule repository, where they appear on the Detections overview and threat-model coverage board.
  3. Alert ingestion — a branded Zscaler trigger source receives alert events pushed from Zscaler (Cloud NSS feeds or alert-rule webhooks) and can start a response agent, creating a Cotool alert for each event.

​
Connecting the integration

The integration uses a Zidentity OneAPI client (client-credentials OAuth). Tenants that have not migrated to Zidentity are not supported.
  1. In the ZIdentity Admin Portal, go to Integration > API Clients and create an API client.
  2. Assign it roles covering the products you use:
    • ZIA: URL lookup, security policy, policy activation, user management (read), and audit reports.
    • ZPA / ZDX / ZCC: the corresponding read (and for ZCC device removal, write) roles.
  3. In Cotool, open Tools > Zscaler > Connect and enter:
    • Client ID and Client Secret from the API client.
    • Vanity domain — the acme in acme.zslogin.net.
    • Cloud — production (default) or beta.
    • ZPA customer ID — optional; required only for ZPA tools (find it in the ZPA Admin Portal under Company Details).
Cotool validates the credentials against Zscaler before saving them.

​
Alert ingestion (response agent trigger)

Zscaler delivers alert events by push only. Create a Zscaler trigger on a response agent (Agent > Triggers > Add Trigger > Zscaler); Cotool generates a webhook URL and a token. Then point one or both Zscaler channels at it:
  1. In ZIA, go to Administration > Nanolog Streaming Service > Cloud NSS Feeds and add a feed.
  2. Set SIEM Type to Other, the log type to Alert (optionally add the UEBA alert feeds), and the output format to JSON.
  3. Set the API URL to the trigger’s webhook URL.
  4. Add an HTTP header X-Cotool-Webhook-Token with the trigger’s token.
  5. Activate the change.
Cloud NSS is a separately licensed Zscaler feature. Feeds can also be created programmatically via POST /zia/api/v1/nssFeeds.

​
Option 2: ZIA alert-rule webhooks

  1. In ZIA, go to Administration > Alerts and add a webhook destination pointing at the trigger’s webhook URL, using bearer authentication with the trigger’s token.
  2. Attach the webhook to the Security Alert / UEBA rules you want to route to Cotool.

​
Notes

  • Keep Create Alert enabled on the trigger so each event mints a Cotool alert and starts the response agent. Incoming alerts are automatically linked to synced Zscaler detection rules by name.
  • ZDX alerts have no webhook — they are pull-only and covered by the zscaler_zdx_get_alerts agent tool.
  • ZPA has no alert channel; its session logs stream only to a self-hosted LSS collector.

​
Detection-rule sync

Once connected, the weekly classification job ingests:
  • ZIA policy rules — URL filtering, firewall filtering, DNS control, IPS control, Sandbox, web DLP, and SSL inspection rules.
  • ZIA alerting rules — alert definitions, Security Alert rules, and UEBA rules (these are what fire into the webhook trigger).
  • ZPA AppProtection — inspection profiles and custom controls (requires the ZPA customer ID).
Rule inventories the tenant is not licensed for are skipped automatically.

​
Local development

Populate cogent-backend/.env with ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAIN (optionally ZSCALER_CLOUD, ZSCALER_ZPA_CUSTOMER_ID) and run npm run bootstrap-tools <API_KEY> from the repo root.