url_filtering

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

Methods are accessible via zia.url_filtering

Copyright (c) 2023, Zscaler Inc.

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 URLFilteringAPI

Bases: APIClient

A Client object for the URL Filtering Rule resources.

add_rule(**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. Accepted values are: CONNECT, DELETE, GET, HEAD, OPTIONS, OTHER, POST, PUT, TRACE

  • user_agent_types (list) – User Agent types on which this rule will be applied. Accepted values are: OPERA, FIREFOX, MSIE, MSEDGE, CHROME, SAFARI, OTHER, MSCHREDGE

  • 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.

  • url_categories2 (list) – The names of URL categories that this rule applies to. Note: The urlCategories and urlCategories2 parameters are connected with a logical AND operator

  • 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:

Tuple

Examples

Add a url filtering rule:

>>> added_rule, _, error = client.zia.url_filtering.add_rule(
...     name=f"NewRule {random.randint(1000, 10000)}",
...     description=f"NewRule {random.randint(1000, 10000)}",
...     state="ENABLED",
...     order=1,
...     rank=7,
...     action='ALLOW',
...     url_categories = ["OTHER_ADULT_MATERIAL"],
...     protocols = ["ANY_RULE"],
...     device_trust_levels=["UNKNOWN_DEVICETRUSTLEVEL", "LOW_TRUST", "MEDIUM_TRUST", "HIGH_TRUST"],
...     user_agent_types = [        "OPERA", "FIREFOX", "MSIE", "MSEDGE", "CHROME", "SAFARI", "MSCHREDGE", "OTHER" ],
...     request_methods = [ "CONNECT", "DELETE", "GET", "HEAD", "OPTIONS", "OTHER", "POST", "PUT", "TRACE"],
... )
>>> 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 url filtering filter rule.

Parameters:

rule_id (str) – The unique identifier for the url filtering rule.

Returns:

The status code for the operation.

Return type:

int

Examples

>>> _, _, error = client.zia.url_filtering.delete_rule('524558')
>>> if error:
...     print(f"Error deleting rule: {error}")
...     return
... print(f"Rule with ID {'524558'} deleted successfully.")
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:

Tuple

Examples

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

Retrieves information about URL and Cloud App Control advanced policy settings

Returns:

A tuple containing:

  • AdvancedUrlFilterAndCloudAppSettings: The current advanced settings object.

  • Response: The raw HTTP response returned by the API.

  • error: An error message if the request failed; otherwise, None.

Return type:

tuple

Examples

Retrieve and print the current url and app settings:

>>> settings, response, err = client.zia.url_filtering.get_update_url_and_app_settings()
>>> if err:
...     print(f"Error fetching settings: {err}")
... else:
...     print(f"Enable Office365: {settings.enable_office365}")
list_rules(query_params=None)

Lists url filtering rules in your organization. If the search parameter is provided, the function filters the rules client-side.

Parameters:

{dict} (query_params) –

Map of query parameters for the request. [query_params.search] {str}: Search string for filtering results by rule name.

[query_params.page] (int): Specifies the page offset.

[query_params.page_size] (int): Specifies the page size.

The default size is 100, but the maximum size is 100.

Returns:

A tuple containing (list of url filtering rules instances, Response, error)

Return type:

tuple

Examples: >>> rules_list, _, error = client.zia.url_filtering.list_rules( … query_params={‘page’: 1, ‘page_size’: 10} ) >>> if error: … print(f”Error listing url filtering rules: {error}”) … return … print(f”Total rules found: {len(rules_list)}”) … for rule in rules_list: … print(rule.as_dict())

reformat_params = [('cbi_profile', 'cbiProfile'), ('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'), ('workload_groups', 'workloadGroups'), ('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.

  • request_methods (list) – The request methods that this rule will apply to. If not specified, the rule will apply to all methods. Accepted values are: CONNECT, DELETE, GET, HEAD, OPTIONS, OTHER, POST, PUT, TRACE

  • user_agent_types (list) – User Agent types on which this rule will be applied. Accepted values are: OPERA, FIREFOX, MSIE, MSEDGE, CHROME, SAFARI, OTHER, MSCHREDGE

  • 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.

  • 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.

  • url_categories2 (list) – The names of URL categories that this rule applies to. Note: The urlCategories and urlCategories2 parameters are connected with a logical AND operator

  • 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:

Tuple

Examples

Updating an exiisting url filtering rule:

>>> updated_rule, _, error = client.zia.url_filtering.add_rule(
...     name=f"UpdateRule_{random.randint(1000, 10000)}",
...     description=f"UpdateRule_{random.randint(1000, 10000)}",
...     state="ENABLED",
...     order=1,
...     rank=7,
...     action='ALLOW',
...     url_categories = ["OTHER_ADULT_MATERIAL"],
...     protocols = ["ANY_RULE"],
...     device_trust_levels=["UNKNOWN_DEVICETRUSTLEVEL", "LOW_TRUST", "MEDIUM_TRUST", "HIGH_TRUST"],
...     user_agent_types = [        "OPERA", "FIREFOX", "MSIE", "MSEDGE", "CHROME", "SAFARI", "MSCHREDGE", "OTHER" ],
...     request_methods = [ "CONNECT", "DELETE", "GET", "HEAD", "OPTIONS", "OTHER", "POST", "PUT", "TRACE"],
... )
>>> if error:
...     print(f"Error adding rule: {error}")
...     return
... print(f"Rule added successfully: {updated_rule.as_dict()}")
update_url_and_app_settings(**kwargs)

Updates the URL and Cloud App Control advanced policy settings

Parameters:

settings (AdvancedUrlFilterAndCloudAppSettings) – An instance of AdvancedSettings containing the updated configuration.

Supported attributes:

  • enable_dynamic_content_cat (bool): Enables dynamic categorization of URLs using AI/ML analysis.

  • consider_embedded_sites (bool): Apply URL filtering to sites translated with translation services.

  • enforce_safe_search (bool): Only return safe web, image, and video content in search results.

  • enable_office365 (bool): Enables Microsoft Office 365 configuration in the policy.

  • enable_msft_o365 (bool): Enables Microsoft-recommended one-click Office 365 configuration.

  • enable_ucaas_zoom (bool): Automatically permit secure breakout for Zoom traffic.

  • enable_ucaas_log_me_in (bool): Automatically permit secure breakout for GoTo traffic.

  • enable_ucaas_ring_central (bool): Automatically permit secure breakout for RingCentral traffic.

  • enable_ucaas_webex (bool): Automatically permit secure breakout for Webex traffic.

  • enable_ucaas_talkdesk (bool): Automatically permit secure breakout for Talkdesk traffic.

  • enable_chat_gpt_prompt (bool): Categorize and log user prompts sent to ChatGPT.

  • enable_microsoft_copilot_prompt (bool): Categorize and log user prompts sent to Microsoft Copilot.

  • enable_gemini_prompt (bool): Categorize and log user prompts sent to Google Gemini.

  • enable_poe_prompt (bool): Categorize and log user prompts sent to Poe AI.

  • enable_meta_prompt (bool): Categorize and log user prompts sent to Meta AI.

  • enable_perplexity_prompt (bool): Categorize and log user prompts sent to Perplexity AI.

  • block_skype (bool): Specifies whether Skype access is blocked.

  • enable_newly_registered_domains (bool): Block or allow domains identified shortly after registration.

  • enable_block_override_for_non_auth_user (bool): Allow authenticated users to override website blocks.

  • enable_cipa_compliance (bool): Enables the predefined CIPA Compliance Rule.

Returns:

  • AdvancedUrlFilterAndCloudAppSettings: The updated URL and Cloud App Control advanced object.

  • Response: The raw HTTP response returned by the API.

  • error: An error message if the update failed; otherwise, None.

Return type:

tuple

Examples

Update URL and Cloud App Control advanced by enabling Office365 and adjusting the session timeout:

>>> settings, response, err = client.zia.url_filtering.get_advanced_settings()
>>> if not err:
...     settings.enable_office365 = True
...     settings.ui_session_timeout = 7200
...     updated_settings, response, err = client.zia.url_filtering.update_url_and_app_settings(settings)
...     if not err:
...         print(f"Updated Enable Office365: {updated_settings.enable_office365}")
...     else:
...         print(f"Failed to update settings: {err}")