# Zscaler

> Manage Zscaler Internet Access: URL categories, the allow and deny lists, URL filtering rules and activation, look up users and URLs, and start workflows when users, rules or pending changes appear.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/zscaler

## Actions

### Activate changes

Activate every saved change in Zscaler Internet Access, so it reaches traffic. This includes changes other admins have saved.

**Inputs**: None.

**Outputs**

- `pending` (true/false): True while changes wait
- `status` (text): ACTIVE, PENDING (changes wait) or INPROGRESS

**Example output**

```json
{
  "pending": false,
  "status": "ACTIVE"
}
```

### Add URLs to allowlist

Add URLs to the allowlist, so threat scanning skips them. It holds up to 255. Takes effect once changes are activated.

**Inputs**

- URLs (`urls`, list, required): The URLs or domains to add, one per row.

**Outputs**

- `added` (list): The URLs added
- `count` (number): How many URLs the allowlist holds
- `note` (text): Whether the change waits for activation, or that nothing changed
- `unchanged` (list): The URLs given that were already as asked
- `urls` (list): Every URL on the allowlist now

**Example output**

```json
{
  "added": [
    "example.net"
  ],
  "count": 2,
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console.",
  "unchanged": [],
  "urls": [
    "example.com",
    "example.net"
  ]
}
```

### Add URLs to denylist

Block URLs by adding them to the denylist. Takes effect once changes are activated.

**Inputs**

- URLs (`urls`, list, required): The URLs or domains to block, one per row.

**Outputs**

- `added` (list): The URLs added
- `count` (number): How many URLs the denylist holds
- `note` (text): Whether the change waits for activation, or that nothing changed
- `unchanged` (list): The URLs given that were already as asked
- `urls` (list): Every URL on the denylist now

**Example output**

```json
{
  "added": [
    "example.net"
  ],
  "count": 2,
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console.",
  "unchanged": [],
  "urls": [
    "example.com",
    "example.net"
  ]
}
```

### Add URLs to URL category

Add URLs to a URL category, keeping the ones it has. Takes effect once changes are activated.

**Inputs**

- URL category (`category_id`, text, required): The category. Pick one, or give its id.
- URLs (`urls`, list, required): The URLs and domains to add, one per row, such as example.com, or .example.com for it and every subdomain.

**Outputs**

- `added` (list): The URLs added
- `category` (object): The URL category as it is now
- `note` (text): Whether the change waits for activation, or that nothing changed
- `unchanged` (list): The URLs given that were already as asked

**Example output**

```json
{
  "added": [
    "vendor.example.org"
  ],
  "category": {
    "configuredName": "Approved vendors",
    "customCategory": true,
    "customUrlsCount": 2,
    "dbCategorizedUrls": [],
    "description": "Sites staff may always reach",
    "editable": true,
    "id": "CUSTOM_01",
    "ipRanges": [],
    "keywords": [],
    "superCategory": "USER_DEFINED",
    "type": "URL_CATEGORY",
    "urls": [
      ".example.com",
      "vendor.example.org"
    ],
    "val": 128
  },
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console.",
  "unchanged": []
}
```

### Create URL category

Create a custom URL category holding the URLs given, for URL filtering and other policies to use. It takes effect once changes are activated.

**Inputs**

- Name (`name`, text, required): The category's name, as admins will see it.
- URLs (`urls`, list, required): The URLs and domains in the category, one per row, such as example.com, or .example.com for it and every subdomain.
- Description (`description`, text): What the category is for.

**Outputs**

- `category` (object): The new URL category
- `note` (text): Whether the change waits for activation, or that nothing changed

**Example output**

```json
{
  "category": {
    "configuredName": "Approved vendors",
    "customCategory": true,
    "customUrlsCount": 2,
    "dbCategorizedUrls": [],
    "description": "Sites staff may always reach",
    "editable": true,
    "id": "CUSTOM_01",
    "ipRanges": [],
    "keywords": [],
    "superCategory": "USER_DEFINED",
    "type": "URL_CATEGORY",
    "urls": [
      ".example.com",
      "vendor.example.org"
    ],
    "val": 128
  },
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console."
}
```

### Delete URL category

Delete one of your organization's custom URL categories. A category a rule still uses can't be deleted. Takes effect once changes are activated.

**Inputs**

- URL category (`category_id`, text, required): The custom category to delete. Pick one, or give its id, such as CUSTOM_01.

**Outputs**

- `category_id` (text): The deleted category's id
- `deleted` (true/false): True once deleted
- `note` (text): Whether the change waits for activation, or that nothing changed

**Example output**

```json
{
  "category_id": "CUSTOM_01",
  "deleted": true,
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console."
}
```

### Get activation status

Find out whether saved changes are waiting to be activated.

**Inputs**: None.

**Outputs**

- `pending` (true/false): True while changes wait
- `status` (text): ACTIVE, PENDING (changes wait) or INPROGRESS

**Example output**

```json
{
  "pending": true,
  "status": "PENDING"
}
```

### Get allowlist

Get the allowlist: URLs the malware, advanced threat and sandbox policies don't scan.

**Inputs**: None.

**Outputs**

- `count` (number): How many URLs it holds
- `urls` (list): The URLs on the allowlist

**Example output**

```json
{
  "count": 1,
  "urls": [
    "example.com"
  ]
}
```

### Get denylist

Get the denylist: URLs your organization blocks outright.

**Inputs**: None.

**Outputs**

- `count` (number): How many URLs it holds
- `urls` (list): The URLs on the denylist

**Example output**

```json
{
  "count": 1,
  "urls": [
    "blocked.example.com"
  ]
}
```

### Get sandbox report

Get the Cloud Sandbox's verdict on a file by its MD5 hash: malicious, suspicious or benign, its threat score and the file's details.

**Inputs**

- MD5 hash (`md5`, text, required): The file's MD5 hash: 32 letters and digits.
- Detail (`details`, text): A summary, or the full report. Defaults to the summary. One of: `summary` (Summary (default)), `full`.

**Outputs**

- `found` (true/false): False when there is no report
- `md5` (text): The hash looked up
- `message` (text): Why there is no report, when there isn't one
- `report` (object): The report: its summary, verdict and file details

**Example output**

```json
{
  "found": true,
  "md5": "3e1b3e2c7e2a5d4c9f0a1b2c3d4e5f60",
  "message": "",
  "report": {
    "Classification": {
      "Category": "MALWARE_BOTNET",
      "DetectedMalware": "Trojan.Generic",
      "Score": 100,
      "Type": "MALICIOUS"
    },
    "FileProperties": {
      "DigitalCerificate": "",
      "FileSize": 405504,
      "FileType": "exe",
      "Issuer": "",
      "MD5": "3e1b3e2c7e2a5d4c9f0a1b2c3d4e5f60",
      "RootCA": "",
      "SHA1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
      "SSDeep": "6144:abc",
      "Sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    },
    "Summary": {
      "Category": "EXECUTABLE",
      "Duration": 312000,
      "FileType": "exe",
      "StartTime": 1762905600,
      "Status": "COMPLETED"
    }
  }
}
```

### Get URL category

Get one URL category with its custom URLs, keywords and IP ranges.

**Inputs**

- URL category (`category_id`, text, required): The category. Pick one, or give its id.

**Outputs**

- `category` (object): The URL category

**Example output**

```json
{
  "category": {
    "configuredName": "Approved vendors",
    "customCategory": true,
    "customUrlsCount": 2,
    "dbCategorizedUrls": [],
    "description": "Sites staff may always reach",
    "editable": true,
    "id": "CUSTOM_01",
    "ipRanges": [],
    "keywords": [],
    "superCategory": "USER_DEFINED",
    "type": "URL_CATEGORY",
    "urls": [
      ".example.com",
      "vendor.example.org"
    ],
    "val": 128
  }
}
```

### Get URL filtering rule

Get one URL filtering rule with its conditions and action.

**Inputs**

- URL filtering rule (`rule_id`, text, required): The rule. Pick one, or give its id.

**Outputs**

- `rule` (object): The rule

**Example output**

```json
{
  "rule": {
    "action": "BLOCK",
    "departments": [
      {
        "id": 81896,
        "name": "Sales"
      }
    ],
    "description": "No gambling sites at work",
    "groups": [],
    "id": 1203,
    "lastModifiedBy": {
      "id": 4512,
      "name": "admin@example.com"
    },
    "lastModifiedTime": 1762905600,
    "locations": [],
    "name": "Block gambling",
    "order": 1,
    "protocols": [
      "HTTPS_RULE",
      "HTTP_RULE"
    ],
    "rank": 7,
    "requestMethods": [
      "GET",
      "POST"
    ],
    "state": "ENABLED",
    "urlCategories": [
      "GAMBLING"
    ],
    "users": []
  }
}
```

### Get user

Get one user with their email, department and groups.

**Inputs**

- User (`user`, text, required): The user. Pick one, or give their id from 'List users'.

**Outputs**

- `user` (object): The user

**Example output**

```json
{
  "user": {
    "adminUser": false,
    "comments": "",
    "deleted": false,
    "department": {
      "id": 81896,
      "name": "Sales"
    },
    "email": "jo@example.com",
    "groups": [
      {
        "id": 81900,
        "name": "Finance"
      }
    ],
    "id": 70021,
    "name": "Jo Bloggs",
    "type": ""
  }
}
```

### List departments

List departments, optionally matching a search. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Search (`search`, text): Only those whose name matches this text.
- Page (`page`, number): Which page to get, from 1. Use the 'next_page' an earlier run gave to read on. At least 1.
- Page size (`page_size`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000.

**Outputs**

- `count` (number): How many came back
- `departments` (list): The departments
- `next_page` (number): The next page to read, or 0 when this was the last
- `page` (number): The page read

**Example output**

```json
{
  "count": 1,
  "departments": [
    {
      "comments": "",
      "deleted": false,
      "id": 81896,
      "idpId": 0,
      "name": "Sales"
    }
  ],
  "next_page": 0,
  "page": 1
}
```

### List firewall rules

List the cloud firewall rules with their order, action, state and what each matches.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back
- `rules` (list): The firewall rules

**Example output**

```json
{
  "count": 1,
  "rules": [
    {
      "action": "BLOCK_DROP",
      "defaultRule": false,
      "departments": [],
      "description": "",
      "destAddresses": [],
      "destCountries": [],
      "groups": [],
      "id": 2201,
      "lastModifiedBy": {
        "id": 4512,
        "name": "admin@example.com"
      },
      "lastModifiedTime": 1762905600,
      "locations": [],
      "name": "Block outbound SMB",
      "nwServices": [
        {
          "id": 774,
          "name": "SMB"
        }
      ],
      "order": 1,
      "predefined": false,
      "rank": 7,
      "srcIps": [],
      "state": "ENABLED",
      "users": []
    }
  ]
}
```

### List groups

List user groups, optionally matching a search. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Search (`search`, text): Only those whose name matches this text.
- Page (`page`, number): Which page to get, from 1. Use the 'next_page' an earlier run gave to read on. At least 1.
- Page size (`page_size`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000.

**Outputs**

- `count` (number): How many came back
- `groups` (list): The groups
- `next_page` (number): The next page to read, or 0 when this was the last
- `page` (number): The page read

**Example output**

```json
{
  "count": 1,
  "groups": [
    {
      "comments": "",
      "id": 81900,
      "idpId": 0,
      "name": "Finance"
    }
  ],
  "next_page": 0,
  "page": 1
}
```

### List locations

List locations (offices and sites) with their IP addresses and settings, optionally matching a search. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Search (`search`, text): Only those whose name matches this text.
- Page (`page`, number): Which page to get, from 1. Use the 'next_page' an earlier run gave to read on. At least 1.
- Page size (`page_size`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000.

**Outputs**

- `count` (number): How many came back
- `locations` (list): The locations
- `next_page` (number): The next page to read, or 0 when this was the last
- `page` (number): The page read

**Example output**

```json
{
  "count": 1,
  "locations": [
    {
      "authRequired": true,
      "country": "UNITED_STATES",
      "description": "",
      "id": 30441,
      "ipAddresses": [
        "203.0.113.10"
      ],
      "ipsControl": true,
      "name": "Head office",
      "ofwEnabled": true,
      "parentId": 0,
      "ports": [],
      "profile": "CORPORATE",
      "sslScanEnabled": true,
      "tz": "UNITED_STATES_AMERICA_NEW_YORK",
      "xffForwardEnabled": false
    }
  ],
  "next_page": 0,
  "page": 1
}
```

### List URL categories

List the URL categories: Zscaler's own and your organization's custom ones, with their custom URLs and keywords.

**Inputs**

- Only custom categories (`custom_only`, true/false): Turn on to list only the categories your organization made.

**Outputs**

- `categories` (list): The URL categories
- `count` (number): How many came back

**Example output**

```json
{
  "categories": [
    {
      "configuredName": "Approved vendors",
      "customCategory": true,
      "customUrlsCount": 2,
      "dbCategorizedUrls": [],
      "description": "Sites staff may always reach",
      "editable": true,
      "id": "CUSTOM_01",
      "ipRanges": [],
      "keywords": [],
      "superCategory": "USER_DEFINED",
      "type": "URL_CATEGORY",
      "urls": [
        ".example.com",
        "vendor.example.org"
      ],
      "val": 128
    }
  ],
  "count": 1
}
```

### List URL filtering rules

List the URL filtering rules with their order, action, state and the categories, users and locations each covers.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back
- `rules` (list): The URL filtering rules

**Example output**

```json
{
  "count": 1,
  "rules": [
    {
      "action": "BLOCK",
      "departments": [
        {
          "id": 81896,
          "name": "Sales"
        }
      ],
      "description": "No gambling sites at work",
      "groups": [],
      "id": 1203,
      "lastModifiedBy": {
        "id": 4512,
        "name": "admin@example.com"
      },
      "lastModifiedTime": 1762905600,
      "locations": [],
      "name": "Block gambling",
      "order": 1,
      "protocols": [
        "HTTPS_RULE",
        "HTTP_RULE"
      ],
      "rank": 7,
      "requestMethods": [
        "GET",
        "POST"
      ],
      "state": "ENABLED",
      "urlCategories": [
        "GAMBLING"
      ],
      "users": []
    }
  ]
}
```

### List users

List users with their email, department and groups, by name, department or group. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Name (`name`, text): Only users whose name starts with this.
- Department (`department`, text): Only users in a department whose name starts with this.
- Group (`group`, text): Only users in a group whose name starts with this.
- Page (`page`, number): Which page to get, from 1. Use the 'next_page' an earlier run gave to read on. At least 1.
- Page size (`page_size`, number): How many to return, 1 to 10,000. Defaults to 100. From 1 to 10000.

**Outputs**

- `count` (number): How many came back
- `next_page` (number): The next page to read, or 0 when this was the last
- `page` (number): The page read
- `users` (list): The users

**Example output**

```json
{
  "count": 1,
  "next_page": 0,
  "page": 1,
  "users": [
    {
      "adminUser": false,
      "comments": "",
      "deleted": false,
      "department": {
        "id": 81896,
        "name": "Sales"
      },
      "email": "jo@example.com",
      "groups": [
        {
          "id": 81900,
          "name": "Finance"
        }
      ],
      "id": 70021,
      "name": "Jo Bloggs",
      "type": ""
    }
  ]
}
```

### Look up URL categories

Find which URL categories Zscaler files each URL under, including security categories such as malware or phishing.

**Inputs**

- URLs (`urls`, list, required): Up to 100 URLs or domains, one per row.

**Outputs**

- `count` (number): How many came back
- `results` (list): Each URL and its categories

**Example output**

```json
{
  "count": 1,
  "results": [
    {
      "application": "",
      "url": "example.com",
      "urlClassifications": [
        "WEB_SEARCH"
      ],
      "urlClassificationsWithSecurityAlert": []
    }
  ]
}
```

### Remove URLs from allowlist

Take URLs off the allowlist, so threat scanning covers them again. Takes effect once changes are activated.

**Inputs**

- URLs (`urls`, list, required): The URLs to take off, one per row, exactly as listed.

**Outputs**

- `count` (number): How many URLs the allowlist holds
- `note` (text): Whether the change waits for activation, or that nothing changed
- `removed` (list): The URLs removed
- `unchanged` (list): The URLs given that were already as asked
- `urls` (list): Every URL on the allowlist now

**Example output**

```json
{
  "count": 2,
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console.",
  "removed": [
    "example.net"
  ],
  "unchanged": [],
  "urls": [
    "example.com",
    "example.net"
  ]
}
```

### Remove URLs from denylist

Unblock URLs by taking them off the denylist. Takes effect once changes are activated.

**Inputs**

- URLs (`urls`, list, required): The URLs to take off, one per row, exactly as listed.

**Outputs**

- `count` (number): How many URLs the denylist holds
- `note` (text): Whether the change waits for activation, or that nothing changed
- `removed` (list): The URLs removed
- `unchanged` (list): The URLs given that were already as asked
- `urls` (list): Every URL on the denylist now

**Example output**

```json
{
  "count": 2,
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console.",
  "removed": [
    "example.net"
  ],
  "unchanged": [],
  "urls": [
    "example.com",
    "example.net"
  ]
}
```

### Remove URLs from URL category

Take URLs out of a URL category, keeping the rest. A category must keep at least one URL, keyword or IP range. Takes effect once changes are activated.

**Inputs**

- URL category (`category_id`, text, required): The category. Pick one, or give its id.
- URLs (`urls`, list, required): The URLs to take out, one per row, exactly as listed.

**Outputs**

- `category` (object): The URL category as it is now
- `note` (text): Whether the change waits for activation, or that nothing changed
- `removed` (list): The URLs removed
- `unchanged` (list): The URLs given that were already as asked

**Example output**

```json
{
  "category": {
    "configuredName": "Approved vendors",
    "customCategory": true,
    "customUrlsCount": 2,
    "dbCategorizedUrls": [],
    "description": "Sites staff may always reach",
    "editable": true,
    "id": "CUSTOM_01",
    "ipRanges": [],
    "keywords": [],
    "superCategory": "USER_DEFINED",
    "type": "URL_CATEGORY",
    "urls": [
      ".example.com",
      "vendor.example.org"
    ],
    "val": 128
  },
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console.",
  "removed": [
    "vendor.example.org"
  ],
  "unchanged": []
}
```

### Turn URL filtering rule on or off

Enable or disable a URL filtering rule, leaving the rest of it as it is. Takes effect once changes are activated.

**Inputs**

- URL filtering rule (`rule_id`, text, required): The rule. Pick one, or give its id.
- State (`state`, text, required): Enabled to turn the rule on, Disabled to turn it off. One of: `ENABLED`, `DISABLED`.

**Outputs**

- `changed` (true/false): False when the rule was already in that state
- `note` (text): Whether the change waits for activation, or that nothing changed
- `rule` (object): The rule as it is now

**Example output**

```json
{
  "changed": true,
  "note": "Saved in Zscaler. It reaches traffic once changes are activated: run 'Activate changes', or activate them in the Zscaler Admin Console.",
  "rule": {
    "action": "BLOCK",
    "departments": [
      {
        "id": 81896,
        "name": "Sales"
      }
    ],
    "description": "No gambling sites at work",
    "groups": [],
    "id": 1203,
    "lastModifiedBy": {
      "id": 4512,
      "name": "admin@example.com"
    },
    "lastModifiedTime": 1762905600,
    "locations": [],
    "name": "Block gambling",
    "order": 1,
    "protocols": [
      "HTTPS_RULE",
      "HTTP_RULE"
    ],
    "rank": 7,
    "requestMethods": [
      "GET",
      "POST"
    ],
    "state": "ENABLED",
    "urlCategories": [
      "GAMBLING"
    ],
    "users": []
  }
}
```
