zscaler-sdk-python 1.0.0__py2.py3-none-any.whl

zscaler/zia/web_dlp.py

@@ -0,0 +1,295 @@
+# -*- coding: utf-8 -*-
+
+# 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.
+
+from box import Box, BoxList
+from requests import Response
+
+from zscaler.utils import (
+    convert_keys,
+    recursive_snake_to_camel,
+    snake_to_camel,
+    transform_common_id_fields,
+)
+from zscaler.zia import ZIAClient
+
+
+class WebDLPAPI:
+    # Web DLP rule keys that only require an ID to be provided.
+    reformat_params = [
+        ("auditor", "auditor"),
+        ("dlp_engines", "dlpEngines"),
+        ("departments", "departments"),
+        ("excluded_departments", "excludedDepartments"),
+        ("excluded_groups", "excludedGroups"),
+        ("excluded_users", "excludedUsers"),
+        ("groups", "groups"),
+        ("labels", "labels"),
+        ("locations", "locations"),
+        ("location_groups", "locationGroups"),
+        ("notification_template", "notificationTemplate"),
+        ("time_windows", "timeWindows"),
+        ("users", "users"),
+        ("url_categories", "urlCategories"),
+    ]
+
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def list_rules(self) -> BoxList:
+        """
+        Returns a list of DLP policy rules, excluding SaaS Security API DLP policy rules.
+
+        Returns:
+            :obj:`BoxList`: List of Web DLP items.
+
+        Examples:
+            Get a list of all Web DLP Items
+
+            >>> results = zia.web_dlp.list_rules()
+            ... for item in results:
+            ...    print(item)
+
+        """
+        response = self.rest.get("/webDlpRules")
+        if isinstance(response, Response):
+            return None
+        return response
+
+    def get_rule(self, rule_id: str) -> Box:
+        """
+        Returns a DLP policy rule, excluding SaaS Security API DLP policy rules.
+
+        Args:
+            rule_id (str): The unique id for the Web DLP rule.
+
+        Returns:
+            :obj:`Box`: The Web DLP Rule resource record.
+
+        Examples:
+            Get information on a Web DLP item by ID
+
+            >>> results = zia.web_dlp.get_rule(rule_id='9999')
+            ... print(results)
+
+        """
+        return self.rest.get(f"webDlpRules/{rule_id}")
+
+    def list_rules_lite(self) -> BoxList:
+        """
+        Returns the name and ID for all DLP policy rules, excluding SaaS Security API DLP policy rules.
+
+        Returns:
+            :obj:`BoxList`: List of Web DLP name/ids.
+
+        Examples:
+            Get Web DLP Lite results
+
+            >>> results = zia.web_dlp.list_rules_lite()
+            ... for item in results:
+            ...    print(item)
+
+        """
+        response = self.rest.get("webDlpRules/lite")
+        if isinstance(response, Response):
+            return None
+        return response
+
+    def add_rule(self, name: str, action: str, **kwargs) -> Box:
+        """
+        Adds a new DLP policy rule.
+
+        Args:
+            name (str): The name of the filter rule. 31 char limit.
+            action (str): The action for the filter rule.
+
+        Keyword Args:
+            order (str): The order of the rule, defaults to adding rule to bottom of list.
+            rank (str): The admin rank of the rule.
+            state (str): The rule state. Accepted values are 'ENABLED' or 'DISABLED'.
+            auditor (:obj:`list` of :obj:`int`): IDs for the auditors this rule applies to.
+            cloud_applications (list): IDs for cloud applications this rule applies to.
+            description (str): Additional information about the rule
+            departments (:obj:`list` of :obj:`int`): IDs for departments this rule applies to.
+            dlp_engines (:obj:`list` of :obj:`int`): IDs for DLP engines this rule applies to.
+            excluded_groups (:obj:`list` of :obj:`int`): IDs for excluded groups.
+            excluded_departments (:obj:`list` of :obj:`int`): IDs for excluded departments.
+            excluded_users (:obj:`list` of :obj:`int`): IDs for excluded users.
+            file_types (list): List of file types the DLP policy rule applies to.
+            groups (:obj:`list` of :obj:`int`): IDs for groups this rule applies to.
+            icap_server (:obj:`list` of :obj:`int`): IDs for the icap server this rule applies to.
+            labels (:obj:`list` of :obj:`int`): IDs for labels this rule applies to.
+            locations (:obj:`list` of :obj:`int`): IDs for locations this rule applies to.
+            location_groups (:obj:`list` of :obj:`int`): IDs for location groups this rule applies to.
+            notification_template (:obj:`list` of :obj:`int`): IDs for the notification template.
+            time_windows (:obj:`list` of :obj:`int`): IDs for time windows this rule applies to.
+            users (:obj:`list` of :obj:`int`): IDs for users this rule applies to.
+            url_categories (list): IDs for URL categories the rule applies to.
+            external_auditor_email (str): Email of an external auditor for DLP notifications.
+            dlp_download_scan_enabled (bool): True enables DLP scan for file downloads.
+            min_size (str): Minimum file size (in KB) for DLP policy rule evaluation.
+            match_only (bool): If true, matches file size for DLP policy rule evaluation.
+            ocr_enabled (bool): True allows OCR scanning of image files.
+            without_content_inspection (bool): True indicates a DLP rule without content inspection.
+            zcc_notifications_enabled (bool): True enables Zscaler Client Connector notification.
+
+        Returns:
+            :obj:`Box`: The new dlp web rule resource record.
+
+        Examples:
+            Add a rule to allow all traffic to Google DNS (admin ranking is enabled):
+
+            >>> zia.web_dlp.add_rule(rank='7',
+            ...    file_types=['BITMAP', 'JPEG', 'PNG'],
+            ...    name='ALLOW_ANY_TO_GOOG-DNS',
+            ...    action='ALLOW',
+            ...    description='TT#1965432122')
+
+            Add a rule to block all traffic to Quad9 DNS for Finance Group:
+
+            >>> zia.web_dlp.add_rule(rank='7',
+            ...    file_types=['BITMAP', 'JPEG', 'PNG'],
+            ...    name='BLOCK_GROUP-FIN_TO_Q9-DNS',
+            ...    action='BLOCK_ICMP',
+            ...    groups=['95016183'],
+            ...    description='TT#1965432122')
+        """
+        # Convert enabled to API format if present
+        if "enabled" in kwargs:
+            kwargs["state"] = "ENABLED" if kwargs.pop("enabled") else "DISABLED"
+
+        payload = {
+            "name": name,
+            "action": action,
+            "order": kwargs.pop("order", len(self.list_rules())),
+        }
+
+        # Transform ID fields in kwargs
+        transform_common_id_fields(self.reformat_params, kwargs, payload)
+        for key, value in kwargs.items():
+            if value is not None:
+                payload[snake_to_camel(key)] = value
+
+        # Convert the entire payload's keys to camelCase before sending
+        camel_payload = recursive_snake_to_camel(payload)
+        for key, value in kwargs.items():
+            if value is not None:
+                camel_payload[snake_to_camel(key)] = value
+
+        # Send POST request to create the rule
+        response = self.rest.post("webDlpRules", json=payload)
+        if isinstance(response, Response):
+            status_code = response.status_code
+            # Handle error response
+            raise Exception(
+                f"API call failed with status {status_code}: {response.json()}"
+            )
+        return response
+
+    def update_rule(self, rule_id: str, **kwargs) -> Box:
+        """
+        Updates an existing DLP policy rule. Not applicable to SaaS Security API DLP policy rules.
+
+        Args:
+            rule_id (str): ID of the rule.
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            order (str): Rule order, defaults to bottom of list.
+            rank (str): Admin rank of the rule.
+            state (str): Rule state ('ENABLED' or 'DISABLED').
+            auditor (list): IDs for auditors this rule applies to.
+            cloud_applications (list): IDs for cloud applications rule applies to.
+            description (str): Additional information about the rule.
+            departments (list): IDs for departments rule applies to.
+            dlp_engines (list): IDs for DLP engines rule applies to.
+            excluded_groups (list): IDs for excluded groups.
+            excluded_departments (list): IDs for excluded departments.
+            excluded_users (list): IDs for excluded users.
+            file_types (list): List of file types the rule applies to.
+            groups (list): IDs for groups rule applies to.
+            icap_server (list): IDs for the ICAP server rule applies to.
+            labels (list): IDs for labels rule applies to.
+            locations (list): IDs for locations rule applies to.
+            location_groups (list): IDs for location groups rule applies to.
+            notification_template (list): IDs for the notification template.
+            time_windows (list): IDs for time windows rule applies to.
+            users (list): IDs for users rule applies to.
+            url_categories (list): IDs for URL categories rule applies to.
+            external_auditor_email (str): Email of external auditor for DLP notifications.
+            dlp_download_scan_enabled (bool): True enables DLP scan for file downloads.
+            min_size (str): Minimum file size (in KB) for rule evaluation.
+            match_only (bool): If true, uses min_size for rule evaluation.
+            ocr_enabled (bool): True allows OCR scanning of image files.
+            without_content_inspection (bool): True for DLP rule without content inspection.
+            zcc_notifications_enabled (bool): True enables ZCC notification for block action.
+
+        Returns:
+            :obj:`Box`: The updated web dlp rule resource record.
+
+        Examples:
+            Update a Web DLP Policy Rule:
+
+                >>> zia.web_dlp.get_rule('9999')
+                ... name="updated name."
+                ... description="updated name."
+
+            Update a web dlp policy rule to update description:
+
+                >>> zia.web_dlp.update_rule('976597', description="TT#1965232866")
+        """
+        # Set payload to value of existing record and convert nested dict keys.
+        payload = convert_keys(self.get_rule(rule_id))
+
+        # Convert enabled to API format if present in kwargs
+        if "enabled" in kwargs:
+            kwargs["state"] = "ENABLED" if kwargs.pop("enabled") else "DISABLED"
+
+        # Transform ID fields in kwargs
+        transform_common_id_fields(self.reformat_params, kwargs, payload)
+
+        # Add remaining optional parameters to payload
+        for key, value in kwargs.items():
+            payload[snake_to_camel(key)] = value
+
+        response = self.rest.put(f"webDlpRules/{rule_id}", json=payload)
+        if isinstance(response, Response) and not response.ok:
+            # Handle error response
+            raise Exception(
+                f"API call failed with status {response.status_code}: {response.json()}"
+            )
+
+        # Return the updated object
+        return self.get_rule(rule_id)
+
+    def delete_rule(self, rule_id: str) -> Box:
+        """
+        Deletes a DLP policy rule. This endpoint is not applicable to SaaS Security API DLP policy rules.
+
+        Args:
+            rule_id (str): Unique id of the Web DLP Policy Rule that will be deleted.
+
+        Returns:
+            :obj:`Box`: Response message from the ZIA API endpoint.
+
+        Examples:
+            Delete a rule with an id of 9999.
+
+            >>> results = zia.web_dlp.delete_rule(rule_id=9999)
+            ... print(results)
+
+
+        """
+        return self.rest.delete(f"webDlpRules/{rule_id}").status_code

zscaler/zia/workload_groups.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+
+# 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.
+
+from box import BoxList
+from requests import Response
+
+from zscaler.zia import ZIAClient
+
+
+class WorkloadGroupsAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def list_groups(self, **kwargs) -> BoxList:
+        """
+        Returns a list of all firewall filter rules.
+
+        Returns:
+            :obj:`BoxList`: The list of firewall filter rules
+
+        Examples:
+            >>> for rule in zia.workload_groups.list_groups():
+            ...    pprint(rule)
+
+        """
+        response = self.rest.get("/workloadGroups")
+        if isinstance(response, Response):
+            return None
+        return response
+
+    # Search Workload Group By Name
+    def get_group_by_name(self, name):
+        groups = self.list_groups()
+        for group in groups:
+            if group.get("name") == name:
+                return group
+        return None
+
+    # Search Workload Group By ID
+    def get_group_by_id(self, group_id):
+        groups = self.list_groups()
+        for group in groups:
+            if group.get("id") == group_id:
+                return group
+        return None

zscaler/zia/zpa_gateway.py

@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+
+# 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.
+
+from box import Box, BoxList
+from requests import Response
+
+from zscaler.utils import convert_keys, snake_to_camel
+from zscaler.zia import ZIAClient
+
+
+class ZPAGatewayAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def list_gateways(self, **kwargs) -> BoxList:
+        """
+        Returns a list of all ZPA Gateways.
+
+        Returns:
+            :obj:`BoxList`: The list of all ZPA Gateways Items
+
+        Returns:
+            :obj:`BoxList`: The list of all ZPA Gateways Items
+
+        Examples:
+            Get a list of all  ZPA Gateways Items
+
+            >>> results = zia.zpa_gateway.list_gateways()
+            ... for item in results:
+            ...    print(item)
+        """
+        return self.rest.get("zpaGateways")
+
+    def get_gateway(self, gateway_id: str) -> Box:
+        """
+        Returns the zpa gateway details for a given ZPA Gateway.
+
+        Args:
+            gatewayId (str): The unique identifier for the ZPA Gateway.
+
+        Returns:
+            :obj:`Box`: The ZPA Gateway resource record.
+
+        Examples:
+            >>> gw = zia.zpa_gateway.get_gateway('99999')
+        """
+        response = self.rest.get("/zpaGateways/%s" % (gateway_id))
+        if isinstance(response, Response):
+            status_code = response.status_code
+            if status_code != 200:
+                return None
+        return response
+
+    def add_gateway(
+        self,
+        name: str,
+        zpa_server_group: dict = None,
+        zpa_app_segments: list = None,
+        **kwargs,
+    ) -> Box:
+        """
+        Creates a new ZPA Gateway.
+
+        Args:
+            name (str): The name of the ZPA Gateway.
+            zpa_server_group (dict, required): The ZPA Server Group that is
+                configured for Source IP Anchoring.
+            zpa_app_segments (list, optional): All the Application Segments that are
+                associated with the selected ZPA Server Group for which Source IP
+                Anchoring is enabled.
+
+        Keyword Args:
+            description (str): Additional details about the ZPA gateway.
+            type (str): Indicates whether the ZPA gateway is configured for Zscaler
+                Internet Access (using option ZPA) or Zscaler Cloud Connector (using
+                option ECZPA). Accepted values are 'ZPA' or 'ECZPA'.
+            zpa_tenant_id (int): The ID of the ZPA tenant where Source IP Anchoring
+                is configured
+
+        Returns:
+            :obj:`Box`: The newly added ZPA Gateway resource record.
+        """
+        payload = {"name": name, "type": "ZPA"}
+
+        if zpa_server_group:
+            payload["zpaServerGroup"] = {
+                "externalId": zpa_server_group.get("external_id"),
+                "name": zpa_server_group.get("name"),
+            }
+
+        if zpa_app_segments:
+            payload["zpaAppSegments"] = [
+                {"externalId": segment.get("external_id"), "name": segment.get("name")}
+                for segment in zpa_app_segments
+            ]
+
+        # Add other optional parameters to payload
+        for key, value in kwargs.items():
+            payload[snake_to_camel(key)] = value
+
+        response = self.rest.post("zpaGateways", json=payload)
+        if isinstance(response, Response):
+            # Handle error response
+            status_code = response.status_code
+            raise Exception(
+                f"API call failed with status {status_code}: {response.json()}"
+            )
+        return response
+
+    def update_gateway(self, gateway_id: str, **kwargs):
+        """
+        Updates information for the specified ZPA Gateway.
+
+        Args:
+            gateway_id (str): The unique id for the ZPA Gateway to be updated.
+
+        Keyword Args:
+            name (str): The name of the ZPA gateway.
+            description (str): Additional details about the ZPA gateway.
+            type (str): Indicates whether the ZPA gateway is configured for
+                Zscaler Internet Access (using option ZPA) or Zscaler Cloud
+                Connector (using option ECZPA). Accepted values are 'ZPA' or 'ECZPA'.
+            zpa_server_group (dict, optional): The ZPA Server Group configured for
+                Source IP Anchoring.
+            zpa_app_segments (list, optional): All the Application Segments associated
+                with the selected ZPA Server Group for which Source IP Anchoring is
+                enabled.
+            zpa_tenant_id (int): The ID of the ZPA tenant where Source IP Anchoring
+                is configured
+
+        Returns:
+            :obj:`Box`: The updated ZPA Gateway resource record.
+        """
+        payload = convert_keys(self.get_gateway(gateway_id))
+
+        # Update payload with provided arguments
+        for key, value in kwargs.items():
+            if key == "zpa_server_group" and isinstance(value, dict):
+                # Convert nested keys in zpa_server_group to camelCase
+                value = {snake_to_camel(k): v for k, v in value.items()}
+            elif key == "zpa_app_segments" and isinstance(value, list):
+                # Convert nested keys in zpa_app_segments to camelCase
+                value = [
+                    {snake_to_camel(k): v for k, v in item.items()} for item in value
+                ]
+
+            payload[snake_to_camel(key)] = value
+
+        response = self.rest.put(f"zpaGateways/{gateway_id}", json=payload)
+        if isinstance(response, Response) and not response.ok:
+            # Handle error response
+            raise Exception(
+                f"API call failed with status {response.status_code}: "
+                f"{response.json()}"
+            )
+
+        # Return the updated object
+        return self.get_gateway(gateway_id)
+
+    def delete_gateway(self, gateway_id):
+        """
+        Deletes the specified ZPA Gateway.
+
+        Args:
+            gateway_id (str): The unique identifier of the ZPA Gateway that will be deleted.
+
+        Returns:
+            :obj:`int`: The response code for the request.
+
+        Examples
+            >>> gateway = zia.zpa_gateway.delete_gateway('99999')
+
+        """
+        return self.rest.delete(f"zpaGateways/{gateway_id}").status_code