Module: Uirusu::VTFile

Defined in:
lib/uirusu/vtfile.rb

Overview

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

Constant Summary collapse

SCAN_URL = 
Uirusu::VT_API + "/file/scan"
SCAN_UPLOAD_URL = 
Uirusu::VT_API + "/file/scan/upload_url"
RESCAN_URL = 
Uirusu::VT_API + "/file/rescan"
RESCAN_DELETE_URL = 
Uirusu::VT_API + "/file/rescan/delete"
REPORT_URL = 
Uirusu::VT_API + "/file/report"
BEHAVIOUR_URL = 
Uirusu::VT_API + "/file/behaviour"
NETWORK_TRAFFIC_URL = 
Uirusu::VT_API + "/file/network-traffic"
SEARCH_URL = 
Uirusu::VT_API + "/file/search"
CLUSTERS_URL = 
Uirusu::VT_API + "/file/clusters"
DOWNLOAD_URL = 
Uirusu::VT_API + "/file/download"
FEED_URL =

not implemented

Uirusu::VT_API + "/file/feed"
FALSE_POSITIVES_URL =

not implemented

Uirusu::VT_API + "/file/false-positives"

Class Method Summary collapse

Class Method Details

.behaviour(api_key, hash) ⇒ JSON

Requests a behavioural report on a hash.

Parameters:

  • api_key —

    Virustotal.com API key

  • hash —

    MD5/sha1/sha256 to query

Returns:

  • (JSON) —

    Parsed response



135
136
137
138
139
140
141
142
143
144
145
 
# 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) ⇒ JSON

Access the clustering section of VT Intelligence.

Parameters:

  • api_key —

    Virustotal.com API key

  • date —

    A specific day for which we want to access the clustering details, example: 2013-09-10

Returns:

  • (JSON) —

    Parsed response



190
191
192
193
194
195
196
197
198
199
200
 
# 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) ⇒ File

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

Parameters:

  • api_key —

    Virustotal.com API key

  • hash —

    The md5/sha1/sha256 of the file you want to download

Returns:

  • (File) —

    the downloaded file



208
209
210
211
212
213
214
215
216
217
218
 
# 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) ⇒ JSON

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

Parameters:

  • api_key —

    Virustotal.com API key

  • limit (defaults to: 100) —

    The number of false positive notifications to consume, if available. The max value is 1000.

Returns:

  • (JSON) —

    Parsed response



236
237
238
 
# 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) ⇒ JSON

Retrieve a live feed of all uploaded files to VT.

Parameters:

  • api_key —

    Virustotal.com API key

  • 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.

Returns:

  • (JSON) —

    Parsed response



226
227
228
 
# 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) ⇒ PCAP

Requests a network traffic report on a hash.

Parameters:

  • api_key —

    Virustotal.com API key

  • hash —

    MD5/sha1/sha256 to query

Returns:

  • (PCAP) —

    A PCAP file containing the network traffic dump



153
154
155
156
157
158
159
160
161
162
163
 
# 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) ⇒ JSON

Queries a report from Virustotal.com

Parameters:

  • api_key —

    Virustotal.com API key

  • resource —

    MD5/sha1/sha256/scan_id to search for

Returns:

  • (JSON) —

    Parsed response



47
48
49
50
51
52
53
54
55
56
57
 
# 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) ⇒ JSON

Deletes a scheduled rescan request.

Parameters:

  • api_key —

    Virustotal.com API key

  • resource —

    MD5/sha1/sha256/scan_id to rescan

Returns:

  • (JSON) —

    Parsed response



116
117
118
119
120
121
122
123
124
125
126
127
 
# 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) ⇒ JSON

Requests an existing file to be rescanned.

Parameters:

  • api_key —

    Virustotal.com API key

  • resource —

    MD5/sha1/sha256/scan_id to rescan

Returns:

  • (JSON) —

    Parsed response



98
99
100
101
102
103
104
105
106
107
108
 
# 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) ⇒ JSON

Submits a file to Virustotal.com for analysis

Parameters:

  • api_key —

    Virustotal.com API key

  • path_to_file —

    Path to file on disk to upload

Returns:

  • (JSON) —

    Parsed response



66
67
68
69
70
71
72
73
74
75
76
77
 
# 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) ⇒ JSON

Retrieves a custom upload URL for files larger than 32MB

Parameters:

  • api_key —

    Virustotal.com API key

Returns:

  • (JSON) —

    Parsed response



84
85
86
87
88
89
 
# 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

.search(api_key, query, **args) ⇒ JSON

Perform an advanced reverse search.

Parameters:

Returns:

  • (JSON) —

    Parsed response



172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/uirusu/vtfile.rb', line 172

def self.search(api_key, query, **args)
	if query == nil
		raise "Please enter a valid query."
	end

	params = {
		apikey: api_key,
		query: query
	}
	Uirusu.query_api SEARCH_URL, params.merge!(args)
end