url_filtering#

The following methods allow for interaction with the ZIA URL Filtering Policy API endpoints.

Methods are accessible via zia.url_filtering

class URLFilteringAPI#

Bases: object

add_rule(rank, name, action, protocols, **kwargs)#

Adds a new URL Filtering Policy rule.

Parameters:

  • rank (str) – The admin rank of the user who creates the rule.

  • name (str) – The name of the rule.

  • action (str) –

    Action taken when traffic matches rule criteria. Accepted values are:

    ANY, NONE, BLOCK, CAUTION, ALLOW and ICAP_RESPONSE

  • device_trust_levels (list) – List of device trust levels for which the rule must be applied. Accepted values are: ANY, UNKNOWN_DEVICETRUSTLEVEL, LOW_TRUST, MEDIUM_TRUST, and HIGH_TRUST

  • protocols (list) – The protocol criteria for the rule.

  • **kwargs – Optional keyword args.

Keyword Arguments:

  • block_override (bool) – When set to true, a ‘BLOCK’ action triggered by the rule could be overridden. Defaults to False.

  • ciparule (bool) – The CIPA compliance rule is enabled if this is set to True. Defaults to False.

  • departments (list) – The IDs for the departments that this rule applies to.

  • devices (list) – The IDs for the devices that this rule applies to.

  • device_groups (list) – The IDs for the device groups that this rule applies to.

  • labels (list) – The IDs for the labels that this rule applies to.

  • description (str) – Additional information about the URL Filtering rule.

  • end_user_notification_url (str) – URL of end user notification page to be displayed when the rule is matched. Not applicable if either override_users or override_groups is specified.

  • enforce_time_validity (bool) – Enforce a set validity time period for the URL Filtering rule.

  • groups (list) – The IDs for the groups 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.

  • order (str) – Order of execution of rule with respect to other URL Filtering rules. Defaults to placing rule at the bottom of the list.

  • override_users (list of int) – The IDs of users that this rule can be overridden for. Only applies if block_override is True, action is BLOCK and override_groups is not set.

  • override_groups (list of int) – The IDs of groups that this rule can be overridden for. Only applies if block_override is True and action is BLOCK.

  • request_methods (list) – The request methods that this rule will apply to. If not specified, the rule will apply to all methods.

  • size_quota (str) – Size quota in KB for applying the URL Filtering rule.

  • time_quota (str) – Time quota in minutes elapsed after the URL Filtering rule is applied.

  • time_windows (list) – The IDs for the time windows that this rule applies to.

  • url_categories (list) – The names of URL categories that this rule applies to.

  • users (list) – The IDs for the users that this rule applies to.

  • validity_start_time (str) – Date and time the rule’s effects will be valid from. enforce_time_validity must be set to True for this to take effect.

  • validity_end_time (str) – Date and time the rule’s effects will end. enforce_time_validity must be set to True for this to take effect.

  • validity_time_zone_id (str) – The URL Filter rule validity date and time will be based on the TZ provided. enforce_time_validity must be set to True for this to take effect.

Returns:

The newly created URL Filtering Policy rule.

Return type:

Box

Examples

Add a rule with the minimum required parameters:

>>> zia.url_filters.add_rule(rank='7',
...    name="Empty URL Filter",
...    action="ALLOW",
...    protocols=['ANY_RULE']

Add a rule to block HTTP POST to Social Media sites for the Finance department.

>>> zia.url_filters.add_rule(rank='7',
...    name="Block POST to Social Media",
...    action="BLOCK",
...    protocols=["HTTP_PROXY", "HTTP_RULE", "HTTPS_RULE"],
...    request_methods=['POST'],
...    departments=["95022175"],
...    url_categories=["SOCIAL_NETWORKING"])
delete_rule(rule_id)#

Deletes the specified URL Filtering Policy rule.

Parameters:

rule_id (str) – The unique ID for the URL Filtering Policy rule.

Returns:

The status code for the operation.

Return type:

int

Examples

>>> zia.url_filters.delete_rule('977463')
get_rule(rule_id)#

Returns information on the specified URL Filtering Policy rule.

Parameters:

rule_id (str) – The unique ID for the URL Filtering Policy rule.

Returns:

The URL Filtering Policy rule.

Return type:

Box

Examples

>>> pprint(zia.url_filters.get_rule('977469'))
list_rules()#

Returns the list of URL Filtering Policy rules

Returns:

The list of URL Filtering Policy rules.

Return type:

BoxList

Examples

>>> for rule in zia.url_filters.list_rules():
...    pprint(rule)
reformat_params = [('departments', 'departments'), ('devices', 'devices'), ('device_groups', 'deviceGroups'), ('groups', 'groups'), ('labels', 'labels'), ('locations', 'locations'), ('location_groups', 'locationGroups'), ('override_users', 'overrideUsers'), ('override_groups', 'overrideGroups'), ('time_windows', 'timeWindows'), ('users', 'users')]#
update_rule(rule_id, **kwargs)#

Updates the specified URL Filtering Policy rule.

Parameters:

  • rule_id – The unique ID of the URL Filtering Policy rule to be updated.

  • **kwargs – Optional keyword args.

Keyword Arguments:

  • name (str) – The name of the rule.

  • action (str) –

    Action taken when traffic matches rule criteria. Accepted values are:

    ANY, NONE, BLOCK, CAUTION, ALLOW and ICAP_RESPONSE

  • device_trust_levels (list) – List of device trust levels for which the rule must be applied. Accepted values are: ANY, UNKNOWN_DEVICETRUSTLEVEL, LOW_TRUST, MEDIUM_TRUST, and HIGH_TRUST

  • protocols (list) – The protocol criteria for the rule.

  • block_override (bool) – When set to true, a ‘BLOCK’ action triggered by the rule could be overridden. Defaults to False.

  • ciparule (bool) – The CIPA compliance rule is enabled if this is set to True. Defaults to False.

  • departments (list) – The IDs for the departments that this rule applies to.

  • devices (list) – The IDs for the devices that this rule applies to.

  • device_groups (list) – The IDs for the device groups that this rule applies to.

  • labels (list) – The IDs for the labels that this rule applies to.

  • description (str) – Additional information about the URL Filtering rule.

  • end_user_notification_url (str) – URL of end user notification page to be displayed when the rule is matched. Not applicable if either override_users or override_groups is specified.

  • enforce_time_validity (bool) – Enforce a set validity time period for the URL Filtering rule.

  • groups (list) – The IDs for the groups 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.

  • order (str) – Order of execution of rule with respect to other URL Filtering rules. Defaults to placing rule at the bottom of the list.

  • override_users (list of int) – The IDs of users that this rule can be overridden for. Only applies if block_override is True, action is BLOCK and override_groups is not set.

  • override_groups (list of int) – The IDs of groups that this rule can be overridden for. Only applies if block_override is True and action is BLOCK.

  • request_methods (list) – The request methods that this rule will apply to. If not specified, the rule will apply to all methods.

  • size_quota (str) – Size quota in KB for applying the URL Filtering rule.

  • time_quota (str) – Time quota in minutes elapsed after the URL Filtering rule is applied.

  • time_windows (list) – The IDs for the time windows that this rule applies to.

  • url_categories (list) – The names of URL categories that this rule applies to.

  • users (list) – The IDs for the users that this rule applies to.

  • validity_start_time (str) – Date and time the rule’s effects will be valid from. enforce_time_validity must be set to True for this to take effect.

  • validity_end_time (str) – Date and time the rule’s effects will end. enforce_time_validity must be set to True for this to take effect.

  • validity_time_zone_id (str) – The URL Filter rule validity date and time will be based on the TZ provided. enforce_time_validity must be set to True for this to take effect.

Returns:

The updated URL Filtering Policy rule.

Return type:

Box

Examples

Update the name of a URL Filtering Policy rule:

>>> zia.url_filters.update_rule('977467',
...    name="Updated Name")

Add GET to request methods and change action to ALLOW:

>>> zia.url_filters.update_rule('977468',
...    request_methods=['POST', 'GET'],
...    action="ALLOW")