Publisher: Splunk
Connector Version: 2.3.1
Product Vendor: Zscaler
Product Name: Zscaler
Product Version Supported (regex): ".*"
Minimum Product Version: 5.2.0
This app implements containment and investigative actions on Zscaler
Below points are considered for providing the URL Category parameter value.
-
Entire URL category string has to be mentioned in block letters
-
The most child category on UI has to be passed as the URL category parameter value to the action
-
From the URL category value on UI, every space has to be replaced by an underscore '_' before passing it in the action's parameter value
- For example, Alternate Lifestyle on UI becomes ALTERNATE_LIFESTYLE
-
When you specify a url_category , you can give it either the name you created or the ID which is assigned to it from Zscaler. The search will first search for the name, as opposed to the ID. So if you create a category phantom-block , you could use either phantom-block or CUSTOM_** . The name for these is case sensitive.
The following are considered for providing the URL parameter value.
- The comma-separated values of URL should correctly be given e.g. test.com,test1.com else the Phantom framework's parameter validator will return the error mentioning Exception occurred: string index out of range .
Configure and set up permissions for the lookup_url action
- Login to Zscaler UI using the Administrator credentials.
- Once logged in, go to Administration -> Role Management section.
- Click on the Edit icon beside the role that your account uses to configure the test connectivity.
- Go to the Functional Scope section, enable Security if disabled, and save it.
The above steps would help run the Lookup URL action as expected.
The Sandbox Submission API requires a separate API key and uses a different host (csbapi.[zscaler-cloud-name]). For the submit_file action, the sandbox_base_url and sandbox_api_token asset configuration parameters should be configured. These two asset parameters won't affect test_connectivity. Follow the below steps to fetch these credentials for the submit_file action
- Log in to the ZIA Admin Portal using your admin credentials.
- Once logged in, go to Administration -> Cloud Service API Key Management section. In order to view the Cloud Service API Key Management page, the admin must be assigned an admin role.
- For the Cloud Sandbox Submission API used in this action, the base URL and token are displayed on the Sandbox Submission API Token tab.
- The base URL and token displayed here can be configured in the asset parameters in sandbox_base_url and sandbox_api_token parameters respectively and will be used for the submit_file action.
The above steps would help run the Submit File action as expected.
NOTE: This action would work according to the API behavior
Port Information
The app uses HTTP/ HTTPS protocol for communicating with the Zscaler server. Below are the default ports used by Splunk SOAR.
        Service Name | Transport Protocol | Port |
---|---|---|
        http | tcp | 80 |
        https | tcp | 443 |
The below configuration variables are required for this Connector to operate. These variables are specified when configuring a Zscaler asset in SOAR.
VARIABLE | REQUIRED | TYPE | DESCRIPTION |
---|---|---|---|
base_url | required | string | Base URL (e.g. https://admin.zscaler_instance.net) |
api_key | required | password | API Key |
username | required | string | Username |
password | required | password | Password |
sandbox_base_url | optional | string | Sandbox Base URL |
sandbox_api_token | optional | password | Sandbox API Token |
test connectivity - Validate the asset configuration for connectivity using supplied configuration
get report - Fetch sandbox report for provided md5 file hash
list url categories - List all URL categories
block ip - Block an IP
block url - Block a URL
unblock ip - Unblock an IP
unblock url - Unblock a URL
allow ip - Add an IP address to the allowlist
allow url - Add a URL to the allowed list
unallow ip - Remove an IP address from the allowlist
unallow url - Remove a URL from the allowed list
lookup ip - Lookup the categories related to an IP
lookup url - Lookup the categories related to a URL
submit file - Submit a file to Zscaler Sandbox
get admin users - Get a list of admin users
get users - Gets a list of all users and allows user filtering by name, department, or group
get groups - Gets a list of groups
add group user - Add user to group
remove group user - Remove user from group
Validate the asset configuration for connectivity using supplied configuration
Type: test
Read only: True
No parameters are required for this action
No Output
Fetch sandbox report for provided md5 file hash
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
file_hash | required | The md5 file hash | string | md5 |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.file_hash | string | md5 |
action_result.data.*.Full Details.Classification.Category | string | |
action_result.data.*.Full Details.Classification.DetectedMalware | string | |
action_result.data.*.Full Details.Classification.Score | numeric | |
action_result.data.*.Full Details.Classification.Type | string | |
action_result.data.*.Full Details.FileProperties.DigitalCerificate | string | |
action_result.data.*.Full Details.FileProperties.FileSize | numeric | |
action_result.data.*.Full Details.FileProperties.FileType | string | |
action_result.data.*.Full Details.FileProperties.Issuer | string | |
action_result.data.*.Full Details.FileProperties.MD5 | string | md5 |
action_result.data.*.Full Details.FileProperties.RootCA | string | |
action_result.data.*.Full Details.FileProperties.SHA1 | string | sha1 |
action_result.data.*.Full Details.FileProperties.SSDeep | string | |
action_result.data.*.Full Details.FileProperties.Sha256 | string | sha256 |
action_result.data.*.Full Details.Origin.Country | string | |
action_result.data.*.Full Details.Origin.Language | string | |
action_result.data.*.Full Details.Origin.Risk | string | |
action_result.data.*.Full Details.Summary.Category | string | |
action_result.data.*.Full Details.Summary.Duration | numeric | |
action_result.data.*.Full Details.Summary.FileType | string | |
action_result.data.*.Full Details.Summary.StartTime | numeric | |
action_result.data.*.Full Details.Summary.Status | string | |
action_result.data.*.Full Details.SystemSummary.*.Risk | string | |
action_result.data.*.Full Details.SystemSummary.*.Signature | string | |
action_result.data.*.Full Details.SystemSummary.*.SignatureSources | string | |
action_result.summary | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
List all URL categories
Type: investigate
Read only: True
No parameters are required for this action
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.customIpRangesCount | numeric | |
action_result.data.*.customUrlsCount | numeric | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.editable | boolean | |
action_result.data.*.id | string | zscaler url category |
action_result.data.*.ipRangesRetainingParentCategoryCount | numeric | |
action_result.data.*.scopes.*.Type | string | |
action_result.data.*.type | string | |
action_result.data.*.urlsRetainingParentCategoryCount | numeric | |
action_result.data.*.val | numeric | |
action_result.summary.total_url_categories | numeric | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Block an IP
Type: contain
Read only: False
If a url_category is specified, it will add the IP(s) as a rule to that category. If it is left blank, it will instead add the IP(s) to the global blocklist.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
ip | required | A list of IPs | string | ip ipv6 |
url_category | optional | Add to this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.ip | string | ip ipv6 |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.id | string | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Block a URL
Type: contain
Read only: False
If a url_category is specified, it will add the URL(s) as a rule to that category. If it is left blank, it will instead add the URL(s) to the global blocklist.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
url | required | A list of URLs | string | url domain url list |
url_category | optional | Add to this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.url | string | url domain url list |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.customUrlsCount | numeric | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.editable | boolean | |
action_result.data.*.id | string | |
action_result.data.*.type | string | |
action_result.data.*.urlsRetainingParentCategoryCount | numeric | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Unblock an IP
Type: correct
Read only: False
If a url_category is specified, it will remove the IP(s) from that category. If it is left blank, it will instead remove the IP(s) from the global blocklist.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
ip | required | A list of IPs | string | ip ipv6 |
url_category | optional | Remove from this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.ip | string | ip ipv6 |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.id | string | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Unblock a URL
Type: correct
Read only: False
If a url_category is specified, it will remove the URL(s) from that category. If it is left blank, it will instead remove the URL(s) from the global blocklist.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
url | required | A list of URLs | string | url domain url list |
url_category | optional | Remove from this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.url | string | url domain url list |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.customUrlsCount | numeric | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.editable | boolean | |
action_result.data.*.id | string | |
action_result.data.*.type | string | |
action_result.data.*.urlsRetainingParentCategoryCount | numeric | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Add an IP address to the allowlist
Type: contain
Read only: False
If a url_category is specified, it will add the IP(s) as a rule to that category. If it is left blank, it will instead add this IP(s) to the global allowlist.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
ip | required | A list of IPs | string | ip ipv6 |
url_category | optional | Add to this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.ip | string | ip ipv6 |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.id | string | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Add a URL to the allowed list
Type: contain
Read only: False
If a url_category is specified, it will add the URL(s) as a rule to that category. If it is left blank, it will instead add the URL(s) to the global allowed list.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
url | required | A list of URLs | string | url domain url list |
url_category | optional | Add to this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.url | string | url domain url list |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.customUrlsCount | numeric | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.editable | boolean | |
action_result.data.*.id | string | |
action_result.data.*.type | string | |
action_result.data.*.urlsRetainingParentCategoryCount | numeric | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Remove an IP address from the allowlist
Type: correct
Read only: False
If a url_category is specified, it will remove the IP(s) from that category. If it is left blank, it will instead remove the IP(s) from the global allowlist.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
ip | required | A list of IPs | string | ip ipv6 |
url_category | optional | Remove from this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.ip | string | ip ipv6 |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.id | string | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Remove a URL from the allowed list
Type: correct
Read only: False
If a url_category is specified, it will remove the URL(s) from that category. If it is left blank, it will instead remove the URL(s) from the global allowed list.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
url | required | A list of URLs | string | url domain url list |
url_category | optional | Remove from this category | string | zscaler url category |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.url | string | url domain url list |
action_result.parameter.url_category | string | zscaler url category |
action_result.data.*.configuredName | string | |
action_result.data.*.customCategory | boolean | |
action_result.data.*.dbCategorizedUrls | string | |
action_result.data.*.description | string | |
action_result.data.*.id | string | |
action_result.data.*.val | numeric | |
action_result.summary.ignored | string | |
action_result.summary.updated | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Lookup the categories related to an IP
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
ip | required | A list of IPs | string | ip ipv6 |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.ip | string | ip ipv6 |
action_result.data.*.blocklisted | boolean | |
action_result.data.*.url | string | ip ipv6 |
action_result.data.*.urlClassifications | string | |
action_result.data.*.urlClassificationsWithSecurityAlert | string | |
action_result.summary | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Lookup the categories related to a URL
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
url | required | A list of URLs | string | url domain url list |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.url | string | url domain url list |
action_result.data.*.blocklisted | boolean | |
action_result.data.*.url | string | url domain url list |
action_result.data.*.urlClassifications | string | |
action_result.data.*.urlClassificationsWithSecurityAlert | string | |
action_result.summary | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Submit a file to Zscaler Sandbox
Type: generic
Read only: False
This action requires a Sandbox Submission API token. By default, files are scanned by Zscaler antivirus (AV) and submitted directly to the sandbox in order to obtain a verdict. However, if a verdict already exists for the file, you can use the 'force' parameter to make the sandbox to reanalyze it. You can submit up to 100 files per day.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
vault_id | required | Vault ID of file to submit | string | vault id sha1 |
force | optional | Submit file to sandbox even if found malicious during AV scan and a verdict already exists | boolean |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.force | boolean | |
action_result.parameter.vault_id | string | vault id sha1 |
action_result.data.*.code | numeric | |
action_result.data.*.fileType | string | |
action_result.data.*.md5 | string | md5 |
action_result.data.*.message | string | |
action_result.data.*.sandboxSubmission | string | |
action_result.data.*.virusName | string | |
action_result.data.*.virusType | string | |
action_result.summary | string | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Get a list of admin users
Type: investigate
Read only: True
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
limit | optional | Maximum number of records to fetch | numeric |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.limit | numeric | |
action_result.data.*.adminScopeScopeEntities.*.id | numeric | |
action_result.data.*.adminScopeScopeEntities.*.name | string | |
action_result.data.*.adminScopeType | string | |
action_result.data.*.adminScopescopeGroupMemberEntities.*.id | numeric | |
action_result.data.*.comments | string | |
action_result.data.*.disabled | boolean | |
action_result.data.*.email | string | email |
action_result.data.*.id | numeric | zscaler user id |
action_result.data.*.isDefaultAdmin | boolean | |
action_result.data.*.isDeprecatedDefaultAdmin | boolean | |
action_result.data.*.isExecMobileAppEnabled | boolean | |
action_result.data.*.isNonEditable | boolean | |
action_result.data.*.isPasswordLoginAllowed | boolean | |
action_result.data.*.isProductUpdateCommEnabled | boolean | |
action_result.data.*.isSecurityReportCommEnabled | boolean | |
action_result.data.*.isServiceUpdateCommEnabled | boolean | |
action_result.data.*.loginName | string | |
action_result.data.*.name | string | |
action_result.data.*.pwdLastModifiedTime | numeric | |
action_result.data.*.role.extensions.adminRank | string | |
action_result.data.*.role.extensions.roleType | string | |
action_result.data.*.role.id | numeric | |
action_result.data.*.role.isNameL10nTag | boolean | |
action_result.data.*.role.name | string | |
action_result.data.*.userName | string | |
action_result.summary.total_admin_users | numeric | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Gets a list of all users and allows user filtering by name, department, or group
Type: investigate
Read only: True
Gets a list of all users and allows user filtering by name, department, or group. The name search parameter performs a partial match. The dept and group parameters perform a 'starts with' match.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
name | optional | User Name/ID | string | |
dept | optional | User department | string | |
group | optional | User group | string | |
limit | optional | Maximum number of records to fetch | numeric |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.dept | string | |
action_result.parameter.group | string | |
action_result.parameter.limit | numeric | |
action_result.parameter.name | string | |
action_result.data.*.adminUser | boolean | |
action_result.data.*.comments | string | |
action_result.data.*.deleted | boolean | |
action_result.data.*.department.id | numeric | |
action_result.data.*.department.name | string | |
action_result.data.*.disabled | boolean | |
action_result.data.*.email | string | email |
action_result.data.*.groups.*.id | numeric | zscaler group id |
action_result.data.*.groups.*.name | string | |
action_result.data.*.id | numeric | zscaler user id |
action_result.data.*.isNonEditable | boolean | |
action_result.data.*.name | string | |
action_result.summary.total_users | numeric | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Gets a list of groups
Type: investigate
Read only: True
Gets a list of groups. The search parameters find matching values in the name or comments attributes.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
search | optional | The search string used to match against a group's name or comments attributes | string | |
limit | optional | Maximum number of records to fetch | numeric |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.limit | numeric | |
action_result.parameter.search | string | |
action_result.data.*.comments | string | |
action_result.data.*.id | numeric | zscaler group id |
action_result.data.*.isNonEditable | boolean | |
action_result.data.*.name | string | |
action_result.summary.total_groups | numeric | |
action_result.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Add user to group
Type: generic
Read only: False
Add a group to the user's profile.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
user_id | required | ZScaler User ID | numeric | zscaler user id |
group_id | required | ZScaler Group ID | numeric | zscaler group id |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.group_id | numeric | zscaler group id |
action_result.parameter.user_id | numeric | zscaler user id |
action_result.data.*.adminUser | boolean | |
action_result.data.*.deleted | boolean | |
action_result.data.*.department.id | numeric | |
action_result.data.*.department.name | string | |
action_result.data.*.email | string | |
action_result.data.*.groups.*.id | numeric | |
action_result.data.*.groups.*.name | string | |
action_result.data.*.id | numeric | |
action_result.data.*.name | string | |
action_result.summary | string | |
action_result.summary.message | string | |
action_result.message | string | |
summary.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |
Remove user from group
Type: correct
Read only: False
Remove a group from the user's profile.
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
---|---|---|---|---|
user_id | required | ZScaler User Id | numeric | zscaler user id |
group_id | required | ZScaler Group Id | numeric | zscaler group id |
DATA PATH | TYPE | CONTAINS |
---|---|---|
action_result.status | string | |
action_result.parameter.group_id | numeric | zscaler group id |
action_result.parameter.user_id | numeric | zscaler user id |
action_result.data.*.adminUser | boolean | |
action_result.data.*.deleted | boolean | |
action_result.data.*.department.id | numeric | |
action_result.data.*.department.name | string | |
action_result.data.*.email | string | |
action_result.data.*.groups.*.id | numeric | |
action_result.data.*.groups.*.name | string | |
action_result.data.*.id | numeric | |
action_result.data.*.name | string | |
action_result.summary | string | |
action_result.summary.message | string | |
action_result.message | string | |
summary.message | string | |
summary.total_objects | numeric | |
summary.total_objects_successful | numeric |