virustotal_api_compat 0.1.7

data/lib/virustotal_api/base.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+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
+
+    def self.perform(path, api_key, method = :get, options = {})
+      base_perform(api_uri + path, api_key, method, options)
+    end
+
+    def self.perform_absolute(url, api_key, method = :get, options = {})
+      base_perform(url, api_key, method, options)
+    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.base_perform(url, api_key, method = :get, options = {})
+      response = RestClient::Request.execute(
+        method: method,
+        url: url,
+        headers: { 'x-apikey': api_key },
+        payload: options
+      )
+      JSON.parse(response.body)
+    rescue RestClient::NotFound, RestClient::BadRequest
+      {}
+    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
+
+    private_class_method :base_perform
+
+    # @return [String] string of API URI instance method
+    def api_uri
+      self.class.api_uri
+    end
+
+    # @return [Boolean] if report for resource exists
+    def exists?
+      !report.empty?
+    end
+
+    # Generate a URL identifier.
+    # @see https://developers.virustotal.com/v3.0/reference#url
+    def self.url_identifier(url)
+      Base64.urlsafe_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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module VirustotalAPI
+  class RateLimitError < RuntimeError
+  end
+
+  class Unauthorized < RuntimeError
+  end
+end

data/lib/virustotal_api/file.rb

@@ -0,0 +1,67 @@
+# 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
+
+    # Upload a new file with size more than 32MB.
+    #
+    # @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_large(file_path, api_key, opts = {})
+      filename = opts.fetch('filename') { ::File.basename(file_path) }
+      url      = upload_url(api_key)
+      report   = perform_absolute(url, 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
+
+    # @return [String] url for upload file
+    def self.upload_url(api_key)
+      data = perform('/files/upload_url', api_key)
+      data&.dig('data')
+    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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module VirustotalAPI
+  # 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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module VirustotalAPI
+  # The GEM version
+  VERSION = '0.1.7'
+end

data/lib/virustotal_api.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'virustotal_api/analysis'
+require 'virustotal_api/domain'
+require 'virustotal_api/file'
+require 'virustotal_api/group'
+require 'virustotal_api/ip'
+require 'virustotal_api/url'
+require 'virustotal_api/uri'
+require 'virustotal_api/user'
+require 'virustotal_api/version'

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require './test/test_helper'
+
+class VirustotalAPIBaseTest < Minitest::Test
+  def setup
+    @domain  = 'xpressco.za'
+    @sha256  = '01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b'
+    @url     = 'https://www.dropbox.com/s/qmi112rc4ns75eb/Confidential_123.xls?dl=1'
+    @api_key = 'testapikey'
+  end
+
+  def test_class_exists
+    assert VirustotalAPI::Base
+  end
+
+  # Instance Method
+  def test_api_uri_instance_method
+    base_uri = 'https://www.virustotal.com/api/v3'
+    vt_base = VirustotalAPI::Base.new(nil)
+
+    assert vt_base.api_uri.is_a?(String)
+    assert_equal base_uri, vt_base.api_uri
+  end
+
+  # Class Method
+  def test_api_uri_class_method
+    base_uri = 'https://www.virustotal.com/api/v3'
+
+    assert VirustotalAPI::Base.api_uri.is_a?(String)
+    assert_equal base_uri, VirustotalAPI::Base.api_uri
+  end
+
+  def test_exists?
+    VCR.use_cassette('file_find') do
+      virustotal_report = VirustotalAPI::File.find(@sha256, @api_key)
+
+      assert virustotal_report.exists?
+    end
+  end
+
+  def test_not_exists?
+    VCR.use_cassette('file_not_found') do
+      virustotal_report = VirustotalAPI::File.find(@sha256, @api_key)
+
+      assert !virustotal_report.exists?
+    end
+
+    VCR.use_cassette('domain_bad_request') do
+      virustotal_report = VirustotalAPI::Domain.find(@domain, @api_key)
+
+      assert !virustotal_report.exists?
+    end
+  end
+
+  def test_url_encoding
+    VCR.use_cassette('url_encoding_find') do
+      virustotal_report = VirustotalAPI::URL.find(@url, @api_key)
+
+      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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+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,73 @@
+# 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_upload_large
+    VCR.use_cassette('large_file_upload') do
+      vt_file_upload = VirustotalAPI::File.upload_large(@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