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

zscaler/zia/sandbox.py

@@ -0,0 +1,180 @@
+# -*- 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.
+
+
+import mimetypes
+
+from box import Box
+
+from zscaler.zia import ZIAClient
+
+
+class CloudSandboxAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+        self.sandbox_token = client.sandbox_token
+        self.env_cloud = client.env_cloud
+
+    def submit_file(self, file: str, force: bool = False) -> Box:
+        """
+        Submits a file to the ZIA Advanced Cloud Sandbox for analysis.
+
+        Args:
+            file (str): The filename that will be submitted for sandbox analysis.
+            force (bool): Force ZIA to analyse the file even if it has been submitted previously.
+
+        Returns:
+            :obj:`Box`: The Cloud Sandbox submission response information.
+
+        Examples:
+            Submit a file in the current directory called malware.exe to the cloud sandbox, forcing analysis.
+
+            >>> zia.sandbox.submit_file('malware.exe', force=True)
+
+        """
+        with open(file, "rb") as f:
+            file_content = f.read()
+
+        content_type, _ = mimetypes.guess_type(file)
+        if not content_type:
+            content_type = "application/octet-stream"
+        params = {
+            "api_token": self.sandbox_token,
+        }
+
+        params = {
+            "api_token": self.sandbox_token,
+            "force": int(force),  # convert boolean to int for ZIA
+        }
+
+        url = "/zscsb/submit"
+
+        return self.rest.post(
+            url,
+            data=file_content,
+            params=params,
+        )
+
+    def submit_file_for_inspection(self, file: str) -> Box:
+        """
+        Submits raw or archive files to Zscaler service for out-of-band file inspection.
+
+        Args:
+            file (str): The filename that will be submitted for inspection.
+
+        Returns:
+            :obj:`Box`: The Cloud Sandbox inspection response information.
+
+        Examples:
+            Submit a file in the current directory called sample.zip for inspection.
+
+            >>> zia.sandbox.submit_file_for_inspection('sample.zip')
+
+        """
+        with open(file, "rb") as f:
+            file_content = f.read()
+
+        content_type, _ = mimetypes.guess_type(file)
+        if not content_type:
+            content_type = "application/octet-stream"
+
+        params = {
+            "api_token": self.sandbox_token,
+        }
+
+        return self.rest.post(
+            "/zscsb/discan",
+            params=params,
+            data=file_content,
+            headers={"Content-Type": content_type},
+        )
+
+    def get_quota(self) -> Box:
+        """
+        Returns the Cloud Sandbox API quota information for the organisation.
+
+        Returns:
+            :obj:`Box`: The Cloud Sandbox quota report.
+
+        Examples:
+            >>> pprint(zia.sandbox.get_quota())
+
+        """
+        return self.rest.get("sandbox/report/quota")[0]
+
+    def get_report(self, md5_hash: str, report_details: str = "summary") -> Box:
+        """
+        Returns the Cloud Sandbox Report for the provided hash.
+
+        Args:
+            md5_hash (str):
+                The MD5 hash of the file that was analysed by Cloud Sandbox.
+            report_details (str):
+                The type of report. Accepted values are 'full' or 'summary'. Defaults to 'summary'.
+
+        Returns:
+            :obj:`Box`: The cloud sandbox report.
+
+        Examples:
+            Get a summary report:
+
+            >>> zia.sandbox.get_report('8350dED6D39DF158E51D6CFBE36FB012')
+
+            Get a full report:
+
+            >>> zia.sandbox.get_report('8350dED6D39DF158E51D6CFBE36FB012', 'full')
+
+        """
+
+        return self.rest.get(f"sandbox/report/{md5_hash}?details={report_details}")
+
+    def get_behavioral_analysis(self) -> Box:
+        """
+        Returns the custom list of MD5 file hashes that are blocked by Sandbox.
+
+        Returns:
+            :obj:`Box`: The custom list of MD5 file hashes that are blocked by Sandbox.
+
+        Examples:
+            >>> pprint(zia.sandbox.get_behavioral_analysis())
+
+        """
+        return self.rest.get("behavioralAnalysisAdvancedSettings")
+
+    def add_hash_to_custom_list(self, file_hashes_to_be_blocked: list) -> Box:
+        """
+        Updates the custom list of MD5 file hashes that are blocked by Sandbox.
+
+        Args:
+            file_hashes_to_be_blocked (:obj:`list` of :obj:`str`):
+                The list of MD5 Hashes to be added. Pass an empty list to clear the blocklist.
+
+        Returns:
+            :obj:`Box`: The updated custom list of MD5 Hashes.
+
+        Examples:
+            >>> zia.sandbox.add_hash_to_custom_list(['42914d6d213a20a2684064be5c80ffa9', 'c0202cf6aeab8437c638533d14563d35'])
+            >>> zia.sandbox.add_hash_to_custom_list([])  # Clear the list
+
+        """
+
+        payload = {"fileHashesToBeBlocked": file_hashes_to_be_blocked}
+
+        # Update the custom list with the provided hashes
+        self.rest.put("behavioralAnalysisAdvancedSettings", json=payload)
+
+        # Return the most up-to-date list after the update
+        return self.get_behavioral_analysis()

zscaler/zia/security.py

@@ -0,0 +1,236 @@
+# -*- 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 SecurityPolicyAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def get_whitelist(self) -> BoxList:
+        """
+        Returns a list of whitelisted URLs.
+
+        Returns:
+            :obj:`BoxList`: A list of whitelisted URLs
+
+        Examples:
+            >>> for url in zia.security.get_whitelist():
+            ...    pprint(url)
+
+        """
+        response = self.rest.get("security")
+
+        # ZIA removes the whitelistUrls key from the JSON response when it's empty.
+        if "whitelist_urls" in self.rest.get("security"):
+            return response.whitelist_urls
+        else:
+            return (
+                BoxList()
+            )  # Return empty list so other methods in this class don't break
+
+    def get_blacklist(self) -> BoxList:
+        """
+        Returns a list of blacklisted URLs.
+
+        Returns:
+            :obj:`BoxList`: A list of blacklisted URLs
+
+        Examples:
+            >>> for url in zia.security.get_blacklist():
+            ...    pprint(url)
+
+        """
+
+        return self.rest.get("security/advanced").blacklist_urls
+
+    def erase_whitelist(self) -> int:
+        """
+        Erases all URLs in the whitelist.
+
+        Returns:
+            :obj:`int`: The status code for the operation.
+
+        Examples:
+            >>> zia.security.erase_whitelist()
+
+        """
+        payload = {"whitelistUrls": []}
+
+        return self.rest.put("security", json=payload).status_code
+
+    def replace_whitelist(self, url_list: list) -> BoxList:
+        """
+        Replaces the existing whitelist with the URLs provided.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs for the new whitelist.
+
+        Returns:
+            :obj:`BoxList`: The complete and updated whitelist.
+
+        Examples:
+            >>> zia.security.replace_whitelist(['example.com'])
+
+        """
+
+        payload = {"whitelistUrls": url_list}
+
+        return self.rest.put("security", json=payload).whitelist_urls
+
+    def add_urls_to_whitelist(self, url_list: list) -> BoxList:
+        """
+        Adds the provided URLs to the whitelist.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs to be added.
+
+        Returns:
+            :obj:`BoxList`: The complete and updated whitelist.
+
+        Examples:
+            >>> zia.security.add_urls_to_whitelist(['example.com', 'web.example.com'])
+
+        """
+
+        # Get the current whitelist
+        whitelist = self.get_whitelist()
+
+        # Add existing URLs to whitelist
+        whitelist.extend(url for url in url_list if url not in whitelist)
+
+        payload = {"whitelistUrls": whitelist}
+
+        return self.rest.put("security", json=payload).whitelist_urls
+
+    def delete_urls_from_whitelist(self, url_list: list) -> BoxList:
+        """
+        Deletes the provided URLs from the whitelist.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs to be deleted.
+
+        Returns:
+            :obj:`BoxList`: The complete and updated whitelist.
+
+        Examples:
+            >>> zia.security.delete_urls_from_whitelist(['example.com', 'web.example.com'])
+
+        """
+        # Get the current whitelist
+        whitelist = self.get_whitelist()
+
+        # If URLs provided, create new whitelist without them
+        whitelist = [url for url in whitelist if url not in url_list]
+
+        payload = {"whitelistUrls": whitelist}
+
+        return self.rest.put("security", json=payload).whitelist_urls
+
+    def add_urls_to_blacklist(self, url_list: list) -> BoxList:
+        """
+        Adds the provided URLs to the blacklist.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs to be added.
+
+        Returns:
+            :obj:`BoxList`: The complete and updated blacklist.
+
+        Examples:
+            >>> zia.security.add_urls_to_blacklist(['example.com', 'web.example.com'])
+
+        """
+
+        payload = {"blacklistUrls": url_list}
+
+        resp = self.rest.post(
+            "security/advanced/blacklistUrls?action=ADD_TO_LIST", json=payload
+        ).status_code
+
+        # Return the object if it was updated successfully
+        if resp == 204:
+            return self.get_blacklist()
+
+    def replace_blacklist(self, url_list: list) -> BoxList:
+        """
+        Replaces the existing blacklist with the URLs provided.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs for the new blacklist.
+
+        Returns:
+            :obj:`BoxList`: The complete and updated blacklist.
+
+        Examples:
+            >>> zia.security.replace_blacklist(['example.com'])
+
+        """
+
+        payload = {"blacklistUrls": url_list}
+
+        return self.rest.put("security/advanced", json=payload).blacklist_urls
+
+    def erase_blacklist(self) -> int:
+        """
+        Erases all URLs in the blacklist.
+
+        Returns:
+            :obj:`int`: The status code for the operation.
+
+        Examples:
+            >>> zia.security.erase_blacklist()
+
+        """
+
+        payload = {"blacklistUrls": []}
+        try:
+            self.rest.put("security/advanced", json=payload)
+            return "Blacklist successfully erased."
+        except Exception as e:
+            return f"An error occurred: {str(e)}"
+
+    def delete_urls_from_blacklist(self, url_list: list) -> int:
+        """
+        Deletes the provided URLs from the blacklist.
+
+        Args:
+            url_list (:obj:`list` of :obj:`str`):
+                The list of URLs to be deleted.
+
+        Returns:
+            :obj:`int`: The status code for the operation.
+
+        Examples:
+            >>> zia.security.delete_urls_from_blacklist(['example.com', 'web.example.com'])
+
+        """
+
+        payload = {"blacklistUrls": url_list}
+
+        return self.rest.post(
+            "security/advanced/blacklistUrls?action=REMOVE_FROM_LIST",
+            json=payload,
+        ).status_code

zscaler/zia/ssl_inspection.py

@@ -0,0 +1,175 @@
+# -*- 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 SSLInspectionAPI:
+    def __init__(self, client: ZIAClient):
+        self.rest = client
+
+    def get_csr(self) -> str:
+        """
+        Downloads a CSR after it has been generated.
+
+        Returns:
+            :obj:`str`: Base64 encoded PKCS#10 CSR text.
+
+        Examples:
+            Retrieve the CSR for use in another function.
+
+            >>> csr = zia.ssl.get_csr()
+
+        """
+        return self.rest.get("sslSettings/downloadcsr").text
+
+    def get_intermediate_ca(self) -> Box:
+        """
+        Returns information on the signed Intermediate Root CA certificate.
+
+        Returns:
+            :obj:`Box`: The Intermediate Root CA resource record.
+
+        Examples:
+            >>> pprint(zia.ssl.get_intermediate_ca())
+
+        """
+        return self.rest.get("sslSettings/showcert")
+
+    def generate_csr(
+        self,
+        cert_name: str,
+        cn: str,
+        org: str,
+        dept: str,
+        city: str,
+        state: str,
+        country: str,
+        signature: str,
+    ) -> int:
+        """
+        Generates a Certificate Signing Request.
+
+        Args:
+            cert_name (str): Certificate Name
+            cn (str): Common Name
+            org (str): Organisation
+            dept (str): Department
+            city (str): City
+            state (str): State
+            country (str): Country. Must be in the two-letter country code (ISO 3166-1 alpha-2) format and prefixed by
+                `COUNTRY`. E.g.::
+
+                    United States = US = COUNTRY_US
+                    Australia = AU = COUNTRY_AU
+
+            signature  (str): Certificate signature algorithm. Accepted values are `SHA_1` and `SHA_256`.
+
+        Returns:
+            :obj:`int`: The response code for the operation.
+
+        Examples:
+            >>> zia.ssl.generate_csr(cert_name='Example.com Intermediate CA 2',
+            ...    cn='Example.com Intermediate CA 2',
+            ...    org='Example.com',
+            ...    dept='IT',
+            ...    city='Sydney',
+            ...    state='NSW',
+            ...    country='COUNTRY_AU',
+            ...    signature='SHA_256')
+
+        """
+        payload = {
+            "certName": cert_name,
+            "commName": cn,
+            "orgName": org,
+            "deptName": dept,
+            "city": city,
+            "state": state,
+            "country": country,
+            "signatureAlgorithm": signature,
+        }
+
+        return self.rest.post(
+            "sslSettings/generatecsr", json=payload, box=False
+        ).status_code
+
+    def upload_int_ca_cert(self, cert: tuple) -> int:
+        """
+        Uploads a signed Intermediate Root CA certificate.
+
+        Args:
+            cert (tuple): The Intermediate Root CA certificate tuple in the following format, where `int_ca_pem` is a
+                ``File Object`` representation of the Intermediate Root CA certificate PEM file::
+
+                ('filename.pem', int_ca_pem)
+
+        Returns:
+            :obj:`int`: The status code for the operation.
+
+        Examples:
+            Upload an Intermediate Root CA certificate from a file:
+
+            >>> zia.ssl.upload_int_ca_cert(('int_ca.pem', open('int_ca.pem', 'rb')))
+
+        """
+
+        payload = {"fileUpload": cert}
+
+        return self.rest.post(
+            "sslSettings/uploadcert/text", files=payload, box=False
+        ).status_code
+
+    def upload_int_ca_chain(self, cert: tuple) -> int:
+        """
+        Uploads the Intermediate Root CA certificate chain.
+
+        Args:
+            cert (tuple): The Intermediate Root CA chain certificate tuple in the following format, where
+                `int_ca_chain_pem` is a ``File Object`` representation of the Intermediate Root CA certificate chain
+                PEM file::
+
+                ('filename.pem', int_ca_chain_pem)
+
+
+        Returns:
+            :obj:`int`: The status code for the operation
+
+        Examples:
+            Upload an Intermediate Root CA chain from a file:
+
+            >>> zia.ssl.upload_int_ca_chain(('int_ca_chain.pem', open('int_ca_chain.pem', 'rb')))
+
+        """
+
+        payload = {"fileUpload": cert}
+
+        return self.rest.post(
+            "sslSettings/uploadcertchain/text", files=payload, box=False
+        ).status_code
+
+    def delete_int_chain(self) -> int:
+        """
+        Deletes the Intermediate Root CA certificate chain.
+
+        Returns:
+            :obj:`int`: The status code for the operation.
+
+        """
+        return self.rest.delete("sslSettings/certchain", box=False).status_code