virustotalx 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18dd7bc4a5890a35b197f8ce635e736dec2507a9af5405cee5289dd7b2713ea2
-  data.tar.gz: d4d8c7ce2a065cfc287b8f376d8a15128542a7e1ad95db3f4d0000a32a721bce
+  metadata.gz: b93b0c39cdd1dbf4efdeffbe4f9ed6c30892f75a3a73172b1e5eb2db11678334
+  data.tar.gz: 38be1389296d3bd50edbf0bdb8906b83a2639a681b0b91b7a9fc1df8539a35b4
 SHA512:
-  metadata.gz: 1b2b3ca2a70c7861dcf9c04c8570134157bc0bda833bbac8e25cdc10378968e0cbf075bc80d8523537c1f8398e24f005dae4da7d26ca48d69ef874d1d0942b29
-  data.tar.gz: a6d86db493ba0045bed293681be7a7d640dbcec2c3bd795bdefd5f666b3dc7d53465b6c15d7268d82044f537c74add8a512d51449fbe06629867415029164cfc
+  metadata.gz: 86a227bded77dba22902a4531f09683cfc618c850ae178762f6ba5cd1438dbd546313bcd67f27041af3b562dcb0d1e047b570f160ad5a6db91a773b9e8aa6edc
+  data.tar.gz: 1b73b35965ee06d99b02fc5674d30ea234f5a64909a2a8a4dfb12cac6c38df8b648ada8c0aaf981338ca3e61accd267a971ddb3883a8eee0fb25f1774b387d4e

data/README.md

@@ -3,8 +3,9 @@
 [![Gem Version](https://badge.fury.io/rb/virustotalx.svg)](https://badge.fury.io/rb/virustotalx)
 [![Build Status](https://travis-ci.org/ninoseki/virustotalx.svg?branch=master)](https://travis-ci.org/ninoseki/virustotalx)
 [![Coverage Status](https://coveralls.io/repos/github/ninoseki/virustotalx/badge.svg?branch=master)](https://coveralls.io/github/ninoseki/virustotalx?branch=master)
+[![CodeFactor](https://www.codefactor.io/repository/github/ninoseki/virustotalx/badge)](https://www.codefactor.io/repository/github/ninoseki/virustotalx)
 
-Yet another VirusTotal API wrapper for Ruby
+Yet another VirusTotal API (version 3) wrapper for Ruby.
 
 ## Installation
 
@@ -19,59 +20,88 @@ require "virustotalx"
 # or
 require "virustotal"
 
-# when given nothing, it tries to load your API key from ENV["VIRUSTOTASL_API_KEY"]
+# when given nothing, it tries to load your API key from ENV["VIRUSTOAL_API_KEY"]
 api = VirusTotal::API.new
 # or you can set it manually
 api = VirusTotal::API.new(key: "YOUR_API_KEY")
 
 hash = "726a2eedb9df3d63ec1b4a7d774a799901f1a2b9"
-api.file.report(hash)
-api.file.scan("PAHT_TO_FILE")
-api.file.rescan(hash)
-api.file.upload_url
-api.file.download(hash)
-api.file.behaviour(hash)
-api.file.network_traffic(hash)
-api.file.clusters("DATETIME")
-api.file.search("resource:#{hash}")
-
-api.url.report("http://github.com")
-api.url.scan("https://github.com/ninoseki/virustotalx")
-
-api.domain.report("github.com")
-
-api.ip_address.report("1.1.1.1")
-
-# it returns nil when given a non-existing resource to #report methods
-api.domain.report("a_domain_which_does_not_exist.com")
-# => nil
-```
+api.file.get(hash)
+api.file.upload("/tmp/test.txt")
+
+api.url.get("http://github.com")
+api.url.analyse("https://github.com/ninoseki/virustotalx")
 
-See `/spec/clients` for more.
+api.domain.get("github.com")
+
+api.ip_address.get("1.1.1.1")
+```
 
 ## Supported API endpoints
 
-* [VirusTotal API reference](https://developers.virustotal.com/reference)
-
-| HTTP Method | URL                   | Public / Private | API method                                                |
-|-------------|-----------------------|------------------|-----------------------------------------------------------|
-| GET         | /file/report          | Public           | `VirusTotal::Client::File#report(resource, allinfo: nil)` |
-| POST        | /file/scan            | Public           | `VirusTotal::Client::File#scan(path)`                     |
-| GET         | /file/scan/upload_url | Private          | `VirusTotal::Client::File#upload_url`                     |
-| POST        | /file/rescan          | Public           | `VirusTotal::Client::File#rescan(resource)`               |
-| GET         | /file/download        | Private          | `VirusTotal::Client::File#download(hash)`                 |
-| GET         | /file/behaviour       | Private          | `VirusTotal::Client::File#behaviour(hash)`                |
-| GET         | /file/network-traffic | Private          | `VirusTotal::Client::File#network_traffic(hash)`          |
-| GET         | /file/feed            | Private          | N/A                                                       |
-| GET         | /file/clusters        | Private          | `VirusTotal::Client::File#clusters(date)`                 |
-| GET         | /file/search          | Private          | `VirusTotal::Client::File#search(query, offset: nil)`     |
-| GET         | /url/report           | Public           | `VirusTotal::Client::URL#report(resource, allinfo: nil)`  |
-| POST        | /url/scan             | Public           | `VirusTotal::Client::URL#scan(url)`                       |
-| GET         | /url/feed             | Private          | N/A                                                       |
-| GET         | /domain/report        | Public           | `VirusTotal::Client::Domain#report(domain)`               |
-| GET         | /ip-address/report    | Public           | `VirusTotal::Client::IPAddress(ip)`                       |
-| GET         | /comments/            | Public           | N/A                                                       |
-| POST        | /comments/put         | Public           | N/A                                                       |
+* [VirusTotal API reference](https://developers.virustotal.com/v3.0/reference#overview)
+
+### Files
+
+| HTTP Method | URL                                | API method                                                 |
+|-------------|------------------------------------|------------------------------------------------------------|
+| POST        | /files                             | api.file.upload(filepath)                                  |
+| GET         | /files/upload_url                  | api.file.upload_url                                        |
+| GET         | /files/{id}                        | api.file.get(id)                                           |
+| POST        | /files                             | api.file.upload(path)                                      |
+| POST        | /files/{id}/analyse                | api.file.analyse(id)                                       |
+| GET         | /files/{id}/comments               | api.file.comments(id)                                      |
+| POST        | /files/{id}/comments               | api.file.add_comment(id, text)                             |
+| GET         | /files/{id}/votes                  | api.file.votes(id)                                         |
+| POST        | /files/{id}/votes                  | api.file.add_vote(id, verdict)                             |
+| GET         | /files/{id}/download_url           | api.file.downbload_url(id)                                 |
+| GET         | /files/{id}/download               | api.file.download(id)                                      |
+| GET         | /files/{id}/{relationship}         | api.file.`relationship`(id) (e.g. api.file.behaviours(id)) |
+| GET         | /file_behaviours/{sandbox_id}/pcap | api.file.pcap(sandbox_id)                                  |
+
+### URLs
+
+| HTTP Method | URL                         | API method                                                     |
+|-------------|-----------------------------|----------------------------------------------------------------|
+| POST        | /urls                       | N/A                                                            |
+| GET         | /urls/{id}                  | api.url.get(id)                                                |
+| POST        | /urls/{id}/analyse          | api.url.analyse(id)                                            |
+| GET         | /urls/{id}/comments         | api.url.comments(id)                                           |
+| POST        | /urls/{id}/comments         | api.url.add_comment(id)                                        |
+| GET         | /urls/{id}/votes            | api.url.votes(id)                                              |
+| POST        | /urls/{id}/votes            | api.url.add_vote(id, text)                                     |
+| GET         | /urls/{id}/network_location | api.url.network_location(id)                                   |
+| GET         | /urls/{id}/{relationship}   | api.url.`relationship`(id) (e.g. api.url.downloaded_files(id)) |
+
+Note: you can use a URL as an id.
+
+### Domains
+
+| HTTP Method | URL                              | API method                                                   |
+|-------------|----------------------------------|--------------------------------------------------------------|
+| GET         | /domains/{domain}                | api.domain.get(domain)                                       |
+| GET         | /domains/{domain}/comments       | api.domain.comment(domain)                                   |
+| POST        | /domains/{domain}/comments       | api.domain.add_comment(domain, text)                         |
+| GET         | /domains/{domain}/{relationship} | api.domain.`relationship`(domain) (e.g. api.domain.(domain)) |
+
+### IP addresses
+
+| HTTP Method | URL                               | API method                                                                      |
+|-------------|-----------------------------------|---------------------------------------------------------------------------------|
+| GET         | /ip_addresses/{ip}                | api.ip_address.get(ip)                                                          |
+| GET         | /ip_addresses/{ip}/comments       | api.ip_address.comments(id)                                                     |
+| POST        | /ip_addresses/{ip}/comments       | api.ip_address.add_comment(id, text)                                            |
+| GET         | /ip_addresses/{ip}/{relationship} | api.ip_address.`relationship`(id) (e.g. api.ip_address.communicating_files(ip)) |
+
+### Analyses
+
+| HTTP Method | URL            | API method           |
+|-------------|----------------|----------------------|
+| GET         | /analyses/{id} | api.analysis.get(ip) |
+
+## Graphs
+
+N/A.
 
 ## License
 

data/lib/virustotal.rb

@@ -7,12 +7,13 @@ require "virustotal/errors"
 require "virustotal/api"
 
 require "virustotal/clients/base"
+require "virustotal/clients/object"
 
+require "virustotal/clients/analysis"
 require "virustotal/clients/domain"
 require "virustotal/clients/file"
 require "virustotal/clients/ip_address"
 require "virustotal/clients/url"
 
 module VirusTotal
-  class Error < StandardError; end
 end

data/lib/virustotal/api.rb

@@ -4,6 +4,7 @@ require_relative "clients/base"
 
 module VirusTotal
   class API
+    attr_reader :analysis
     attr_reader :domain
     attr_reader :file
     attr_reader :ip_address
@@ -12,6 +13,7 @@ module VirusTotal
     def initialize(key: ENV["VIRUSTOTAL_API_KEY"])
       raise ArgumentError, "No API key has been found or provided! (setup your VIRUSTOTAL_API_KEY environment varialbe)" unless key
 
+      @analysis = Client::Analysis.new(key: key)
       @domain = Client::Domain.new(key: key)
       @file = Client::File.new(key: key)
       @ip_address = Client::IPAddress.new(key: key)

data/lib/virustotal/clients/analysis.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module VirusTotal
+  module Client
+    class Analysis < Base
+      def get(id)
+        _get("/analyses/#{id}") { |json| json }
+      end
+    end
+  end
+end

data/lib/virustotal/clients/base.rb

@@ -8,8 +8,8 @@ module VirusTotal
   module Client
     class Base
       HOST = "www.virustotal.com"
-      VERSION = "v2"
-      BASE_URL = "https://#{HOST}/vtapi/#{VERSION}"
+      VERSION = "v3"
+      BASE_URL = "https://#{HOST}/api/#{VERSION}"
 
       attr_reader :key
 
@@ -24,10 +24,6 @@ module VirusTotal
         !key.nil?
       end
 
-      def default_params
-        { apikey: key }
-      end
-
       def url_for(path)
         URI(BASE_URL + path)
       end
@@ -46,58 +42,75 @@ module VirusTotal
         end
       end
 
+      def raise_error(code, message)
+        code = code.to_s.to_sym
+
+        table = {
+          "400": BadRequestError,
+          "401": AuthenticationRequiredError,
+          "403": ForbiddenError,
+          "404": NotFoundError,
+          "409": AlreadyExistsError,
+          "429": QuotaExceededError,
+          "503": TransientError,
+        }
+        raise Error, "Unsupported response code returned: #{code} - #{message}" unless table.key?(code)
+
+        klass = table[code]
+        raise klass, message
+      end
+
       def request(req)
         Net::HTTP.start(HOST, 443, https_options) do |http|
+          req["x-apikey"] = key
+
           response = http.request(req)
 
-          case response.code
-          when "200"
-            if response["Content-Type"] == "application/json"
-              yield JSON.parse(response.body)
+          code = response.code.to_i
+          body = response.body
+          json = JSON.parse(body) if response["Content-Type"].to_s.include?("application/json")
+          message = json ? json.dig("message") : body
+
+          case code
+          when 200
+            if json
+              yield json
             else
-              yield response.body
+              yield body
             end
-          when "204"
-            raise(RateLimitError, response.body)
-          when "302"
+          when 302
             yield response["Location"]
           else
-            raise(Error, "unsupported response code returned: #{response.code}")
+            raise_error code, message
           end
         end
       end
 
-      def get(path, params = {}, &block)
+      def _get(path, params = {}, &block)
         uri = url_for(path)
-        uri.query = URI.encode_www_form(params.merge(default_params))
+        uri.query = URI.encode_www_form(params)
         get = Net::HTTP::Get.new(uri)
 
         request(get, &block)
       end
 
-      def post(path, params = {}, &block)
+      def _post(path, params = {}, &block)
         post = Net::HTTP::Post.new(url_for(path))
-        post.set_form_data params.merge(default_params)
+        post.body = JSON.generate(params)
 
         request(post, &block)
       end
 
-      def post_with_file(path, file:, filename:, &block)
+      def _post_with_file(path, file:, filename:, &block)
         post = Net::HTTP::Post.new(url_for(path))
 
         data = [
           ["file", file, { "filename": filename }],
-          ["apikey", key]
         ]
         post.set_form(data, "multipart/form-data")
 
         request(post, &block)
       end
-
-      def handle_response_code(json)
-        response_code = json.dig("response_code").to_i
-        response_code.zero? ? nil : json
-      end
     end
   end
 end

data/lib/virustotal/clients/domain.rb

@@ -2,11 +2,20 @@
 
 module VirusTotal
   module Client
-    class Domain < Base
-      def report(domain)
-        get("/domain/report", domain: domain) do |json|
-          handle_response_code json
-        end
+    class Domain < Object
+      private
+
+      def relationships
+        %w(
+          communicating_files
+          downloaded_files
+          graphs
+          historical_whois
+          referrer_files
+          resolutions
+          siblings
+          urls
+        ).map(&:to_sym)
       end
     end
   end

data/lib/virustotal/clients/file.rb

@@ -2,47 +2,76 @@
 
 module VirusTotal
   module Client
-    class File < Base
-      def report(resource, allinfo: nil)
-        params = { resource: resource, allinfo: allinfo }.compact
-        post("/file/report", params) do |json|
-          handle_response_code json
-        end
-      end
-
-      def scan(path)
+    class File < Object
+      def upload(path)
         name = ::File.basename(path)
         data = ::File.read(path)
-        post_with_file("/file/scan", filename: name, file: data) { |json| json }
+        _post_with_file("/files", file: data, filename: name) { |json| json }
       end
 
-      def rescan(resource)
-        post("/file/rescan", resource: resource) { |json| json }
+      def upload_url
+        _get("/files/upload_url") { |json| json }
       end
 
-      def upload_url
-        get("/file/scan/upload_url") { |location| location }
+      def analyse(hash)
+        _post("/files/#{hash}/analyse") { |json| json }
       end
 
-      def download(hash)
-        get("/file/download", hash: hash) { |raw| raw }
+      def votes(hash)
+        _get("/files/#{hash}/votes") { |json| json }
       end
 
-      def behaviour(hash)
-        get("/file/behaviour", hash: hash) { |json| json }
+      def add_vote(hash, verdict)
+        params = {
+          data: {
+            type: "vote",
+            attributes: {
+              verdict: verdict
+            }
+          }
+        }
+        _post("/files/#{hash}/votes", params) { |json| json }
       end
 
-      def network_traffic(hash)
-        get("/file/network-traffic", hash: hash) { |json| json }
+      def download_url(hash)
+        _get("/files/#{hash}/download_url") { |json| json }
       end
 
-      def clusters(date)
-        get("/file/clusters", date: date) { |json| json }
+      def download(hash)
+        _get("/files/#{hash}/download") { |location| location }
+      end
+
+      def pcap(id)
+        _get("/file_behaviours/#{id}/pcap") { |raw| raw }
       end
 
-      def search(query, offset: nil)
-        params = { query: query, offset: offset }.compact
-        get("/file/search", params) { |json| json }
+      private
+
+      def relationships
+        %w(
+          analyses
+          behaviours
+          bundled_files
+          carbonblack_children
+          carbonblack_parents
+          compressed_parents
+          contacted_domains
+          contacted_ips
+          contacted_urls
+          email_parents
+          embedded_domains
+          embedded_ips
+          execution_parents
+          graphs
+          itw_urls
+          overlay_parents
+          pcap_parents
+          pe_resource_parents
+          similar_files
+          submissions
+          screenshots
+          votes
+        ).map(&:to_sym)
       end
     end
   end

data/lib/virustotal/clients/ip_address.rb

@@ -2,11 +2,19 @@
 
 module VirusTotal
   module Client
-    class IPAddress < Base
-      def report(ip)
-        get("/ip-address/report", ip: ip) do |json|
-          handle_response_code json
-        end
+    class IPAddress < Object
+      private
+
+      def relationships
+        %w(
+          communicating_files
+          downloaded_files
+          graphs
+          historical_whois
+          referrer_files
+          resolutions
+          urls
+        ).map(&:to_sym)
       end
     end
   end

data/lib/virustotal/clients/object.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module VirusTotal
+  module Client
+    class Object < Base
+      CONVERT_TABLE = {
+        ipaddress: "ip_addresses",
+        domain: "domains",
+        url: "urls",
+        file: "file"
+      }.freeze
+
+      def get(id)
+        id = to_id(id)
+        _get("/#{name}/#{id}") { |json| json }
+      end
+
+      def comments(id)
+        id = to_id(id)
+        _get("/#{name}/#{id}/comments") { |json| json }
+      end
+
+      def add_comment(id, text)
+        id = to_id(id)
+        params = {
+          data: {
+            type: "comment",
+            attributes: {
+              text: text
+            }
+          }
+        }
+        _post("/#{name}/#{id}/comments", params) { |json| json }
+      end
+
+      def relationships
+        []
+      end
+
+      def method_missing(method, *args)
+        if relationships.include?(method)
+          id = to_id(args.first)
+          params = args.length == 2 ? args[1] : {}
+
+          _get("/#{name}/#{id}/#{method}", params) { |json| json }
+        else
+          super
+        end
+      end
+
+      def respond_to?(sym, *)
+        return true if relationships.include? sym
+
+        super
+      end
+
+      private
+
+      def to_id(id)
+        id
+      end
+
+      def klass
+        self.class.to_s.split("::").last.to_s.downcase.to_sym
+      end
+
+      def name
+        CONVERT_TABLE.fetch klass
+      end
+    end
+  end
+end

data/lib/virustotal/clients/url.rb

@@ -1,17 +1,53 @@
 # frozen_string_literal: true
 
+require "base64"
+
 module VirusTotal
   module Client
-    class URL < Base
-      def report(resource, allinfo: nil)
-        params = { resource: resource, allinfo: allinfo }.compact
-        post("/url/report", params) do |json|
-          handle_response_code json
-        end
+    class URL < Object
+      def analyse(url)
+        id = to_id(url)
+        _post("/urls/#{id}/analyse") { |json| json }
+      end
+
+      def votes(url)
+        id = to_id(url)
+        _get("/urls/#{id}/votes") { |json| json }
+      end
+
+      def network_location(url)
+        id = to_id(url)
+        _get("/urls/#{id}/network_location") { |json| json }
+      end
+
+      def add_vote(url, verdict)
+        id = to_id(url)
+        params = {
+          data: {
+            type: "vote",
+            attributes: {
+              verdict: verdict
+            }
+          }
+        }
+        _post("/urls/#{id}/votes", params) { |json| json }
+      end
+
+      private
+
+      def to_id(url)
+        Base64.urlsafe_encode64(url).split("=").first
       end
 
-      def scan(url)
-        post("/url/scan", url: url) { |json| json }
+      def relationships
+        %w(
+          analyses
+          downloaded_files
+          graphs
+          last_serving_ip_address
+          redirecting_urls
+          submissions
+        ).map(&:to_sym)
       end
     end
   end

data/lib/virustotal/errors.rb

@@ -2,5 +2,17 @@
 
 module VirusTotal
   class Error < StandardError; end
+
+  class AlreadyExistsError < Error; end
+  class AuthenticationRequiredError < Error; end
+  class BadRequestError < Error; end
+  class ForbiddenError < Error; end
+  class InvalidArgumentError < Error; end
+  class NotFoundError < Error; end
+  class QuotaExceededError < Error; end
   class RateLimitError < Error; end
+  class TooManyRequestsError < Error; end
+  class TransientError < Error; end
+  class UserNotActiveError < Error; end
+  class WrongCredentialsError < Error; end
 end

data/lib/virustotal/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VirusTotal
-  VERSION = "0.1.1"
+  VERSION = "1.0.0"
 end

data/virustotalx.gemspec

@@ -28,6 +28,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "coveralls", "~> 0.8"
   spec.add_development_dependency "rake", "~> 12.3"
   spec.add_development_dependency "rspec", "~> 3.8"
-  spec.add_development_dependency "vcr", "~> 4.0"
-  spec.add_development_dependency "webmock", "~> 3.5"
+  spec.add_development_dependency "vcr", "~> 5.0"
+  spec.add_development_dependency "webmock", "~> 3.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: virustotalx
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Manabu Niseki
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-05-03 00:00:00.000000000 Z
+date: 2019-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -72,28 +72,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '3.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '3.7'
 description: Yet another VirusTotal API wrapper for Ruby
 email:
 - manabu.niseki@gmail.com
@@ -112,10 +112,12 @@ files:
 - bin/setup
 - lib/virustotal.rb
 - lib/virustotal/api.rb
+- lib/virustotal/clients/analysis.rb
 - lib/virustotal/clients/base.rb
 - lib/virustotal/clients/domain.rb
 - lib/virustotal/clients/file.rb
 - lib/virustotal/clients/ip_address.rb
+- lib/virustotal/clients/object.rb
 - lib/virustotal/clients/url.rb
 - lib/virustotal/errors.rb
 - lib/virustotal/version.rb
@@ -140,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.0.4
 signing_key: 
 specification_version: 4
 summary: Yet another VirusTotal API wrapper for Ruby