zscaler-sdk-python 0.9.0__tar.gz → 0.9.1__tar.gz

{zscaler_sdk_python-0.9.0 → zscaler_sdk_python-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 0.9.0
+Version: 0.9.1
 Summary: Official Python SDK for the Zscaler Products (Beta)
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT
@@ -22,7 +22,7 @@ Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: dev
 Requires-Dist: aenum ; extra == "dev"
-Requires-Dist: aiohttp (>=3.10.5)
+Requires-Dist: aiohttp (>=3.10.2)
 Requires-Dist: arrow
 Requires-Dist: black (>=24.3.0) ; extra == "dev"
 Requires-Dist: certifi (>=2024.2.2)
@@ -30,7 +30,7 @@ Requires-Dist: charset-normalizer
 Requires-Dist: cryptography (>=43.0.0)
 Requires-Dist: flake8
 Requires-Dist: flatdict
-Requires-Dist: idna (>=3.7,<4.0)
+Requires-Dist: idna
 Requires-Dist: okta (>=2.9.7)
 Requires-Dist: pycryptodomex
 Requires-Dist: pydash (>=8.0.3) ; extra == "dev"

{zscaler_sdk_python-0.9.0 → zscaler_sdk_python-0.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zscaler-sdk-python"
-version = "0.9.0"
+version = "0.9.1"
 description = "Official Python SDK for the Zscaler Products (Beta)"
 authors = ["Zscaler, Inc. <devrel@zscaler.com>"]
 license = "MIT"
@@ -32,7 +32,7 @@ python = ">=3.9,<4.0"
 arrow = "*"
 certifi = ">=2024.2.2"
 charset-normalizer = "*"
-idna = "^3.7"
+idna = "*"
 python-box = ">=7.2.0"
 python-dateutil = "*"
 requests = ">=2.32.3"
@@ -52,12 +52,12 @@ black = ">=24.3.0"
 # cryptography = ">=3.4,<43.0"
 cryptography = ">=43.0.0"
 okta = ">=2.9.7"
-aiohttp = ">=3.10.5"
+aiohttp = ">=3.10.2"
 
 [tool.poetry.dev-dependencies]
 black = ">=24.3.0"
 pytest = ">=8.3.1"
-pytest-asyncio = ">=0.23.8"
+pytest-asyncio = "^0.23.8"
 pytest-mock = "*"
 pytest-recording = "^0.13.2"
 pytest-cov = "*"

{zscaler_sdk_python-0.9.0 → zscaler_sdk_python-0.9.1}/zscaler/__init__.py

@@ -29,9 +29,10 @@ __license__ = "MIT"
 __contributors__ = [
     "William Guilherme",
 ]
-__version__ = "0.9.0"
+__version__ = "0.9.1"
 
 from zscaler.zdx import ZDXClientHelper  # noqa
 from zscaler.zia import ZIAClientHelper  # noqa
 from zscaler.zpa import ZPAClientHelper  # noqa
 from zscaler.zcon import ZCONClientHelper  # noqa
+from zscaler.zcc import ZCCClientHelper  # noqa

zscaler_sdk_python-0.9.1/zscaler/zcc/__init__.py

@@ -0,0 +1,265 @@
+import logging
+import os
+import urllib.parse
+import uuid
+import time
+import requests
+from datetime import datetime, timedelta
+
+from zscaler import __version__
+from zscaler.user_agent import UserAgent
+from zscaler.utils import (
+    dump_request,
+    dump_response,
+    format_json_response,
+    is_token_expired,
+    retry_with_backoff,
+)
+from zscaler.logger import setup_logging
+from .devices import DevicesAPI
+from .secrets import SecretsAPI
+
+from zscaler.zcc.client import ZCCClient
+
+# Setup the logger
+setup_logging(logger_name="zscaler-sdk-python")
+logger = logging.getLogger("zscaler-sdk-python")
+
+
+class ZCCClientHelper(ZCCClient):
+    """
+    A Controller to access Endpoints in the Zscaler Mobile Admin Portal API.
+
+    The ZCC object stores the session token and simplifies access to CRUD options within the ZCC Portal.
+
+    Attributes:
+        client_id (str): The ZCC Client ID generated from the ZCC Portal.
+        client_secret (str): The ZCC Client Secret generated from the ZCC Portal.
+        cloud (str): The Zscaler cloud for your tenancy, accepted values are:
+
+            * ``zscaler``
+            * ``zscalerone``
+            * ``zscalertwo``
+            * ``zscalerthree``
+            * ``zscloud``
+            * ``zscalerbeta``
+        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://.
+
+    """
+
+    _vendor = "Zscaler"
+    _product = "Zscaler Mobile Admin Portal"
+    _backoff = 3
+    _build = __version__
+    _env_base = "ZCC"
+    _env_cloud = "zscaler"
+
+    RATE_LIMIT = 100  # 100 API calls per hour
+    DOWNLOAD_DEVICES_LIMIT = 3  # 3 calls per day
+    RATE_LIMIT_RESET_TIME = timedelta(hours=1)
+    DOWNLOAD_DEVICES_RESET_TIME = timedelta(days=1)
+
+    def __init__(self, **kw):
+        self._apikey = kw.get("apikey", os.getenv(f"{self._env_base}_CLIENT_ID"))
+        self._secret_key = kw.get("secret_key", os.getenv(f"{self._env_base}_CLIENT_SECRET"))
+        self._env_cloud = (
+            os.getenv(f"{self._env_base}_CLOUD") if os.getenv(f"{self._env_base}_CLOUD") is not None else kw.get("cloud")
+        )
+        self.login_url = f"https://api-mobile.{self._env_cloud}.net/papi/auth/v1/login"
+        self.url = f"https://api-mobile.{self._env_cloud}.net/papi/public/v1"
+
+        self.user_agent = UserAgent().get_user_agent_string()  # Ensure this returns a string
+        self.auth_token = None
+        self.headers = {}
+        self.refreshToken()
+
+        # Initialize rate limit tracking
+        self.last_request_time = datetime.utcnow()
+        self.request_count = 0
+
+        # Track specific download devices endpoint usage
+        self.download_devices_count = 0
+        self.download_devices_last_reset = datetime.utcnow()
+
+    def __enter__(self):
+        self.refreshToken()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        logger.debug("Deauthenticating...")
+
+    def refreshToken(self):
+        if not self.auth_token or is_token_expired(self.auth_token):
+            response = self.login()
+            if response is None or response.status_code > 299 or not response.json():
+                logger.error("Failed to login using provided credentials, response: %s", response)
+                raise Exception("Failed to login using provided credentials.")
+            self.auth_token = response.json().get("jwtToken")
+            self.headers = {
+                "Content-Type": "application/json",
+                "Accept": "*/*",
+                "auth-token": f"{self.auth_token}",
+                "User-Agent": self.user_agent,
+            }
+
+    @retry_with_backoff(retries=5)
+    def login(self):
+        data = {"apiKey": self._apikey, "secretKey": self._secret_key}
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "*/*",
+            "User-Agent": self.user_agent,
+        }
+        try:
+            url = self.login_url
+            resp = requests.post(url, json=data, headers=headers)
+            logger.info("Login attempt with status: %d", resp.status_code)
+            return resp
+        except Exception as e:
+            logger.error("Login failed due to an exception: %s", str(e))
+            return None
+
+    def check_rate_limit(self, path):
+        """
+        Checks the rate limit and adjusts the request timing accordingly.
+        """
+        current_time = datetime.utcnow()
+        time_since_last_request = current_time - self.last_request_time
+
+        # Reset the rate limit counter if the reset time has passed
+        if time_since_last_request >= self.RATE_LIMIT_RESET_TIME:
+            self.request_count = 0
+            self.last_request_time = current_time
+
+        if "/downloadDevices" in path:
+            time_since_last_reset = current_time - self.download_devices_last_reset
+            if time_since_last_reset >= self.DOWNLOAD_DEVICES_RESET_TIME:
+                self.download_devices_count = 0
+                self.download_devices_last_reset = current_time
+            if self.download_devices_count >= self.DOWNLOAD_DEVICES_LIMIT:
+                logger.warning("Rate limit exceeded for /downloadDevices endpoint. Backing off...")
+                time.sleep(24 * 60 * 60)  # Back off for a day
+                self.download_devices_count = 0
+                self.download_devices_last_reset = datetime.utcnow()
+            self.download_devices_count += 1
+        else:
+            if self.request_count >= self.RATE_LIMIT:
+                logger.warning("Rate limit exceeded. Backing off...")
+                time.sleep(3600)  # Back off for an hour
+                self.request_count = 0
+                self.last_request_time = datetime.utcnow()
+            self.request_count += 1
+
+    def send(self, method, path, json=None, params=None, stream=False):
+        api = self.url
+        if params is None:
+            params = {}
+        url = f"{api}/{path.lstrip('/')}"
+        if params:
+            url = f"{url}?{urllib.parse.urlencode(params)}"
+
+        start_time = time.time()
+        headers_with_user_agent = self.headers.copy()
+        headers_with_user_agent["User-Agent"] = self.user_agent
+        request_uuid = str(uuid.uuid4())
+        dump_request(logger, url, method, json, None, headers_with_user_agent, request_uuid)
+
+        # Check rate limits
+        self.check_rate_limit(path)
+
+        attempts = 0
+        while attempts < 5:
+            try:
+                self.refreshToken()
+                resp = requests.request(
+                    method,
+                    url,
+                    json=json,
+                    params=None,
+                    headers=headers_with_user_agent,
+                    stream=stream,
+                )
+                dump_response(
+                    logger=logger,
+                    url=url,
+                    params=None,
+                    method=method,
+                    resp=resp,
+                    request_uuid=request_uuid,
+                    start_time=start_time,
+                )
+                if resp.status_code == 429:
+                    retry_after = resp.headers.get("Retry-After")
+                    if retry_after:
+                        try:
+                            sleep_time = int(retry_after)
+                        except ValueError:
+                            sleep_time = int(retry_after[:-1])
+                        logger.warning(f"Rate limit exceeded. Retrying in {sleep_time} seconds.")
+                        time.sleep(sleep_time)
+                    else:
+                        time.sleep(60)
+                    attempts += 1
+                    continue
+                else:
+                    break
+            except requests.RequestException as e:
+                if attempts == 4:
+                    logger.error(f"Failed to send {method} request to {url} after 5 attempts. Error: {str(e)}")
+                    raise e
+                else:
+                    logger.warning(f"Failed to send {method} request to {url}. Retrying... Error: {str(e)}")
+                    attempts += 1
+                    time.sleep(5)
+
+        return resp
+
+    def get(self, path, json=None, params=None, stream=False):
+        """
+        Send a GET request to the ZCC API.
+
+        Parameters:
+        path (str): API endpoint path.
+        json (dict, optional): Request payload. Defaults to None.
+        params (dict, optional): Query parameters. Defaults to None.
+        stream (bool, optional): Whether to stream the response content. Defaults to False.
+
+        Returns:
+        Response: The response object from the API request.
+        """
+        resp = self.send("GET", path, json, params, stream=stream)
+        if stream:
+            return resp
+        formatted_resp = format_json_response(resp, box_attrs=dict())
+        return formatted_resp
+
+    def post(self, path, json=None, params=None):
+        """
+        Send a POST request to the ZCC API.
+
+        Parameters:
+        path (str): API endpoint path.
+        json (dict, optional): Request payload. Defaults to None.
+        params (dict, optional): Query parameters. Defaults to None.
+
+        Returns:
+        dict: Formatted JSON response from the API.
+        """
+        resp = self.send("POST", path, json, params)
+        formatted_resp = format_json_response(resp, box_attrs=dict())
+        return formatted_resp
+
+    @property
+    def devices(self):
+        """The interface object for the :ref:`ZCC Devices interface <zcc-devices>`."""
+        return DevicesAPI(self)
+
+    @property
+    def secrets(self):
+        """The interface object for the :ref:`ZCC Secrets interface <zcc-secrets>`."""
+        return SecretsAPI(self)

zscaler_sdk_python-0.9.1/zscaler/zcc/client.py

@@ -0,0 +1,65 @@
+# -*- 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.
+
+
+class ZCCClient:
+    def __init__():
+        pass
+
+    def get(
+        self,
+        path: str,
+        json=None,
+        params=None,
+        stream=False,
+    ):
+        """
+        Send a GET request to the ZCC API.
+        Parameters:
+        - path (str): API endpoint path.
+        - json (str): the request body.
+        - params (dict): the query params
+        """
+        pass
+
+    def get_paginated_data(
+        self,
+        path=None,
+        params=None,
+        search=None,
+        search_field="name",
+        page=None,
+        pagesize=20,
+    ):
+        """
+        Send a GET request to the ZCC API to fetch all pages of a resources.
+        Parameters:
+        - path (str): API endpoint path.
+        - data_key_name (str): list field key.
+        - data_per_page: the page size
+        - params (dict): the query params
+        """
+        pass
+
+    def post(self, path: str, json=None, params=None):
+        """
+        Send a POST request to the ZCC API.
+        Parameters:
+        - path (str): API endpoint path.
+        - json (str): the request body.
+        - params (dict): the query params
+        """
+        pass

zscaler_sdk_python-0.9.1/zscaler/zcc/devices.py

@@ -0,0 +1,220 @@
+import shutil
+from datetime import datetime
+from box import BoxList
+from zscaler.zcc.client import ZCCClient
+from zscaler.utils import convert_keys, zcc_param_map
+
+
+class DevicesAPI:
+
+    def __init__(self, client: ZCCClient):
+        self.rest = client
+
+    def download_devices(
+        self,
+        filename: str = None,
+        os_types: list = None,
+        registration_types: list = None,
+    ):
+        """
+        Downloads the list of devices in the Client Connector Portal as a CSV file.
+
+        By default, this method will create a file named `zcc-devices-YYmmDD-HH_MM_SS.csv`. This can be overridden by
+        specifying the ``filename`` argument.
+
+        Notes:
+            This API endpoint is heavily rate-limited by Zscaler and as of NOV 2022 only 3 calls per-day are allowed.
+
+        Args:
+            filename (str):
+                The name of the file that you want to save to disk.
+            os_types (list):
+                A list of OS Types to filter the device list. Omitting this argument will result in all OS types being
+                matched.
+                Valid options are:
+
+                - ios
+                - android
+                - windows
+                - macos
+                - linux
+            registration_types (list):
+                A list of device registration states to filter the device list.
+                Valid options are:
+
+                - all (provides all states except for 'removed')
+                - registered
+                - removal_pending
+                - unregistered
+                - removed
+                - quarantined
+
+        Returns:
+            :obj:`str`: The local filename for the CSV file that was downloaded.
+
+        Examples:
+            Create a CSV with all OS types and all registration types:
+
+            >>> zcc.devices.download_devices(registration_types=["all", "removed"])
+
+            Create a CSV for Windows and macOS devices that are in the `registered` state:
+
+            >>> zcc.devices.download_devices(os_types=["windows", "macos"],
+            ...     registration_types=["registered"])
+
+            Create a CSV with filename `unregistered.csv` for devices in the unregistered state:
+
+            >>> zcc.devices.download_devices(filename="unregistered.csv",
+            ...     registration_types=["unregistered"])
+
+        """
+
+        if not filename:
+            filename = f"zcc-devices-{datetime.now().strftime('%Y%m%d-%H_%M_%S')}.csv"
+
+        params = {}
+
+        # Simplify the os_type argument, raise an error if the user supplies the wrong one.
+        if os_types:
+            for item in os_types:
+                os_type = zcc_param_map["os"].get(item, None)
+                if os_type:
+                    if "osTypes" not in params:
+                        params["osTypes"] = str(os_type)
+                    else:
+                        params["osTypes"] += "," + str(os_type)
+                else:
+                    raise ValueError("Invalid os_type specified. Check the pyZscaler documentation for valid os_type options.")
+
+        # Simplify the registration_type argument, raise an error if the user supplies the wrong one.
+        if registration_types:
+            for item in registration_types:
+                reg_type = zcc_param_map["reg_type"].get(item, None)
+                if reg_type:
+                    if "registrationTypes" not in params:
+                        params["registrationTypes"] = str(reg_type)
+                    else:
+                        params["registrationTypes"] += "," + str(reg_type)
+                else:
+                    raise ValueError(
+                        "Invalid registration_type specified. Check the pyZscaler documentation for valid "
+                        "registration_type options."
+                    )
+
+        # Create the local file and stream the device list csv to it
+        with self.rest.get("downloadDevices", params=params, stream=True) as r:
+            with open(filename, "wb") as f:
+                f.write(r.content)
+
+        return filename
+
+    def list_devices(self, **kwargs) -> BoxList:
+        """
+        Returns the list of devices enrolled in the Client Connector Portal.
+
+        Keyword Args:
+            os_type (str):
+                Filter by device operating system. Valid options are:
+
+                - ios
+                - android
+                - windows
+                - macos
+                - linux
+            page (int):
+                Return a specific page number.
+            page_size (int):
+                Specify the number of devices per page, defaults to ``30``.
+            user_name (str):
+                Filter by the enrolled user for the device.
+
+        Returns:
+            :obj:`BoxList`: A list containing devices using ZCC enrolled in the Client Connector Portal.
+
+        Examples:
+            Prints all devices in the Client Connector Portal to the console:
+
+            >>> for device in zcc.devices.list_devices():
+            ...    print(device)
+
+        """
+        payload = convert_keys(dict(kwargs))
+
+        # Simplify the os_type argument, raise an error if the user supplies the wrong one.
+        if kwargs.get("os_type"):
+            os_type = zcc_param_map["os"].get(payload["osType"], None)
+            if os_type:
+                payload["osType"] = os_type
+            else:
+                raise ValueError("Invalid os_type specified. Check the Zscaler documentation for valid os_type options.")
+
+        return self.rest.get("getDevices", **payload)
+
+    def remove_devices(self, force: bool = False, **kwargs):
+        """
+        Removes the specified devices from the Zscaler Client Connector Portal.
+
+        Notes:
+            You must be using API credentials with the `Write` role.
+            You must specify at least one criterion from `Keyword Args` to remove devices.
+
+        Args:
+            force (bool):
+                Setting force to ``True`` removes the enrolled device from the portal. You can only remove devices that
+                are in the `registered` or `device removal pending` state.
+            **kwargs:
+                Optional keyword args.
+
+        Keyword Args:
+            client_connector_version (list):
+                A list of client connector versions that will be removed. You must supply the exact version number, i.e.
+                if the Client Connector version is `3.2.0.18` you must specify `3.2.0.18` and not `3.2`.
+            os_type (str):
+                The OS Type for the devices to be removed. Valid options are:
+
+                - ios
+                - android
+                - windows
+                - macos
+                - linux
+            udids (list):
+                A list of Unique Device IDs.
+            user_name (str):
+                The username of the user whose devices will be removed.
+
+        Returns:
+            :obj:`Box`: Server response containing the total number of devices removed.
+
+        Examples:
+            Soft-remove devices using ZCC version 3.7.1.44 from the Client Connector Portal:
+
+            >>> zcc.devices.remove_devices(client_connector_version=["3.7.1.44"])
+
+            Soft-remove Android devices from the Client Connector Portal:
+
+            >>> zcc.devices.remove_devices(os_type="android")
+
+            Hard-remove devices from the Client Connector Portal by UDID:
+
+            >>> zcc.devices.remove_devices(force=True, udids=["99999", "88888", "77777"])
+
+            Hard-remove Android devices for johnno@widgets.co from the Client Connector Portal:
+
+            >>> zcc.devices.remove_devices(force=True, os_type="android",
+            ...     user_name="johnno@widgets.co")
+
+        """
+        payload = convert_keys(dict(kwargs))
+
+        # Simplify the os_type argument, raise an error if the user supplies the wrong one.
+        if kwargs.get("os_type"):
+            os_type = zcc_param_map["os"].get(payload["osType"], None)
+            if os_type:
+                payload["osType"] = os_type
+            else:
+                raise ValueError("Invalid os_type specified. Check the pyZscaler documentation for valid os_type options.")
+
+        if force:
+            return self.rest.post("forceRemoveDevices", json=payload)
+        else:
+            return self.rest.post("removeDevices", json=payload)

zscaler_sdk_python-0.9.1/zscaler/zcc/secrets.py

@@ -0,0 +1,66 @@
+from zscaler.zcc.client import ZCCClient
+from zscaler.utils import zcc_param_map
+
+
+class SecretsAPI:
+    def __init__(self, client: ZCCClient):
+        self.rest = client
+
+    def get_otp(self, device_id: str):
+        """
+        Returns the OTP code for the specified device id.
+
+        Args:
+            device_id (str): The unique id for the enrolled device that the OTP will be obtained for.
+
+        Returns:
+            :obj:`Box`: A dictionary containing the requested OTP code for the specified device id.
+
+        Examples:
+            Obtain the OTP code for a device and print it to console:
+
+            >>> otp_code = zcc.secrets.get_otp('System-Serial-Number:1234ABCDEF')
+            ... print(otp_code.otp)
+
+        """
+
+        payload = {"udid": device_id}
+
+        return self.rest.get("getOtp", params=payload)
+
+    def get_passwords(self, username: str, os_type: str = "windows"):
+        """
+        Return passwords for the specified username and device OS type.
+
+        Args:
+            username (str): The username that the device belongs to.
+            os_type (str): The OS Type for the device, defaults to `windows`. Valid options are:
+
+                - ios
+                - android
+                - windows
+                - macos
+                - linux
+
+        Returns:
+            :obj:`Box`: Dictionary containing passwords for the specified username's device.
+
+        Examples:
+            Print macOS device passwords for username test@example.com:
+
+            >>> print(zcc.secrets.get_passwords(username='test@example.com',
+            ...    os_type='macos'))
+
+        """
+
+        # Simplify the os_type argument, raise an error if the user supplies the wrong one.
+        os_type = zcc_param_map["os"].get(os_type, None)
+        if not os_type:
+            raise ValueError("Invalid os_type specified. Check the pyZscaler documentation for valid os_type options.")
+
+        params = {
+            "username": username,
+            "osType": os_type,
+        }
+
+        return self.rest.get("getPasswords", params=params)

{zscaler_sdk_python-0.9.0 → zscaler_sdk_python-0.9.1}/zscaler/zcon/__init__.py

@@ -67,7 +67,7 @@ class ZCONClientHelper(ZCONClient):
     """
 
     _vendor = "Zscaler"
-    _product = "Zscaler CON Cloud"
+    _product = "Zscaler Cloud and Branch Connector"
     _build = __version__
     _env_base = "ZCON"
     env_cloud = "zscaler"