ReversingLabs SDK for Python

Extend Your Integrations and Enrich Your Workflows Using Python

Mislav Sever
Blog Author

Mislav Sever, Senior Integration Engineer at ReversingLabs.

ReversingLabs SDK for Python
Just recently ReversingLabs officially released its extensive Python SDK created for automating and simplifying the lives of developers and security software integrators who intend on using ReversingLabs services programmatically. The name of the SDK in question is, conveniently and descriptively, ReversingLabs SDK.

For a rather brief look into the ReversingLabs SDK (in further text: SDK), one could describe it as a Python tool for easier use of ReversingLabs appliances and platforms that have a REST API. In a more detailed dive into the project, one can see various possibilities when it comes to developing your own software integrations, automating security pipelines and workflows and writing interactive file analysis pivoting interfaces.

The SDK comes in two versions: one for Python 2 and one for Python 3. Both versions can be found on PyPI (https://pypi.org/project/reversinglabs-sdk-py3/ ; https://pypi.org/project/reversinglabs-sdk-py2/) and are regularly updated and maintained by ReversingLabs.

Upon installing the SDK using your Python package manager of choice, we can begin hunting for malware.

Let us say that we came across a file of suspicious behavior and signature. What we can do to start off our pivoting analysis is to calculate the SHA-1 hash of the mentioned file.
21841b32c6165b27dddbd4d6eb3a672defe54271 is the string we got out of it.

For a top level reputation and classification info, we can send the hash to the TitaniumCloud File Reputation API.

Creating a File Reputation request

Figure 1: Creating a File Reputation request

The File Reputation API is one of ReversingLabs’ most popular and convenient API-s and it gives us much more reputation information than just the bare sample classification. Let us import the FileReputation class from the SDK and see the reputation of the mentioned hash:

File Reputation report

Figure 2: File Reputation report

So the questionable file turned out to be malicious and also a malware well known to the ever growing ReversingLabs database: a Win32.Ransomware.Tox

Since we are interested in investigating this type of malware to its full extent, we can again take its SHA-1 hash and use it to query the TitaniumCloud RHA1 Functional Similarity API. The code for this step is again very simple and straightforward.

To simulate a programmatic approach, we took the classification statement out of the File Reputation report and used it to query the RHA1 Functional Similarity API in case it is equal to “SUSPICIOUS” or “MALICIOUS”. Since the file indeed is classified as malicious, our code will proceed to use the hash for further investigation:

Obtaining functionally similar hashes

Figure 3: Obtaining functionally similar hashes

What we did here is use the SDK’s capability to return a list of up to 5000 hashes of malicious files similar to the one we already have. Since ReversingLabs constantly collects intel on huge amounts of file samples in the wild, we received an extensive list of those files that have already been seen, analyzed and classified by ReversingLabs’ services.

A list of functionally similar hashes

Figure 4: A list of functionally similar hashes

In case we want reputation information for each of the returned similar hashes too, we would set extended_results to True. The similarity function can also be used to return hashes of files that are not exclusively malicious but also of any other classification.

Additionally, since the similarity lists can become very long, we might want to have a brief overview of how many functionally similar files to our ransomware there really is in the wild, sorted by classification:

Creating an RHA1 Analytics report

Figure 5: Creating an RHA1 Analytics report


RHA1 Analytics report

Figure 6: RHA1 Analytics report

The results we get here are easy to interpret: there are 144 malicious files functionally similar to our ransomware.

Just like in the RHA1 Functional Similarity calls, here we can also return extended reputation results alongside the similarity counters if we set the function call like this:

Adding the extended results parameter

Figure 7: Adding the extended results parameter


RHA1 Analytics report with extended information

Figure 8: RHA1 Analytics report with extended information

Notice how this time we have much more information about the original ransomware, alongside the expected similarity counters. This kind of action makes the SDK very practical for obtaining extensive information about an analyzed sample from a single data source.

Now that we have a whole list of malicious samples, we might want to get information that includes much more than just reputation and similarity. This is where we can make a bulk request to the TitaniumCloud File Analysis API utilizing the FileAnalysis class from the SDK:

Creating a File Analysis request

Figure 9: Creating a File Analysis request

Using the similar_hashes list we obtained earlier, we engaged the File Analysis class and its get_analysis_results method to create a bulk request. All of these pivoting actions we are doing right now in Python would take many more time, resources and much more code if it were not for the SDK. The SDK takes care of input validation, error handling, creating requests, formatting the results and much more. It is a very functional user-oriented code library intended for ease of use when it comes to all ReversingLabs services and appliances that have a REST API.


Part of the File Analysis report

Figure 10: Part of the File Analysis report

What we see here is only a fragment of one of the analyzed file’s File Analysis reports. This API gives us a plethora of information related to static file analysis and also gives us a summed up human readable output like the following description:

Human readable File Analysis output

Figure 11: Human readable File Analysis output

Now we ended up with in-depth analysis and similarity information of all the malicious files related to our original ransomware. While all of this already seems like extensive intel, there are even more actions we can take using our SDK.
Maybe we want to upload a new file to TitaniumCloud, detonate it in a Windows 10 dynamic analysis environment and retrieve its results.
Or maybe we want to download some of the files from our similarity list locally and use them for detailed analysis in a secure environment ourselves:

Creating a File Download request

Figure 12: Creating a File Download request

Downloaded sample

Figure 13: Downloaded sample

On the other hand, we might want to send our original ransomware to our instance of ReversingLabs A1000 file analysis appliance. Since the SDK does not only support working with TitaniumCloud, this is very much possible.

We can upload the file, retrieve the extensive analysis report into our code and also visit A1000 sample listing to see what the appliance did with the file firsthand.

Creating an A1000 request for uploading a file and waiting for the analysis report

Figure 14: Creating an A1000 request for uploading a file and waiting for the analysis report

Here we can see that the A1000 module of the SDK allows various customizable parameters. Since this method uploads the sample to A1000 and waits for it to process the file and returns its report, we might want to be able to set our own timeout values: the number of retries and seconds of wait time in between retries. As for the other customizable parameters, we will observe their effect on the A1000 web interface.

A1000 submission list

Figure 15: A1000 submission list

Here we can clearly see our ransomware uploaded to A1000 with the custom filename we have given it using the SDK.

A1000 sample analysis overview

Figure 16: A1000 sample analysis overview

A1000 sample description and tags

Figure 17: A1000 sample description and tags

These two views show us just a small amount of options and information that the A1000 gives us but we can clearly see that our custom tags from the SDK call were recorded and are now visible.

Since the ReversingLabs SDK for Python is always growing, we will surely be adding more functionality, methods, classes and whole modules to it soon enough. At this point in time, the SDK supports working with a number of TitaniumCloud APIs, TitaniumScale and A1000.


Sign up now to receive notifications for the ReversingLabs Blog

Request a DEMO

Request a live demo today for a walkthrough of how ReversingLabs detects and analyzes more hidden threats, built to evade security controls—and how we do it faster than anyone else.