SANS Digital Forensics and Incident Response Blog

Managing and Exploring Malware Samples with Viper

Keeping track of all the samples on your plate can become cumbersome and at times, next to impossible; that's where projects like Viper come in. Viper is "a framework to store, classify and investigate binary files." This project is an improvement on another tool called VxCage. Viper is lightweight (due its usage of SQLite), and brings a lot to the table with an ever-growing list of included modules and analysis tools. The following article, contributed by David Westcott, explains how to get started with this tool.

Viper project is maintained by Claudio Guarnieri (@botherder), Kevin Breen (@KevTheHermit) and Mariano Graziano (@emd3l). This tool is included in the latest version of REMnux. To take full advantage of the latest features of Viper, update the version of the tool included with REMnux using the instructions below. Some of the features available in the updated version of Viper are:

  • The introduction of projects
  • Additional processing and reporting modules
  • Multiple fixes (see Github history for more info)

Make sure you're running the latest version of Viper (see update instructions below), then run it using the "" command.

Getting to Know Viper

Viper presents its user with an interactive shell. Type "help" in the Viper's shell to see a listing of the available commands:

You will also see a listing of the more interesting commands that Viper calls "modules":

Going through all the things Viper can do is beyond the scope of this post, but for sake of demonstration, let's take a look at a few things not mentioned within the Viper's README document. Note that all modules will be run against the currently opened session (a.k.a. file currently referenced).

You can download a sample and directly add it to your repository using the "open" command:

You can quickly tag a sample for easier reference in the future using the "tags" command:

You can examine the current PE sample for shellcode characteristics using the "shellcode" module:

You can analyze a binary Microsoft Office document for OLE details using the "office" module:

You can locate scripts within an HTML sample using the "html" module:

You can look up the current sample's hash on VirusTotal using the "virustotal" module:

You can also look up the sample on on using the "reports malwr" command:

It's worth noting the API that Viper makes available to its users. At the moment, the API is pretty basic, you can perform the following:

  • Query for a hash
  • Upload a file
  • List current tags within the repo
  • Download a given file

To activate Viper's API engine, go to the directory where it's installed (on REMnux that's /usr/local/viper) and run "python" as the root user:

If you want to use the API portion of the application, you need to install the Bottle framework by running "sudo pip install bottle".

Updating Viper on REMnux

Confirm that you're running the latest version of REMnux. These update instructions are written for REMnux version 5, released in May 2014. You don't need to take these steps if running a later version of REMnux.

If running REMnux v5, first configure your REMnux virtual appliance to be connected to the Internet. The virtual machine ships with host-only networking. You'll need to adjust its configuration to use NAT mode, then run "dhcp-renew" to refresh IP settings.

Remove the current set of Viper files and download the latest version using the following steps:

sudo -s
cd /usr/local
rm -rf viper
git clone

Modify Viper's configuration in the /usr/local/viper/modules/ file to point it to the packer signatures database. To do this, run "scite /usr/local/viper/modules/". Then change from:


Also, modify Viper's configuration in the /usr/local/viper/modules/ file to point to the location of Yara signatures. To do this, run "scite /usr/local/viper/modules/" and changing "data/yara/index.yara" to "/usr/local/viper/data/yara/index.yara":

Next, install new dependency to be used with OLE plugin by running the following command:

pip  install OleFileIO_PL

If you haven't already installed Bottle, as indicated above, to so by running "pip install bottle".

Lastly, create the directory where Viper will store its projects data by running:

mkdir ~remnux/projects

After this, exit the root shell ("exit") and run Viper ("") as a non-root user. You should run Viper from the directory to which the "remnux" user has write access, such as this user's home directory.


Viper is a promising tool for managing and exploring malware samples in your collection. Based on the projects that Viper's developers have created previously (most notably Cuckoo Sandbox), this tool has a bright future as part of a malware analyst's toolkit.

This article was written by David Westcott (@beast_fighter)