mihari 3.5.0 → 3.7.1

data/lib/mihari/analyzers/otx.rb

@@ -39,10 +39,20 @@ module Mihari
         @ip_client ||= ::OTX::IP.new(Mihari.config.otx_api_key)
       end
 
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_type?
         %w[ip domain].include? type
       end
 
+      #
+      # IP/domain search
+      #
+      # @return [Array<String>]
+      #
       def search
         case type
         when "domain"
@@ -54,6 +64,11 @@ module Mihari
         end
       end
 
+      #
+      # Domain search
+      #
+      # @return [Array<String>]
+      #
       def domain_search
         records = domain_client.get_passive_dns(query)
         records.filter_map do |record|
@@ -61,6 +76,11 @@ module Mihari
         end.uniq
       end
 
+      #
+      # IP search
+      #
+      # @return [Array<String>]
+      #
       def ip_search
         records = ip_client.get_passive_dns(query)
         records.filter_map do |record|

data/lib/mihari/analyzers/passivetotal.rb

@@ -35,10 +35,20 @@ module Mihari
         @api ||= ::PassiveTotal::API.new(username: Mihari.config.passivetotal_username, api_key: Mihari.config.passivetotal_api_key)
       end
 
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_type?
         %w[ip domain mail hash].include? type
       end
 
+      #
+      # Passive DNS/SSL, reverse whois search
+      #
+      # @return [Array<String>]
+      #
       def search
         case type
         when "domain", "ip"
@@ -52,11 +62,21 @@ module Mihari
         end
       end
 
+      #
+      # Passive DNS search
+      #
+      # @return [Array<String>]
+      #
       def passive_dns_search
         res = api.dns.passive_unique(query)
         res["results"] || []
       end
 
+      #
+      # Reverse whois search
+      #
+      # @return [Array<String>]
+      #
       def reverse_whois_search
         res = api.whois.search(query: query, field: "email")
         results = res["results"] || []
@@ -65,6 +85,11 @@ module Mihari
         end.flatten.compact.uniq
       end
 
+      #
+      # Passive SSL search
+      #
+      # @return [Array<String>]
+      #
       def ssl_search
         res = api.ssl.history(query)
         results = res["results"] || []

data/lib/mihari/analyzers/pulsedive.rb

@@ -35,10 +35,20 @@ module Mihari
         @api ||= ::Pulsedive::API.new(Mihari.config.pulsedive_api_key)
       end
 
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_type?
         %w[ip domain].include? type
       end
 
+      #
+      # Search
+      #
+      # @return [Array<String>]
+      #
       def search
         raise InvalidInputError, "#{query}(type: #{type || "unknown"}) is not supported." unless valid_type?
 

data/lib/mihari/analyzers/rule.rb

@@ -22,6 +22,8 @@ module Mihari
         super(**kwargs)
 
         @source = id || UUIDTools::UUID.md5_create(UUIDTools::UUID_URL_NAMESPACE, title + description).to_s
+
+        validate_analyzer_configurations
       end
 
       ANALYZER_TO_CLASS = {
@@ -119,6 +121,22 @@ module Mihari
 
         raise ArgumentError, "#{analyzer_name} is not supported"
       end
+
+      #
+      # Validate configuration of analyzers
+      #
+      def validate_analyzer_configurations
+        queries.each do |params|
+          analyzer_name = params[:analyzer]
+          klass = get_analyzer_class(analyzer_name)
+
+          instance = klass.new("dummy")
+          unless instance.configured?
+            klass_name = klass.to_s.split("::").last
+            raise ArgumentError, "#{klass_name} is not configured correctly"
+          end
+        end
+      end
     end
   end
 end

data/lib/mihari/analyzers/securitytrails.rb

@@ -35,10 +35,20 @@ module Mihari
         @api ||= ::SecurityTrails::API.new(Mihari.config.securitytrails_api_key)
       end
 
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_type?
         %w[ip domain mail].include? type
       end
 
+      #
+      # IP/domain/mail search
+      #
+      # @return [Array<String>]
+      #
       def search
         case type
         when "domain"
@@ -52,6 +62,11 @@ module Mihari
         end
       end
 
+      #
+      # Domain search
+      #
+      # @return [Array<String>]
+      #
       def domain_search
         result = api.history.get_all_dns_history(query, type: "a")
         records = result["records"] || []
@@ -60,12 +75,22 @@ module Mihari
         end.flatten.compact.uniq
       end
 
+      #
+      # IP search
+      #
+      # @return [Array<String>]
+      #
       def ip_search
         result = api.domains.search(filter: { ipv4: query })
         records = result["records"] || []
         records.filter_map { |record| record["hostname"] }.uniq
       end
 
+      #
+      # Mail search
+      #
+      # @return [Array<String>]
+      #
       def mail_search
         result = api.domains.search(filter: { whois_email: query })
         records = result["records"] || []

data/lib/mihari/analyzers/shodan.rb

@@ -14,12 +14,11 @@ module Mihari
         results = search
         return [] unless results || results.empty?
 
+        results = results.map { |result| Structs::Shodan::Result.from_dynamic!(result) }
         results.map do |result|
-          matches = result["matches"] || []
-          matches.filter_map do |match|
-            match["ip_str"]
-          end
-        end.flatten.compact.uniq
+          matches = result.matches || []
+          matches.map { |match| build_artifact match }
+        end.flatten.compact.uniq(&:data)
       end
 
       private
@@ -34,6 +33,14 @@ module Mihari
         @api ||= ::Shodan::API.new(key: Mihari.config.shodan_api_key)
       end
 
+      #
+      # Search with pagination
+      #
+      # @param [String] query
+      # @param [Integer] page
+      #
+      # @return [Hash]
+      #
       def search_with_page(query, page: 1)
         api.host.search(query, page: page)
       rescue ::Shodan::Error => e
@@ -42,6 +49,11 @@ module Mihari
         raise e
       end
 
+      #
+      # Search
+      #
+      # @return [Array<Hash>]
+      #
       def search
         responses = []
         (1..Float::INFINITY).each do |page|
@@ -57,6 +69,28 @@ module Mihari
         end
         responses
       end
+
+      #
+      # Build an artifact from a Shodan search API response
+      #
+      # @param [Structs::Shodan::Match] match
+      #
+      # @return [Artifact]
+      #
+      def build_artifact(match)
+        as = AutonomousSystem.new(asn: normalize_asn(match.asn))
+        geolocation = Geolocation.new(
+          country: match.location.country_name,
+          country_code: match.location.country_code
+        )
+
+        Artifact.new(
+          data: match.ip_str,
+          source: source,
+          autonomous_system: as,
+          geolocation: geolocation
+        )
+      end
     end
   end
 end

data/lib/mihari/analyzers/spyse.rb

@@ -30,10 +30,20 @@ module Mihari
         @api ||= ::Spyse::API.new(Mihari.config.spyse_api_key)
       end
 
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_type?
         %w[ip domain cert].include? type
       end
 
+      #
+      # Domain search
+      #
+      # @return [Array<String>]
+      #
       def domain_search
         res = api.domain.search(search_params, limit: 100)
         items = res.dig("data", "items") || []
@@ -42,6 +52,11 @@ module Mihari
         end.uniq.compact
       end
 
+      #
+      # IP search
+      #
+      # @return [Array<String>]
+      #
       def ip_search
         res = api.ip.search(search_params, limit: 100)
         items = res.dig("data", "items") || []
@@ -50,6 +65,11 @@ module Mihari
         end.uniq.compact
       end
 
+      #
+      # IP/domain search
+      #
+      # @return [Array<String>]
+      #
       def search
         case type
         when "domain"

data/lib/mihari/analyzers/urlscan.rb

@@ -43,12 +43,22 @@ module Mihari
         @api ||= ::UrlScan::API.new(Mihari.config.urlscan_api_key)
       end
 
+      #
+      # Search
+      #
+      # @return [Array<Hash>]
+      #
       def search
         return api.pro.similar(query) if use_similarity
 
         api.search(query, size: 10_000)
       end
 
+      #
+      # Check whether a data type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_alllowed_data_types?
         allowed_data_types.all? { |type| SUPPORTED_DATA_TYPES.include? type }
       end

data/lib/mihari/analyzers/virustotal.rb

@@ -35,10 +35,20 @@ module Mihari
         @api = ::VirusTotal::API.new(key: Mihari.config.virustotal_api_key)
       end
 
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_type?
         %w[ip domain].include? type
       end
 
+      #
+      # Search
+      #
+      # @return [Array<String>]
+      #
       def search
         case type
         when "domain"
@@ -50,6 +60,11 @@ module Mihari
         end
       end
 
+      #
+      # Domain search
+      #
+      # @return [Array<String>]
+      #
       def domain_search
         res = api.domain.resolutions(query)
 
@@ -59,6 +74,11 @@ module Mihari
         end.uniq
       end
 
+      #
+      # IP search
+      #
+      # @return [Array<String>]
+      #
       def ip_search
         res = api.ip_address.resolutions(query)
 

data/lib/mihari/analyzers/zoomeye.rb

@@ -26,6 +26,11 @@ module Mihari
 
       PAGE_SIZE = 10
 
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
       def valid_type?
         %w[host web].include? type
       end
@@ -38,6 +43,13 @@ module Mihari
         @api ||= ::ZoomEye::API.new(api_key: Mihari.config.zoomeye_api_key)
       end
 
+      #
+      # Convert responses into an array of String
+      #
+      # @param [Array<Hash>] responses
+      #
+      # @return [Array<String>]
+      #
       def convert_responses(responses)
         responses.map do |res|
           matches = res["matches"] || []
@@ -47,12 +59,25 @@ module Mihari
         end.flatten.compact.uniq
       end
 
+      #
+      # Host search
+      #
+      # @param [String] query
+      # @param [Integer] page
+      #
+      # @return [Hash, nil]
+      #
       def _host_search(query, page: 1)
         api.host.search(query, page: page)
       rescue ::ZoomEye::Error => _e
         nil
       end
 
+      #
+      # Host search
+      #
+      # @return [Array<String>]
+      #
       def host_search
         responses = []
         (1..Float::INFINITY).each do |page|
@@ -66,12 +91,25 @@ module Mihari
         convert_responses responses.compact
       end
 
+      #
+      # Web search
+      #
+      # @param [String] query
+      # @param [Integer] page
+      #
+      # @return [Hash, nil]
+      #
       def _web_search(query, page: 1)
         api.web.search(query, page: page)
       rescue ::ZoomEye::Error => _e
         nil
       end
 
+      #
+      # Web search
+      #
+      # @return [Array<String>]
+      #
       def web_search
         responses = []
         (1..Float::INFINITY).each do |page|