zscaler-sdk-python 1.9.9__tar.gz → 1.9.11__tar.gz

{zscaler_sdk_python-1.9.9 → zscaler_sdk_python-1.9.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 1.9.9
+Version: 1.9.11
 Summary: Official Python SDK for the Zscaler Products
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT
@@ -20,17 +20,19 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: dev
+Requires-Dist: PyJWT (>=2.10.1)
 Requires-Dist: aenum (>=3.1.11)
 Requires-Dist: arrow (>=1.3.0)
 Requires-Dist: cryptography (>=45.0.2)
 Requires-Dist: flatdict (>=4.0.0)
+Requires-Dist: jwcrypto (>=1.5.6)
 Requires-Dist: pydash (>=8.0.3)
 Requires-Dist: python-box (>=7.3.0)
 Requires-Dist: python-dateutil (>=2.9.0)
-Requires-Dist: python-jose[cryptography] (>=3.5.0)
 Requires-Dist: pytz (>=2024.2)
 Requires-Dist: pyyaml (>=6.0.0)
 Requires-Dist: requests (>=2.32.3)
+Requires-Dist: urllib3 (>=2.6.0)
 Project-URL: Bug Tracker, https://github.com/zscaler/zscaler-sdk-python/issues
 Project-URL: Documentation, https://zscaler-sdk-python.readthedocs.io
 Project-URL: Repository, https://github.com/zscaler/zscaler-sdk-python

{zscaler_sdk_python-1.9.9 → zscaler_sdk_python-1.9.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zscaler-sdk-python"
-version = "1.9.9"
+version = "1.9.11"
 description = "Official Python SDK for the Zscaler Products"
 authors = ["Zscaler, Inc. <devrel@zscaler.com>"]
 license = "MIT"
@@ -30,13 +30,15 @@ packages = [
 [tool.poetry.dependencies]
 python = ">=3.9.2,<4.0"
 requests = ">=2.32.3"
+urllib3 = ">=2.6.0"
 cryptography = ">=45.0.2"
 pyyaml = ">=6.0.0"
 pytz = ">=2024.2"
 python-box = ">=7.3.0"
 python-dateutil = ">=2.9.0"
 flatdict = ">=4.0.0"
-python-jose = {extras = ["cryptography"], version = ">=3.5.0"}
+PyJWT = ">=2.10.1"
+jwcrypto = ">=1.5.6"
 aenum = ">=3.1.11"
 pydash = ">=8.0.3"
 arrow = ">=1.3.0"
@@ -50,7 +52,7 @@ pytest-mock = ">=3.12.0"
 pytest-asyncio = ">=0.23.0"
 pytest-cov = ">=6.2.1"
 pytest-recording = ">=0.13.1"
-vcrpy = ">=7.0.0"  # Requires 7.0+ for urllib3 2.x support on Python 3.10+
+vcrpy = {version = ">=8.1.0", python = ">=3.10"}
 pyfakefs = ">=5.7.0"
 responses = ">=0.25.7"
 sphinx = ">=7.2.0"
@@ -59,7 +61,7 @@ sphinx_rtd_theme = ">=1.3.0"
 wheel = ">=0.42.0"
 
 [tool.poetry.extras]
-dev = ["black", "pytest", "pytest-asyncio", "pytest-mock", "pytest-recording", "pytest-cov", "pyfakefs", "vcrpy", "isort", "wheel"]
+dev = ["black", "pytest", "pytest-asyncio", "pytest-mock", "pytest-recording", "pytest-cov", "pyfakefs", "isort", "wheel"]
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

{zscaler_sdk_python-1.9.9 → zscaler_sdk_python-1.9.11}/zscaler/__init__.py

@@ -29,7 +29,7 @@ __license__ = "MIT"
 __contributors__ = [
     "William Guilherme",
 ]
-__version__ = "1.9.9"
+__version__ = "1.9.11"
 
 
 from zscaler.oneapi_client import Client as ZscalerClient  # noqa

zscaler_sdk_python-1.9.11/zscaler/errors/__init__.py

@@ -0,0 +1,26 @@
+"""
+Zscaler SDK Error Classes
+
+This module provides error handling for all Zscaler API responses.
+"""
+
+from zscaler.errors.error import Error
+from zscaler.errors.http_error import HTTPError
+from zscaler.errors.zscaler_api_error import ZscalerAPIError
+from zscaler.errors.graphql_error import (
+    GraphQLAPIError,
+    GraphQLErrorDetail,
+    GraphQLErrorLocation,
+    is_graphql_error_response,
+)
+
+__all__ = [
+    "Error",
+    "HTTPError",
+    "ZscalerAPIError",
+    "GraphQLAPIError",
+    "GraphQLErrorDetail",
+    "GraphQLErrorLocation",
+    "is_graphql_error_response",
+]
+

zscaler_sdk_python-1.9.11/zscaler/errors/graphql_error.py

@@ -0,0 +1,207 @@
+"""
+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 typing import Dict, Any, List, Optional, Union
+from dataclasses import dataclass, field
+import json
+import requests
+
+
+@dataclass
+class GraphQLErrorLocation:
+    """Represents a location in a GraphQL query where an error occurred."""
+    line: int
+    column: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, int]) -> "GraphQLErrorLocation":
+        return cls(
+            line=data.get("line", 0),
+            column=data.get("column", 0)
+        )
+
+
+@dataclass
+class GraphQLErrorDetail:
+    """Represents a single GraphQL error from the errors array."""
+    message: str
+    locations: List[GraphQLErrorLocation] = field(default_factory=list)
+    path: List[str] = field(default_factory=list)
+    extensions: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GraphQLErrorDetail":
+        locations = [
+            GraphQLErrorLocation.from_dict(loc)
+            for loc in data.get("locations", [])
+        ]
+        return cls(
+            message=data.get("message", "Unknown GraphQL error"),
+            locations=locations,
+            path=data.get("path", []),
+            extensions=data.get("extensions", {})
+        )
+
+    @property
+    def classification(self) -> Optional[str]:
+        """Get the error classification from extensions."""
+        return self.extensions.get("classification")
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.path:
+            parts.append(f"Path: {'.'.join(str(p) for p in self.path)}")
+        if self.classification:
+            parts.append(f"Classification: {self.classification}")
+        return " | ".join(parts)
+
+
+class GraphQLAPIError(Exception):
+    """
+    Exception for GraphQL API errors from Z-Insights.
+
+    GraphQL APIs return errors in a different format than REST:
+    {
+        "errors": [
+            {
+                "message": "...",
+                "locations": [{"line": 1, "column": 1}],
+                "path": ["query", "field"],
+                "extensions": {"classification": "BAD_REQUEST"}
+            }
+        ],
+        "data": {...}
+    }
+    """
+
+    def __init__(
+        self,
+        url: str,
+        response_details: requests.Response,
+        response_body: Union[Dict[str, Any], str],
+        service_type: str = "zins"
+    ) -> None:
+        self.url: str = url
+        self.status_code: int = response_details.status_code
+        self.service_type: str = service_type
+        self.headers: Dict[str, Any] = dict(response_details.headers)
+
+        # Parse the response body
+        if isinstance(response_body, str):
+            try:
+                response_body = json.loads(response_body)
+            except json.JSONDecodeError:
+                response_body = {"errors": [{"message": response_body}]}
+
+        # Extract GraphQL errors
+        raw_errors = response_body.get("errors", [])
+        self.errors: List[GraphQLErrorDetail] = [
+            GraphQLErrorDetail.from_dict(err) for err in raw_errors
+        ]
+
+        # Store the data portion (may be partial)
+        self.data: Optional[Dict[str, Any]] = response_body.get("data")
+
+        # Build the error message
+        if self.errors:
+            self.error_message = self.errors[0].message
+            self.classification = self.errors[0].classification
+            self.path = self.errors[0].path
+        else:
+            self.error_message = "Unknown GraphQL error"
+            self.classification = None
+            self.path = []
+
+        # Construct the full message
+        message_parts = [f"GraphQL Error"]
+        if self.status_code != 200:
+            message_parts.append(f"HTTP {self.status_code}")
+        if self.classification:
+            message_parts.append(f"[{self.classification}]")
+        message_parts.append(self.error_message)
+
+        self.message = " - ".join(message_parts)
+        super().__init__(self.message)
+
+    @property
+    def is_bad_request(self) -> bool:
+        """Check if the error is a BAD_REQUEST classification."""
+        return self.classification == "BAD_REQUEST"
+
+    @property
+    def is_validation_error(self) -> bool:
+        """Check if the error is a validation error."""
+        return self.classification in ["BAD_REQUEST", "VALIDATION_ERROR"]
+
+    @property
+    def is_authorization_error(self) -> bool:
+        """Check if the error is an authorization error."""
+        return self.classification in ["UNAUTHORIZED", "FORBIDDEN"]
+
+    @property
+    def all_error_messages(self) -> List[str]:
+        """Get all error messages from the errors array."""
+        return [err.message for err in self.errors]
+
+    def __str__(self) -> str:
+        error_payload = {
+            "service": self.service_type,
+            "status": self.status_code,
+            "url": self.url,
+            "errors": [
+                {
+                    "message": err.message,
+                    "path": err.path,
+                    "classification": err.classification
+                }
+                for err in self.errors
+            ]
+        }
+        return json.dumps(error_payload, indent=2)
+
+    def __repr__(self) -> str:
+        return f"GraphQLAPIError({self.message})"
+
+
+def is_graphql_error_response(response_body: Union[Dict[str, Any], str]) -> bool:
+    """
+    Check if a response body contains GraphQL errors.
+
+    GraphQL can return HTTP 200 with errors in the body, so we need
+    to check the response structure, not just the status code.
+
+    Args:
+        response_body: The response body (dict or JSON string)
+
+    Returns:
+        True if the response contains GraphQL errors
+    """
+    if isinstance(response_body, str):
+        try:
+            response_body = json.loads(response_body)
+        except json.JSONDecodeError:
+            return False
+
+    if not isinstance(response_body, dict):
+        return False
+
+    # GraphQL error responses have an "errors" array
+    errors = response_body.get("errors")
+    if errors and isinstance(errors, list) and len(errors) > 0:
+        return True
+
+    return False
+

{zscaler_sdk_python-1.9.9 → zscaler_sdk_python-1.9.11}/zscaler/errors/response_checker.py

@@ -4,6 +4,7 @@ import json
 import logging
 from zscaler.errors.http_error import HTTPError
 from zscaler.errors.zscaler_api_error import ZscalerAPIError
+from zscaler.errors.graphql_error import GraphQLAPIError, is_graphql_error_response
 from zscaler.exceptions import HTTPException, ZscalerAPIException
 from zscaler.exceptions import exceptions
 
@@ -11,7 +12,7 @@ logger = logging.getLogger(__name__)
 
 
 # @staticmethod
-def check_response_for_error(url, response_details, response_body):
+def check_response_for_error(url, response_details, response_body, service_type: str = ""):
     """
     Checks HTTP response for errors in the response body.
 
@@ -19,6 +20,7 @@ def check_response_for_error(url, response_details, response_body):
         url (str): URL of the response
         response_details (requests.Response): Response object with details
         response_body (str): Response body in JSON or plain string
+        service_type (str): The service type (e.g., 'zins' for GraphQL)
 
     Returns:
         Tuple(dict or None, error or None)
@@ -43,6 +45,29 @@ def check_response_for_error(url, response_details, response_body):
     # ✅ Only now we are confident it's safe to access .status_code
     status_code = response_details.status_code
 
+    # Check for GraphQL errors (can return HTTP 200 with errors in body)
+    # GraphQL APIs like Z-Insights return errors in the response body
+    if is_graphql_error_response(formatted_response):
+        try:
+            # Determine service type from URL if not provided
+            if not service_type and "/zins" in url:
+                service_type = "zins"
+
+            error = GraphQLAPIError(url, response_details, formatted_response, service_type)
+            logger.debug(f"GraphQL error detected: {error.message}")
+            if exceptions.raise_exception:
+                raise ZscalerAPIException(error)
+            return None, error
+        except ZscalerAPIException:
+            raise
+        except Exception as e:
+            logger.exception("Failed to construct GraphQLAPIError.")
+            generic_error = HTTPError(url, response_details, formatted_response)
+            if exceptions.raise_exception:
+                raise HTTPException(str(generic_error)) from e
+            return None, generic_error
+
+    # Standard REST API response handling
     if 200 <= status_code < 300:
         return formatted_response, None
 
@@ -52,6 +77,8 @@ def check_response_for_error(url, response_details, response_body):
             raise ZscalerAPIException(error)
         return None, error
 
+    except ZscalerAPIException:
+        raise
     except Exception as e:
         logger.exception("Failed to construct ZscalerAPIError.")
         generic_error = HTTPError(url, response_details, formatted_response)

{zscaler_sdk_python-1.9.9 → zscaler_sdk_python-1.9.11}/zscaler/oneapi_client.py

@@ -185,7 +185,7 @@ class Client:
         )
         # self.logger.debug("Request executor initialized.")
 
-        # Lazy load ZIA and ZPA clients
+        # Lazy load service clients
         self._zcc = None
         self._ztw = None
         self._zia = None
@@ -193,7 +193,8 @@ class Client:
         self._zpa = None
         self._zdx = None
         self._zidentity = None
-        self._zeasm= None
+        self._zeasm = None
+        self._zins = None  # Z-Insights (GraphQL Analytics API)
         # self.logger.debug("Client initialized successfully.")
 
     def authenticate(self):
@@ -271,6 +272,44 @@ class Client:
             self._zeasm = ZEASMService(self._request_executor)
         return self._zeasm
 
+    @property
+    def zinsights(self):
+        """
+        Z-Insights Analytics Service (GraphQL API).
+
+        Provides access to Zscaler analytics data including:
+        - WEB_TRAFFIC: Web traffic analytics and reports
+        - CYBER_SECURITY: Security incidents and threat data
+        - ZERO_TRUST_FIREWALL: Firewall traffic and policy data
+        - IOT: IoT device visibility and statistics
+        - SHADOW_IT: Shadow IT discovery and application data
+        - SAAS_SECURITY: CASB and SaaS security data
+
+        Note: Z-Insights only supports OneAPI authentication.
+        Legacy client authentication is not supported.
+
+        Example:
+            with ZscalerClient(config) as client:
+                response, error = client.zinsights.graphql.execute(
+                    query='{ WEB_TRAFFIC { ... } }'
+                )
+        """
+        if self.use_legacy_client:
+            raise RuntimeError(
+                "Z-Insights (zinsights) does not support legacy client authentication. "
+                "Please use OneAPI authentication with clientId and clientSecret."
+            )
+        if self._zins is None:
+            from zscaler.zinsights.zinsights_service import ZInsightsService
+            self._zins = ZInsightsService(self._request_executor)
+        return self._zins
+
+    # Alias for backward compatibility
+    @property
+    def zins(self):
+        """Alias for zinsights property."""
+        return self.zinsights
+
     def __enter__(self):
         """
         Automatically create and set session within context manager.

{zscaler_sdk_python-1.9.9 → zscaler_sdk_python-1.9.11}/zscaler/oneapi_oauth_client.py

@@ -3,11 +3,15 @@ import logging
 import json
 import os
 import requests
-from jose import jwt
 import time
 from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric import rsa
+
+# JWT handling - using PyJWT instead of python-jose to avoid ecdsa dependency (CVE-2024-23342)
+import jwt as pyjwt
+from jwcrypto.jwk import JWK
+
 from zscaler.user_agent import UserAgent
 from zscaler.oneapi_http_client import HTTPClient
 from zscaler.errors.response_checker import check_response_for_error
@@ -335,9 +339,15 @@ class OAuth:
         private_key_obj: Union[rsa.RSAPrivateKey, Any]
         if private_key.strip().startswith("{"):
             # **JWK JSON Format**
+            # Using jwcrypto instead of python-jose to avoid ecdsa dependency (CVE-2024-23342)
             logging.info("Using JWK JSON format for private key.")
             jwk_key: Dict[str, Any] = json.loads(private_key.strip())  # Convert JWK string to dict
-            private_key_obj = jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(jwk_key))
+            # Convert JWK to PEM using jwcrypto, then load with cryptography
+            jwk_obj = JWK.from_json(json.dumps(jwk_key))
+            pem_bytes = jwk_obj.export_to_pem(private_key=True, password=None)
+            private_key_obj = serialization.load_pem_private_key(
+                pem_bytes, password=None, backend=default_backend()
+            )
 
         elif "BEGIN PRIVATE KEY" in private_key:
             # **Raw PEM Private Key**
@@ -365,7 +375,8 @@ class OAuth:
         }
 
         # **Generate the JWT assertion using the private key**
-        assertion: str = jwt.encode(payload, private_key_obj, algorithm="RS256")
+        # Using PyJWT instead of python-jose to avoid ecdsa dependency (CVE-2024-23342)
+        assertion: str = pyjwt.encode(payload, private_key_obj, algorithm="RS256")
 
         # **Step 3: Prepare OAuth Request**
         form_data: Dict[str, str] = {

{zscaler_sdk_python-1.9.9 → zscaler_sdk_python-1.9.11}/zscaler/request_executor.py

@@ -156,6 +156,12 @@ class RequestExecutor:
             else:
                 return f"https://{self.vanity_domain}-admin.zslogin.net/admin/api/v1"
 
+        # Special handling for Z-Insights (zins) GraphQL API
+        if "/zins" in endpoint:
+            if self.cloud and self.cloud != "production":
+                return f"https://api.{self.cloud}.zsapi.net"
+            return self.BASE_URL
+
         if self.cloud and self.cloud != "production":
             return f"https://api.{self.cloud}.zsapi.net"
         return self.BASE_URL
@@ -182,6 +188,8 @@ class RequestExecutor:
             return "admin"
         elif "/easm/easm-ui/v1" in url:
             return "zeasm"
+        elif "/zins" in url:
+            return "zins"
         if self.use_legacy_client:
             url = self.remove_oneapi_endpoint_prefix(url)
             # Recheck for service type after removing the prefix
@@ -202,7 +210,7 @@ class RequestExecutor:
         raise ValueError(f"Unsupported service: {url}")
 
     def remove_oneapi_endpoint_prefix(self, endpoint: str) -> str:
-        prefixes = ["admin", "/zia", "/zpa", "/zcc", "/ztw", "/zdx", "/zwa"]
+        prefixes = ["admin", "/zia", "/zpa", "/zcc", "/ztw", "/zdx", "/zwa", "/zins"]
         for prefix in prefixes:
             if endpoint.startswith(prefix):
                 return endpoint[len(prefix) :]

zscaler_sdk_python-1.9.11/zscaler/zinsights/__init__.py

@@ -0,0 +1,21 @@
+"""
+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 zscaler.zinsights.zinsights_service import ZInsightsService
+
+__all__ = [
+    "ZInsightsService",
+]