Merge pull request #47 from MislavReversingLabs/main

Update to version to 2.5.6

Author: MislavReversingLabs

Diff for: CHANGELOG.md

@@ -271,3 +271,11 @@ v2.5.1 (2024-04-02)
 #### Bugfixes
 - **a1000** module:
   - Changed the `risk_score` parameter's type hint from `str` to `int` in `set_classification` method's docstring.
+
+
+2.5.6 (2024-05-23)
+-------------------
+
+#### Improvements
+- **a1000** module:
+  - Reintroduced the `a1000.A1000.advanced_search_v2` method. This method will remain in the DEPRECATED state until its permanent removal from the SDK. The permanent removal date will be announced in the CHANGELOG's "Scheduled removals" section. In the meantime, the use of `a1000.A1000.advanced_search_v3` is highly advised.

Diff for: ReversingLabs/SDK/__init__.py

@@ -5,4 +5,4 @@
 A Python SDK for communicating with ReversingLabs services.
 """
 
-__version__ = "2.5.5"
+__version__ = "2.5.6"

Diff for: ReversingLabs/SDK/a1000.py

@@ -9,6 +9,7 @@
 import requests
 import time
 from urllib import parse
+from warnings import warn
 
 from ReversingLabs.SDK.helper import ADVANCED_SEARCH_SORTING_CRITERIA, DEFAULT_USER_AGENT, RESPONSE_CODE_ERROR_MAP, \
     MD5, SHA1, SHA256, SHA512, \
@@ -1595,6 +1596,131 @@ def get_yara_cloud_retro_scan_status(self, ruleset_name):
 
         return response
 
+    def advanced_search_v2(self, query_string, ticloud=False, page_number=1, records_per_page=20, sorting_criteria=None,
+                           sorting_order="desc"):
+        """THIS METHOD IS DEPRECATED. Use advanced_search_v3 instead.
+
+        Sends a query string to the A1000 Advanced Search API v2.
+        The query string must be composed of key-value pairs separated by space.
+        A key is separated from its value by a colon symbol and no spaces.
+        For directions on how to write advanced search queries, consult the A1000 documentation.
+        If a page number is not provided, the first page of results will be returned.
+            Query string example:
+            'av-count:5 available:TRUE'
+
+            :param query_string: query string
+            :type query_string: str
+            :param ticloud: show only cloud results
+            :type ticloud: bool
+            :param page_number: page number
+            :type page_number: int
+            :param records_per_page: number of records returned per page; maximum value is 100
+            :type records_per_page: int
+            :param sorting_criteria: define the criteria used in sorting; possible values are 'sha1', 'firstseen',
+            'threatname', 'sampletype', 'filecount', 'size'
+            :type sorting_criteria: str
+            :param sorting_order: sorting order; possible values are 'desc', 'asc'
+            :type sorting_order: str
+            :return: response
+            :rtype: requests.Response
+        """
+        warn("This method is deprecated. Use advanced_search_v3 instead.", DeprecationWarning)
+
+        if not isinstance(query_string, str):
+            raise WrongInputError("The search query must be a string.")
+
+        if not isinstance(ticloud, bool):
+            raise WrongInputError("ticloud parameter must be boolean.")
+
+        if not isinstance(records_per_page, int) or not 1 <= records_per_page <= 100:
+            raise WrongInputError("records_per_page parameter must be an integer with a value "
+                                  "between 1 and 100 (included).")
+
+        url = self._url.format(endpoint=self.__ADVANCED_SEARCH_ENDPOINT_V2)
+
+        post_json = {"query": query_string, "ticloud": ticloud, "page": page_number,
+                     "records_per_page": records_per_page}
+
+        if sorting_criteria:
+            if sorting_criteria not in ADVANCED_SEARCH_SORTING_CRITERIA or sorting_order not in ("desc", "asc"):
+                raise WrongInputError("Sorting criteria must be one of the following options: {criteria}. "
+                                      "Sorting order needs to be 'desc' or 'asc'.".format(
+                    criteria=ADVANCED_SEARCH_SORTING_CRITERIA
+                ))
+            sorting_expression = "{criteria} {order}".format(
+                criteria=sorting_criteria,
+                order=sorting_order
+            )
+
+            post_json["sort"] = sorting_expression
+
+        response = self.__post_request(url=url, post_json=post_json)
+
+        self.__raise_on_error(response)
+
+        return response
+
+    def advanced_search_v2_aggregated(self, query_string, ticloud=False, max_results=5000, sorting_criteria=None,
+                                      sorting_order="desc"):
+        """THIS METHOD IS DEPRECATED. Use advanced_search_v3_aggregated instead.
+
+        Sends a query string to the A1000 Advanced Search API v2.
+        The query string must be composed of key-value pairs separated by space.
+        A key is separated from its value by a colon symbol and no spaces.
+        For directions on how to write advanced search queries, consult the A1000 documentation.
+        Paging is done automatically and results from individual
+        responses aggregated into one list and returned`.
+        The 'max_results' parameter defines the maximum desired number of results to be returned.
+            Query string example:
+            'av-count:5 available:TRUE'
+
+            :param query_string: search query - see API documentation for details on writing search queries
+            :type query_string: str
+            :param ticloud: show only cloud results
+            :type ticloud: bool
+            :param max_results: maximum results to be returned in a list; default value is 5000
+            :type max_results: int
+            :param sorting_criteria: define the criteria used in sorting; possible values are 'sha1', 'firstseen',
+            'threatname', 'sampletype', 'filecount', 'size'
+            :type sorting_criteria: str
+            :param sorting_order: sorting order; possible values are 'desc', 'asc'
+            :type sorting_order: str
+            :return: list of results
+            :rtype: list
+        """
+        warn("This method is deprecated. Use advanced_search_v3_aggregated instead.", DeprecationWarning)
+
+        if not isinstance(max_results, int):
+            raise WrongInputError("max_results parameter must be integer.")
+
+        results = []
+        next_page = 1
+        more_pages = True
+
+        while more_pages:
+            response = self.advanced_search_v2(
+                query_string=query_string,
+                ticloud=ticloud,
+                page_number=next_page,
+                records_per_page=100,
+                sorting_criteria=sorting_criteria,
+                sorting_order=sorting_order
+            )
+
+            response_json = response.json()
+
+            entries = response_json.get("rl").get("web_search_api").get("entries", [])
+            results.extend(entries)
+
+            if len(results) > max_results:
+                results = results[:max_results]
+                return results
+
+            next_page = response_json.get("rl").get("web_search_api").get("next_page", None)
+            more_pages = response_json.get("rl").get("web_search_api").get("more_pages", False)
+
+        return results
+
     def advanced_search_v3(self, query_string, ticloud=False, start_search_date=None, end_search_date=None,
                            page_number=1, records_per_page=20, sorting_criteria=None, sorting_order="desc"):
         """Sends a query string to the A1000 Advanced Search API v3.