sandbox¶

The following methods allow for interaction with the ZIA Cloud Sandbox API endpoints.

Methods are accessible via zia.sandbox

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 CloudSandboxAPI¶

Bases: APIClient

A Client object for the Cloud Sandbox resource.

add_hash_to_custom_list(md5_hash_value_list)¶

Updates the custom list of MD5 file hashes that are blocked by Sandbox.

Parameters:

md5_hash_value_list (list[dict]) –

A list of MD5 hash entries to be blocked. Each entry should be a dictionary with the following keys:

url (str): The MD5 hash value.

urlComment (str): A comment describing the hash.

type (str): The type of threat, e.g., “MALWARE”.

Pass an empty list to clear the blocklist.

Returns:

A tuple containing (BehavioralAnalysisAdvancedSettings, Response, error).

Return type:

tuple

Examples

Add MD5 hashes to the sandbox blocklist:

>>> hash_list = [
...     {
...         "url": "42914d6d213a20a2684064be5c80ffa9",
...         "urlComment": "Malicious file detected",
...         "type": "MALWARE"
...     }
... ]
>>> result, response, error = client.zia.sandbox.add_hash_to_custom_list(
...     md5_hash_value_list=hash_list
... )

get_behavioral_analysis()¶

Returns the custom list of MD5 file hashes that are blocked by Sandbox.

Returns:: A tuple containing the result, response, and error.
Return type:: tuple

get_file_hash_count()¶

Retrieves the Cloud Sandbox used and unused quota for blocking MD5 file hashes.

This method fetches the count of MD5 hashes currently blocked by the Sandbox and the remaining quota available for blocking additional hashes.

Returns:: A tuple containing the result, response, and error.
Return type:: tuple

get_quota()¶

Returns the Cloud Sandbox API quota information for the organisation.

Returns:: A tuple containing the result, response, and error.
Return type:: tuple

get_report(md5_hash, report_details='summary')¶

Returns the Cloud Sandbox Report for the provided hash.

Parameters:

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:

A tuple containing the result, response, and error.

Return type:

tuple

submit_file(file_path, force=False)¶

Submits a file to the ZIA Advanced Cloud Sandbox for analysis.

Parameters:

file_path (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:

The Cloud Sandbox submission response information.

Return type:

Tuple

Examples

Submit a file in the current directory called malware.exe to the cloud sandbox, forcing analysis.

>>> script_dir = os.path.dirname(os.path.abspath(__file__))
... file_path = os.path.join(script_dir, "test-pe-file.exe")
... force_analysis = True
...     submit, _, err = client.zia.sandbox.submit_file(
    file_path=file_path, force=force_analysis)
>>>     if err:
...         print(f"Error submitting file: {err}")
...     else:
...         print("File submitted successfully!")
...         print(f"Response: {submit}")

submit_file_for_inspection(file_path)¶

Submits a file for inspection.

Parameters:: file_path (str) – The path to the file to be inspected.
Returns:: A tuple containing the result, response, and error.
Return type:: tuple

Examples

Submit a file in the current directory called malware.exe to the cloud sandbox, forcing analysis.

>>> script_dir = os.path.dirname(os.path.abspath(__file__))
... file_path = os.path.join(script_dir, "test-pe-file.exe")
... force_analysis = True
...     submit, _, err = client.zia.sandbox.submit_file_for_inspection(
    file_path=file_path, force=force_analysis)
>>>     if err:
...         print(f"Error submitting file: {err}")
...     else:
...         print("File submitted successfully!")
...         print(f"Response: {submit}")