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

zscaler/__init__.py

@@ -0,0 +1,34 @@
+# -*- 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.
+
+"""Zscaler SDK for Python
+
+Zscaler SDK Python is an SDK that provides a uniform and easy-to-use interface for each of the Zscaler product APIs.
+
+Documentation available at https://zscaler-sdk-python.readthedocs.io
+
+"""
+
+__author__ = "Zscaler Inc"
+__email__ = "devrel@zscaler.com"
+__license__ = "MIT"
+__contributors__ = [
+    "William Guilherme",
+]
+__version__ = "1.0.0"
+
+from zscaler.zia import ZIAClientHelper  # noqa
+from zscaler.zpa import ZPAClientHelper  # noqa

zscaler/cache/cache.py

@@ -0,0 +1,105 @@
+from urllib.parse import parse_qs, urlencode, urlparse
+
+
+class Cache:
+    """
+    This is the ABSTRACT class that defines a Cache object for the ZPA Client
+    """
+
+    def __init__(self):
+        pass
+
+    def get(self, key):
+        """
+        A method which retrieves the desired value from the cache.
+
+        Arguments:
+            key {str} -- The key used to find the desired value
+
+        Raises:
+            NotImplementedError: If the subclass inheriting this class
+            has not implemented this function
+        """
+        raise NotImplementedError
+
+    def contains(self, key):
+        """
+        A method which checks if the cache contains the desired value.
+
+        Arguments:
+            key {str} -- The key used to check the desired value
+
+        Raises:
+            NotImplementedError: If the subclass inheriting this class
+            has not implemented this function
+        """
+        raise NotImplementedError
+
+    def add(self, key, value):
+        """
+        A method which adds a key-value pair to the cache.
+
+        Arguments:
+            key {str} -- The key used to identify the entry.
+            value {[type]} -- The value in the pair
+
+        Raises:
+            NotImplementedError: If the subclass inheriting this class
+            has not implemented this function
+        """
+        raise NotImplementedError
+
+    def delete(self, key):
+        """
+        A method which deletes a key-value pair from the cache.
+
+        Arguments:
+            key {str} -- The key used to identify the entry
+
+        Raises:
+            NotImplementedError: If the subclass inheriting this class
+            has not implemented this function
+        """
+        raise NotImplementedError
+
+    def clear(self):
+        """
+        A method used to empty the cache.
+
+        Raises:
+            NotImplementedError: If the subclass inheriting this class
+            has not implemented this function
+        """
+        raise NotImplementedError
+
+    def create_key(self, request, params):
+        """
+        A method used to create a unique key for an entry in the cache.
+        Used with URLs that requests fire at.
+
+        Arguments:
+            request {str} -- The key to use to produce a unique key
+
+        Returns:
+            str -- Unique key based on the input URL without query parameters
+        """
+        # Validate URL and return URL string without query parameters
+        # Parse the original URL
+        url_object = urlparse(request)
+
+        # Extract the query parameters from the URL
+        original_query_params = parse_qs(url_object.query)
+
+        # Update the query parameters with the provided `params` dictionary
+        if params is not None and len(params) > 0:
+            original_query_params.update(params)
+
+        # Create a new query string with the updated parameters
+        updated_query_string = urlencode(original_query_params, doseq=True)
+
+        # Combine the netloc, path, and the updated query string to form the new URL
+        base_url = f"{url_object.netloc}{url_object.path}"
+        if updated_query_string != "":
+            base_url = f"{base_url}?{updated_query_string}"
+
+        return base_url

zscaler/cache/no_op_cache.py

@@ -0,0 +1,68 @@
+import logging
+
+from zscaler.cache.cache import Cache
+
+# Setting up the logger
+logging.basicConfig(
+    level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+
+
+class NoOpCache(Cache):
+    """
+    This is a disabled Cache Class where no operations occur
+    in the cache.
+    Implementing the zscaler.cache.cache.Cache abstract class.
+    """
+
+    def __init__(self):
+        super()
+
+    def get(self, key):
+        """
+        Nothing is returned.
+
+        Arguments:
+            key {str} -- Key to look for
+
+        Returns:
+            None -- No op cache doesn't contain any data to return
+        """
+        logging.debug("Serving from cache.")
+        return None
+
+    def contains(self, key):
+        """
+        False is returned
+
+        Arguments:
+            key {str} -- Key to look for
+
+        Returns:
+            False -- No data to return so key can never be in cache
+        """
+        return False
+
+    def add(self, key, value):
+        """
+        This is a void method.
+
+        Arguments:
+            key {str} -- Key in pair
+            value {str} -- Val in pair
+        """
+        logging.warning("Saving to cache.")
+
+    def delete(self, key):
+        """This is a void method. No need to delete anything not contained.
+
+        Arguments:
+            key {str} -- Key to delete
+        """
+        pass
+
+    def clear(self):
+        """
+        This is a void method. No need to clear when nothing's stored.
+        """
+        pass

zscaler/cache/zscaler_cache.py

@@ -0,0 +1,161 @@
+import logging
+import time
+from urllib.parse import urlparse
+
+from zscaler.cache.cache import Cache
+
+logger = logging.getLogger("zscaler-sdk-python")
+
+
+class ZscalerCache(Cache):
+    """
+    This is a base class implementing a Cache using TTL and TTI.
+    Implementing the zscaler.cache.cache.Cache abstract class.
+    """
+
+    def __init__(self, ttl, tti):
+        """
+        Constructor.
+
+        Arguments:
+            ttl {float} -- Time to Live: for cache entries
+            tti {float} -- Time to Idle: for cache entries
+        """
+        super()  # Inherit from parent class
+        self._store = {}  # key -> {value, TTI, TTL}
+        self._time_to_live = ttl
+        self._time_to_idle = tti
+
+    def get(self, key):
+        """
+        Retrieves value from cache using key
+
+        Arguments:
+            key {str} -- Desired key
+
+        Returns:
+            str -- Corresponding value to given key
+            None -- Unable to find value for this key
+        """
+        # Get current time
+        now = self._get_current_time()
+        # Check if key is in cache and valid
+        if self.contains(key):
+            entry = self._store[key]
+            # Reset TTI
+            entry["tti"] = now + self._time_to_idle
+            # Return desired value and update cache
+            self._clean_cache()
+            logger.info(f'Got value from cache for key "{key}".')
+            logger.debug(f'Cached value for key {key}: {entry["value"]}')
+            return entry["value"]
+
+        # Return None if key isn't in cache and update cache
+        self._clean_cache()
+        return None
+
+    def contains(self, key):
+        """
+        Returns existence of key in cache, as boolean
+
+        Arguments:
+            key {str} -- Desired key
+
+        Returns:
+            bool -- Existence of key in cache
+        """
+        return key in self._store and self._is_valid_entry(self._store[key])
+
+    def add(self, key: str, value: tuple):
+        """
+        Adds a key-value pair to the cache.
+
+        Arguments:
+            key {str} -- Key in pair
+            value {tuple} -- Tuple of response and response body
+        """
+        if type(key) == str and (type(value) != list or type(value[1]) != list):
+            # Get current time
+            now = self._get_current_time()
+
+            # Add new entry to cache with timers
+            self._store[key] = {
+                "value": value,
+                "tti": now + self._time_to_idle,
+                "ttl": now + self._time_to_live,
+            }
+            logger.info(f'Added to cache value for key "{key}".')
+            logger.debug(f"Cached value for key {key}: {value}.")
+        # Update cache
+        self._clean_cache()
+
+    def delete(self, key):
+        """
+        Delete a key-value pair from the cache.
+
+        Arguments:
+            key {str} -- Desired key
+        """
+        logger.info(f'Removing value from cache for key "{key}".')
+        # Make sure key is in cache
+        if key in self._store:
+            # Delete entry
+            del self._store[key]
+            logger.info(f'Removed value from cache for key "{key}".')
+        url_object = urlparse(key)
+        base_url = f"{url_object.netloc}{url_object.path}"
+        for other_key in self._store.keys():
+            other_url_object = urlparse(other_key)
+            other_base_url = f"{other_url_object.netloc}{other_url_object.path}"
+            if not self._is_valid_entry(
+                self._store[other_key]
+            ) and other_base_url.startswith(base_url):
+                del self._store[other_key]
+                logger.info(f'Removed also value from cache for key "{other_key}".')
+
+    def clear(self):
+        """
+        Clear the cache.
+        """
+        self._store.clear()
+        logger.info("Cleared the cache.")
+
+    def _clean_cache(self):
+        """
+        Updates cache by removing expired entries at time of call
+        """
+        expired = []
+        # Check every entry
+        for key in self._store.keys():
+            # If not valid, delete
+            if not self._is_valid_entry(self._store[key]):
+                expired.append(key)
+        # Delete keys
+        for expired_key in expired:
+            self.delete(expired_key)
+
+    def _is_valid_entry(self, entry):
+        """
+        Determines if a given cache entry is not expired.
+
+        Args:
+            entry (dict): An entry from the cache composed of value,
+            TTI, and TTL
+
+        Returns:
+            bool: Boolean value representing if entry is expired
+        """
+        # Get Current time
+        now = self._get_current_time()
+        # Check timers and compare against current time
+        timers = [entry["tti"], entry["ttl"]]
+        return not any(timer <= now for timer in timers)
+
+    def _get_current_time(self):
+        """
+        Helper function to get current time
+
+        Returns:
+            float: value representing the number of seconds since the epoch
+        """
+        return time.time()

zscaler/constants.py

@@ -0,0 +1,26 @@
+import os
+
+ZPA_BASE_URLS = {
+    "PRODUCTION": "https://config.private.zscaler.com",
+    "ZPATWO": "https://config.zpatwo.net",
+    "BETA": "https://config.zpabeta.net",
+    "GOV": "https://config.zpagov.net",
+    "GOVUS": "https://config.zpagov.us",
+    "PREVIEW": "https://config.zpapreview.net",
+    "QA": "https://config.qa.zpath.net",
+    "QA2": "https://pdx2-zpa-config.qa2.zpath.net",
+}
+
+RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+MAX_RETRIES = 5
+BACKOFF_FACTOR = 1
+BACKOFF_BASE_DURATION = 2
+
+DATETIME_FORMAT = "%a, %d %b %Y %H:%M:%S %Z"
+
+EPOCH_YEAR = 1970
+EPOCH_MONTH = 1
+EPOCH_DAY = 1
+
+_GLOBAL_YAML_PATH = os.path.join(os.path.expanduser("~"), ".zpa", "zpa.yaml")
+_LOCAL_YAML_PATH = os.path.join(os.getcwd(), "zpa.yaml")

zscaler/errors/error.py

@@ -0,0 +1,10 @@
+class Error:
+    """
+    Base Error Class
+    """
+
+    def __init__(self):
+        self.message = ""
+
+    def __repr__(self):
+        return str({"message": self.message})

zscaler/errors/http_error.py

@@ -0,0 +1,20 @@
+import json
+
+from zscaler.errors.error import Error
+
+
+class HTTPError(Error):
+    def __init__(self, url, response_details, response_body):
+        self.status = response_details.status
+        self.url = url
+        self.response_headers = response_details.headers
+        self.stack = ""
+        self.message = f"HTTP {self.status} {response_body}"
+
+
+class ZscalerAPIError(Error):
+    def __init__(self, url, response, response_body):
+        self.status = response.status_code
+        self.url = url
+        self.response_body = json.dumps(response_body)
+        self.message = f"ZSCALER HTTP {url} {self.status} {self.response_body}"

zscaler/errors/zscaler_api_error.py

@@ -0,0 +1,24 @@
+from zscaler.errors.error import Error
+
+
+# ZPA API Errors
+class ZPAAPIError(Error):
+    def __init__(self, url, response_details, response_body):
+        self.status = response_details.status
+        self.error_id = response_body.get("id", "")
+        self.reason = response_body.get("reason", "")
+        self.params = response_body.get("params", [])
+
+        params_string = ", ".join(self.params)
+
+        self.url = url
+        self.headers = response_details.headers
+        self.stack = ""
+
+        self.message = (
+            f"ZPA HTTP {self.status} {self.error_id} "
+            f"{self.reason}\nParameters: {params_string}"
+        )
+
+
+# ZIA API Errors

zscaler/exceptions/__init__.py

@@ -0,0 +1 @@
+from .exceptions import HTTPException, ZpaAPIException  # noqa

zscaler/exceptions/exceptions.py

@@ -0,0 +1,101 @@
+import json
+
+
+# Zscaler Base Exceptions
+class ZscalerBaseException(Exception):
+    def __init__(self, url, response, response_body):
+        self.status = response.status_code
+        self.url = url
+        self.response_body = json.dumps(response_body)
+        self.message = f"ZSCALER HTTP {url} {self.status} {self.response_body}"
+
+    def __repr__(self):
+        return str({"message": self.message})
+
+    def __str__(self):
+        return self.message
+
+
+class HTTPException(ZscalerBaseException):
+    pass
+
+
+class ZscalerAPIException(ZscalerBaseException):
+    pass
+
+
+# Zscaler Private Access specific exceptions (Potential Future Use)
+class ZpaBaseException(Exception):
+    pass
+
+
+class ZpaAPIException(ZpaBaseException):
+    pass
+
+
+class RateLimitExceededError(Exception):
+    """Raised when the API rate limit is exceeded."""
+
+    pass
+
+
+class RetryLimitExceededError(Exception):
+    """Raised when the maximum number of retries is exceeded."""
+
+    pass
+
+
+class CacheError(Exception):
+    """Raised for errors related to caching operations."""
+
+    pass
+
+
+class BadRequestError(Exception):
+    """Raised when the API responds with a 400 status code."""
+
+    pass
+
+
+class UnauthorizedError(Exception):
+    pass
+
+
+class ForbiddenError(Exception):
+    pass
+
+
+class NotFoundError(Exception):
+    pass
+
+
+class APIClientError(Exception):
+    """General exception related to the API client operations."""
+
+    pass
+
+
+class InvalidCloudEnvironmentError(Exception):
+    """Raised when an unrecognized cloud environment is specified."""
+
+    def __init__(self, cloud: str):
+        self.cloud = cloud
+        super().__init__(f"Unrecognized cloud environment: {self.cloud}")
+
+
+class TokenExpirationError(Exception):
+    """Raised when the authentication token has expired."""
+
+    pass
+
+
+class TokenRefreshError(Exception):
+    """Raised when there's an issue refreshing the authentication token."""
+
+    pass
+
+
+class HeaderUpdateError(Exception):
+    """Raised if there's a problem updating the session headers."""
+
+    pass

zscaler/logger.py

@@ -0,0 +1,57 @@
+import logging
+import os
+from http.client import HTTPConnection
+
+LOG_FORMAT = "%(asctime)s - %(name)s - %(module)s - %(levelname)s - %(message)s"
+
+
+def setup_logging(logger_name="zscaler-sdk-python"):
+    """
+    Set up logging with specified level and logger name.
+    Log level is controlled via ZSCALER_SDK_VERBOSE environment variable.
+    Logging can be enabled/disabled via ZSCALER_SDK_LOG environment variable.
+
+    Parameters:
+    - logger_name (str, optional): Logger name. Defaults to "zscaler-sdk-python".
+    """
+    logging_enabled = os.getenv("ZSCALER_SDK_LOG", "false").lower() == "true"
+
+    if not logging_enabled:
+        # If logging is not enabled, set up a null handler
+        logging.disable(logging.INFO)
+        return
+
+    verbose = os.getenv("ZSCALER_SDK_VERBOSE", "false").lower() == "true"
+    log_level = logging.DEBUG if verbose else logging.INFO
+    HTTPConnection.debuglevel = 0
+    # Create a logger with the specified name
+    logger = logging.getLogger(logger_name)
+    default_logger = logging.getLogger()
+
+    # If the logger already has handlers, remove them to avoid duplicate logging
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+
+    for handler in default_logger.handlers[:]:
+        default_logger.removeHandler(handler)
+
+    # Set log level
+    logger.setLevel(log_level)
+    default_logger.setLevel(log_level)
+    logging.basicConfig(level=log_level)
+
+    # Create a stream handler with the specified level and formatter
+    stream_handler = logging.StreamHandler()
+    stream_handler.setLevel(log_level)
+    log_formatter = logging.Formatter(LOG_FORMAT)
+    stream_handler.setFormatter(log_formatter)
+
+    # Add the handler to the logger
+    logger.addHandler(stream_handler)
+
+    # Option: Add FileHandler if you want logs to be written to a file.
+    if os.getenv("LOG_TO_FILE", "false").lower() == "true":
+        file_handler = logging.FileHandler(os.getenv("LOG_FILE_PATH", "sdk.log"))
+        file_handler.setLevel(log_level)
+        file_handler.setFormatter(log_formatter)
+        logger.addHandler(file_handler)

zscaler/ratelimiter/ratelimiter.py

@@ -0,0 +1,39 @@
+import threading
+import time
+
+
+class RateLimiter:
+    def __init__(
+        self, get_limit, post_put_delete_limit, get_freq, post_put_delete_freq
+    ):
+        self.lock = threading.Lock()
+        self.get_requests = []
+        self.post_put_delete_requests = []
+        self.get_limit = get_limit
+        self.post_put_delete_limit = post_put_delete_limit
+        self.get_freq = get_freq
+        self.post_put_delete_freq = post_put_delete_freq
+
+    def wait(self, method):
+        with self.lock:
+            now = time.time()
+
+            if method == "GET":
+                if len(self.get_requests) >= self.get_limit:
+                    oldest_request = self.get_requests[0]
+                    if now - oldest_request < self.get_freq:
+                        d = self.get_freq - (now - oldest_request)
+                        return True, d
+                    self.get_requests.pop(0)
+                self.get_requests.append(now)
+
+            elif method in ["POST", "PUT", "DELETE"]:
+                if len(self.post_put_delete_requests) >= self.post_put_delete_limit:
+                    oldest_request = self.post_put_delete_requests[0]
+                    if now - oldest_request < self.post_put_delete_freq:
+                        d = self.post_put_delete_freq - (now - oldest_request)
+                        return True, d
+                    self.post_put_delete_requests.pop(0)
+                self.post_put_delete_requests.append(now)
+
+            return False, 0

zscaler/user_agent.py

@@ -0,0 +1,23 @@
+import platform
+
+from zscaler import __version__ as VERSION
+
+
+class UserAgent:
+    SDK_NAME = "zscaler-sdk-python"
+    PYTHON = "python"
+
+    def __init__(self, user_agent_extra=None):
+        python_version = platform.python_version()
+        os_name = platform.system()
+        os_version = platform.release()
+        self._user_agent_string = (
+            f"{UserAgent.SDK_NAME}/{VERSION} "
+            f"{UserAgent.PYTHON}/{python_version} "
+            f"{os_name}/{os_version}"
+        )
+        if user_agent_extra:
+            self._user_agent_string += f" {user_agent_extra}"
+
+    def get_user_agent_string(self):
+        return self._user_agent_string