Zscaler Digital Experience (ZDX)

Import the hostnames and IP addresses of your Zscaler Digital Experience managed devices into Guard as assets.

The Zscaler Digital Experience (ZDX) integration imports your ZDX managed devices into the Praetorian Guard Platform (PGP). Guard reads each device's hostname and network addresses through Zscaler OneAPI and adds them as assets. This guide walks you through creating a OneAPI client and connecting it to Guard.

What the integration does

Each time the integration runs, Guard signs in to Zscaler OneAPI and:

  1. Lists the devices in your ZDX tenant.
  2. Reads each device's details. A device that ZDX no longer returns is skipped.
  3. Adds each of the device's IPv4 and IPv6 addresses as an asset. When the device's hostname is a fully qualified domain name, such as laptop-42.example.com, Guard records it together with the address. Short hostnames, such as LAPTOP-42, are not recorded.

Guard also drops assets it should not scan:

  • Loopback, link-local, multicast, and unspecified addresses.
  • IP addresses in public cloud provider ranges, and domains that resolve to a public cloud provider.
  • Private IP addresses, such as 10.0.0.0/8 or 192.168.0.0/16, and domains that do not resolve in public DNS.
  • Any single IP address, public or private, that does not answer a single ping within half a second. IP ranges are not pinged.

Device addresses are often private, so this filter drops them by default. To import private and non-responding assets, contact Praetorian support.

The integration only reads from Zscaler. It does not change devices, probes, or settings.

Prerequisites

  • A ZDX tenant that signs in through Zidentity. Guard connects through Zscaler OneAPI, which requires Zidentity. Legacy ZDX API keys are not supported.
  • A Zidentity administrator account that can create API clients.
  • The Zidentity vanity domain for your tenant: the acme part of acme.zslogin.net.
  • Permission to add integrations in Guard.

Step 1: Create a OneAPI client in Zidentity

  1. In the Zidentity admin portal, create an API client.
  2. On the client's Resources tab, assign a read-only ZDX API role.
  3. Save the client, then copy the Client ID and Client Secret and store them safely.

One API client can serve several Zscaler products. To also import ZIA, ZPA, or EASM data through the same integration, assign an API role for each of those products too.

Step 2: Connect Zscaler in Guard

  1. In Guard, go to Integrations and open Cyber Asset Attack Surface Management → Zscaler.
  2. Enter:
    • Client ID: the OneAPI client ID from step 1.
    • Client Secret: the OneAPI client secret from step 1.
    • Vanity Domain: your Zidentity hostname prefix, for example acme. You can also enter the full host, acme.zslogin.net.
  3. Keep ZDX (Digital Experience) selected. EASM and ZIA are also selected by default. Clear any product your API client has no role for.
  4. Click Connect.

Before saving, Guard requests an access token from Zidentity and reads one device from ZDX. Guard checks every product you selected, and stops at the first one that fails, shows the error, and does not save the integration. Guard repeats these checks at the start of every run, so if the client later loses access to one selected product, no product imports until you restore the access or clear that product.

You can add more than one Zscaler integration, for example one per tenant.

Verify the integration

After the first run, go to Assets and search for the public IP address of a ZDX device that is outside cloud provider ranges and answers ping. It should appear as an asset.

Troubleshooting

Message

What to do

Missing Module Selection

Select at least one Zscaler product.

Invalid Format: vanity_domain must be a hostname prefix (acme) or a Zidentity host (acme.zslogin.net)

Enter only the prefix, such as acme, or the host acme.zslogin.net.

Connection Failed: Could not reach the Zscaler API

Guard could not connect to Zidentity. Check the vanity domain, and try again in case of a network problem.

Validation Failed: Zscaler returned HTTP 400 or 404 during validation

Check the vanity domain, client ID, and client secret.

Authentication Failed

Check the client ID, client secret, and vanity domain. If Zidentity issued a token but OneAPI rejected it, confirm your tenant uses Zidentity and OneAPI.

Insufficient Permissions: authenticated but cannot read ZDX inventory

Assign a ZDX API role to the API client in Zidentity.

License Required: the Zscaler ZDX module is not licensed or unavailable

Your tenant does not have ZDX. Clear ZDX (Digital Experience).

An error names a different product, such as EASM or ZIA

That product is selected but your client cannot read it. Clear it, or assign its API role.

Devices are missing from Assets

Their addresses are likely private, in a cloud provider range, or do not answer ping. See What the integration does.

If you need help with this integration, contact support@praetorian.com.