Using a websocket client to access the Content Analysis REST API

Products

• Content Analysis Software - CA

Issue/Introduction

As of Content Analysis (CA) 2.1 you now have the ability to send files for analysis directly to the CA device without the need to use the ICAP protocol. This essentially means you can access the features of the CA and the Malware Analysis device (MA), if configured, without the need to first have the data go through a ProxySG. This feature is typically used by security teams to test files.

Environment

This article assumes the following prerequisites are in place:

1. Client workstation running Windows or Linux OS (for this article we will use a linux client)
2. Python 2.7 or 3.x (this article will use Python 2.7.12)
3. websocket client
4. CA 2.x
5. Sandboxing solution (this article will use Symantecs Malware Analysis Appliance 4.2.1.1)

Resolution

CA documentation includes a "Developer's Guide for Content Analysis File Submission REST API" which in turn contains two scripts. "cas-submit.txt" and "cas-websocket.txt"

To start with, download the websocket client for Python from here https://pypi.python.org/pypi/websocket-client

You will also need the requests file which can be downloaded from here: https://codeload.github.com/kennethreitz/requests/legacy.tar.gz/master

Extract these files. At the root of each directory you will find a "setup.py file.

Run the following command to install these files (this assumes the python executable is in your path)

python setup.py install

NOTE: you need to do this for both the websocket client and the requests file.

To start the websocket client open a terminal command prompt and run the following command

python cas-websocket.txt --host CA_IP:8082 --key "----------MYKEYSTRING----------------"

The "key" refers to the REST API key that needs to be generated on the CA device by running the following command

ma-actions api-key create administrator

if a connection is established you will not get a return prompt, You should see something like this.

Note: the key has been blacked out, but the point here is that the websocket will not return any message until a file has been sent to it which requires a response

 

In order to submit files to the CA via the websocket client open a new terminal command prompt and run the following command

python cas-submit.txt --host CA_IP:8082 -k "----------MYKEYSTRING----------------" --file mymalwaresample.exe

this will return the response back from the CA device whose contents will vary depending on what features are enabled (file reputation, antivirus, static analyses etc) and the processing done on the file ie was it sent to the MA device or not. The following example shows a file that was not sent to the MA device

Note: as nothing was sent to the MA device u'expected_sandbox':False, there will be no MA output sent to the websocket terminal

 

In the following example the file was sent by CA to the MA device (u'expected_sandbox':True) so we get two outputs, one from CA and one from MA.

The output from MA will take longer to show up in the escheat client terminal as it needs to run the file in the virtual environment and this can take two to 3 minutes

 

 

and eventually the websocket client terminal will return