sandbox_rules¶

The following methods allow for interaction with the ZIA Sandbox Rules API endpoints.

Methods are accessible via zia.sandbox_rules

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class SandboxRulesAPI¶

Bases: APIClient

add_rule(**kwargs)¶

Adds a new sandbox filter rule.

Parameters:

name (str) – Name of the rule, max 31 chars.
ba_rule_action (str) – Action to take place if the traffic matches the rule criteria

Keyword Arguments:

order (str) – The order of the rule, defaults to adding rule to bottom of list.
rank (str) – The admin rank of the rule. Supported values 1-7
state (str) – The rule state. Accepted values are ‘ENABLED’ or ‘DISABLED’.
description (str) – Additional information about the rule
first_time_enable (str) – Indicates whether a First-Time Action is specifically configured for the rule
first_time_operation (str) – Action that must take place when users download unknown files for the first time
ml_action_enabled (bool) – Indicates whether to enable or disable the AI Instant Verdict option.
by_threat_score (int) – Minimum threat score can be set between 40 to 70.
groups (list) – The IDs for the groups that this rule applies to.
users (list) – The IDs for the users that this rule applies to.
file_types (list) – The file types to which the rule applies.
protocols (list) – The protocol criteria for the rule.
labels (list) – The IDs for the labels that this rule applies to.
locations (list) – The IDs for the locations that this rule applies to.
location_groups (list) – The IDs for the location groups that this rule applies to.

Returns:

New sandbox rule resource record.

Return type:

Tuple

Example

Add a sandbox rule to block specific file types:

>>> added_rule, _, error = client.zia.sandbox_rules.add_rule(
...     name=f"NewRule {random.randint(1000, 10000)}",
...     description=f"NewRule {random.randint(1000, 10000)}",
...     ba_rule_action='BLOCK',
...     state="ENABLED",
...     order=1,
...     rank=7,
...     first_time_enable=True,
...     ml_action_enabled=True,
...     first_time_operation="ALLOW_SCAN",
...     url_categories = ["OTHER_ADULT_MATERIAL"],
...     protocols=["FOHTTP_RULE", "FTP_RULE", "HTTPS_RULE", "HTTP_RULE"],
...     ba_policy_categories=["ADWARE_BLOCK", "BOTMAL_BLOCK", "ANONYP2P_BLOCK",
...     "RANSOMWARE_BLOCK", "OFFSEC_TOOLS_BLOCK", "SUSPICIOUS_BLOCK"],
...     file_types=["FTCATEGORY_BZIP2", "FTCATEGORY_P7Z"],
...     by_threat_score=40,
...     groups=['12006601'],
...     departments=['15616629'],
... )
>>> if error:
...     print(f"Error adding rule: {error}")
...     return
... print(f"Rule added successfully: {added_rule.as_dict()}")

delete_rule(rule_id)¶

Deletes the specified sandbox filter rule.

Parameters:: rule_id (str) – The unique identifier for the sandbox rule.
Returns:: The status code for the operation.
Return type:: int

Examples

>>> _, _, error = client.zia.sandbox_rules.delete_rule('544852')
>>> if error:
...     print(f"Error deleting rule: {error}")
...     return
... print(f"Rule with ID {'544852'} deleted successfully.")

get_rule(rule_id)¶

Returns information for the specified sandbox filter rule.

Parameters:: rule_id (str) – The unique identifier for the sandbox filter rule.
Returns:: A tuple containing (sandbox rule instance, Response, error).
Return type:: tuple

Example

Retrieve a sandbox rule by its ID:

>>> fetched_rule, _, error = client.zia.sandbox_rules.get_rule('5422385')
>>> if error:
...     print(f"Error fetching rule by ID: {error}")
...     return
... print(f"Fetched rule by ID: {fetched_rule.as_dict()}")

list_rules(query_params=None)¶

Lists sandbox rules in your organization with pagination. A subset of sandbox rules can be returned that match a supported filter expression or query.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.search] {str}: Search string for filtering results.

Returns:

A tuple containing (list of sandbox rules instances, Response, error).

Return type:

tuple

Example

List all sandbox rules with a specific page size:

>>> rules_list, response, error = zia.sandbox_rules.list_rules()
>>> for rule in rules_list:
...    print(rule.as_dict())

update_rule(rule_id, **kwargs)¶

Updates an existing sandbox filter rule.

Parameters:

rule_id (str) – The unique ID for the rule that is being updated.
**kwargs – Optional keyword args.

Keyword Arguments:

name (str) – Name of the rule, max 31 chars.
description (str) – Additional information about the rule
ba_rule_action (str) – Action to take place if the traffic matches the rule criteria
order (str) – The order of the rule, defaults to adding rule to bottom of list.
rank (str) – The admin rank of the rule. Supported values 1-7
state (str) – The rule state. Accepted values are ‘ENABLED’ or ‘DISABLED’.
first_time_enable (str) – Indicates whether a First-Time Action is specifically configured for the rule
first_time_operation (str) – Action that must take place when users download unknown files for the first time
ml_action_enabled (bool) – Indicates whether to enable or disable the AI Instant Verdict option.
by_threat_score (int) – Minimum threat score can be set between 40 to 70.
groups (list) – The IDs for the groups that this rule applies to.
users (list) – The IDs for the users that this rule applies to.
file_types (list) – The file types to which the rule applies.
protocols (list) – The protocol criteria for the rule.
labels (list) – The IDs for the labels that this rule applies to.
locations (list) – The IDs for the locations that this rule applies to.
location_groups (list) – The IDs for the location groups that this rule applies to.

Returns:

Updated sandbox filter rule resource record.

Return type:

tuple

Example

Update an existing rule to change its name and action:

>>> updated_rule, _, error = client.zia.sandbox_rules.update_rule(
...     name=f"UpdateRule_{random.randint(1000, 10000)}",
...     description=f"UpdateRule_{random.randint(1000, 10000)}",
...     ba_rule_action='BLOCK',
...     state="ENABLED",
...     order=1,
...     rank=7,
...     first_time_enable=True,
...     ml_action_enabled=True,
...     first_time_operation="ALLOW_SCAN",
...     url_categories = ["OTHER_ADULT_MATERIAL"],
...     protocols=["FOHTTP_RULE", "FTP_RULE", "HTTPS_RULE", "HTTP_RULE"],
...     ba_policy_categories=["ADWARE_BLOCK", "BOTMAL_BLOCK", "ANONYP2P_BLOCK",
...     "RANSOMWARE_BLOCK", "OFFSEC_TOOLS_BLOCK", "SUSPICIOUS_BLOCK"],
...     file_types=["FTCATEGORY_BZIP2", "FTCATEGORY_P7Z"],
...     by_threat_score=40,
...     groups=['12006601'],
...     departments=['15616629'],
... )
>>> if error:
...     print(f"Error adding rule: {error}")
...     return
... print(f"Rule added successfully: {updated_rule.as_dict()}")