hybridanalysisx 0.1.0

data/lib/hybridanalysis/clients/file_collection.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module HybridAnalysis
+  module Clients
+    class FileCollection < Client
+      #
+      # remove file within collection without hard removal from system
+      #
+      # @param [String] id File collection id
+      # @param [String] hash SHA256 of file to remove
+      #
+      # @return [Hash]
+      #
+      def delete(id:, hash: )
+        _delete("/file-collection/#{id}/files/#{hash}") { |json| json }
+      end
+
+      #
+      # return a summary of file collection
+      #
+      # @param [String] id File collection id
+      #
+      # @return [Hash]
+      #
+      def get(id)
+        _get("/file-collection/#{id}") { |json| json }
+      end
+
+      #
+      # return an archive with all collection samples
+      #
+      # @param [String] id File collection id
+      #
+      # @return [Hash]
+      #
+      def download(id)
+        _get("/file-collection/#{id}/files/download") { |json| json }
+      end
+
+      #
+      # search the database using the search terms
+      #
+      # @param [String, nil] collection_name Collection Name
+      # @param [String, nil] tag Hashtag e.g. ransomware
+      #
+      # @return [Hash]
+      #
+      def search(collection_name: nil, tag: nil)
+        params = {
+          collection_name: collection_name,
+          tag: tag
+        }.compact
+        _post("/file-collection/search", params) { |json| json }
+      end
+
+      #
+      # create file collection
+      #
+      # @param [String, nil] collection_name Optional collection name
+      # @param [String, nil] comment Optional comment text that may be associated with the file collection (Note: you can use #tags here)
+      # @param [Boolean, nil] no_share_third_party When set to 'true', samples within collection will never be shared with any third party. Default: true
+      # @param [Boolean, nil] allow_community_access When set to 'true', samples within collection will be available for the community. Default: true
+      #
+      # @return [Hash]
+      #
+      def create(collection_name: nil, comment: nil, no_share_third_party: nil, allow_community_access: nil)
+        params = {
+          collection_name: collection_name,
+          comment: comment,
+          no_share_third_party: no_share_third_party,
+          allow_community_access: allow_community_access
+        }.compact
+        _post("/file-collection/create", params) { |json| json }
+      end
+
+      #
+      # add file to collection
+      #
+      # @param [String] id File collection id
+      # @param [String] file File to add
+      #
+      # @return [Hash]
+      #
+      def add(id:, file: )
+        params = { file: file }.compact
+        _post("/file-collection/#{id}/files/add", params) { |json| json }
+      end
+    end
+
+    class Key < Client
+      #
+      # return information about the used API key and it limits
+      #
+      # @return [Hash]
+      #
+      def current
+        _get("/key/current") { |json| json }
+      end
+    end
+  end
+end

data/lib/hybridanalysis/clients/overview.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module HybridAnalysis
+  module Clients
+    class Overview < Client
+      #
+      # return overview for hash
+      #
+      # @param [String] sha256 SHA256 for lookup
+      #
+      # @return [Hash]
+      #
+      def get(sha256)
+        _get("/overview/#{sha256}") { |json| json }
+      end
+
+      #
+      # refresh overview and download fresh data from external services
+      #
+      # @param [String] sha256 SHA256 for lookup
+      #
+      # @return [Hash]
+      #
+      def refresh(sha256)
+        _get("/overview/#{sha256}/refresh") { |json| json }
+      end
+
+      #
+      # return overview for hash
+      #
+      # @param [String] sha256 SHA256 for lookup
+      #
+      # @return [Hash]
+      #
+      def summary(sha256)
+        _get("/overview/#{sha256}/summary") { |json| json }
+      end
+
+      #
+      # downloading sample file
+      #
+      # @param [String] sha256 SHA256 for download
+      #
+      # @return [Hash]
+      #
+      def sample(sha256)
+        _get("/overview/#{sha256}/sample") { |json| json }
+      end
+    end
+  end
+end

data/lib/hybridanalysis/clients/quick_scan.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module HybridAnalysis
+  module Clients
+    class QuickScan < Client
+      #
+      # return list of available scanners
+      #
+      # @return [Array]
+      #
+      def state
+        _get("/quick-scan/state") { |json| json }
+      end
+
+      #
+      # submit a file for quick scan, you can check results in overview endpoint
+      #
+      # @param [String] scan_type Type of scan, please see /quick-scan/state to see available scanners
+      # @param [String] file File to submit
+      # @param [Boolean, nil] no_share_third_party When set to 'true', the sample is never shared with any third party. Default: true
+      # @param [Boolean, nil] allow_community_access When set to 'true', the sample will be available for the community. Default: true (Note: when 'no_share_third_party' is set to 'false', it won't be possible to set different value than 'true')
+      # @param [String, nil] comment Optional comment text that may be associated with the submission/sample (Note: you can use #tags here)
+      # @param [String, nil] submit_name Optional 'submission name' field that will be used for file type detection and analysis
+      #
+      # @return [Hash]
+      #
+      def file(scan_type:, file:, no_share_third_party: nil, allow_community_access: nil, comment: nil, submit_name: nil)
+        name = File.basename(file)
+        data = File.read(file)
+
+        params = {
+          scan_type: scan_type,
+          no_share_third_party: no_share_third_party,
+          allow_community_access: allow_community_access,
+          comment: comment,
+          submit_name: submit_name
+        }.compact
+
+        _post_with_file("/quick-scan/file", file: data, filename: name, params: params) { |json| json }
+      end
+
+      #
+      # submit a website's url or url with file for analysis
+      #
+      # @param [String] scan_type type of scan, please see /quick-scan/state to see available scanners
+      # @param [String] url website's url or url with file to submit
+      # @param [Boolean, nil] no_share_third_party When set to 'true', the sample is never shared with any third party. Default: true
+      # @param [Boolean, nil] allow_community_access When set to 'true', the sample will be available for the community. Default: true (Note: when 'no_share_third_party' is set to 'false', it won't be possible to set different value than 'true')
+      # @param [String, nil] comment Optional comment text that may be associated with the submission/sample (Note: you can use #tags here)
+      # @param [String, nil] submit_name Optional 'submission name' field that will be used for file type detection and analysis
+      #
+      # @return [Hash]
+      #
+      def url(scan_type:, url:, no_share_third_party: nil, allow_community_access: nil, comment: nil, submit_name: nil)
+        params = {
+          scan_type: scan_type,
+          url: url,
+          no_share_third_party: no_share_third_party,
+          allow_community_access: allow_community_access,
+          comment: comment,
+          submit_name: submit_name
+        }.compact
+        _post("/quick-scan/url", params) { |json| json }
+      end
+
+      #
+      # some scanners need time to process file, if in response `finished` is set to false, then you need use this endpoint to get final results
+      #
+      # @param [String] id id of scan
+      #
+      # @return [Hash]
+      #
+      def get(id)
+        _get("/quick-scan/#{id}") { |json| json }
+      end
+
+      #
+      # convert quick scan to sandbox report
+      #
+      # @param [String] id ID of quick scan to convert
+      # @param [Integer, nil] environment_id Environment ID. Available environments ID: <strong>300</strong>: 'Linux (Ubuntu 16.04, 64 bit)', <strong>200</strong>: 'Android Static Analysis', <strong>120</strong>: 'Windows 7 64 bit', <strong>110</strong>: 'Windows 7 32 bit (HWP Support)', <strong>100</strong>: 'Windows 7 32 bit'
+      # @param [Boolean, nil] no_hash_lookup Default: false
+      # @param [String, nil] action_script Optional custom runtime action script. Available runtime scripts: **default**, **default_maxantievasion**, **default_randomfiles**, **default_randomtheme**, **default_openie**
+      # @param [Boolean, nil] hybrid_analysis When set to 'false', no memory dumps or memory dump analysis will take place. Default: true
+      # @param [Boolean, nil] experimental_anti_evasion When set to 'true', will set all experimental anti-evasion options of the Kernelmode Monitor. Default: false
+      # @param [Boolean, nil] script_logging When set to 'true', will set the in-depth script logging engine of the Kernelmode Monitor. Default: false
+      # @param [Boolean, nil] input_sample_tampering When set to 'true', will allow experimental anti-evasion options of the Kernelmode Monitor that tamper with the input sample. Default: false
+      # @param [Boolean, nil] tor_enabled_analysis When set to 'true', will route the network traffic for the analysis via TOR (if properly configured on the server). Default: false
+      # @param [Boolean, nil] offline_analysis When set to “true”, will disable outbound network traffic for the guest VM (takes precedence over ‘tor_enabled_analysis’ if both are provided). Default: false
+      # @param [String, nil] email Optional E-Mail address that may be associated with the submission for notification
+      # @param [String, nil] comment Optional comment text that may be associated with the submission/sample (Note: you can use #tags here)
+      # @param [String, nil] custom_date_time Optional custom date/time that can be set for the analysis system. Expected format: yyyy-MM-dd HH:mm
+      # @param [String, nil] custom_cmd_line Optional commandline that should be passed to the analysis file
+      # @param [Integer, nil] custom_run_time Optional runtime duration (in seconds)
+      # @param [String, nil] submit_name Optional 'submission name' field that will be used for file type detection and analysis
+      # @param [String, nil] document_password Optional document password that will be used to fill-in Adobe/Office password prompts
+      # @param [String, nil] environment_variable Optional system environment value. The value is provided in the format: name=value
+      #
+      # @return [Hash]
+      #
+      def convert_to_full(id, environment_id:, no_hash_lookup: nil, action_script: nil, hybrid_analysis: nil, experimental_anti_evasion: nil, script_logging: nil, input_sample_tampering: nil, tor_enabled_analysis: nil, offline_analysis: nil, email: nil, comment: nil, custom_date_time: nil, custom_cmd_line: nil, custom_run_time: nil, submit_name: nil, document_password: nil, environment_variable: nil)
+        params = {
+          environment_id: environment_id,
+          no_hash_lookup: no_hash_lookup,
+          action_script: action_script,
+          hybrid_analysis: hybrid_analysis,
+          experimental_anti_evasion: experimental_anti_evasion,
+          script_logging: script_logging,
+          input_sample_tampering: input_sample_tampering,
+          tor_enabled_analysis: tor_enabled_analysis,
+          offline_analysis: offline_analysis,
+          email: email,
+          comment: comment,
+          custom_date_time: custom_date_time,
+          custom_cmd_line: custom_cmd_line,
+          custom_run_time: custom_run_time,
+          submit_name: submit_name,
+          document_password: document_password,
+          environment_variable: environment_variable
+        }.compact
+
+        _post("/quick-scan/#{id}/convert-to-full", params) { |json| json }
+      end
+    end
+  end
+end

data/lib/hybridanalysis/clients/report.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module HybridAnalysis
+  module Clients
+    class Report < Client
+      #
+      # downloading certificate file from report (is available)
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def certificate(id)
+        _get("/report/#{id}/certificate") { |json| json }
+      end
+
+      #
+      # downloading process memory dump files as zip file (is available)
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def memory_dumps(id)
+        _get("/report/#{id}/memory-dumps") { |json| json }
+      end
+
+      #
+      # downloading network PCAP file from report (is available)
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def pcap(id)
+        _get("/report/#{id}/pcap") { |json| json }
+      end
+
+      #
+      # downloading sample file
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def sample(id)
+        _get("/report/#{id}/sample") { |json| json }
+      end
+
+      #
+      # return state of a submission
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def state(id)
+        _get("/report/#{id}/state") { |json| json }
+      end
+
+      #
+      # return summary of a submission
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def summary(id)
+        _get("/report/#{id}/summary") { |json| json }
+      end
+
+      #
+      # return summary of multiple submissions (bulk query)
+      #
+      # @param [Array<String>] hashes[] List of ids. Allowed format: jobId, md5:environmentId, sha1:environmentId or sha256:environmentId
+      #
+      # @return [Array]
+      #
+      def summaries(*hashes)
+        params = { "hashes[]": hashes }.compact
+        _post("/report/summary", params) { |json| json }
+      end
+
+      #
+      # downloading report data (e.g. JSON, XML, PCAP)
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      # @param [String] type Type of requested report,
+      #
+      # @return [Hash]
+      #
+      def get(id:, type: )
+        _get("/report/#{id}/report/#{type}") { |json| json }
+      end
+
+      #
+      # retrieve an array of screenshots from a report in the Base64 format
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def screenshots(id)
+        _get("/report/#{id}/screenshots") { |json| json }
+      end
+
+      #
+      # retrieve single extracted/dropped binaries files for a report
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      # @param [String] hash SHA256 of dropped file
+      #
+      # @return [Hash]
+      #
+      def dropped_file_raw(id:, hash: )
+        _get("/report/#{id}/dropped-file-raw/#{hash}") { |json| json }
+      end
+
+      #
+      # retrieve all extracted/dropped binaries files for a report, as zip
+      #
+      # @param [String] id Id in one of format: 'jobId' or 'sha256:environmentId'
+      #
+      # @return [Hash]
+      #
+      def dropped_files(id)
+        _get("/report/#{id}/dropped-files") { |json| json }
+      end
+    end
+  end
+end

data/lib/hybridanalysis/clients/search.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module HybridAnalysis
+  module Clients
+    class Search < Client
+      #
+      # summary for given hash
+      #
+      # @param [String] hash MD5, SHA1 or SHA256
+      #
+      # @return [Array]
+      #
+      def hash(hash)
+        params = { hash: hash }.compact
+        _post("/search/hash", params) { |json| json }
+      end
+
+      #
+      # summary for given hashes
+      #
+      # @param [Array<String>] List of hashes. Allowed type: MD5, SHA1 or SHA256
+      #
+      # @return [Array]
+      #
+      def hashes(*hashes)
+        params = { "hashes[]": hashes }.compact
+        _post("/search/hashes", params) { |json| json }
+      end
+
+      #
+      # search the database using the search terms
+      #
+      # @param [String, nil] filename Filename e.g. invoice.exe
+      # @param [String, nil] filetype Filetype e.g. docx <p>Available options: .NET exe, 64-bit .NET exe, 64-bit dll, 64-bit exe, 64-bit service, apk, bat, cmd, com, csv, bash, chm, composite, database, dll, doc, docx, dos, empty, exe, elf, 64-bit elf, file link, gen link, hta, html, hwp, hwpx, image, iqy, java jar, js, jse, lib, mach-o, 64-bit mach-o, mime, msg, msi, pdf, perl, ppt, pptx, ps1, psd1, psm1, pub, python, sct, raw data, rtf, service, svg, swf, text, url, vbe, vbs, wsf, xls, xlsx, zip</p>
+      # @param [String, nil] filetype_desc Filetype description e.g. PE32 executable
+      # @param [String, nil] env_id Environment Id
+      # @param [String, nil] country Country (3 digit ISO) e.g. swe
+      # @param [Integer, nil] verdict Verdict e.g. 1 <p>Available options: <strong>1</strong> 'whitelisted', <strong>2</strong> 'no verdict', <strong>3</strong> 'no specific threat', <strong>4</strong> 'suspicious', <strong>5</strong> 'malicious'</p>
+      # @param [String, nil] av_detect AV Multiscan range e.g. 50-70 (min 0, max 100)
+      # @param [String, nil] vx_family AV Family Substring e.g. nemucod
+      # @param [String, nil] tag Hashtag e.g. ransomware
+      # @param [String, nil] date_from Date from in format: 'Y-m-d H:i:s' e.g. 2018-09-28 15:30:00
+      # @param [String, nil] date_to Date to in format: 'Y-m-d H:i:s' e.g. 2018-09-28 15:30:00
+      # @param [Integer, nil] port Port e.g. 8080
+      # @param [String, nil] host Host e.g. 192.168.0.1
+      # @param [String, nil] domain Domain e.g. checkip.dyndns.org
+      # @param [String, nil] url HTTP Request Substring e.g. google
+      # @param [String, nil] similar_to Similar Samples e.g. \<sha256\>
+      # @param [String, nil] context Sample Context e.g. \<sha256\>
+      # @param [String, nil] imp_hash
+      # @param [String, nil] ssdeep
+      # @param [String, nil] authentihash
+      # @param [Boolean, nil] uses_tactic Uses Tactic
+      # @param [Boolean, nil] uses_technique Uses Technique
+      #
+      # @return [Hash]
+      #
+      def terms(filename: nil, filetype: nil, filetype_desc: nil, env_id: nil, country: nil, verdict: nil, av_detect: nil, vx_family: nil, tag: nil, date_from: nil, date_to: nil, port: nil, host: nil, domain: nil, url: nil, similar_to: nil, context: nil, imp_hash: nil, ssdeep: nil, authentihash: nil, uses_tactic: nil, uses_technique: nil)
+        params = {
+          filename: filename,
+          filetype: filetype,
+          filetype_desc: filetype_desc,
+          env_id: env_id,
+          country: country,
+          verdict: verdict,
+          av_detect: av_detect,
+          vx_family: vx_family,
+          tag: tag,
+          date_from: date_from,
+          date_to: date_to,
+          port: port,
+          host: host,
+          domain: domain,
+          url: url,
+          similar_to: similar_to,
+          context: context,
+          imp_hash: imp_hash,
+          ssdeep: ssdeep,
+          authentihash: authentihash,
+          uses_tactic: uses_tactic,
+          uses_technique: uses_technique
+        }.compact
+        _post("/search/terms", params) { |json| json }
+      end
+    end
+  end
+end