falconz 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7a44850612a4491a8bc2ccb46218be8f36f80510
-  data.tar.gz: 2b8f3f8708774e65bd77169bdcbd7652786d0a99
+SHA256:
+  metadata.gz: a0e967b3178e27809a9bb0c71c48fef2e6ff1e450f560b43a76ba3fc4caebef0
+  data.tar.gz: 05a4e019d926775d4c305bac4fc714156e5b1eaf68ca14a3edb83b7155256895
 SHA512:
-  metadata.gz: 7bc77c69372fdfae991f229a5e26b7e54c8f7e221764b9d2320f164491e824a3c9538ac4ad59d4a2281afc1b7235a9eaa6d4aedbf9849f51b7fe637d9eaed8d1
-  data.tar.gz: e6dd9024bedfc6496a166ca35bcd7f2569da29be41b407e9b1cb029b023a0d5ed330dcffda9364afdbc4811c7bb9fd390d5c5003c59aedf86b9d3dc3fd81f9a2
+  metadata.gz: 2df07a457057f0a29d43e16d6fe3399014652862bf976d6fab3de337c010a634b571c44e27f4bafa282159ee7e4a98ee7d16143eb20522a1bb8a97114eb2c98a
+  data.tar.gz: e1f11b5808000e438b3cc1e403e12bee9fba06c122ce4cd66d22969a15c72cb1bc640d8d8937256c0fb477a0638224dcbed9638536a5e8f49f796ba37fed42c4

data/Gemfile.lock

@@ -1,16 +1,21 @@
 PATH
   remote: .
   specs:
-    falconz (1.0.0)
+    falconz (1.0.1)
       httparty (~> 0.16.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    coderay (1.1.2)
     diff-lcs (1.3)
     httparty (0.16.2)
       multi_xml (>= 0.5.2)
+    method_source (0.9.0)
     multi_xml (0.6.0)
+    pry (0.11.3)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
     rake (10.5.0)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
@@ -32,8 +37,9 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.16)
   falconz!
+  pry
   rake (~> 10.0)
   rspec (~> 3.0)
 
 BUNDLED WITH
-   1.16.0
+   1.16.1

data/README.md

@@ -5,7 +5,7 @@
   <img alt="i like birds" src="falcon.jpg"/>
 <p>
 
-Falcon Sandbox has a powerful and simple API that can be used to submit files/URLs for analysis, pull report data, but also perform advanced search queries. The API is open and free to the entire IT-security community.
+[Falcon Sandbox](https://www.hybrid-analysis.com/docs/api/v2) has a powerful and simple API that can be used to submit files/URLs for analysis, pull report data, but also perform advanced search queries. The API is open and free to the entire IT-security community.
 
 ## Installation
 
@@ -13,7 +13,7 @@ Falcon Sandbox has a powerful and simple API that can be used to submit files/UR
 
 ## Usage
 
-Currently requires the `HYBRID_ANALYSIS_API_KEY` enviroment variable set to communicate with the API.
+Currently requires the `HYBRID_ANALYSIS_API_KEY` environment variable set to communicate with the API.
 
 ```ruby
 require "falconz"
@@ -21,6 +21,16 @@ require "falconz"
 client = Falconz.client.new
 ```
 
+Get the current file hashes that are being processed along with their environment IDs.
+```ruby
+client.in_progress
+# => [{:hash=>"b8560ce1bacb5515fdaef7cb3615a8172663da749b038687ab4a439cbf64f23b", :environment=>"100"},
+#  {:hash=>"4f456ae8d592a73be8e898384a6b78cf1406965bcb2cea38ffa976c1084acb74", :environment=>"120"},
+#  {:hash=>"6e206c74d4b9796264e5e2cb351e563806320e8d6d794fba38d3be93aa4b1bb5", :environment=>"100"},
+#  {:hash=>"8d5bd56a19d06d46c8e92552f0bf81fa38cbf3365ab022e97075810be18000d9", :environment=>"120"},
+#  {:hash=>"497f631d332b6b242528409778ecb7a778b1b50d6964139b549fdd71410381bc", :environment=>"120"}]
+```
+
 Upload a local file to the sandbox.
 ```ruby
 client.submit_file(file: "malware.exe", environment_id: 100)
@@ -47,6 +57,12 @@ client.number_of_environments
 # => 5
 ```
 
+Get the available environments ID numbers.
+```ruby
+client.environment_ids
+# => [100, 110, 120, 300, 200]
+```
+
 Get information about current API key being used.
 ```ruby
 client.current_key

data/bin/console

@@ -7,8 +7,8 @@ require "falconz"
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+require "pry"
+Pry.start
 
-require "irb"
-IRB.start(__FILE__)
+#require "irb"
+#IRB.start(__FILE__)

data/examples/debug.rb

@@ -4,5 +4,4 @@ require 'pry'
 
 client = Falconz::Client.new
 
-
 binding.pry

data/falconz.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "httparty", "~> 0.16.2"
 
+  spec.add_development_dependency "pry"
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"

data/lib/falconz/apis/feed.rb

@@ -1,9 +1,49 @@
 module Falconz
   module APIs
+    # A module consisting of the method associted with the 
+    # Feed section of the API.
+    #
+    # @author Kent 'picat' Gruber
     module Feed
       # access a feed of last 250 reports over 24h
-      def latest_feed(**options)
-        get_request("/feed/latest", options)
+      #
+      # == Example
+      #   client = Falconz.client.new
+      #
+      #   client.latest_feed do |data|
+      #     # do something with the data
+      #     puts data.to_json
+      #   end
+      #
+      # 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 )
+        return get_request('/feed/latest') unless block_given?
+        # capture response
+        response = get_request('/feed/latest')
+        # raise error (built out of the response) unless everything is ok
+        raise "response not ok: #{response}" unless Falconz.response_is_ok?(response)
+        # raise error unless there is any data
+        raise "no data to iterate through in response #{response}" unless response['data'] or !response['data'].zero?
+        response['data'].each do |data|
+          yield data
+        end
+      end
+
+      # A little wrapper method to #latest_feed that returns the count
+      # of the ammount of data found in the feed.
+      #
+      # @return [void]
+      # @see #latest_feed
+      def latest_feed_count
+        # capture response
+        response = latest_feed   
+        # raise error (built out of the response) unless everything is ok
+        raise response unless Falconz.response_is_ok?(response)
+        # raise error unless there is any count in the response
+        raise "no count found in response #{response}" unless response['count']
+        # return the count
+        response["count"] 
       end
     end
   end

data/lib/falconz/apis/key.rb

@@ -2,8 +2,9 @@ module Falconz
   module APIs
     module Key 
       # return information about the used API key
-      def current_key(**options)
-        get_request("/key/current", options)
+      # https://www.hybrid-analysis.com/docs/api/v2#/Key/get_key_current
+      def current_key
+        get_request("/key/current")
       end
     end
   end

data/lib/falconz/apis/report.rb

@@ -1,30 +1,96 @@
 module Falconz
   module APIs
     module Report 
-      def report_state(id, **options)
-        raise "ID in one of format: ‘jobId’ or ‘sha256:environmentId’" if id.nil?
-        get_request("/report/#{id}/hash", options)
+      # return state of a submission
+      # https://www.hybrid-analysis.com/docs/api/v2#/Report/get_report__id__state
+      def report_state(id)
+        raise_if_id_is_not_valid(id)
+        get_request("/report/#{id}/hash")
       end
 
-      def report_summary(id, **options)
-        raise "ID in one of format: ‘jobId’ or ‘sha256:environmentId’" if id.nil?
-        get_request("/report/#{id}/hash", options)
+      # return summary of a submission
+      # https://www.hybrid-analysis.com/docs/api/v2#/Report/get_report__id__summary
+      def report_summary(id)
+        raise_if_id_is_not_valid(id)
+        get_request("/report/#{id}/hash")
       end
 
-      def report_file(id, type, **options)
-        raise "ID in one of format: ‘jobId’ or ‘sha256:environmentId’" if id.nil?
-        raise "Type requirest https://www.reverse.it/docs/api/v2#/Report/get_report__id__file__type_" if type.nil?
-        get_request("/report/#{id}/file/#{type}", options)
+      # return summary of multiple submissions (bulk query)
+      # https://www.hybrid-analysis.com/docs/api/v2#/Report/post_report_summary
+      def report_summary(**options)
+        post_request("/report/summary", options)
       end
 
-      def report_sreenshots(id, **options)
-        raise "ID in one of format: ‘jobId’ or ‘sha256:environmentId’" if id.nil?
-        get_request("/report/#{id}/screenshots", options)
+      # downloading report data (e.g. JSON, XML, PCAP)
+      # https://www.hybrid-analysis.com/docs/api/v2#/Report/get_report__id__file__type_
+      def report_file(id, type)
+        raise_if_id_is_not_valid(id)
+        raise_if_report_file_type_is_not_valid(type)
+        get_request("/report/#{id}/file/#{type}")
       end
 
-      def report_droppedfiles(id, **options)
-        raise "ID in one of format: ‘jobId’ or ‘sha256:environmentId’" if id.nil?
-        get_request("/report/#{id}/dropped-files", options)
+      # retrieve an array of screenshots from a report in the Base64 format
+      # https://www.hybrid-analysis.com/docs/api/v2#/Report/get_report__id__screenshots
+      def report_sreenshots(id)
+        raise_if_id_is_not_valid(id)
+        get_request("/report/#{id}/screenshots")
+      end
+
+      # retrieve all extracted/dropped binaries files for a report, as zip
+      # https://www.hybrid-analysis.com/docs/api/v2#/Report/get_report__id__dropped_files
+      def report_droppedfiles(id)
+        raise_if_id_is_not_valid(id)
+        get_request("/report/#{id}/dropped-files")
+      end
+
+      private
+      
+      # raise an error if the given ID isn't (probably) valid
+      def raise_if_id_is_not_valid(id)
+        unless id_is_in_probably_valid_format?(id)
+          raise "need if in format: ‘jobId’ or ‘sha256:environmentId’"
+        end
+      end
+
+      # check if a given ID is probably valid or not
+      # @see #report_file
+      def id_is_in_probably_valid_format?(id)
+        return false if id.nil?
+        return false unless id.is_a? String
+        return true 
+      end
+
+      # valid report file types for #report_file
+      # @see #report_file
+      VALID_REPORT_FILE_TYPES = {
+        "xml":  "The XML report as application/xml content and *.gz compressed.",
+        "json": "The JSON report as application/json content",
+        "html": "The HTML report as text/html content and *.gz compressed",
+        "pdf":  "The PDF report as application/pdf content",
+        "maec": "The MAEC (4.1) report as application/xml content",
+        "stix": "The STIX report as application/xml content",
+        "misp": "The MISP XML report as application/xml content",
+        "misp-json": "The MISP JSON report as application/json content",
+        "openioc": "The OpenIOC (1.1) report as application/xml content",
+        "bin": "The binary sample as application/octet-stream and *.gz compressed. Note: if the file was uploaded with ‘no_share_vt’ (i.e. not shared), this might fail.",
+        "crt": "The binary sample certificate file (is available) as application/octet-stream content",
+        "memory": "The process memory dump files as application/octet-stream and zip compressed.",
+        "pcap": "The PCAP network traffic capture file as application/octet-stream and *.gz compressed."
+      }
+
+      # check if a report file type argument is valid
+      # @see #report_file
+      def report_file_type_is_valid?(type)
+        return true if VALID_REPORT_FILE_TYPES.keys.include? type.to_s.downcase
+        false
+      end
+
+      # raise an error if the report file type argument isn't valid
+      # @see #report_file
+      def raise_if_report_file_type_is_not_valid(type)
+        unless report_file_type_is_valid?(id)
+          raise "Type requires https://www.reverse.it/docs/api/v2#/Report/get_report__id__file__type:\n#{VALID_REPORT_FILE_TYPES}"
+        end
       end
     end
   end

data/lib/falconz/apis/submission.rb

@@ -2,6 +2,7 @@ module Falconz
   module APIs
     module Submission 
       # submit a local file for analysis
+      # https://www.hybrid-analysis.com/docs/api/v2#/Submission/post_submit_file
       def submit_file(**options)
         options[:file] = File.open(options[:file], "r")
         response = post_request("/submit/file", options)
@@ -10,27 +11,29 @@ module Falconz
       end
      
       # submit a file by url for analysis 
+      # 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
+      # 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
+      # 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 
+      # submit dropped file for analysis
+      # https://www.hybrid-analysis.com/docs/api/v2#/Submission/post_submit_dropped_file
       def submit_dropped_file(**options)
         post_request("/submit/dropped-file", 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
-      def hash_from_url(**options)
-        post_request("/submit/hash-for-url", options)
-      end
     end
   end
 end

data/lib/falconz/apis/system.rb

@@ -1,45 +1,83 @@
 module Falconz
   module APIs
     module System
-      def system_heartbeat(wait = 15, **options)
-        return get_request("/system/heartbeat", options) unless block_given?
+      # return heartbeat
+      #
+      # == Example
+      #   client = Falconz.client.new
+      #
+      #   client.system_heartbeat do |response|
+      #     # do something with the response
+      #     puts response.to_json
+      #   end
+      #
+      # == Example without Block Syntax
+      #   client = Falconz.client.new
+      #
+      #   response = client.system_heartbeat
+      #
+      # https://www.hybrid-analysis.com/docs/api/v2#/System/get_system_heartbeat
+      def system_heartbeat(wait = 15)
+        return get_request("/system/heartbeat") unless block_given?
         while true
-          yield get_request("/system/heartbeat", options)
+          yield get_request("/system/heartbeat")
           sleep wait
         end
       end
 
+      # check the number of seconds since last update
+      # @see #system_heartbeat
       def number_of_seconds_since_last_update
         system_heartbeat["number_of_seconds_since_last_update"]
       end
 
-      def total_submissions_in_system(**options)
-        get_request("/system/total-submissions", options)["value"]
-      end
-      
-      def in_progress(**options)
-        return get_request("/system/in-progress", options)["values"] unless block_given?
-        get_request("/system/in-progress", options)["values"].each do |value| 
-          hash, env = value.split(":")
-          yield hash, env 
+      # check the total submissions in the system
+      # https://www.hybrid-analysis.com/docs/api/v2#/System/get_system_total_submissions
+      def total_submissions_in_system
+        get_request("/system/total-submissions")["value"]
+      end
+
+      # get the in progress jobs
+      # https://www.hybrid-analysis.com/docs/api/v2#/System/get_system_in_progress
+      def in_progress
+        jobs = get_request("/system/in-progress")["values"].map do |job| 
+          kv = {}
+          kv[:hash], kv[:environment] = job.split(":")
+          kv
+        end
+        return jobs unless block_given?
+        jobs.each do |job|
+          yield job
         end
       end
-      
-      def backend(**options)
-        get_request("/system/backend", options)
+
+      # number of jobs currently being processed
+      # @see #in_progress
+      def in_progress_count
+        get_request("/system/in-progress")["values"].count
+      end
+
+      # return information about configured backend nodes
+      # https://www.hybrid-analysis.com/docs/api/v2#/System/get_system_backend
+      def backend
+        get_request("/system/backend")
       end
-      
-      def environments(**options)
-        return get_request("/system/environments", options) unless block_given?
-        get_request("/system/environments", options).each do |enviroment|
-          yield enviroment
+
+      # return information about available execution environments
+      # https://www.hybrid-analysis.com/docs/api/v2#/System/get_system_environments
+      def environments
+        return get_request("/system/environments") unless block_given?
+        get_request("/system/environments").each do |environment|
+          yield environment
         end
       end
 
+      # return the number of environments in the system
       def number_of_environments
         environments.count
       end
 
+      # find an environment by an ID
       def find_environment_by_id(id)
         id = id.to_i
         environments do |env|
@@ -47,7 +85,17 @@ module Falconz
         end
       end
 
-      def enviroments_busy_percentages
+      # list available environment IDs
+      def environment_ids(refresh: false)
+        if refresh or @environment_ids.nil?
+          @environment_ids = environments.map { |env| env["id"] } 
+        end
+        return @environment_ids unless block_given?
+        @environment_ids.each { |env| yield id }
+      end
+
+      # return environments
+      def environments_busy_percentages
         envs = {}
         environments do |env|
           if env["busy_virtual_machines"] == 0 || env["total_virtual_machines"] == 0
@@ -62,13 +110,15 @@ module Falconz
         end
       end
 
+      # check if a given environment ID is a windows system 
       def environment_windows?(id)
         env = find_environment_by_id(id)
         return nil if env.nil?
         return true if env["architecture"] == "WINDOWS"
         false
       end
-      
+
+      # check if a given environment ID is a linux system 
       def environment_linux?(id)
         env = find_environment_by_id(id)
         return nil if env.nil?
@@ -76,16 +126,23 @@ module Falconz
         false
       end
 
-      def system_state(**options)
-        get_request("/system/state", options)
+      # a full system state query, including all available 
+      # action scripts, environments, files in progress, etc.
+      # https://www.reverse.it/docs/api/v2#/System/get_system_state
+      def system_state
+        get_request("/system/state")
       end
 
-      def system_version(**options)
-        get_request("/system/version", options)
+      # return information about the instance version
+      # https://www.reverse.it/docs/api/v2#/System/get_system_version
+      def system_version
+        get_request("/system/version")
       end
-      
-      def queue_size(**options)
-        get_request("/system/queue-size", options)["value"]
+
+      # return information about queue size
+      # https://www.reverse.it/docs/api/v2#/System/get_system_queue_size
+      def queue_size
+        get_request("/system/queue-size")["value"]
       end
     end
   end

data/lib/falconz/client.rb

@@ -5,6 +5,7 @@ require_relative "apis/key.rb"
 require_relative "apis/system.rb"
 require_relative "apis/submission.rb"
 require_relative "apis/feed.rb"
+require_relative "apis/report.rb"
 
 module Falconz
   class Client 
@@ -15,6 +16,7 @@ module Falconz
     include APIs::System
     include APIs::Submission
     include APIs::Feed
+    include APIs::Report
 
     def initialize
       @url = "https://www.hybrid-analysis.com/api/v2"

data/lib/falconz/rest/get.rb

@@ -1,15 +1,14 @@
 module Falconz
   module REST
+    # HTTP 1.1 GET request method to make on the API endpoint.
+    #
+    # This is a module that is used in pretty much all the API
+    # modules in order to talk to the API endpoint.
     module GET
-      def get_request(path, json: false, **options)
+      def get_request(path)
         response = HTTParty.get(url + path, headers: header)
-        if response.success?
-          return response.body if json
-          return response 
-        else
-          binding.pry
-          raise response.to_h
-        end
+        return response if response.success?
+        raise response
       end
     end
   end

data/lib/falconz/version.rb

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

data/lib/falconz.rb

@@ -11,4 +11,11 @@ module Falconz
   def self.client
     Client
   end
+
+  def self.response_is_ok?(resp)
+    return false unless resp.respond_to?(:has_key?)
+    return false unless resp.has_key? "status"
+    return true if resp["status"].match?("ok")
+    return false
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: falconz
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Kent 'picat' Gruber
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-10 00:00:00.000000000 Z
+date: 2018-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.16.2
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -119,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Falcon Malware Sandbox APIv2 Connector