A rubygem for interacting with Virustotal.com's public API v2

View the Project on GitHub


Gem Version Build Status Code Climate Inline docs

uirusu is an Virustotal automation and convenience tool for hash, file and URL submission.

The current version is 1.1.0.



% gem install uirusu
% uirusu [options]

Create your configuration file

% uirusu --create-config

Edit your configuration file with API key

% $EDITOR ~/.uirusu

Alternatively you can set Environment variables without a config file



Searching a file of hashes

% uirusu -f <file_with_hashes_one_per_line>

Searching a single hash

% uirusu -h FD287794107630FA3116800E617466A9

Searching a file of hashes and outputting to XML

% uirusu -f <file_with_hashes_one_per_line> -x

Upload a file to Virustotal and wait for analysis

% uirusu -u </path/to/file>

Search for a single URL

% uirusu -s "http://www.google.com"

Saving results to a file

% uirusu -s "http://www.google.com" --yaml-output > file.yaml

Scan a directory and have them searched and save the results as json

% uirusu -d /bin/ --json-output > file.json

API Usage

#First you need to include the correct require files
require 'uirusu'


hash = "FD287794107630FA3116800E617466A9" #Hash for a version of Poison Ivy
url = "http://www.google.com"
comment = "Hey this is Poison Ivy, anyone have a copy of this binary?"

#To query a hash(sha1/sha256/md5)
results = Uirusu::VTFile.query_report(API_KEY, hash)
result = Uirusu::VTResult.new(hash, results)
print result.to_stdout if result != nil

#To scan for a url
results = Uirusu::VTUrl.query_report(API_KEY, url)
result = Uirusu::VTResult.new(url, results)
print result.to_stdout if result != nil

#To post a comment to a resource(url/hash/scan_id)
results = Uirusu::VTComment.post_comment(API_KEY, hash, comment)
print results if results != nil

Private API Support

Private API support is supported by the gem, but is not yet supported in the CLI application.

Notes: * Details on the private API can be found here * Optional parameters can be sent to the method calls as named parameters (see VTFile#query_report below) * #feed and #false_positive are currently not supported, as they require a special API key


Below are some examples specific to the private API.

# Search for a hash and get additional metadata
Uirusu::VTFile.query_report(API_KEY, hash, allinfo: 1)

# Get a file upload URL for larger files

# Submit a file with a callback URL
Uirusu::VTFile.scan_file(API_KEY, filepath, notify_url: 'http://requestb.in/117n0hb1')

# Request a behavioural report on a hash
Uirusu::VTFile.behaviour(API_KEY, hash)

# Request a network traffic report on a hash
Uirusu::VTFile.network_traffic(API_KEY, hash)
Domains and IPs

# Get a report for a domain
Uirusu::VTDomain.query_report(API_KEY, domain)

# Get a report for an IP address
Uirusu::VTIPAddr.query_report(API_KEY, ip)

##License Uirusu is licensed under the MIT license see the LICENSE file for the full license.


You can reach the team at jacob.hammack[@]hammackj[dot]com, http://www.hammackj.com, or contact hammackj