Zscaler Internet Access integration

The Block in Zscaler Internet Access rule response adds each domain a matched rule cites, with its subdomains, as an IOC in a URL category that a Zscaler Internet Access (ZIA) URL filtering rule blocks. IOCs do not expire. When the category is full, the IOC cited least recently makes way for a new one. The rule decides which alerts trigger the response. Connecting creates the category and the block rule, with no IOCs in them.

Prerequisites

• A Zscaler Internet Access subscription whose tenant is linked to a ZIdentity tenant, so it can be reached through the Zscaler OneAPI.
• A ZIA administrator who can create API roles, and a ZIdentity administrator who can create API clients.
• The network enforcement add-on on the Have I Been Squatted organization, and an organization admin to configure it.

Create an API client

1. In the ZIA Admin Portal, under Administration > Role Management, create an API role with full access to URL Categories and URL Filtering Policy and permission to activate changes. Nothing else is needed.
2. In ZIdentity, open Administration > API > API Clients and select Add API Client. Name it, for example haveibeensquatted.
3. Choose Client secret authentication, assign the ZIA API role from step 1, and save.
4. Copy the client ID and secret. ZIdentity shows the secret once.
5. Note your vanity subdomain: the first label of your ZIdentity sign-in URL, such as acme in acme.zslogin.net.

Connect

1. In the app, open Connectors > Zscaler Internet Access.
2. Select the cloud, then enter the vanity subdomain, the client ID and the secret. You can paste the whole sign-in URL; only the subdomain is kept.
3. Optionally change IOCs to keep (see The IOC queue).
4. Select Connect.

Cloud	ZIdentity domain	API base URL
Commercial	zslogin.net	https://api.zsapi.net
Government	zidentitygov.net	https://api.zscalergov.net
Government (US)	zidentitygov.us	https://api.zscalergov.us

Requests go only to these hosts. The secret is stored server-side and never returned to the browser. Leave the secret blank to keep the saved one; a new client ID, vanity subdomain or cloud needs its own secret.

What connecting creates

Both objects are named after your Have I Been Squatted organization ID, so two organizations, or a test and a production account, connected to the same ZIA tenant never share them. The connector page shows the exact names.

Object	Name
Custom URL category	haveibeensquatted-<organization ID>-iocs
URL filtering block rule	haveibeensquatted-<first 8 characters of the organization ID>-iocs

The rule name is shortened to 31 characters, because Zscaler limits some policy rule names to that length.

Connecting runs these steps and saves the connection only when all of them succeed:

1. Requests a token from your ZIdentity tenant with the client ID and secret.
2. Creates the custom URL category, or adopts it by exact name if it exists. A new category starts with one entry, anchor.zia-queue.haveibeensquatted.com, because ZIA may refuse an empty category.
3. Creates the URL filtering rule with the Block action for the category, at the top of the rule order. A rule with that name is adopted only when it already blocks the category; it is never edited, so you can narrow it to some users or locations.
4. Activates the change (see Activation).

Connecting again repeats the steps and adopts what already exists.

Connection check

Test connection changes nothing. It requests a token, reads the category and the rule, and reads the tenant’s remaining custom URL quota. A failed check pauses blocking until a later check passes.

Result	Meaning
Authentication	ZIdentity rejected the client ID and secret, or the Zscaler API refused the token.
Wrong tenant	No ZIdentity tenant answered for the vanity subdomain on the selected cloud.
Permission missing	The API role cannot manage URL categories or URL filtering rules, or activate changes.
Rate limited	Zscaler throttled the request. Test again in a minute.
Maintenance	ZIA is in maintenance and accepts no changes. Test again later.
Category missing	The IOC category was deleted. Connect again to recreate it.
Not enforced	No enabled block rule references the category. Restore the rule, or delete it and reconnect.
Unreachable	Zscaler timed out, returned a server error, or another change held the tenant’s edit lock.

Add the response to a rule

1. Create or edit a rule and open the Response tab.
2. Select Add action > Block in Zscaler Internet Access.
3. Select the Zscaler Internet Access destination.
4. Save the rule.

The response needs at least one domain condition in the rule, because only cited domain records are blocked.

What is sent

For each active rule alert that cites domain records, Have I Been Squatted takes each distinct cited domain, up to 10 per alert, converts it to punycode, and adds it with a leading dot (.examp1e.com), which ZIA matches for the domain and all its subdomains. The monitored domain and its subdomains are never sent, and email and canary evidence never produce IOCs.

Each delivery reads the category, makes at most one batched addition and one batched removal, activates once, then reads the category back.

The IOC queue

Have I Been Squatted keeps at most IOCs to keep IOCs in the category (1,000 by default, up to 5,000), ordered by when each domain was last cited:

• A newly cited domain joins the front of the queue.
• A domain cited again moves back to the front, so an IOC that keeps appearing in alerts is never the one removed.
• When the queue is full, the IOC cited least recently is removed to make room for each new one. Nothing is removed for any other reason, and nothing expires.

ZIA category entries carry no date or note, so each IOC has a companion entry under zia-queue.haveibeensquatted.com, such as 1791504000-4f3cc009d5c7.zia-queue.haveibeensquatted.com. It records when the domain was last cited and a short fingerprint of the domain. These hosts do not exist, so blocking them has no effect.

Your own entries are left alone

Entries you add to the category by hand have no companion entry, so Have I Been Squatted never removes them and does not count them toward IOCs to keep. Removing an IOC by hand is also fine; its companion entry is cleaned up later.

Quota

A ZIA tenant holds 25,000 custom URLs across all its categories, shared with your own. Each IOC uses two: the domain and its companion entry, so the default of 1,000 IOCs uses 2,000. When the tenant quota has no room, new domains are skipped and the delivery is recorded as failed. Nothing is removed to make room for them, and your entries are never removed.

Activation

ZIA applies a change only once it is activated. Each delivery that changes the category activates once, through the API client’s own session:

• If no other administrator or API client has saved but unactivated changes, the change applies at once.
• If one has, ZIA queues the activation until they activate, or until their session ends: after 30 idle minutes in the Admin Portal by default, or 5 to 20 minutes for an API client. ZIA then applies everything queued together, as it does for any administrator. The delivery records that the activation was queued.
• Have I Been Squatted never uses Force Activate, so it never applies another administrator’s changes before they activate them.

ZIA allows one category edit per second and 40 activations an hour. Each delivery activates at most once, so a burst of alerts can reach that limit; throttled requests are retried once when Zscaler asks to wait ten seconds or less.

If Zscaler rejects a request after an earlier edit applied, Have I Been Squatted still activates what was saved and records the delivery as partly applied.

What is recorded

Have I Been Squatted stores the cloud, the vanity subdomain, the client ID and secret, the category ID and name, the rule ID and name, the queue size, and the time and outcome of the last connection check. For each alert and response it records the delivery status, the domains added, moved to the front, already present, skipped, refused or removed to make room, whether the activation was queued, and, when a delivery fails, a short error code. Tokens and Zscaler response bodies are not stored.

Disable and disconnect

Disable stops new IOCs and keeps the connection and rule responses. A passing connection test turns blocking back on.

Disconnect deletes the stored credentials and removes the Block in Zscaler Internet Access response from every rule, along with those responses’ delivery records.

Neither action changes ZIA. The category, its IOCs and the block rule stay, and keep blocking, until an administrator deletes the rule from the URL filtering policy and the category from URL categories in the ZIA Admin Portal, then activates. To revoke access, delete the API client in ZIdentity.

Limits

• Each delivery requests a new token and makes up to seven API calls.
• IOCs block domains and their subdomains, not single URLs or IP addresses.
• Blocking applies to traffic Zscaler Internet Access inspects.
• Only client secret authentication is supported. Private key (JWT) authentication and the legacy ZIA API key are not.

Note

Only organization admins can view or change the Zscaler Internet Access connection.