uirusu 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8fba998a37e7972030ea7e2e963634c191d1e0e0
-  data.tar.gz: 2271e8d73ccf95edba19e4248a0f92d317c07234
+  metadata.gz: 0d8bd0db705cc4042aab3420b2cfca3d78485313
+  data.tar.gz: f4650d576d718833039845d83eb5ccebc4a7ef46
 SHA512:
-  metadata.gz: f7d43fe9f146334af62dfa4cc425fb9401af52645b4c5baab6b641f24b9c03944ceb38ace7e1d8739333421a09dd3a3474d430efec8e4917b5d51bf38db7e42b
-  data.tar.gz: dfd744984a492dd2103eca9f2474da73a716a9f4a4d5f335ac2a2cf4709e5767da855aa1a5ca9f4433660f164f5193ecbac1479fdfaf6d52f3588c6ce2738c5d
+  metadata.gz: 89be7b9bd3c0908e4f195dc1c2cbb47d87424b5e21000fc5fbe3859c87dbcd95e621aa70276f731112903216c401e23c96a67a034f94c735a29a759bf140034d
+  data.tar.gz: 8c73cd4a596243fa5d0a2ed40378d9bca99df2bf29dbe2708336915f7d571a2138154db0ddee6a44489bae7ceab54d1633751d7fd7a5c99676416191c842e95b

data/README.markdown

@@ -2,7 +2,7 @@
 
 uirusu is an [Virustotal](http://www.virustotal.com) automation and convenience tool for hash, file and URL submission.
 
-The current version is 1.0.1.
+The current version is 1.0.2.
 
 ## Requirements
 
@@ -77,6 +77,45 @@ 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](https://www.virustotal.com/en/documentation/private-api)
+* 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
+
+#### Examples
+Below are some examples specific to the private API.
+
+##### Files
+```ruby
+# 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
+Uirusu::VTFile.scan_upload_url(API_KEY)
+
+# 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
+```ruby
+
+# 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.
 

data/docs/NEWS.markdown

@@ -1,5 +1,8 @@
 # News
 
+# 1.0.2 (September 21, 2016)
+- Added Private API support [@joshporter1]
+
 # 1.0.1 (July 1, 2016)
 - Fixed email address
 - Changed License to MIT

data/lib/uirusu.rb

@@ -22,6 +22,57 @@ module Uirusu
 	CONFIG_FILE = "#{Dir.home}/.uirusu"
 	VT_API = "https://www.virustotal.com/vtapi/v2"
 	RESULT_FIELDS = [ :hash, :scanner, :version, :detected, :result, :md5, :sha1, :sha256, :update, :permalink ]
+
+	protected
+	# Queries the API using RestClient and parses the response.
+	#
+	# @param url [string] URL endpoint to send the request to
+	# @param params [hash] Hash of HTTP params
+	# @param post [boolean] (optional) Specifies whether to use POST or GET
+	#
+	# @return [JSON] Parsed response
+	def self.query_api(url, params, post=false)
+		if params[:apikey] == nil
+			raise "Invalid API Key"
+		end
+
+		begin
+			if post
+				response = RestClient.post url, **params
+			else
+				response = RestClient.get url, params: params
+			end
+		rescue => e
+			response = e.response
+		end
+		self.parse_response response
+	end
+
+	# Parses the response or raises an exception accordingly.
+	#
+	# @param response The response from RestClient
+	#
+	# @return [JSON] Parsed response
+	def self.parse_response(response)
+		case response.code
+			when 429, 204
+				raise "Virustotal limit reached. Try again later."
+			when 403
+				raise "Invalid privileges, please check your API key."
+			when 200
+				# attempt to parse it as json, otherwise return the raw response
+				# network_traffic and download return non-JSON data
+				begin
+					JSON.parse(response)
+				rescue
+					response
+				end
+			when 500
+				nil
+			else
+				raise "Unknown Server error. (#{response.code})"
+		end
+	end
 end
 
 require 'json'
@@ -32,6 +83,8 @@ require 'yaml'
 require 'uirusu/version'
 require 'uirusu/vtfile'
 require 'uirusu/vturl'
+require 'uirusu/vtipaddr'
+require 'uirusu/vtdomain'
 require 'uirusu/vtcomment'
 require 'uirusu/vtresult'
 require 'uirusu/scanner'

data/lib/uirusu/version.rb

@@ -20,7 +20,7 @@
 
 module Uirusu
 	APP_NAME = "uirusu"
-	VERSION = "1.0.1"
+	VERSION = "1.0.2"
 	HOME_PAGE = "http://arxopia.github.io/uirusu"
 	AUTHOR = "Jacob Hammack"
 	EMAIL = "jacob.hammack@arxopia.com"

data/lib/uirusu/vtcomment.rb

@@ -23,6 +23,7 @@ module Uirusu
 	# Virustotal.com public API
 	module VTComment
 		POST_URL = Uirusu::VT_API + "/comments/put"
+		GET_URL = Uirusu::VT_API + "/comments/get"
 
 		# Submits a comment to Virustotal.com for a specific resource
 		#
@@ -32,10 +33,6 @@ module Uirusu
 		#
 		# @return [JSON] Parsed response
 		def self.post_comment(api_key, resource, comment)
-			if api_key == nil
-				raise "Invalid API Key"
-			end
-
 			if resource == nil
 				raise "Invalid resource, must be a valid url"
 			end
@@ -44,18 +41,32 @@ module Uirusu
 				raise "You must provide a comment to submit."
 			end
 
-			response = RestClient.post POST_URL, :apikey => api_key, :resource => resource, :comment => comment
+			params = {
+				apikey: api_key,
+				resource: resource,
+				comment: comment
+			}
+			Uirusu.query_api POST_URL, params
+		end
 
-			case response.code
-				when 429, 204
-					raise "Virustotal limit reached. Try again later."
-				when 403
-					raise "Invalid privileges, please check your API key."
-				when 200
-					JSON.parse(response)
-				else
-					raise "Unknown Server error."
+		# Retrieve a list of comments to Virustotal.com for a specific resource
+		#
+		# @param [String] api_key Virustotal.com API key
+		# @param [String] resource MD5/sha1/sha256/scan_id/URL to search for
+		# @param [DateTime] before A datetime token that allows you to iterate over all comments on a specific item whenever it has been commented on more than 25 times
+		#
+		# @return [JSON] Parsed response
+		def self.get_comments(api_key, resource, before=nil)
+			if resource == nil
+				raise "Invalid resource, must be a valid url"
 			end
+
+			params = {
+				apikey: api_key,
+				resource: resource
+			}
+			params[:before] = before unless before.nil?
+			Uirusu.query_api GET_URL, params
 		end
 	end
 end

data/lib/uirusu/vtdomain.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2010-2016 Arxopia LLC.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Uirusu
+	#
+	#
+	module VTDomain
+		REPORT_URL = Uirusu::VT_API + "/domain/report"
+
+		# Searches reports by Domain from Virustotal.com
+		#
+		# @param api_key Virustotal.com API key
+		# @param domain domain name to search
+		#
+		# @return [JSON] Parsed response
+		def self.query_report(api_key, domain)
+			if domain == nil
+				raise "Invalid resource, must be a valid domain"
+			end
+
+			params = {
+				apikey: api_key,
+				domain: domain
+			}
+			Uirusu.query_api REPORT_URL, params
+		end
+	end
+end

data/lib/uirusu/vtfile.rb

@@ -23,99 +23,219 @@ module Uirusu
 	# Module for Accessing the File scan and report functionalities of the
 	# Virustotal.com public API
 	module VTFile
-		SCAN_URL   = Uirusu::VT_API + "/file/scan"
-		RESCAN_URL = Uirusu::VT_API + "/file/rescan"
-		REPORT_URL = Uirusu::VT_API + "/file/report"
+        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             = Uirusu::VT_API + "/file/feed" #not implemented
+		FALSE_POSITIVES_URL  = Uirusu::VT_API + "/file/false-positives" #not implemented
+
 
 		# 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 - https://www.virustotal.com/en/documentation/private-api/#get-report
 		#
 		# @return [JSON] Parsed response
-		def VTFile.query_report(api_key, resource)
-			if api_key == nil
-				raise "Invalid API Key"
+		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)
+		end
+
+        # 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 - https://www.virustotal.com/en/documentation/private-api/#scan
+        #
+        # @return [JSON] Parsed response
+        def self.scan_file(api_key, path_to_file, **args)
+            if !File.exists?(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
+
+		# Retrieves a custom upload URL for files larger than 32MB
+		#
+		# @param api_key Virustotal.com API key
+		#
+		# @return [JSON] Parsed response
+		def self.scan_upload_url(api_key)
+			params = { 
+				apikey: api_key
+			}
+			Uirusu.query_api SCAN_UPLOAD_URL, params
+		end
+
+        # 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 - https://www.virustotal.com/en/documentation/private-api/#rescan
+        #
+        # @return [JSON] Parsed response
+        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
+
+		# 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
+		def self.rescan_delete(api_key, resource)
 			if resource == nil
 				raise "Invalid resource, must be md5/sha1/sha256/scan_id"
 			end
 
-			response = RestClient.post REPORT_URL, :apikey => api_key, :resource => resource
-
-			case response.code
-				when 429, 204
-					raise "Virustotal limit reached. Try again later."
-				when 403
-					raise "Invalid privileges, please check your API key."
-				when 200
-					JSON.parse(response)
-				when 500
-					nil
-				else
-					raise "Unknown Server error."
-			end
+			params = { 
+				apikey: api_key,
+				resource: resource
+			}
+
+			Uirusu.query_api RESCAN_DELETE_URL, params, true
 		end
 
-		# Submits a file to Virustotal.com for analysis
+		# Requests a behavioural report on a hash.
 		#
 		# @param api_key Virustotal.com API key
-		# @param path_to_file Path to file on disk to upload
+		# @param hash MD5/sha1/sha256 to query
 		#
 		# @return [JSON] Parsed response
-		def self.scan_file(api_key, path_to_file)
-			if !File.exists?(path_to_file)
-				raise Errno::ENOENT
+		def self.behaviour(api_key, hash)
+			if hash == nil
+				raise "Invalid hash, must be md5/sha1/sha256"
 			end
 
-			if api_key == nil
-				raise "Invalid API Key"
-			end
+			params = {
+				apikey: api_key,
+				hash: hash
+			}
+			Uirusu.query_api BEHAVIOUR_URL, params
+		end
 
-			response = RestClient.post SCAN_URL, :apikey => api_key, :filename=> path_to_file, :file => File.new(path_to_file, 'rb')
-
-			case response.code
-				when 429, 204
-					raise "Virustotal limit reached. Try again later."
-				when 403
-					raise "Invalid privileges, please check your API key."
-				when 200
-					JSON.parse(response)
-				else
-					raise "Unknown Server error."
+		# 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
+		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
 
-		# Requests an existing file to be rescanned.
+		# Perform an advanced reverse search.
 		#
 		# @param api_key Virustotal.com API key
-		# @param resource MD5/sha1/sha256/scan_id to rescan
+		# @param query A search modifier compliant file search query (https://www.virustotal.com/intelligence/help/file-search/#search-modifiers)
+		# @param **args named optional arguments - https://www.virustotal.com/en/documentation/private-api/#search
 		#
 		# @return [JSON] Parsed response
-		def self.rescan_file(api_key, resource)
-			if api_key == nil
-				raise "Invalid API Key"
+		def self.search(api_key, query, **args)
+			if query == nil
+				raise "Please enter a valid query."
 			end
 
-			if resource == nil
-				raise "Invalid resource, must be md5/sha1/sha256/scan_id"
+			params = {
+				apikey: api_key,
+				query: query
+			}
+			Uirusu.query_api SEARCH_URL, params.merge!(args)
+		end
+
+		# 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
+		def self.clusters(api_key, date)
+			if date == nil
+				raise "Please enter a valid date (Ex: 2013-09-10)"
 			end
 
-			response = RestClient.post RESCAN_URL, :apikey => api_key, :resource => resource
-
-			case response.code
-				when 429, 204
-					raise "Virustotal limit reached. Try again later."
-				when 403
-					raise "Invalid privileges, please check your API key."
-				when 200
-					JSON.parse(response)
-				when 500
-					nil
-				else
-					raise "Unknown Server error."
+			params = {
+				apikey: api_key,
+				date: date
+			}
+			Uirusu.query_api CLUSTERS_URL, params
+		end
+
+		# 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
+		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
+
+		# 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
+		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
+
+		# 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
+		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	
 	end
 end

data/lib/uirusu/vtipaddr.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2010-2016 Arxopia LLC.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Uirusu
+	#
+	#
+	module VTIPAddr
+		REPORT_URL = Uirusu::VT_API + "/ip-address/report"
+
+		# Searches reports by IP from Virustotal.com
+		#
+		# @param api_key Virustotal.com API key
+		# @param ip IP address to search
+		#
+		# @return [JSON] Parsed response
+		def self.query_report(api_key, ip)
+			if ip == nil
+				raise "Invalid resource, must be a valid IPv4 address"
+			end
+
+			params = {
+				apikey: api_key,
+				ip: ip
+			}
+			Uirusu.query_api REPORT_URL, params
+		end
+	end
+end

data/lib/uirusu/vturl.rb

@@ -32,26 +32,15 @@ module Uirusu
 		#
 		# @return [JSON] Parsed response
 		def self.scan_url(api_key, resource)
-			if api_key == nil
-				raise "Invalid API Key"
-			end
-
 			if resource == nil
 				raise "Invalid resource, must be a valid url"
 			end
 
-			response = RestClient.post SCAN_URL, :apikey => api_key, :url => resource
-
-			case response.code
-				when 429, 204
-					raise "Virustotal limit reached. Try again later."
-				when 403
-					raise "Invalid privileges, please check your API key."
-				when 200
-					JSON.parse(response)
-				else
-					raise "Unknown Server error."
-			end
+			params = {
+				apikey: api_key,
+				resource: resource
+			}
+			Uirusu.query_api SCAN_URL, params
 		end
 
 		# Searches reports by URL from Virustotal.com
@@ -60,27 +49,26 @@ module Uirusu
 		# @param resource url to search
 		#
 		# @return [JSON] Parsed response
-		def self.query_report(api_key, resource)
-			if api_key == nil
-				raise "Invalid API Key"
-			end
-
+		def self.query_report(api_key, resource, **args)
 			if resource == nil
 				raise "Invalid resource, must be a valid url"
 			end
 
-			response = RestClient.post REPORT_URL, :apikey => api_key, :resource => resource
+			params = {
+				apikey: api_key,
+				resource: resource
+			}
+			Uirusu.query_api REPORT_URL, params.merge!(args)
+		end
 
-			case response.code
-				when 429, 204
-					raise "Virustotal limit reached. Try again later."
-				when 403
-					raise "Invalid privileges, please check your API key."
-				when 200
-					JSON.parse(response)
-				else
-					raise "Unknown Server error."
-			end
+		# Searches reports by URL from Virustotal.com
+		#
+		# @param api_key Virustotal.com API key
+		# @param resource url to search
+		#
+		# @return [JSON] Parsed response
+		def self.feed(api_key, resource, **args)
+			raise "#feed not yet implemented. This API call is only available to users that have licensed the unlimited tier of VirusTotal private Mass API."
 		end
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uirusu
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Jacob Hammack
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-02 00:00:00.000000000 Z
+date: 2016-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -154,7 +154,9 @@ files:
 - lib/uirusu/scanner.rb
 - lib/uirusu/version.rb
 - lib/uirusu/vtcomment.rb
+- lib/uirusu/vtdomain.rb
 - lib/uirusu/vtfile.rb
+- lib/uirusu/vtipaddr.rb
 - lib/uirusu/vtresult.rb
 - lib/uirusu/vturl.rb
 - uirusu.gemspec