virustotal_api 0.4.0 → 0.5.3

data/lib/virustotal_api/base.rb

@@ -3,22 +3,50 @@
 require 'virustotal_api/exceptions'
 require 'rest-client'
 require 'json'
+require 'base64'
 
+# The base VirustotalAPI module.
 module VirustotalAPI
+  # The base class implementing the raw calls to Virustotal API V3.
   class Base
+    attr_reader :report, :report_url, :id
+
+    def initialize(report)
+      @report = report
+      @report_url = report&.dig('data', 'links', 'self')
+      @id = report&.dig('data', 'id')
+    end
+
     # @return [String] string of API URI class method
     def self.api_uri
       VirustotalAPI::URI
     end
 
-    # @param [RestClient::Response] response
-    # @return [Hash] the parsed JSON.
-    def self.parse(response)
-      if response.code == 204
-        raise(RateLimitError, 'maximum number of 4 requests per minute reached')
-      end
-
+    # The actual method performing a call to Virustotal
+    #
+    # @param [String] url The url of the API
+    # @param [String] api_key The key for virustotal
+    # @param [String] method The HTTP method to use
+    # @param [Hash] options Options to pass as payload
+    # @return [VirustotalAPI::Domain] Report Search Result
+    def self.perform(url, api_key, method = :get, options = {})
+      response = RestClient::Request.execute(
+        method: method,
+        url: api_uri + url,
+        headers: { 'x-apikey': api_key },
+        payload: options
+      )
       JSON.parse(response.body)
+    rescue RestClient::NotFound
+      {}
+    rescue RestClient::Unauthorized
+      # Raise a custom exception not to expose the underlying
+      # HTTP client.
+      raise VirustotalAPI::Unauthorized
+    rescue RestClient::TooManyRequests
+      # Raise a custom exception not to expose the underlying
+      # HTTP client.
+      raise VirustotalAPI::RateLimitError
     end
 
     # @return [String] string of API URI instance method
@@ -27,11 +55,14 @@ module VirustotalAPI
     end
 
     # @return [Boolean] if report for resource exists
-    # 0 => not_present, 1 => exists, -1 => invalid_ip_address
     def exists?
-      response_code = report.fetch('response_code') { nil }
+      !report.empty?
+    end
 
-      response_code == 1
+    # Generate a URL identifier.
+    # @see https://developers.virustotal.com/v3.0/reference#url
+    def self.url_identifier(url)
+      Base64.encode64(url).strip.gsub('=', '')
     end
   end
 end

data/lib/virustotal_api/domain.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module VirustotalAPI
+  # A class for '/domains' API
+  class Domain < Base
+    # Find a domain.
+    #
+    # @param [String] domain The domain to search
+    # @param [String] api_key for virustotal
+    # @return [VirustotalAPI::Domain] Report Search Result
+    def self.find(domain, api_key)
+      report = perform("/domains/#{domain}", api_key)
+      new(report)
+    end
+  end
+end

data/lib/virustotal_api/exceptions.rb

@@ -3,4 +3,7 @@
 module VirustotalAPI
   class RateLimitError < RuntimeError
   end
+
+  class Unauthorized < RuntimeError
+  end
 end

data/lib/virustotal_api/file.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module VirustotalAPI
+  # A class for '/files' API
+  class File < Base
+    # Find a hash.
+    #
+    # @param [String] resource file as a md5/sha1/sha256 hash
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::File] Report Search Result
+    def self.find(resource, api_key)
+      report = perform("/files/#{resource}", api_key)
+      new(report)
+    end
+
+    # Upload a new file.
+    #
+    # @param [String] file_path for file to be sent for scan
+    # @param [String] api_key The key for virustotal
+    # @param [Hash] opts hash for additional options
+    # @return [VirusotalAPI::File] Report
+    def self.upload(file_path, api_key, opts = {})
+      filename = opts.fetch('filename') { ::File.basename(file_path) }
+      report = perform('/files', api_key, :post, filename: filename, file: ::File.open(file_path, 'r'))
+      new(report)
+    end
+
+    # Analyse a hash again.
+    #
+    # @param [String] resource file as a md5/sha1/sha256 hash
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::File] Report
+    def self.analyse(resource, api_key)
+      report = perform("/files/#{resource}/analyse", api_key, :post)
+      new(report)
+    end
+
+    # Check if the submitted hash is detected by an AV engine.
+    #
+    # @param [String] engine The engine to check.
+    # @return [Boolean] true if detected
+    def detected_by(engine)
+      report&.dig('data', 'attributes', 'last_analysis_results', engine, 'category') == 'malicious'
+    end
+  end
+end

data/lib/virustotal_api/group.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module VirustotalAPI
+  # A class for '/groups' API
+  class Group < Base
+    # Find a Group.
+    #
+    # @param [String] group_id to find
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::User] Report
+    def self.find(group_id, api_key)
+      report = perform("/groups/#{group_id}", api_key)
+      new(report)
+    end
+  end
+end

data/lib/virustotal_api/ip.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module VirustotalAPI
+  # A class for '/ip_addresses' API
+  class IP < Base
+    # Find an IP.
+    #
+    # @param [String] ip address The IP to find.
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::IPReport] Report
+    def self.find(ip, api_key)
+      report = perform("/ip_addresses/#{ip}", api_key)
+      new(report)
+    end
+  end
+end

data/lib/virustotal_api/uri.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module VirustotalAPI
-  URI = 'https://www.virustotal.com/vtapi/v2'
+  # The API base URI
+  URI = 'https://www.virustotal.com/api/v3'
 end

data/lib/virustotal_api/url.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module VirustotalAPI
+  # A class for '/urls' API
+  class URL < Base
+    # Find a URL.
+    #
+    # @param [String] resource as an ip/domain/url
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::URL] Report
+    def self.find(resource, api_key)
+      report = perform("/urls/#{url_identifier(resource)}", api_key)
+      new(report)
+    end
+
+    # Analyse a URL again.
+    #
+    # @param [String] resource as an ip/domain/url
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::URL] Report
+    def self.analyse(resource, api_key)
+      report = perform("/urls/#{url_identifier(resource)}/analyse", api_key, :post)
+      new(report)
+    end
+
+    # Upload a URL for detection.
+    #
+    # @param [String] resource as an ip/domain/url
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::URL] Report
+    def self.upload(resource, api_key)
+      report = perform('/urls', api_key, :post, url: resource)
+      new(report)
+    end
+  end
+end

data/lib/virustotal_api/user.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module VirustotalAPI
+  # A class for '/users' API
+  class User < Base
+    # Find a User.
+    #
+    # @param [String] user_key with id or api_key
+    # @param [String] api_key The key for virustotal
+    # @return [VirustotalAPI::User] Report
+    def self.find(user_key, api_key)
+      report = perform("/users/#{user_key}", api_key)
+      new(report)
+    end
+  end
+end

data/lib/virustotal_api/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module VirustotalAPI
-  VERSION = '0.4.0'
+  # The GEM version
+  VERSION = '0.5.3'
 end

data/test/analysis_test.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require './test/test_helper'
+
+class VirustotalAPIAnalysisTest < Minitest::Test
+  def setup
+    @url     = 'http://www.google.com'
+    @api_key = 'theapikey'
+  end
+
+  def test_todo
+    VCR.use_cassette('url_find') do
+      vtreport = VirustotalAPI::URL.find(@url, @api_key)
+
+      @id = vtreport.id
+      assert @id.is_a?(String)
+    end
+
+    VCR.use_cassette('analysis') do
+      analysis = VirustotalAPI::Analysis.find(@id, @api_key)
+
+      assert analysis.exists?
+      assert analysis.id.is_a?(String)
+    end
+  end
+end

data/test/base_test.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# rubocop:disable LineLength
 require './test/test_helper'
 
 class VirustotalAPIBaseTest < Minitest::Test
@@ -15,45 +14,34 @@ class VirustotalAPIBaseTest < Minitest::Test
 
   # Instance Method
   def test_api_uri_instance_method
-    base_uri = 'https://www.virustotal.com/vtapi/v2'
-    vt_base = VirustotalAPI::Base.new
+    base_uri = 'https://www.virustotal.com/api/v3'
+    vt_base = VirustotalAPI::Base.new(nil)
 
     assert vt_base.api_uri.is_a?(String)
-    assert vt_base.api_uri, base_uri
+    assert_equal base_uri, vt_base.api_uri
   end
 
   # Class Method
   def test_api_uri_class_method
-    base_uri = 'https://www.virustotal.com/vtapi/v2'
+    base_uri = 'https://www.virustotal.com/api/v3'
 
     assert VirustotalAPI::Base.api_uri.is_a?(String)
-    assert VirustotalAPI::Base.api_uri, base_uri
+    assert_equal base_uri, VirustotalAPI::Base.api_uri
   end
 
-  def test_parse_code_200
-    mock_response200 = Minitest::Mock.new
-    mock_response200.expect(:code, 200)
-    mock_response200.expect(:body, '{}')
-
-    assert VirustotalAPI::Base.parse(mock_response200), {}
-  end
-
-  def test_parse_code_204
-    mock_response204 = Minitest::Mock.new
-    mock_response204.expect(:code, 204)
-    mock_response204.expect(:body, '{}')
+  def test_exists?
+    VCR.use_cassette('file_find') do
+      virustotal_report = VirustotalAPI::File.find(@sha256, @api_key)
 
-    assert_raises VirustotalAPI::RateLimitError do
-      VirustotalAPI::Base.parse(mock_response204)
+      assert virustotal_report.exists?
     end
   end
 
-  # Test using FileReport
-  def test_exists?
-    VCR.use_cassette('report') do
-      virustotal_report = VirustotalAPI::FileReport.find(@sha256, @api_key)
+  def test_not_exists?
+    VCR.use_cassette('file_not_found') do
+      virustotal_report = VirustotalAPI::File.find(@sha256, @api_key)
 
-      assert virustotal_report.exists?, true
+      assert !virustotal_report.exists?
     end
   end
 end

data/test/domain_test.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require './test/test_helper'
+
+class VirustotalAPIDomainTest < Minitest::Test
+  def setup
+    @domain  = 'virustotal.com'
+    @api_key = 'testapikey'
+  end
+
+  def test_class_exists
+    assert VirustotalAPI::Domain
+  end
+
+  def test_report_response
+    VCR.use_cassette('domain') do
+      vtdomain_report = VirustotalAPI::Domain.find(@domain, @api_key)
+
+      # Make sure that the JSON was parsed
+      assert vtdomain_report.exists?
+      assert vtdomain_report.is_a?(VirustotalAPI::Domain)
+      assert vtdomain_report.report.is_a?(Hash)
+      assert vtdomain_report.id.is_a?(String)
+      assert vtdomain_report.report_url.is_a?(String)
+    end
+  end
+end

data/test/exceptions_test.rb

@@ -3,7 +3,29 @@
 require './test/test_helper'
 
 class RateLimitErrorTest < Minitest::Test
+  def setup
+    @sha256 = '01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b'
+    @api_key = 'testapikey'
+  end
+
   def test_class_exists
     assert VirustotalAPI::RateLimitError
+    assert VirustotalAPI::Unauthorized
+  end
+
+  def test_unauthorized
+    VCR.use_cassette('file_unauthorized') do
+      assert_raises VirustotalAPI::Unauthorized do
+        VirustotalAPI::File.find(@sha256, @api_key)
+      end
+    end
+  end
+
+  def test_rate_limit
+    VCR.use_cassette('file_rate_limit') do
+      assert_raises VirustotalAPI::RateLimitError do
+        VirustotalAPI::File.analyse(@sha256, @api_key)
+      end
+    end
   end
 end

data/test/file_test.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require './test/test_helper'
+
+class VirustotalAPIFileTest < Minitest::Test
+  def setup
+    @sha256    = '01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b'
+    @file_path = File.expand_path('test/fixtures/null_file')
+    @api_key   = 'testapikey'
+  end
+
+  def test_class_exists
+    assert VirustotalAPI::File
+  end
+
+  def test_report_response
+    VCR.use_cassette('file_find') do
+      vt_file_report = VirustotalAPI::File.find(@sha256, @api_key)
+
+      # Make sure that the JSON was parsed
+      assert vt_file_report.exists?
+      assert vt_file_report.is_a?(VirustotalAPI::File)
+      assert vt_file_report.report.is_a?(Hash)
+      assert vt_file_report.id.is_a?(String)
+      assert vt_file_report.report_url.is_a?(String)
+    end
+  end
+
+  def test_find
+    id        = '01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b'
+    permalink = "https://www.virustotal.com/api/v3/files/#{id}"
+
+    VCR.use_cassette('file_find') do
+      vt_file_report = VirustotalAPI::File.find(@sha256, @api_key)
+
+      assert_equal permalink, vt_file_report.report_url
+      assert_equal id, vt_file_report.id
+      assert vt_file_report.detected_by('Avira')
+      assert !vt_file_report.detected_by('Acronis')
+      assert !vt_file_report.detected_by('Yeyeyeye') # not present in file
+    end
+  end
+
+  def test_upload
+    VCR.use_cassette('file_upload') do
+      vt_file_upload = VirustotalAPI::File.upload(@file_path, @api_key)
+
+      assert vt_file_upload.exists?
+      assert vt_file_upload.report.is_a?(Hash)
+      assert vt_file_upload.id.is_a?(String)
+    end
+  end
+
+  def test_analyse
+    VCR.use_cassette('file_analyse') do
+      vt_file_analyse = VirustotalAPI::File.analyse(@sha256, @api_key)
+
+      assert vt_file_analyse.exists?
+      assert vt_file_analyse.report.is_a?(Hash)
+      assert vt_file_analyse.id.is_a?(String)
+    end
+  end
+end