zscaler-sdk-python 0.5.1__tar.gz → 0.6.0__tar.gz

{zscaler_sdk_python-0.5.1 → zscaler_sdk_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 0.5.1
+Version: 0.6.0
 Summary: Official Python SDK for the Zscaler Products (Beta)
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT
@@ -37,7 +37,7 @@ Requires-Dist: python-box (>=7.2.0,<8.0.0)
 Requires-Dist: python-dateutil
 Requires-Dist: pytz
 Requires-Dist: pyyaml
-Requires-Dist: requests (>=2.32.0)
+Requires-Dist: requests (>=2.32.3)
 Requires-Dist: responses (>=0.25.3)
 Requires-Dist: restfly
 Requires-Dist: six

{zscaler_sdk_python-0.5.1 → zscaler_sdk_python-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zscaler-sdk-python"
-version = "0.5.1"
+version = "0.6.0"
 description = "Official Python SDK for the Zscaler Products (Beta)"
 authors = ["Zscaler, Inc. <devrel@zscaler.com>"]
 license = "MIT"
@@ -35,7 +35,7 @@ charset-normalizer = "*"
 idna = "*"
 python-box = "^7.2.0"
 python-dateutil = "*"
-requests = ">=2.32.0"
+requests = ">=2.32.3"
 responses = ">=0.25.3"
 restfly = "*"
 six = "*"

{zscaler_sdk_python-0.5.1 → zscaler_sdk_python-0.6.0}/zscaler/__init__.py

@@ -29,7 +29,7 @@ __license__ = "MIT"
 __contributors__ = [
     "William Guilherme",
 ]
-__version__ = "0.5.1"
+__version__ = "0.6.0"
 
 from zscaler.zia import ZIAClientHelper  # noqa
 from zscaler.zpa import ZPAClientHelper  # noqa

{zscaler_sdk_python-0.5.1 → zscaler_sdk_python-0.6.0}/zscaler/ratelimiter/ratelimiter.py

@@ -35,3 +35,26 @@ class RateLimiter:
                 self.post_put_delete_requests.append(now)
 
             return False, 0
+
+    def update_limits(self, headers):
+        if "X-Ratelimit-Limit-Second" in headers:
+            self.get_limit = int(headers["X-Ratelimit-Limit-Second"])
+            self.post_put_delete_limit = int(headers["X-Ratelimit-Limit-Second"])
+        if "X-Ratelimit-Reset" in headers:
+            self.get_freq = int(headers["X-Ratelimit-Reset"])
+            self.post_put_delete_freq = int(headers["X-Ratelimit-Reset"])
+
+        # Handle minute, hour, and day limits
+        if "X-RateLimit-Limit-Minute" in headers:
+            self.minute_limit = int(headers["X-RateLimit-Limit-Minute"])
+        if "X-RateLimit-Limit-Hour" in headers:
+            self.hour_limit = int(headers["X-RateLimit-Limit-Hour"])
+        if "X-RateLimit-Limit-Day" in headers:
+            self.day_limit = int(headers["X-RateLimit-Limit-Day"])
+
+        if "X-RateLimit-Remaining-Minute" in headers:
+            self.remaining_minute = int(headers["X-RateLimit-Remaining-Minute"])
+        if "X-RateLimit-Remaining-Hour" in headers:
+            self.remaining_hour = int(headers["X-RateLimit-Remaining-Hour"])
+        if "X-RateLimit-Remaining-Day" in headers:
+            self.remaining_day = int(headers["X-RateLimit-Remaining-Day"])

{zscaler_sdk_python-0.5.1 → zscaler_sdk_python-0.6.0}/zscaler/utils.py

@@ -17,7 +17,7 @@
 import argparse
 import base64
 import datetime
-import json
+import functools
 import json as jsonp
 import logging
 import random
@@ -147,26 +147,6 @@ def add_id_groups(id_groups: list, kwargs: dict, payload: dict):
     return
 
 
-# def transform_common_id_fields(id_groups: list, kwargs: dict, payload: dict):
-#     for entry in id_groups:
-#         if kwargs.get(entry[0]):
-#             # Ensure each ID is treated as an integer before adding it to the payload
-#             payload[entry[1]] = [{"id": int(param_id)} for param_id in kwargs.pop(entry[0])]
-#     return
-
-# ####### Function used in the ZIA Forwarding Control Rule #######
-# def transform_fwd_id_fields(id_groups: list, kwargs: dict, payload: dict):
-#     for entry in id_groups:
-#         key, payload_key = entry
-#         if key in kwargs:
-#             value = kwargs.pop(key)
-#             if isinstance(value, dict):
-#                 payload[payload_key] = {k: v for k, v in value.items() if k in ['id', 'name']}
-#             elif isinstance(value, list):
-#                 payload[payload_key] = [{"id": int(item)} if isinstance(item, str) and item.isdigit() else item for item in value]
-#     return
-
-
 def transform_common_id_fields(id_groups: list, kwargs: dict, payload: dict):
     for entry in id_groups:
         key, payload_key = entry
@@ -343,6 +323,208 @@ class Iterator(APIIterator):
             time.sleep(1)
 
 
+def calculate_epoch(hours: int):
+    current_time = int(time.time())
+    past_time = int(current_time - (hours * 3600))
+    return current_time, past_time
+
+
+def zdx_params(func):
+    """
+    Decorator to add custom parameter functionality for ZDX API calls.
+
+    Args:
+        func: The function to decorate.
+
+    Returns:
+        The decorated function.
+
+    """
+
+    @functools.wraps(func)
+    def wrapper(self, *args, **kwargs):
+        since = kwargs.pop("since", None)
+        search = kwargs.pop("search", None)
+        location_id = kwargs.pop("location_id", None)
+        department_id = kwargs.pop("department_id", None)
+        geo_id = kwargs.pop("geo_id", None)
+
+        if since:
+            current_time, past_time = calculate_epoch(since)
+            kwargs["to"] = current_time
+            kwargs["from"] = past_time
+
+        kwargs["q"] = search or kwargs.get("q")
+        kwargs["loc"] = location_id or kwargs.get("loc")
+        kwargs["dept"] = department_id or kwargs.get("dept")
+        kwargs["geo"] = geo_id or kwargs.get("geo")
+
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+class CommonFilters:
+    def __init__(self, **kwargs):
+        valid_params = {
+            "from_time": None,
+            "to": None,
+            "score_bucket": None,
+            "app_id": None,
+            "loc": None,
+            "exclude_loc": None,
+            "dept": None,
+            "exclude_dept": None,
+            "geo": None,
+            "exclude_geo": None,
+            "offset": None,
+            "limit": None,
+        }
+
+        for key, value in kwargs.items():
+            if key in valid_params:
+                setattr(self, key, value)
+
+    def to_dict(self):
+        return {
+            k: v
+            for k, v in {
+                "from": getattr(self, "from_time", None),
+                "to": getattr(self, "to", None),
+                "score_bucket": getattr(self, "score_bucket", None),
+                "app_id": getattr(self, "app_id", None),
+                "loc": getattr(self, "loc", None),
+                "exclude_loc": getattr(self, "exclude_loc", None),
+                "dept": getattr(self, "dept", None),
+                "exclude_dept": getattr(self, "exclude_dept", None),
+                "geo": getattr(self, "geo", None),
+                "exclude_geo": getattr(self, "exclude_geo", None),
+                "offset": getattr(self, "offset", None),
+                "limit": getattr(self, "limit", None),
+            }.items()
+            if v is not None
+        }
+
+
+class ZDXIterator:
+    def __init__(self, client, endpoint, filters=None):
+        self.client = client
+        self.endpoint = endpoint
+        self.filters = {k: v for k, v in (filters or {}).items() if v is not None}
+        self.next_offset = None
+        self.previous_offset = None
+        self.page = []
+        self.page_count = 0
+        self.total = 0
+        self.logger = logging.getLogger("zscaler-sdk-python")
+        self._get_page()
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if self.page_count >= len(self.page):
+            if self.next_offset is None:
+                raise StopIteration
+            if self.next_offset == self.previous_offset:
+                self.logger.warning(
+                    f"Detected repeated next_offset: {self.next_offset}, stopping iteration to avoid infinite loop."
+                )
+                raise StopIteration
+            self.previous_offset = self.next_offset
+            self._get_page()
+            if not self.page:
+                raise StopIteration
+        item = self.page[self.page_count]
+        self.page_count += 1
+        return item
+
+    def _get_page(self):
+        params = {**self.filters, "offset": self.next_offset} if self.next_offset else self.filters
+        response = self.client.get(self.endpoint, params=params)
+
+        self.logger.debug(f"API response: {response}")
+
+        if response is None:
+            self.logger.error(f"Invalid response: {response}")
+            raise StopIteration
+
+        if isinstance(response, list):
+            self.page = response
+            self.next_offset = None
+        elif isinstance(response, dict):
+            self.next_offset = response.get("next_offset")
+            self.page = (
+                response.get("alerts", [])
+                or response.get("items", [])
+                or response.get("devices", [])
+                or response.get("probes", [])
+                or response.get("software", [])
+            )
+        else:
+            self.logger.error(f"Unexpected response type: {type(response)}")
+            raise StopIteration
+
+        if not self.page:
+            self.next_offset = None
+
+        self.total += len(self.page)
+        self.page_count = 0
+
+
+# class ZDXIterator:
+#     def __init__(self, client, endpoint, filters=None):
+#         self.client = client
+#         self.endpoint = endpoint
+#         self.filters = {k: v for k, v in (filters or {}).items() if v is not None}
+#         self.next_offset = None
+#         self.page = []
+#         self.page_count = 0
+#         self.total = 0
+#         self.logger = logging.getLogger("zscaler-sdk-python")
+#         self._get_page()
+
+#     def __iter__(self):
+#         return self
+
+#     def __next__(self):
+#         if self.page_count >= len(self.page):
+#             if self.next_offset is None:
+#                 raise StopIteration
+#             self._get_page()
+#             if not self.page:
+#                 raise StopIteration
+#         item = self.page[self.page_count]
+#         self.page_count += 1
+#         return item
+
+#     def _get_page(self):
+#         params = {**self.filters, "offset": self.next_offset} if self.next_offset else self.filters
+#         response = self.client.get(self.endpoint, params=params)
+
+#         self.logger.debug(f"API response: {response}")
+
+#         if response is None:
+#             self.logger.error(f"Invalid response: {response}")
+#             raise StopIteration
+
+#         if isinstance(response, list):
+#             self.page = response
+#             self.next_offset = None
+#         elif isinstance(response, dict):
+#             self.next_offset = response.get("next_offset")
+#             self.page = response.get("devices", []) or response.get("items", []) or response.get("probes", [])
+#         else:
+#             self.logger.error(f"Unexpected response type: {type(response)}")
+#             raise StopIteration
+
+#         if not self.page:
+#             self.next_offset = None
+
+#         self.total += len(self.page)
+#         self.page_count = 0
+
+
 def remove_cloud_suffix(str_name: str) -> str:
     """
     Removes appended cloud name (e.g. "(zscalerthree.net)") from the string.
@@ -516,6 +698,26 @@ def validate_and_convert_times(start_time_str, end_time_str, time_zone_str):
     return start_epoch, end_epoch
 
 
+# Maps ZCC numeric os_type and registration_type arguments to a human-readable string
+zcc_param_map = {
+    "os": {
+        "ios": 1,
+        "android": 2,
+        "windows": 3,
+        "macos": 4,
+        "linux": 5,
+    },
+    "reg_type": {
+        "all": 0,
+        "registered": 1,
+        "removal_pending": 3,
+        "unregistered": 4,
+        "removed": 5,
+        "quarantined": 6,
+    },
+}
+
+
 def dump_request(logger, url: str, method: str, json, params, headers, request_uuid: str, body=True):
     request_headers_filtered = {key: value for key, value in headers.items() if key != "Authorization"}
     # Log the request details before sending the request

zscaler_sdk_python-0.6.0/zscaler/zdx/__init__.py

@@ -0,0 +1,78 @@
+import logging
+
+from zscaler import __version__
+from zscaler.zdx.admin import AdminAPI
+from zscaler.zdx.alerts import AlertsAPI
+from zscaler.zdx.apps import AppsAPI
+from zscaler.zdx.devices import DevicesAPI
+from zscaler.zdx.inventory import InventoryAPI
+from zscaler.zdx.troubleshooting import TroubleshootingAPI
+from zscaler.zdx.users import UsersAPI
+
+from zscaler.logger import setup_logging
+from .zdx_client import ZDXClientHelper  # Import ZDXClientHelper from zdx_client.py
+
+# Setup the logger
+setup_logging(logger_name="zscaler-sdk-python")
+logger = logging.getLogger("zscaler-sdk-python")
+
+
+class ZDX:
+    """
+    A Controller to access Endpoints in the Zscaler Digital Experience (ZDX) API.
+
+    The ZDX object stores the session token and simplifies access to CRUD options within the ZDX Portal.
+
+    Attributes:
+        client_id (str): The ZDX Client ID generated from the ZDX Portal.
+        client_secret (str): The ZDX Client Secret generated from the ZDX Portal.
+        cloud (str): The Zscaler cloud for your tenancy, accepted values are below. Defaults to ``zdxcloud``.
+
+            * ``zdxcloud``
+            * ``zdxbeta``
+
+        override_url (str):
+            If supplied, this attribute can be used to override the production URL that is derived
+            from supplying the `cloud` attribute. Use this attribute if you have a non-standard tenant URL
+            (e.g. internal test instance etc). When using this attribute, there is no need to supply the `cloud`
+            attribute. The override URL will be prepended to the API endpoint suffixes. The protocol must be included
+            i.e. http:// or https://.
+    """
+
+    def __init__(self, **kw):
+        self.client = ZDXClientHelper(**kw)
+
+    @property
+    def admin(self):
+        """The interface object for the :ref:`ZDX Admin interface <zdx-admin>`."""
+        return AdminAPI(self.client)
+
+    @property
+    def alerts(self):
+        """The interface object for the :ref:`ZDX Alerts interface <zdx-alerts>`."""
+        return AlertsAPI(self.client)
+
+    @property
+    def apps(self):
+        """The interface object for the :ref:`ZDX Apps interface <zdx-apps>`."""
+        return AppsAPI(self.client)
+
+    @property
+    def devices(self):
+        """The interface object for the :ref:`ZDX Devices interface <zdx-devices>`."""
+        return DevicesAPI(self.client)
+
+    @property
+    def inventory(self):
+        """The interface object for the :ref:`ZDX Inventory interface <zdx-inventory>`."""
+        return InventoryAPI(self.client)
+
+    @property
+    def troubleshooting(self):
+        """The interface object for the :ref:`ZDX Troubleshooting interface <zdx-troubleshooting>`."""
+        return TroubleshootingAPI(self.client)
+
+    @property
+    def users(self):
+        """The interface object for the :ref:`ZDX Users interface <zdx-users>`."""
+        return UsersAPI(self.client)

zscaler_sdk_python-0.6.0/zscaler/zdx/admin.py

@@ -0,0 +1,58 @@
+from box import BoxList
+from zscaler.utils import zdx_params
+from zscaler.utils import ZDXIterator, CommonFilters
+from zscaler.zdx.zdx_client import ZDXClientHelper
+
+
+class AdminAPI:
+    def __init__(self, client: ZDXClientHelper):
+        self.rest = client
+
+    @zdx_params
+    def list_departments(self, filters=None, **kwargs) -> BoxList:
+        """
+        Returns a list of departments that are configured within ZDX.
+
+        Keyword Args:
+            since (int): The number of hours to look back for devices.
+            search (str): The search string to filter by name or department ID.
+
+        Returns:
+            :obj:`BoxList`: The list of departments in ZDX.
+
+        Examples:
+            List all departments in ZDX for the past 2 hours:
+
+            >>> for department in zdx.admin.list_departments():
+            ...     print(department)
+
+        """
+        filters = CommonFilters(**kwargs).to_dict()
+        return ZDXIterator(self.rest, "administration/departments", filters)
+
+    @zdx_params
+    def list_locations(self, filters=None, **kwargs) -> BoxList:
+        """
+        Returns a list of locations that are configured within ZDX.
+
+        Keyword Args:
+            since (int): The number of hours to look back for devices.
+            search (str): The search string to filter by name or location ID.
+
+        Returns:
+            :obj:`BoxList`: The list of locations in ZDX.
+
+        Examples:
+            List all locations in ZDX for the past 2 hours:
+
+            >>> for location in zdx.admin.list_locations():
+            ...     print(location)
+
+        """
+        if filters is None:
+            filters = CommonFilters(**kwargs).to_dict()
+        else:
+            filters.update(kwargs)
+
+        iterator = ZDXIterator(self.rest, "administration/locations", filters)
+        return BoxList(iterator)

zscaler_sdk_python-0.6.0/zscaler/zdx/alerts.py

@@ -0,0 +1,121 @@
+from box import BoxList
+
+from zscaler.utils import ZDXIterator, CommonFilters
+from zscaler.zdx.zdx_client import ZDXClientHelper
+from zscaler.utils import zdx_params
+
+
+class AlertsAPI:
+    def __init__(self, client: ZDXClientHelper):
+        self.rest = client
+
+    @zdx_params
+    def list_ongoing(self, **kwargs) -> BoxList:
+        """
+        Returns a list of all ongoing alert rules across an organization in ZDX.
+
+        Keyword Args:
+            since (int): The number of hours to look back for devices.
+            department_id (str): The unique ID for the department.
+            geo_id (str): The unique ID for the geolocation.
+            user_ids (list): List of user IDs.
+            device_ids (list): List of device IDs.
+
+        Returns:
+            :obj:`BoxList`: The list of software in ZDX.
+
+        Examples:
+            List all ongoing alerts in ZDX for the past 2 hours:
+
+            >>> for alert in zdx.alerts.list_ongoing():
+            ...     print(alert)
+
+            List all ongoing alerts in ZDX for the past 24 hours:
+
+            >>> for alert in zdx.alerts.list_ongoing(since=24):
+            ...     print(alert)
+        """
+        filters = CommonFilters(**kwargs).to_dict()
+        return ZDXIterator(self.rest, "alerts/ongoing", filters)
+
+    @zdx_params
+    def list_historical(self, **kwargs) -> BoxList:
+        """
+        Returns a list of all ongoing alert rules across an organization in ZDX.
+
+        Keyword Args:
+            since (int): The number of hours to look back for devices.
+            department_id (str): The unique ID for the department.
+            geo_id (str): The unique ID for the geolocation.
+            user_ids (list): List of user IDs.
+            device_ids (list): List of device IDs.
+
+        Returns:
+            :obj:`BoxList`: The list of software in ZDX.
+
+        Examples:
+            List all ongoing alerts in ZDX for the past 2 hours:
+
+            >>> for alert in zdx.alerts.list_historical():
+            ...     print(alert)
+
+            List all ongoing alerts in ZDX for the past 24 hours:
+
+            >>> for alert in zdx.alerts.list_historical(since=24):
+            ...     print(alert)
+        """
+        filters = CommonFilters(**kwargs).to_dict()
+        return ZDXIterator(self.rest, "alerts/historical", filters)
+
+    @zdx_params
+    def get_alert(self, alert_id: str, **kwargs):
+        """
+        Returns a single alert in ZDX.
+
+        Args:
+            alert_id (str): The unique ID for the alert.
+
+        Keyword Args:
+            since (int): The number of hours to look back for devices.
+
+        Returns:
+            :obj:`Box`: The ZDX device resource record.
+
+        Examples:
+            Get information for the device with an ID of 123456789.
+            >>> device = zdx.alerts.get_alert('123456789')
+
+            Get information for the device with an ID of 123456789 for the last 24 hours.
+            >>> device = zdx.alerts.get_alert('123456789', since=24)
+
+        """
+        return self.rest.get(f"alerts/{alert_id}", params=kwargs)
+
+    @zdx_params
+    def list_affected_devices(self, alert_id, **kwargs) -> BoxList:
+        """
+        Returns a list of all all affected devices associated with
+        an alert rule in conjunction with provided filters.
+
+        Keyword Args:
+            since (int): The number of hours to look back for devices.
+            department_id (str): The unique ID for the department.
+            geo_id (str): The unique ID for the geolocation.
+            location_groups (list): List of location group IDs.
+
+        Returns:
+            :obj:`BoxList`: The list of software in ZDX.
+
+        Examples:
+            List all ongoing alerts in ZDX for the past 2 hours:
+
+            >>> for alert in zdx.alerts.list_affected_devices():
+            ...     print(alert)
+
+            List all ongoing alerts in ZDX for the past 24 hours:
+
+            >>> for alert in zdx.alerts.list_affected_devices(since=24):
+            ...     print(alert)
+        """
+        filters = CommonFilters(**kwargs).to_dict()
+        return ZDXIterator(self.rest, f"alerts/{alert_id}/affected_devices", filters)