falconz 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0e967b3178e27809a9bb0c71c48fef2e6ff1e450f560b43a76ba3fc4caebef0
-  data.tar.gz: 05a4e019d926775d4c305bac4fc714156e5b1eaf68ca14a3edb83b7155256895
+  metadata.gz: e76c6d1b9897e0c01e5a9dbfe8e717f1220b9e24e77fcde3efa4578dd51c1a94
+  data.tar.gz: 8ba5eaf7e216f0c9010775382debfd11667d0415bfc7ee97d296f0d33ad1d67b
 SHA512:
-  metadata.gz: 2df07a457057f0a29d43e16d6fe3399014652862bf976d6fab3de337c010a634b571c44e27f4bafa282159ee7e4a98ee7d16143eb20522a1bb8a97114eb2c98a
-  data.tar.gz: e1f11b5808000e438b3cc1e403e12bee9fba06c122ce4cd66d22969a15c72cb1bc640d8d8937256c0fb477a0638224dcbed9638536a5e8f49f796ba37fed42c4
+  metadata.gz: afcc9ffd3d7378575bef4ae4e01d61681e15f5744285a8183f8ad13ac2360549b5150c4d0ee7de5fb9e29392f91ce92ed486cad4fe7e01982a357a2a2727d78e
+  data.tar.gz: e96d2a429e161a6b0b37292a9f18e0f07016fa25d9059c612e0187ac05b9292b688325dfb2058abecdc137ff2fff8e67a3c1005abf18e665a4a8e8b73e1a86ef

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    falconz (1.0.1)
+    falconz (1.0.2)
       httparty (~> 0.16.2)
 
 GEM

data/README.md

@@ -13,12 +13,12 @@
 
 ## Usage
 
-Currently requires the `HYBRID_ANALYSIS_API_KEY` environment variable set to communicate with the API.
+To create a client, we can specify our API key or set the `HYBRID_ANALYSIS_API_KEY` environment variable to communicate with the API.
 
 ```ruby
 require "falconz"
 
-client = Falconz.client.new
+client = Falconz.client.new(key: "your_api_key") 
 ```
 
 Get the current file hashes that are being processed along with their environment IDs.
@@ -41,14 +41,41 @@ client.submit_file(file: "malware.exe", environment_id: 100)
 
 Search for results related to a given hash (MD5/SHA1/SHA256).
 ```ruby
-# md5
-client.search_hash("4d86e66537ac0130cce541890e1d9c4b")
-
-# sha1
-client.search_hash("62f585da3fea334b83cb8b4cee9b605d901c825c")
-
-# sha256
-client.search_hash("82d14e45e6a0586e66f359c6854bd90b6180b92d66d3db03e5e85234edfdcc04")
+client.search_hash("cc311a06612f1b420cf788bd8883fa9dbd34d33ba8fa2443b86b7f88c7a75c2c")
+# => [{"job_id"=>"5ae641ad7ca3e175d57a6013",
+#   "environment_id"=>"100",
+#   "environment_description"=>"Windows 7 32 bit",
+#   "size"=>3127633,
+#   "type"=>"PE32 executable (GUI) Intel 80386, for MS Windows",
+#   "type_short"=>["peexe"],
+#   "target_url"=>nil,
+#   "state"=>"SUCCESS",
+#   "submit_name"=>"sospecha.exe",
+#   "md5"=>"7421fed9ae4b6643913b080718b919cc",
+#   "sha1"=>"4f86bc7a578b6ac9d1e5f1fc325917e436f60520",
+#   "sha256"=>"cc311a06612f1b420cf788bd8883fa9dbd34d33ba8fa2443b86b7f88c7a75c2c",
+#   "sha512"=>"684558a218f6039ba718bfeac763f529222474498a41fdfa6994c8a3955b2686c07fd053d1afab73b2403b9f98fd3cf7112faec220c1b12b574c6a7fea828a8b",
+#   "ssdeep"=>"49152:32uJI9LH1MuvxlFl7Z0pnZASuwSpW/vnjC91R8rsiX8L1ViGiJJLQRRtaU:muwLH6oF0pZAS6W/vWzRo8iGi2RtaU",
+#   "imphash"=>"884310b1928934402ea6fec1dbd3cf5e",
+#   "av_detect"=>1,
+#   "vx_family"=>"TSGeneric",
+#   "url_analysis"=>false,
+#   "analysis_start_time"=>"2018-04-30T00:06:01-05:00",
+#   "threat_score"=>85,
+#   "interesting"=>false,
+#   "threat_level"=>2,
+#   "verdict"=>"malicious",
+#   "certificates"=>[],
+#   "domains"=>[],
+#   "classification_tags"=>[],
+#   "compromised_hosts"=>[],
+#   "hosts"=>[],
+#   "total_network_connections"=>0,
+#   "total_processes"=>5,
+#   "total_signatures"=>56,
+#   "extracted_files"=>[],
+#   "processes"=>[],
+#   "file_metadata"=>nil}]
 ```
 
 Check the number of environments available to use.

data/lib/falconz/apis/feed.rb

@@ -1,6 +1,6 @@
 module Falconz
   module APIs
-    # A module consisting of the method associted with the 
+    # A module consisting of the method associated with the 
     # Feed section of the API.
     #
     # @author Kent 'picat' Gruber
@@ -8,6 +8,7 @@ module Falconz
       # access a feed of last 250 reports over 24h
       #
       # == Example
+      #   # create a new client
       #   client = Falconz.client.new
       #
       #   client.latest_feed do |data|
@@ -15,6 +16,13 @@ module Falconz
       #     puts data.to_json
       #   end
       #
+      #   # or, if you'd like, you can be a fancy shamncy pants 
+      #
+      #   client.latest_feed { |data| puts data.to_json }
+      #
+      #   feed = client.latest_feed
+      # 
+      # @return 
       # https://www.hybrid-analysis.com/docs/api/v2#/Feed/get_feed_latest
       def latest_feed
         # return response unless block was given ( like the in-line example )
@@ -31,9 +39,16 @@ module Falconz
       end
 
       # A little wrapper method to #latest_feed that returns the count
-      # of the ammount of data found in the feed.
+      # of the amount of data found in the feed.
+      # 
+      # == Example
+      #   # create a new client
+      #   client = Falconz.client.new
+      #   
+      #   # print latest feed found to the screen
+      #   puts client.latest_feed_count
       #
-      # @return [void]
+      # @return [Integer]
       # @see #latest_feed
       def latest_feed_count
         # capture response

data/lib/falconz/apis/search.rb

@@ -1,23 +1,67 @@
 module Falconz
   module APIs
     module Search
-      # summary for given hash
+      # Get summaries for a given hash.
+      # 
+      # == Example
+      #   search_results = client.search_hash("e2442c82f3af5c6c72694ad670d385571418f64b998e2c470c3a5fcd18181932")
+      #
+      #   search_results.first["total_signatures"]
+      #    # => 15
+      # 
+      # @param string [String] the hash to search for.
+      # @return [Array<Hash>] the result(s) from the search.
+      #
       # https://www.hybrid-analysis.com/docs/api/v2#/Search/post_search_hash
-      def search_hash(string, **options)
-        raise "Requires a MD5, SHA1 or SHA256 hash" if string.nil?
-        options[:hash] = string
+      def search_hash(string)
+        options = {}
+        options[:hash] = string unless string.nil?
+        raise "Requires a MD5, SHA1 or SHA256 hash" if options[:hash].nil?
         post_request("/search/hash", options)
       end
       
-      # summary for given hashes
+      # Get a summaries for any amount of given hashes.
+      #
+      # == Example
+      #   search_results = client.search_hashes("e2442c82f3af5c6c72694ad670d385571418f64b998e2c470c3a5fcd18181932", "1cc406f6bf071bf5d96634cf9ab4ee94c2103e9b96207fdb37234536bb12bd50")
+      # 
+      #   search_results.count 
+      #   # => 2
+      #
+      #   search_results.first["total_signatures"]
+      #   # => 15
+      #
+      #   # print all search results to screen, as json
+      #   puts search.to_json
+      #
+      # @param strings [Array<String>] the hashes to search for.
+      # @return [Array<Hash>] the results from the search.
+      #   
       # https://www.hybrid-analysis.com/docs/api/v2#/Search/post_search_hashes
-      def search_hashes(*strings, **options)
-        raise "Requires at least one MD5, SHA1 or SHA256 hash" if strings.nil? or strings.empty?
-        options[:hashes] = strings
+      def search_hashes(*strings)
+        options = {}
+        options[:hashes] = strings unless strings.nil? or strings.empty?
+        raise "Requires MD5, SHA1 or SHA256 hashes" if options[:hashes].nil?
         post_request("/search/hashes", options)
       end
      
-      # search the database using search terms
+      # Search the database using search terms.
+      #
+      # == Example
+      #   pdf_results = client.search_terms(filetype: "pdf")
+      #
+      #   # count malicious pdfs from results
+      #   pdf_results["result"].select { |r| r["verdict"] == "malicious" }.count
+      #
+      # == Example 
+      #   ransomware_results = client.search_terms(tag: "ransomware")
+      #   
+      #   ransomware_results["count"]
+      #   # => 196
+      #
+      # @param options [Hash] the hashes to search for.
+      # @return [Array<Hash>] the results from the search.
+      #
       # https://www.hybrid-analysis.com/docs/api/v2#/Search/post_search_terms
       def search_terms(**options)
         post_request("/search/terms", options)

data/lib/falconz/apis/submission.rb

@@ -1,7 +1,18 @@
 module Falconz
   module APIs
     module Submission 
-      # submit a local file for analysis
+      # Submit a local file for analysis.
+      #
+      # == Example
+      #
+      #   response = client.submit_file(file: "/path/to/local/file", environment_id: 300)
+      # 
+      #   # print job ID from response
+      #   puts response["job_id"]
+      #
+      # @param options [Hash] the hashes to search for.
+      # @return [Hash] 
+      #
       # https://www.hybrid-analysis.com/docs/api/v2#/Submission/post_submit_file
       def submit_file(**options)
         options[:file] = File.open(options[:file], "r")
@@ -9,27 +20,57 @@ module Falconz
         options[:file].close
         return response
       end
-     
-      # submit a file by url for analysis 
+
+      # Submit a file by URL for analysis.
+      #
+      # == Example
+      #
+      #   response = client.submit_url(url: "www.malicious-google.com/malware.exe", environment_id: 100, no_share_third_party: true)
+      #
+      #   # print job ID from response
+      #   puts response["job_id"]
+      #
+      # @param options [Hash]
+      # @return [Hash] 
+      #
       # https://www.hybrid-analysis.com/docs/api/v2#/Submission/post_submit_url_to_file
       def submit_file_by_url(**options)
         post_request("/submit/url-to-file", options)
       end
-      
-      # submit a url for analysis
+
+      # Submit a url for analysis.
+      #
+      # == Example
+      #
+      #   response = client.submit_url(url: "www.malicious-google.com", environment_id: 100, experimental_anti_evasion: true)
+      # 
+      #   # print job ID from response
+      #   puts response["job_id"]
+      #
+      # @param options [Hash]
+      # @return [Hash] 
+      #
       # https://www.hybrid-analysis.com/docs/api/v2#/Submission/post_submit_url_for_analysis
       def submit_url(**options)
         post_request("/submit/url-for-analysis", options)
       end
-      
+
       # determine a SHA256 that an online file or URL submission will 
       # have when being processed by the system. Note: this is useful when looking up URL analysis
+      #
+      # @param options [Hash]
+      # @return [Hash] 
+      #
       # https://www.hybrid-analysis.com/docs/api/v2#/Submission/post_submit_hash_for_url
       def hash_for_url(url)
         post_request("/submit/hash-for-url", url: url)
       end
-     
+
       # submit dropped file for analysis
+      #
+      # @param options [Hash]
+      # @return [Hash] 
+      #
       # https://www.hybrid-analysis.com/docs/api/v2#/Submission/post_submit_dropped_file
       def submit_dropped_file(**options)
         post_request("/submit/dropped-file", options)

data/lib/falconz/apis/system.rb

@@ -58,6 +58,28 @@ module Falconz
       end
 
       # return information about configured backend nodes
+      #
+      # == Example
+      #   
+      #   client = Falconz.client.new
+      #
+      #   backend_information = client.backend
+      #
+      #   # example of accessing specific information from hash
+      #   puts backend_information["version"]
+      #
+      #   # all the keys in the hash
+      #   puts backend_information.keys
+      #
+      #   # count the number of backend nodes
+      #   puts backend_information["nodes"].count
+      #
+      #   # you can get hell'a fancy
+      #   client.backend["nodes"].map { |node| node["environments"].map { |e| [e["architecture"], e["analysis_mode"]] } }.flatten(1).uniq.each do |arch, mode|
+      #     puts "The " + arch + " architecture supports " + mode + " level analysis." 
+      #   end
+      #  
+      # @return [Hash] all the information about the system backend
       # https://www.hybrid-analysis.com/docs/api/v2#/System/get_system_backend
       def backend
         get_request("/system/backend")
@@ -134,16 +156,49 @@ module Falconz
       end
 
       # return information about the instance version
+      #
+      # == Example
+      #
+      #   client = Falconz.client.new
+      #   
+      #   # get system version info, as a hash
+      #   version_info = client.system_version
+      #   # => {"instance"=>"8.0-5305cf9", "sandbox"=>"8.10", "api"=>"2.1.5"}
+      #
+      #   # iterate over each lil'bit of information
+      #   version_info.each do |name, value|
+      #     puts name + " " + value
+      #   end
+      #
+      #   # you can also access the information directly
+      #   puts "found API version " + version_info["api"]
+      # 
       # https://www.reverse.it/docs/api/v2#/System/get_system_version
       def system_version
         get_request("/system/version")
       end
 
-      # return information about queue size
+      # return information about system queue size
+      #
+      # == Example
+      #
+      #   client = Falconz.client.new
+      #   
+      #   # print the system queue size to the screen
+      #   puts client.system_queue_size
+      #
       # https://www.reverse.it/docs/api/v2#/System/get_system_queue_size
-      def queue_size
-        get_request("/system/queue-size")["value"]
+      def system_queue_size
+        @cached_queue_size = get_request("/system/queue-size")["value"]
+      rescue => error
+        if JSON.parse(error.message)["code"] == 429 && @cached_queue_size
+          return @cached_queue_size
+        end
+        raise error
       end
+      
+      # For backwards compatibility with the old method API.
+      alias queue_size system_queue_size
     end
   end
 end

data/lib/falconz/client.rb

@@ -9,8 +9,12 @@ require_relative "apis/report.rb"
 
 module Falconz
   class Client 
+    # Need some special REST API powers.
     include REST::GET
     include REST::POST
+    
+    # All of the magic API methods, nestled away
+    # into their own modules.
     include APIs::Key
     include APIs::Search
     include APIs::System
@@ -18,12 +22,22 @@ module Falconz
     include APIs::Feed
     include APIs::Report
 
-    def initialize
-      @url = "https://www.hybrid-analysis.com/api/v2"
+    # Client HTTP header information.
+    attr_accessor :header
+
+    # Client HTTP base URL.
+    attr_accessor :url
+
+    # When initializing a Client, you can optionally specify the base API (v2) URL
+    # and the API key to be used for communication. These can both be changed later on. 
+    #
+    # Note: If not specified, the HYBRID_ANALYSIS_API_KEY environment variable is used.
+    def initialize(url: "https://www.hybrid-analysis.com/api/v2", key: ENV["HYBRID_ANALYSIS_API_KEY"])
+      @url = url
 
       @header = { 
         "User-Agent" => "Falcon Sandbox", 
-        "api-key" => ENV["HYBRID_ANALYSIS_API_KEY"]
+        "api-key" => key
       }
     end
    
@@ -44,21 +58,5 @@ module Falconz
     def api_key=(k)
       @header["api-key"] = k
     end
-
-    def url
-      @url
-    end
-
-    def url=(u)
-      @url = u
-    end
-
-    def header
-      @header
-    end
-
-    def header=(h)
-      @header
-    end
   end
 end

data/lib/falconz/rest/get.rb

@@ -8,7 +8,7 @@ module Falconz
       def get_request(path)
         response = HTTParty.get(url + path, headers: header)
         return response if response.success?
-        raise response
+        raise RuntimeError, response
       end
     end
   end

data/lib/falconz/rest/post.rb

@@ -9,8 +9,7 @@ module Falconz
           return response.body if json
           return response
         else
-          binding.pry
-          raise response.to_h
+          raise RuntimeError, response.to_h
         end
       end
     end

data/lib/falconz/version.rb

@@ -1,3 +1,3 @@
 module Falconz
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: falconz
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Kent 'picat' Gruber
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-29 00:00:00.000000000 Z
+date: 2018-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -102,7 +102,6 @@ files:
 - falcon.jpg
 - falconz.gemspec
 - lib/falconz.rb
-- lib/falconz/apis/apis.rb
 - lib/falconz/apis/feed.rb
 - lib/falconz/apis/key.rb
 - lib/falconz/apis/report.rb

data/lib/falconz/apis/apis.rb

@@ -1,27 +0,0 @@
-module Falconz
-  module APIs
-    module Search
-      # summary for given hash
-      # https://www.hybrid-analysis.com/docs/api/v2#/Search/post_search_hash
-      def hash(string, **options)
-        options[:hash] = string unless string.nil?
-        raise "Requires a MD5, SHA1 or SHA256 hash" if options[:hash].nil?
-        get_request("/key/current", options)
-      end
-      
-      # summary for given hashes
-      # https://www.hybrid-analysis.com/docs/api/v2#/Search/post_search_hashes
-      def hashes(*strings, **options)
-        options[:hashes] = strings unless strings.nil? or strings.empty?
-        raise "Requires MD5, SHA1 or SHA256 hashes" if options[:hashes].nil?
-        get_request("/search/hashes", options)
-      end
-     
-      # search the database using search terms
-      # https://www.hybrid-analysis.com/docs/api/v2#/Search/post_search_terms
-      def terms(**options)
-        get_request("/search/terms", options)
-      end
-    end
-  end
-end