module Uirusu::VTFile

Module for Accessing the File scan and report functionalities of the Virustotal.com public API

Constants

BEHAVIOUR_URL
CLUSTERS_URL
DOWNLOAD_URL
FALSE_POSITIVES_URL
FEED_URL
NETWORK_TRAFFIC_URL
REPORT_URL
RESCAN_DELETE_URL
RESCAN_URL
SCAN_UPLOAD_URL
SCAN_URL
SEARCH_URL

Public Class Methods

behaviour(api_key, hash) click to toggle source

Requests a behavioural report on a hash.

@param api_key Virustotal.com API key @param hash MD5/sha1/sha256 to query

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 135
def self.behaviour(api_key, hash)
        if hash == nil
                raise "Invalid hash, must be md5/sha1/sha256"
        end

        params = {
                apikey: api_key,
                hash: hash
        }
        Uirusu.query_api BEHAVIOUR_URL, params
end
clusters(api_key, date) click to toggle source

Access the clustering section of VT Intelligence.

@param api_key Virustotal.com API key @param date A specific day for which we want to access the clustering details, example: 2013-09-10

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 190
def self.clusters(api_key, date)
        if date == nil
                raise "Please enter a valid date (Ex: 2013-09-10)"
        end

        params = {
                apikey: api_key,
                date: date
        }
        Uirusu.query_api CLUSTERS_URL, params
end
download(api_key, hash) click to toggle source

Download a file from vT's store given a hash.

@param api_key Virustotal.com API key @param hash The md5/sha1/sha256 of the file you want to download

@return [File] the downloaded file

# File lib/uirusu/vtfile.rb, line 208
def self.download(api_key, hash)
        if hash == nil
                raise "Please enter a valid md5/sha1/sha256 hash"
        end

        params = {
                apikey: api_key,
                hash: hash
        }
        Uirusu.query_api DOWNLOAD_URL, params
end
false_positives(api_key, limit=100) click to toggle source

Allows vendors to consume false positive notifications for files that they mistakenly detect.

@param api_key Virustotal.com API key @param limit The number of false positive notifications to consume, if available. The max value is 1000.

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 236
def self.false_positives(api_key, limit=100)
        raise "#false_positives not yet implemented. This API is only available to antivirus vendors participating in VirusTotal."
end
feed(api_key, package) click to toggle source

Retrieve a live feed of all uploaded files to VT.

@param api_key Virustotal.com API key @param package Indicates a time window to pull reports on all items received during such window. Only per-minute and hourly windows are allowed, the format is %Y%m%dT%H%M (e.g. 20160304T0900) or %Y%m%dT%H (e.g. 20160304T09). Time is expressed in UTC.

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 226
def self.feed(api_key, package)
        raise "#false_positives not yet implemented. This API call is only available to users that have licensed the unlimited tier of VirusTotal private Mass API."
end
network_traffic(api_key, hash) click to toggle source

Requests a network traffic report on a hash.

@param api_key Virustotal.com API key @param hash MD5/sha1/sha256 to query

@return [PCAP] A PCAP file containing the network traffic dump

# File lib/uirusu/vtfile.rb, line 153
def self.network_traffic(api_key, hash)
        if hash == nil
                raise "Invalid hash, must be md5/sha1/sha256"
        end

        params = {
                apikey: api_key,
                hash: hash
        }
        Uirusu.query_api NETWORK_TRAFFIC_URL, params
end
query_report(api_key, resource, **args) click to toggle source

Queries a report from Virustotal.com

@param api_key Virustotal.com API key @param resource MD5/sha1/sha256/scan_id to search for @params **args named arguments for optional parameters - www.virustotal.com/en/documentation/private-api/#get-report

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 47
def VTFile.query_report(api_key, resource, **args)
        if resource == nil
                raise "Invalid resource, must be md5/sha1/sha256/scan_id"
        end

        params = {
                apikey: api_key,
                resource: resource
        }
        Uirusu.query_api REPORT_URL, params.merge!(args), true
end
rescan_delete(api_key, resource) click to toggle source

Deletes a scheduled rescan request.

@param api_key Virustotal.com API key @param resource MD5/sha1/sha256/scan_id to rescan

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 116
def self.rescan_delete(api_key, resource)
        if resource == nil
                raise "Invalid resource, must be md5/sha1/sha256/scan_id"
        end

        params = {
                apikey: api_key,
                resource: resource
        }

        Uirusu.query_api RESCAN_DELETE_URL, params, true
end
rescan_file(api_key, resource, **args) click to toggle source

Requests an existing file to be rescanned.

@param api_key Virustotal.com API key @param resource MD5/sha1/sha256/scan_id to rescan @params **args named arguments for optional parameters - www.virustotal.com/en/documentation/private-api/#rescan

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 98
def self.rescan_file(api_key, resource, **args)
        if resource == nil
                raise "Invalid resource, must be md5/sha1/sha256/scan_id"
        end

        params = {
                apikey: api_key,
                resource: resource
        }
        Uirusu.query_api RESCAN_URL, params.merge!(args), true
end
scan_file(api_key, path_to_file, **args) click to toggle source

Submits a file to Virustotal.com for analysis

@param api_key Virustotal.com API key @param path_to_file Path to file on disk to upload @params **args named arguments for optional parameters - www.virustotal.com/en/documentation/private-api/#scan

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 66
def self.scan_file(api_key, path_to_file, **args)
        if !File.exist?(path_to_file)
                raise Errno::ENOENT
        end

        params = {
                apikey: api_key,
                filename: path_to_file,
                file: File.new(path_to_file, 'rb')
        }
        Uirusu.query_api SCAN_URL, params.merge!(args), true
end
scan_upload_url(api_key) click to toggle source

Retrieves a custom upload URL for files larger than 32MB

@param api_key Virustotal.com API key

@return [JSON] Parsed response

# File lib/uirusu/vtfile.rb, line 84
def self.scan_upload_url(api_key)
        params = {
                apikey: api_key
        }
        Uirusu.query_api SCAN_UPLOAD_URL, params
end