Merge pull request #35 from MislavReversingLabs/main

v2.4.1

Author: MislavReversingLabs

Diff for: CHANGELOG.md

@@ -173,6 +173,18 @@ v2.4.0 (2023-12-29)
 ---
 
 
+v2.4.1 (2024-01-11)
+-------------------
+
+#### Improvements
+
+- **ticloud** module:
+  - The `get_dynamic_analysis_results` method of the `DynamicAnalysis` class now also supports using a URL-s SHA-1 hash for fetching the URL dynamic analysis results. 
+
+- Error handling: Custom error classes now also carry the original response object. Users can now reach the original status code, error message and all other response properties using the caught error's `response_object` property. 
+
+
+
 ### Scheduled removals
 - **March 2024.**:
   - `a1000.A1000.advanced_search_v2`

Diff for: README.md

@@ -412,8 +412,8 @@ _TCA-0207 and TCA-0106_
 - `detonate_url`
     - Submits a URL for dynamic analysis and returns processing info
 - `get_dynamic_analysis_results`
-    - Returns dynamic analysis results for a desired sample
-    - The analysis of the selected sample must be finished for the results to be available
+    - Returns dynamic analysis results for a desired sample or URL
+    - The analysis of the selected sample or URL must be finished for the results to be available
 
 #### Class:
 ```python

Diff for: ReversingLabs/SDK/helper.py

@@ -26,80 +26,109 @@
 ADVANCED_SEARCH_SORTING_CRITERIA = ("sha1", "firstseen", "threatname", "sampletype", "filecount", "size")
 
 
+class WrongInputError(Exception):
+    def __init__(self, message="This input type is not allowed"):
+        super(WrongInputError, self).__init__(message)
+
+
 class NotFoundError(Exception):
-    def __init__(self, message="Not found. No reference was found for this input"):
+    def __init__(self, response_object, message="Not found. No reference was found for this input"):
         super(NotFoundError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class NoFileTypeError(Exception):
-    def __init__(self, message="There is no determinable file type"):
+    def __init__(self, response_object, message="There is no determinable file type"):
         super(NoFileTypeError, self).__init__(message)
 
-
-class WrongInputError(Exception):
-    def __init__(self, message="This input type is not allowed"):
-        super(WrongInputError, self).__init__(message)
+        self.response_object = response_object
 
 
 class UnauthorizedError(Exception):
-    def __init__(self, message="The provided credentials are invalid"):
+    def __init__(self, response_object, message="The provided credentials are invalid"):
         super(UnauthorizedError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class ForbiddenError(Exception):
-    def __init__(self, message="The provided credentials do not have the required rights to access this resource"):
+    def __init__(self, response_object,
+                 message="The provided credentials do not have the required rights to access this resource"):
         super(ForbiddenError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class BadRequestError(Exception):
-    def __init__(self, message="Bad request created"):
+    def __init__(self, response_object, message="Bad request created"):
         super(BadRequestError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class RequestTimeoutError(Exception):
-    def __init__(self, message="Request timed out"):
+    def __init__(self, response_object, message="Request timed out"):
         super(RequestTimeoutError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class ConflictError(Exception):
-    def __init__(self, message="Can't complete the request due to a conflict"):
+    def __init__(self, response_object, message="Can't complete the request due to a conflict"):
         super(ConflictError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class RequestTooLargeError(Exception):
-    def __init__(self, message="The request is too large"):
+    def __init__(self, response_object, message="The request is too large"):
         super(RequestTooLargeError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class InternalServerError(Exception):
-    def __init__(self, message="Internal server error"):
+    def __init__(self, response_object, message="Internal server error"):
         super(InternalServerError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class BadGatewayError(Exception):
-    def __init__(self, message="The server received an invalid response from another server"):
+    def __init__(self, response_object, message="The server received an invalid response from another server"):
         super(BadGatewayError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class ServiceUnavailableError(Exception):
-    def __init__(self, message="Service unavailable"):
+    def __init__(self, response_object, message="Service unavailable"):
         super(ServiceUnavailableError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class NotAllowedError(Exception):
-    def __init__(self, message="This method is not allowed"):
+    def __init__(self, response_object, message="This method is not allowed"):
         super(NotAllowedError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class TooManyRequestsError(Exception):
-    def __init__(self, message="Too many requests. Your quota limit might be reached"):
+    def __init__(self, response_object, message="Too many requests. Your quota limit might be reached"):
         super(TooManyRequestsError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class NotAcceptableError(Exception):
-    def __init__(self, message="This content is not acceptable"):
+    def __init__(self, response_object, message="This content is not acceptable"):
         super(NotAcceptableError, self).__init__(message)
 
+        self.response_object = response_object
+
 
 class CloudDeepScanException(Exception):
     """Base exception for the clouddeepscan module

Diff for: ReversingLabs/SDK/ticloud.py

@@ -179,7 +179,7 @@ def _raise_on_error(self, response):
             return
         if exception == NotFoundError and self._allow_none_return:
             return None
-        raise exception
+        raise exception(response_object=response)
 
 
 class FileReputation(TiCloudAPI):
@@ -3099,7 +3099,8 @@ class DynamicAnalysis(TiCloudAPI):
     __DETONATE_ARCHIVE_ENDPOINT = "/api/dynamic/analysis/analyze/v1/archive/query/json"
     __GET_FILE_RESULTS = "/api/dynamic/analysis/report/v1/query/sha1"
     __GET_ARCHIVE_RESULTS_ENDPOINT = "/api/dynamic/analysis/report/v1/archive/query/sha1"
-    __GET_URL_RESULTS = "/api/dynamic/analysis/report/v1/query/url/base64"
+    __GET_URL_RESULTS_BASE64 = "/api/dynamic/analysis/report/v1/query/url/base64"
+    __GET_URL_RESULTS_SHA1 = "/api/dynamic/analysis/report/v1/query/url/sha1"
 
     def __init__(self, host, username, password, verify=True, proxies=None, user_agent=DEFAULT_USER_AGENT,
                  allow_none_return=False):
@@ -3206,14 +3207,17 @@ def __detonate(self, platform, sample_sha1=None, url_string=None, is_archive=Fal
 
         return response
 
-    def get_dynamic_analysis_results(self, sample_hash=None, url=None, is_archive=False, latest=False,
+    def get_dynamic_analysis_results(self, sample_hash=None, url=None, url_sha1=None, is_archive=False, latest=False,
                                      analysis_id=None):
         """Returns dynamic analysis results for a desired file, URL or a file archive.
         The analysis of the selected artifact must be finished for the results to be available.
             :param sample_hash: SHA-1 hash of a desired sample or archive. mutually exclusive with url
             :type sample_hash: str
-            :param url: URL string. mutually exclusive with sample_hash
+            :param url: URL string; mutually exclusive with sample_hash
             :type url: str
+            :param url_sha1: the sha1 of the submitter URL; it can be found in the response of the
+            DynamicAnalysis.detonate_url method; mutually exclusive with sample_hash and url
+            :type url_sha1: str
             :param is_archive: needs to be set to True if results for a file archive are being fetched;
             currently supported archive types: .zip; used only with sample_hash
             :type is_archive: bool
@@ -3242,7 +3246,15 @@ def get_dynamic_analysis_results(self, sample_hash=None, url=None, is_archive=Fa
                 raise WrongInputError("url parameter must be a string")
 
             indicator = base64.urlsafe_b64encode(url.encode("utf-8")).strip(b"=").decode()
-            endpoint_base = self.__GET_URL_RESULTS
+            endpoint_base = self.__GET_URL_RESULTS_BASE64
+
+        elif url_sha1:
+            validate_hashes(
+                hash_input=[url_sha1],
+                allowed_hash_types=(SHA1,)
+            )
+            indicator = url_sha1
+            endpoint_base = self.__GET_URL_RESULTS_SHA1
 
         else:
             raise WrongInputError("Either sample_hash or url need to be defined as parameters")

Diff for: setup.py

@@ -11,7 +11,7 @@
 
 setup(
     name="reversinglabs-sdk-py3",
-    version="2.4.0",
+    version="2.4.1",
     description="Python SDK for using ReversingLabs services - Python 3 version.",
     long_description=long_description,
     long_description_content_type="text/markdown",