zscaler-sdk-python 0.1.3__py3-none-any.whl

zscaler/zia/admin_and_role_management.py

@@ -0,0 +1,336 @@
+# -*- 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.
+
+from box import Box, BoxList
+from requests import Response
+
+from zscaler.utils import Iterator, snake_to_camel
+from zscaler.zia import ZIAClient
+
+
+class AdminAndRoleManagementAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def list_users(self, **kwargs) -> BoxList:
+        """
+        Returns a list of admin users.
+
+        Keyword Args:
+            include_auditor_users (bool, optional):
+                Include or exclude auditor user information in the list.
+            include_admin_users (bool, optional):
+                Include or exclude admin user information in the list. (default: True)
+            search (str, optional):
+                The search string used to partially match against an admin/auditor user's Login ID or Name.
+            page (int, optional):
+                Specifies the page offset.
+            page_size (int, optional):
+                Specifies the page size. The default size is 100, but the maximum size is 1000.
+
+        Returns:
+            list: The admin_users resource records.
+
+        Examples:
+            >>> users = zia.admin_and_role_management.list_users('admin@example.com')
+
+        """
+        return BoxList(Iterator(self.rest, "adminUsers", **kwargs))
+
+    def get_user(self, user_id: str) -> Box:
+        """
+        Returns information on the specified admin user id.
+
+        Args:
+            user_id (str): The unique id of the admin user.
+
+        Returns:
+            :obj:`Box`: The admin user resource record.
+
+        Examples:
+            >>> print(zia.admin_and_role_management.get_user('987321202'))
+
+        """
+        response = self.rest.get("/adminUsers/%s" % (user_id))
+        if isinstance(response, Response):
+            status_code = response.status_code
+            if status_code != 200:
+                return None
+        return response
+
+    def add_user(self, name: str, login_name: str, email: str, password: str, **kwargs) -> Box:
+        """
+        Adds a new admin user to ZIA.
+
+        Args:
+            name (str): The user's full name.
+            login_name (str):
+                The name that the admin user will use to login to ZIA in email format, i.e. `user@domain.tld.`
+            email (str): The email address for the admin user.
+            password (str): The password for the admin user.
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            admin_scope (str): The scope of the admin's permissions, accepted values are:
+                ``organization``, ``department``, ``location``, ``location_group``
+            comments (str): Additional information about the admin user.
+            disabled (bool): Set to ``True`` if you want the account disabled upon creation.
+            is_password_login_allowed (bool): Set to ``True`` to allow password login.
+            is_security_report_comm_enabled (bool):
+                Set to ``True`` to allow ZIA Security Update emails to be sent to the admin user.
+            is_service_update_comm_enabled (bool):
+                Set to ``True`` to allow ZIA Service Update emails to be sent to the admin user.
+            is_product_update_comm_enabled (bool):
+                Set to ``True`` to allow ZIA Product Update emails to be sent to the admin user.
+            is_password_expired (bool):
+                Set to ``True`` to expire the admin user's password upon creation.
+            is_exec_mobile_app_enabled (bool):
+                Set to ``True`` to enable to executive insights mobile application for the admin user.
+            role_id (str): The unique id for the admin role being assigned to the admin user.
+            scope_ids (list):
+                A list of entity ids for the admin user's scope. e.g. if the admin user has admin_scope set to
+                ``department`` then you will need to provide a list of department ids.
+                **NOTE**: This param doesn't need to
+                be provided if the admin user's scope is set to ``organization``.
+
+        Returns:
+            :obj:`Box`: The newly created admin user resource record.
+
+        Examples:
+
+            Add an admin user with the minimum required params:
+                >>> admin_user = zia.admin_and_role_management.add_user(
+                ...    name="Jim Bob",
+                ...    login_name="jim@example.com",
+                ...    password="*********",
+                ...    email="jim@example.com")
+
+            Add an admin user with a department admin scope:
+                >>> admin_user = zia.admin_and_role_management.add_user(
+                ...    name="Jane Bob",
+                ...    login_name="jane@example.com",
+                ...    password="*********",
+                ...    email="jane@example.com,
+                ...    admin_scope="department",
+                ...    scope_ids = ['376542', '245688'])
+
+            Add an auditor user:
+                >>> auditor_user = zia.admin_and_role_management.add_user(
+                ...    name="Head Bob",
+                ...    login_name="head@example.com",
+                ...    password="*********",
+                ...    email="head@example.com,
+                ...    is_auditor=True)
+
+        """
+        payload = {
+            "userName": name,
+            "loginName": login_name,
+            "email": email,
+            "password": password,
+        }
+
+        # Get the admin scope if provided
+        admin_scope = kwargs.pop("admin_scope", None)
+
+        # The default admin scope is organization so we don't really need to
+        # send it to ZIA as part of this API call. Otherwise if the user has
+        # supplied something different then we want to explicitly set that for
+        # the adminScopeType.
+        if admin_scope and admin_scope != "organization":
+            payload["adminScopeType"] = admin_scope.upper()
+            payload["adminScopeScopeEntities"] = []
+
+        # Add optional parameters to payload
+        for key, value in kwargs.items():
+            # If the user has supplied ids for the admin scope then we'll add
+            # them to the payload here. If the user doesn't supply them then
+            # ZIA will return an error.
+            if key == "scope_ids":
+                for scope_id in value:
+                    payload["adminScopeScopeEntities"].append({"id": scope_id})
+            elif key == "role_id":
+                payload["role"] = {"id": value}
+            else:
+                payload[snake_to_camel(key)] = value
+
+        response = self.rest.post("adminUsers", json=payload)
+        if isinstance(response, Response):
+            # Handle error response
+            status_code = response.status_code
+            if status_code != 200:
+                raise Exception(f"API call failed with status {status_code}: {response.json()}")
+        return response
+
+    def update_user(self, user_id: str, **kwargs) -> dict:
+        """
+        Update an admin user.
+
+        Args:
+            user_id (str): The unique id of the admin user to be updated.
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            admin_scope (str): The scope of the admin's permissions, accepted values are:
+                ``organization``, ``department``, ``location``, ``location_group``
+            comments (str): Additional information about the admin user.
+            disabled (bool): Set to ``True`` if you want the account disabled upon creation.
+            email (str): The email address for the admin user.
+            is_password_login_allowed (bool): Set to ``True`` to allow password login.
+            is_security_report_comm_enabled (bool):
+                Set to ``True`` to allow ZIA Security Update emails to be sent to the admin user.
+            is_service_update_comm_enabled (bool):
+                Set to ``True`` to allow ZIA Service Update emails to be sent to the admin user.
+            is_product_update_comm_enabled (bool):
+                Set to ``True`` to allow ZIA Product Update emails to be sent to the admin user.
+            is_password_expired (bool):
+                Set to ``True`` to expire the admin user's password upon creation.
+            is_exec_mobile_app_enabled (bool):
+                Set to ``True`` to enable to executive insights mobile application for the admin user.
+            name (str): The user's full name.
+            password (str): The password for the admin user.
+            role_id (str): The unique id for the admin role being assigned to the admin user.
+            scope_ids (list):
+                A list of entity ids for the admin user's scope. e.g. if the admin user has ``admin_scope`` set to
+                ``department`` then you will need to provide a list of department ids.
+                **NOTE:** This param doesn't need to
+                be provided if the admin user's scope is set to `organization`.
+
+        Returns:
+            :obj:`dict`: The updated admin user resource record.
+
+        Examples:
+
+            Update the email address for an admin user:
+                >>> user = zia.admin_and_role_management.update_user('99695301',
+                ...    email='jimbob@example.com')
+
+            Update the admin scope for an admin user to department:
+                >>> user = zia.admin_and_role_management.update_user('99695301',
+                ...    admin_scope='department',
+                ...    scope_ids=['3846532', '3846541'])
+
+        """
+
+        # Get the resource record for the provided user id
+        payload = {snake_to_camel(k): v for k, v in self.get_user(user_id).items()}
+
+        # Get the admin scope if provided
+        admin_scope = kwargs.pop("admin_scope", None)
+
+        # The default admin scope is organization so we don't really need to
+        # send it to ZIA as part of this API call. Otherwise if the user has
+        # supplied something different then we want to explicitly set that for
+        # the adminScopeType.
+        if admin_scope and admin_scope != "organization":
+            payload["adminScopeType"] = admin_scope.upper()
+            payload["adminScopeScopeEntities"] = []
+
+        # Add optional parameters to payload
+        for key, value in kwargs.items():
+            # If the user has supplied ids for the admin scope then we'll add
+            # them to the payload here. If the user doesn't supply them then
+            # ZIA will return an error.
+            if key == "scope_ids":
+                for scope_id in value:
+                    payload["adminScopeScopeEntities"].append({"id": scope_id})
+            elif key == "name":
+                # We renamed the username param to make it more meaningful for zscaler-sdk-python users
+                payload["userName"] = value
+            else:
+                payload[snake_to_camel(key)] = value
+
+        # Update payload
+        for key, value in kwargs.items():
+            payload[snake_to_camel(key)] = value
+
+        response = self.rest.put("/adminUsers/%s" % (user_id), json=payload)
+        if isinstance(response, Response) and not response.ok:
+            # Handle error response
+            raise Exception(f"API call failed with status {response.status_code}: {response.json()}")
+
+        # Return the updated object
+        return self.get_user(user_id)
+
+    def delete_user(self, user_id: str) -> int:
+        """
+        Deletes the specified admin user by id.
+
+        Args:
+            user_id (str): The unique id of the admin user.
+
+        Returns:
+            :obj:`int`: The response code for the request.
+
+        Examples:
+            >>> zia.admin_role_management.delete_admin_user('99272455')
+
+        """
+        response = self.rest.delete("/adminUsers/%s" % (user_id))
+        return response.status_code
+
+    def list_roles(self, **kwargs) -> BoxList:
+        """
+        Return a list of the configured admin roles in ZIA.
+
+        Args:
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            include_auditor_role (bool): Set to ``True`` to include auditor role information in the response.
+            include_partner_role (bool): Set to ``True`` to include partner admin role information in the response.
+
+        Returns:
+            :obj:`BoxList`: A list of admin role resource records.
+
+        Examples:
+            Get a list of all configured admin roles:
+            >>> roles = zia.admin_and_management_roles.list_roles()
+
+        """
+        payload = {snake_to_camel(key): value for key, value in kwargs.items()}
+        return self.rest.get("adminRoles/lite", params=payload)
+
+    def get_role(self, role_id: str) -> Box:
+        """
+        Returns information on the specified admin user id.
+
+        Args:
+            user_id (str): The unique id of the admin user.
+
+        Returns:
+            :obj:`Box`: The admin user resource record.
+
+        Examples:
+            >>> print(zia.admin_and_role_management.get_user('987321202'))
+
+        """
+        admin_role = next(user for user in self.list_roles() if user.id == int(role_id))
+        return admin_role
+
+    def get_roles_by_name(self, name):
+        roles = self.list_roles()
+        for role in roles:
+            if role.get("name") == name:
+                return role
+        return None
+
+    def get_roles_by_id(self, role_id):
+        roles = self.list_roles()
+        for role in roles:
+            if role.get("id") == role_id:
+                return role
+        return None

zscaler/zia/apptotal.py

@@ -0,0 +1,71 @@
+# -*- 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.
+
+from box import Box
+
+from zscaler.zia import ZIAClient
+
+
+class AppTotalAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def get_app(self, app_id: str, verbose: bool = False) -> Box:
+        """
+        Searches the AppTotal App Catalog by app ID. If the app exists in the catalog, the app's information is
+        returned. If not, the app is submitted for analysis. After analysis is complete, a subsequent GET request is
+        required to fetch the app's information.
+
+        Args:
+            app_id (str): The app ID to search for.
+            verbose (bool, optional): Defaults to False.
+
+        Returns:
+            :obj:`Box`: The response object.
+
+        Examples:
+            Return verbose information on an app with ID 12345::
+
+                zia.apptotal.get_app(app_id="12345", verbose=True)
+
+        """
+        params = {
+            "app_id": app_id,
+            "verbose": verbose,
+        }
+        return self.rest.get("apps/app", params=params)
+
+    def scan_app(self, app_id: str) -> Box:
+        """
+        Submits an app for analysis in the AppTotal Sandbox. After analysis is complete, a subsequent GET request is
+        required to fetch the app's information.
+
+        Args:
+            app_id (str): The app ID to scan.
+
+        Returns:
+            :obj:`Box`: The response object.
+
+        Examples:
+            Scan an app with ID 12345::
+
+                zia.apptotal.scan_app(app_id="12345")
+
+        """
+        payload = {
+            "appId": app_id,
+        }
+        return self.rest.post("apps/app", json=payload)

zscaler/zia/audit_logs.py

@@ -0,0 +1,93 @@
+# -*- 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.
+
+
+from box import Box
+
+from zscaler.zia import ZIAClient
+
+
+class AuditLogsAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def status(self) -> Box:
+        """
+        Get the status of a request for an audit log report.
+
+        Returns:
+            :obj:`Box`: Audit log report request status.
+
+        Examples:
+            >>> print(zia.audit_logs.status())
+
+        """
+        return self.rest.get("auditlogEntryReport")
+
+    def create(self, start_time: str, end_time: str) -> int:
+        """
+        Creates an audit log report for the specified time period and saves it as a CSV file. The report
+        includes audit information for every call made to the cloud service API during the specified time period.
+        Creating a new audit log report will overwrite a previously-generated report.
+
+        Args:
+            start_time (str):
+                The timestamp, in epoch, of the admin's last login.
+            end_time (str):
+                The timestamp, in epoch, of the admin's last logout.
+
+        Returns:
+            :obj:`int`: The status code for the operation.
+
+        Examples:
+            >>> zia.audit_logs.create(start_time='1627221600000',
+            ...    end_time='1627271676622')
+
+        """
+        payload = {
+            "startTime": start_time,
+            "endTime": end_time,
+        }
+        return self.rest.post("auditlogEntryReport", json=payload, box=False).status_code
+
+    def cancel(self) -> int:
+        """
+        Cancels the request to create an audit log report.
+
+        Returns:
+            :obj:`int`: The operation response code.
+
+        Examples:
+            >>> zia.audit_logs.cancel()
+
+        """
+        return self.rest.delete("auditlogEntryReport", box=False).status_code
+
+    def get_report(self) -> str:
+        """
+        Returns the most recently created audit log report.
+
+        Returns:
+            :obj:`str`: String representation of CSV file.
+
+        Examples:
+            Write report to CSV file:
+
+            >>> with open("audit_log.csv", "w+") as fh:
+            ...    fh.write(zia.audit_logs.get_report())
+
+        """
+        return self.rest.get("auditlogEntryReport/download").text

zscaler/zia/authentication_settings.py

@@ -0,0 +1,94 @@
+# -*- 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.
+
+
+from box import BoxList
+
+from zscaler.zia import ZIAClient
+
+
+class AuthenticationSettingsAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def get_exempted_urls(self) -> BoxList:
+        """
+        Returns a list of exempted URLs.
+
+        Returns:
+            :obj:`BoxList`: A list of exempted URLs
+
+        Examples:
+            >>> for url in zia.authentication_settings.get_exempted_urls():
+            ...    pprint(url)
+        """
+        response = self.rest.get("authSettings/exemptedUrls")
+
+        # Ensure the correct attribute key is used in the response check.
+        if "urls" in response:
+            return response.urls
+        else:
+            return BoxList()
+
+    def add_urls_to_exempt_list(self, url_list: list) -> BoxList:
+        """
+        Adds the provided URLs to the exempt list.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs to be added.
+
+        Returns:
+            :obj:`BoxList`: The complete and updated exempt list.
+
+        """
+
+        payload = {"urls": url_list}
+
+        resp = self.rest.post("authSettings/exemptedUrls?action=ADD_TO_LIST", json=payload)
+
+        # Check if the response object has a 'status_code' attribute before accessing it
+        if hasattr(resp, "status_code"):
+            if resp.status_code == 204:
+                return self.get_exempted_urls()
+        else:
+            # Handle case where resp is a Box object
+            if "urls" in resp:
+                return resp.urls
+            else:
+                return BoxList()  # Return empty list if no URLs are present
+
+    def delete_urls_from_exempt_list(self, url_list: list) -> BoxList:
+        """
+        Deletes the provided URLs from the exemption list.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs to be removed.
+
+        Returns:
+            :obj:`BoxList`: The updated exemption list.
+
+        Examples:
+            >>> zia.authentication_settings.delete_urls_from_exempt_list(['example.com'])
+
+        """
+        payload = {"urls": url_list}
+        resp = self.rest.post("authSettings/exemptedUrls?action=REMOVE_FROM_LIST", json=payload)
+
+        # Return the updated exemption list if the removal was successful.
+        if resp == 200:
+            return self.get_exempted_urls()

zscaler/zia/client.py

@@ -0,0 +1,88 @@
+# -*- 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 ZIAClient:
+    def __init__():
+        pass
+
+    def get(self, path: str, json=None, params=None, fail_safe: bool = False):
+        """
+        Send a GET request to the ZIA API.
+        Parameters:
+        - path (str): API endpoint path.
+        - json (str): the request body.
+        - params (dict): the query params
+        """
+        pass
+        pass
+
+    def get_paginated_data(
+        self,
+        path: str = None,
+        data_key_name: str = None,
+        data_per_page: int = 500,
+        expected_status_code=200,
+    ):
+        """
+        Send a GET request to the ZIA 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 put(self, path: str, json=None, params=None):
+        """
+        Send a PUT request to the ZIA API.
+        Parameters:
+        - path (str): API endpoint path.
+        - json (str): the request body.
+        - params (dict): the query params
+        """
+        pass
+
+    def patch(self, path: str, json=None, params=None):
+        """
+        Send a PATCH request to the ZIA API.
+        Parameters:
+        - path (str): API endpoint path.
+        - json (str): the request body.
+        - params (dict): the query params
+        """
+        pass
+
+    def post(self, path: str, json=None, params=None):
+        """
+        Send a POST request to the ZIA API.
+        Parameters:
+        - path (str): API endpoint path.
+        - json (str): the request body.
+        - params (dict): the query params
+        """
+        pass
+
+    def delete(self, path: str, json=None, params=None):
+        """
+        Send a DELETE request to the ZIA API.
+        Parameters:
+        - path (str): API endpoint path.
+        - json (str): the request body.
+        - params (dict): the query params
+        """
+        pass