zscaler-sdk-python 0.1.3__py3-none-any.whl

zscaler/zia/web_dlp.py

@@ -0,0 +1,291 @@
+# -*- 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,179 @@
+# -*- 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

zscaler/zpa/README.md

@@ -0,0 +1,40 @@
+## ZPA Pagination
+
+This SDK offers several pagination controls that help manage data retrieval efficiently from the API. Understanding and using these controls properly ensures effective data handling and optimal usage of network resources.
+
+### Available Pagination Controls
+
+1. **`page`**
+   - **Purpose:** Specifies the starting page number for the API request.
+   - **Use Case:** Ideal for resuming data fetching from a specific point, especially useful if the operations were previously interrupted.
+
+2. **`pagesize`**
+   - **Purpose:** Defines the number of items to be returned per page.
+   - **Use Case:** Designed to control the volume of data per API call, which is crucial for managing memory overhead and coping with current rate-limits.
+
+3. **`max_pages`**
+   - **Purpose:** Sets a limit on the number of pages that can be retrieved.
+   - **Use Case:** Great for to cap the extent of data fetched, especially when only a sample or a finite number of API calls is desired.
+
+4. **`max_items`**
+   - **Purpose:** Caps the total number of items retrieved across all pages.
+   - **Use Case:** Ensures that the fetching process stops once a specific number of items is reached, perfect when a precise dataset size is needed.
+
+### Guidelines and Best Practices
+
+- **Combining Controls:**
+  - Combining `page` and `pagesize` provides a straightforward control over the start point and volume of data for each fetch.
+  - Using `max_pages` and `max_items` provides limits on the fetching operations but from different perspectives: `max_pages` limits the number of fetch operations, whereas `max_items` limits the total number of items fetched.
+
+- **Preventing Parameter Conflicts:**
+  - Mixing `page` or `pagesize` with `max_pages` or `max_items` can lead to conflicts in the data fetching logic. To prevent these issues and ensure clarity:
+    - A `ValueError` exception is thrown if both sets of parameters are used simultaneously. This alert helps avoid misconfigurations that can lead to inefficient data fetching and potential performance issues.
+
+- **Error Handling:**
+  - **`ValueError`:** This is raised to alert about the improper use of incompatible pagination controls. It ensures developers are aware to not mix direct pagination controls (`page`, `pagesize`) with overarching limits (`max_pages`, `max_items`).
+
+- **Recommendations:**
+  - Use `page` and `pagesize` for straightforward pagination without intrinsic limits on the number or volume of data.
+  - Choose either `max_pages` or `max_items` based on the specific requirements of the operation to avoid unnecessary complexity and potential conflicts.
+  - Always set sensible defaults for `pagesize` to prevent excessive data fetches.
+