zscaler-sdk-python 1.9.8__tar.gz → 1.9.10__tar.gz

{zscaler_sdk_python-1.9.8 → zscaler_sdk_python-1.9.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 1.9.8
+Version: 1.9.10
 Summary: Official Python SDK for the Zscaler Products
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT

{zscaler_sdk_python-1.9.8 → zscaler_sdk_python-1.9.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zscaler-sdk-python"
-version = "1.9.8"
+version = "1.9.10"
 description = "Official Python SDK for the Zscaler Products"
 authors = ["Zscaler, Inc. <devrel@zscaler.com>"]
 license = "MIT"

{zscaler_sdk_python-1.9.8 → zscaler_sdk_python-1.9.10}/zscaler/__init__.py

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

zscaler_sdk_python-1.9.10/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.10/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.8 → zscaler_sdk_python-1.9.10}/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.8 → zscaler_sdk_python-1.9.10}/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.8 → zscaler_sdk_python-1.9.10}/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.8 → zscaler_sdk_python-1.9.10}/zscaler/zia/legacy.py

@@ -484,8 +484,16 @@ class LegacyZIAClientHelper:
                     )
 
                 if resp.status_code == 429:
-                    sleep_time = int(resp.headers.get("Retry-After", 2))
-                    logger.warning(f"Rate limit exceeded. Retrying in {sleep_time} seconds.")
+                    # ZIA returns "Retry-After": "0 seconds" (with " seconds" suffix)
+                    retry_after = resp.headers.get("Retry-After", "2")
+                    # Strip " seconds" suffix if present
+                    if isinstance(retry_after, str):
+                        retry_after = retry_after.replace(" seconds", "").replace("seconds", "").strip()
+                    sleep_time = int(retry_after) if retry_after else 2
+                    # ZIA rate limit is 1/second, so wait at least 1 second
+                    sleep_time = max(sleep_time, 1)
+                    logger.warning(f"Rate limit exceeded (429). Retrying in {sleep_time} seconds. "
+                                   f"(Attempt {attempts + 1}/5)")
                     sleep(sleep_time)
                     attempts += 1
                     continue

zscaler_sdk_python-1.9.10/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",
+]

zscaler_sdk_python-1.9.10/zscaler/zinsights/cyber_security.py

@@ -0,0 +1,220 @@
+"""
+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 Optional, List
+
+from zscaler.api_client import APIClient
+from zscaler.request_executor import RequestExecutor
+from zscaler.utils import format_url
+
+
+class CyberSecurityAPI(APIClient):
+    """
+    A Client object for the Z-Insights CYBER_SECURITY domain.
+
+    Cybersecurity Insights provides a unified real-time visibility into critical
+    security incidents and policy actions to understand the security efficacy of
+    layered defense across Malware Protection, Advanced Threat Protection (ATP),
+    Sandbox, Firewall, and Isolation for your organization.
+    """
+
+    _zinsights_base_endpoint = "/zins/graphql"
+
+    def __init__(self, request_executor: RequestExecutor) -> None:
+        super().__init__()
+        self._request_executor = request_executor
+
+    def get_incidents(
+        self,
+        start_time: int,
+        end_time: int,
+        categorize_by: List[str] = None,
+        limit: Optional[int] = None,
+    ) -> tuple:
+        """
+        Get cybersecurity incidents data grouped by category.
+
+        Note: This query returns nested entries. Each entry may have sub-entries.
+
+        Args:
+            start_time: Start time in epoch milliseconds.
+            end_time: End time in epoch milliseconds.
+            categorize_by: List of categories to group by. Options:
+                - THREAT_CATEGORY_ID
+                - APP_ID
+                - USER_ID
+                - TIME
+                - SRC_COUNTRY
+                Default: ["THREAT_CATEGORY_ID"]
+            limit: Maximum number of entries to return.
+
+        Returns:
+            tuple: (entries_list, response, error)
+
+        Examples:
+            >>> entries, _, err = client.zinsights.cyber_security.get_incidents(
+            ...     start_time=start_time,
+            ...     end_time=end_time,
+            ...     categorize_by=["THREAT_CATEGORY_ID"],
+            ...     limit=10
+            ... )
+        """
+        if categorize_by is None:
+            categorize_by = ["THREAT_CATEGORY_ID"]
+
+        query = """
+            query CyberSecurityIncidents(
+                $startTime: Long!, $endTime: Long!,
+                $categorizeBy: [IncidentsGroupBy!]!, $limit: Int
+            ) {
+                CYBER_SECURITY {
+                    incidents(
+                        categorize_by: $categorizeBy,
+                        start_time: $startTime,
+                        end_time: $endTime
+                    ) {
+                        obfuscated
+                        entries(limit: $limit) {
+                            name
+                            total
+                            entries(limit: $limit) {
+                                name
+                                total
+                            }
+                        }
+                    }
+                }
+            }
+        """
+
+        variables = {
+            "startTime": start_time,
+            "endTime": end_time,
+            "categorizeBy": categorize_by,
+            "limit": limit,
+        }
+
+        body = {
+            "query": query,
+            "variables": variables,
+            "operationName": "CyberSecurityIncidents",
+        }
+
+        http_method = "POST"
+        api_url = format_url(self._zinsights_base_endpoint)
+
+        request, error = self._request_executor.create_request(http_method, api_url, body, {})
+        if error:
+            return (None, None, error)
+
+        response, error = self._request_executor.execute(request)
+        if error:
+            return (None, response, error)
+
+        try:
+            body = response.get_body() if response else {}
+            # GraphQL responses have data wrapped in "data" key
+            data = body.get("data", {}) if isinstance(body, dict) else {}
+            entries = data.get("CYBER_SECURITY", {}).get("incidents", {}).get("entries", [])
+            return (entries, response, None)
+        except Exception as ex:
+            return (None, response, ex)
+
+    def get_incidents_by_location(
+        self,
+        start_time: int,
+        end_time: int,
+        categorize_by: str = "LOCATION_ID",
+        limit: Optional[int] = None,
+    ) -> tuple:
+        """
+        Get cybersecurity incidents grouped by location or other dimension.
+
+        Args:
+            start_time: Start time in epoch milliseconds.
+            end_time: End time in epoch milliseconds.
+            categorize_by: Category to group by. Options:
+                - LOCATION_ID (default)
+                - APP_ID
+                - USER_ID
+                - DEPARTMENT_ID
+            limit: Maximum number of entries to return.
+
+        Returns:
+            tuple: (entries_list, response, error)
+
+        Examples:
+            >>> entries, _, err = client.zinsights.cyber_security.get_incidents_by_location(
+            ...     start_time=start_time,
+            ...     end_time=end_time,
+            ...     categorize_by="LOCATION_ID",
+            ...     limit=10
+            ... )
+        """
+        query = """
+            query CyberSecurityByLocation(
+                $startTime: Long!, $endTime: Long!,
+                $categorizeBy: IncidentsWithIdGroupBy!, $limit: Int
+            ) {
+                CYBER_SECURITY {
+                    cyber_security_location(
+                        categorize_by: $categorizeBy,
+                        start_time: $startTime,
+                        end_time: $endTime
+                    ) {
+                        obfuscated
+                        entries(limit: $limit) {
+                            id
+                            name
+                            total
+                        }
+                    }
+                }
+            }
+        """
+
+        variables = {
+            "startTime": start_time,
+            "endTime": end_time,
+            "categorizeBy": categorize_by,
+            "limit": limit,
+        }
+
+        body = {
+            "query": query,
+            "variables": variables,
+            "operationName": "CyberSecurityByLocation",
+        }
+
+        http_method = "POST"
+        api_url = format_url(self._zinsights_base_endpoint)
+
+        request, error = self._request_executor.create_request(http_method, api_url, body, {})
+        if error:
+            return (None, None, error)
+
+        response, error = self._request_executor.execute(request)
+        if error:
+            return (None, response, error)
+
+        try:
+            body = response.get_body() if response else {}
+            # GraphQL responses have data wrapped in "data" key
+            data = body.get("data", {}) if isinstance(body, dict) else {}
+            entries = data.get("CYBER_SECURITY", {}).get("cyber_security_location", {}).get("entries", [])
+            return (entries, response, None)
+        except Exception as ex:
+            return (None, response, ex)