Basic Automation with the VMRay API
By Koen Van Impe
Learn more about integrating VMRay Analyzer in different areas of your organizations and how to use its API to automate the submission and processing of the analysis of malware.
According to a report from Honeywell the use of USB removable media in industrial environments increased by 30% last year. One of the reasons for using USB drives in industrial environments is that they serve to transfer vendor updates, changes to configuration files and diagnostical data.
Needless to say that this poses a risk. These transfers punch holes in the concept of air-gapped networks and potentially give attackers the opportunity to pivot between assumed “isolated” networks.
Data Exchange Point
An approach that’s often used in larger industrial environments is a data exchange point where USB drives first have to be scanned before they are allowed into the environment. In practice, vendors plug their USB drive in a media scanner, the scanner analyses the drive and its contents and gives a go/no-go verdict. In another scenario the vendor provides the industrial site the files already upfront and, after they are scanned and approved, these files are available for the technician to execute the update or maintenance.
Unfortunately some of these solutions can be rather costly. But if you already have a malware sandbox, such as the VMRay Malware Analysis & Detection Sandbox, you can also employ it as a solution for media scanning. This post covers a simple workflow where an integration with an existing sandbox is used as a custom media scanner. All files entering the environment are scanned and then, based on the verdict of the scanner, either allowed or blocked.
Scanning Workflow
The workflow that I want to achieve is
· Monitor a directory where files are uploaded for verification;
· If a new file appears, it is submitted to VMRay for scanning;
· Have the file analyzed by VMRay, use the result as the go/no-go verdict. Optionally provide feedback why a certain file was blocked.
To monitor the directory for new files I use a Linux command inotify.
Submit a Sample via VMRay API
Now we have to fill in the “magic”.
Most likely you are customed to use VMRay via its web interface. This interface is good for ad-hoc submission of files but in this case I want to automate the interaction with VMRay as much as possible. To do this I rely on some of the REST endpoints in the VMRay API. The first one is “/rest/sample/submit“, which, as you might already guess from its name, allows you to submit a sample. For this blog post I use simple Linux commands but obviously you can rely on Python or other languages to interact with the API.
The curl command that does the submission is highlighted. You need to provide it your API key, the location to the file that you want to upload and the API end point.
If you don’t have an API key you can get one easily by accessing your VMRay account, go to analysis settings, choose API keys and click “Create new API key”. You can have multiple API keys. The best advice is to create one API key per automation purpose and give that key a descriptive name. This allows you later on to track back the activity to individual keys, scripts or automation workflows.
Submitting the file via curl returns a JSON object. This JSON object not only returns the references to the individual sandbox analysis jobs, it also gives the submission identifier (submission_id) and the general result of the upload.
Once the analysis jobs are finished, there is another REST API endpoint that I can use to get the results: “/rest/submission/<submission_id>”. The submission_id is the ID retrieved from the previous response.
Similar as with submitting the sample, the result of this API call is also a JSON object. The most important element is the submission_verdict field. This field tells me if the sample is “clean”, “suspicious” or “malicious”. This is the result that I can use to allow or block the file.
Behaviour Patterns
There is more useful information to extract from the submission. One of the other REST API endpoints is “/rest/submission/<submission_id>/vtis”. This returns the list of VMRay Threat Identifiers for a specific submission. The curl command fetches these VTIs and then uses the Linux command jq to extract the behaviour patterns.
These patterns immediately give an overview what the sample is doing and is useful information to provide to an integrator or vendor in case a file is marked as malicious.
In a lot of cases a vendor supplies a ZIP or ISO archive instead of a single file. I do not have to extract the files manually from these archives. I can simply submit the archive and then have VMRay extract, and analyse, all the individual files. Another benefit of using VMRay is that the files can also be compared against the VirusTotal reputation engine.
Python Interface to VMRay
The scripts in this post already provide a general overview of what’s possible with the VMRay API and how you can make use of it in various places of your environment. If you want to bring this integration to the next level you might also need a bit of reporting and make further use of the details from the analysis results. This is all possible with bash and jq but it’s far more practical to rely on Python.
As it happens, there is a Python package vmray-rest-api that allows you to easily interact with the VMRay API interface. The package also contains a number of example files to upload samples, get submission details, delete analysis details or create users.
To conclude this post it’s useful to mention that a media scanner is not the only integration that is possible with VMRay. Other integrations include a feed connector with the MISP threat intelligence platform and a MISP module to submit samples and use the sandbox results for threat intelligence.
