> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zscaler Integration

> Connect Cotool to Zscaler for ZIA, ZPA, ZDX, and Client Connector access, detection-rule sync, and alert-driven response agents

## 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:

### Option 1: Cloud NSS alert feed (recommended)

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.