feat: add Validin integration (#1083)

.shadowenv.d/000_unset_all.lisp

@@ -35,5 +35,6 @@
 (env/set "THEHIVE_API_KEY" ())
 (env/set "THEHIVE_URL" ())
 (env/set "URLSCAN_API_KEY" ())
+(env/set "VALIDIN_API_KEY" ())
 (env/set "VIRUSTOTAL_API_KEY" ())
 (env/set "ZOOMEYE_API_KEY" ())

docs/analyzers/validin.md

@@ -0,0 +1,36 @@
+---
+tags:
+  - Artifact:IP
+  - Artifact:Domain
+  - Passive DNS
+  - Reverse Whois
+---
+
+# Validin
+
+- https://www.validin.com/
+
+This analyzer uses [Validin API](https://app.validin.com/docs).
+
+An API endpoint to use is changed based on a type of a query.
+
+| Query type | API endpoint                             | Artifact   |
+| ---------- | ---------------------------------------- | ---------- |
+| IP address | `/api/axon/domain/dns/history/:domain/A` | Domain     |
+| Domain     | `/api/axon/ip/dns/history/:ip`           | IP address |
+
+```yaml
+analyzer: validin
+query: ...
+api_key: ...
+```
+
+## Components
+
+### Query
+
+`query` (`string`) is a domain or an IP address.
+
+### API Key
+
+`api_key` (`string`) is an API key. Optional. Configurable via `VALIDIN_API_KEY` environment variable.

docs/configuration.md

@@ -21,6 +21,7 @@ Alternatively you can set values through `.env` file. Values in `.env` file will
 | SECURITYTRAILS_API_KEY | String | SecurityTrails API key         |         |
 | SHODAN_API_KEY         | String | Shodan API key                 |         |
 | URLSCAN_API_KEY        | String | urlscan.io API key             |         |
+| VALIDIN_API_KEY        | String | Validin API key                |         |
 | VIRUSTOTAL_API_KEY     | String | VirusTotal API key             |         |
 | ZOOMEYE_API_KEY        | String | ZoomEye API key                |         |
 

lib/mihari.rb

@@ -268,6 +268,7 @@ def initialize_sentry
 require "mihari/analyzers/securitytrails"
 require "mihari/analyzers/shodan"
 require "mihari/analyzers/urlscan"
+require "mihari/analyzers/validin"
 require "mihari/analyzers/virustotal_intelligence"
 require "mihari/analyzers/virustotal"
 require "mihari/analyzers/zoomeye"

lib/mihari/analyzers/validin.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "mihari/clients/validin"
+
+module Mihari
+  module Analyzers
+    #
+    # Validin analyzer
+    #
+    class Validin < Base
+      include Concerns::Refangable
+
+      # @return [String, nil]
+      attr_reader :type
+
+      # @return [String, nil]
+      attr_reader :username
+
+      # @return [String, nil]
+      attr_reader :api_key
+
+      #
+      # @param [String] query
+      # @param [Hash, nil] options
+      # @param [String, nil] api_key
+      #
+      def initialize(query, options: nil, api_key: nil)
+        super(refang(query), options:)
+
+        @type = DataType.type(query)
+
+        @api_key = api_key || Mihari.config.validin_api_key
+      end
+
+      def artifacts
+        case type
+        when "domain"
+          dns_history_search
+        when "ip"
+          reverse_ip_search
+        else
+          raise ValueError, "#{query}(type: #{type || "unknown"}) is not supported." unless valid_type?
+        end
+      end
+
+      private
+
+      def dns_history_search
+        res = client.dns_history_search(query)
+        (res.dig("records", "A") || []).filter_map do |r|
+          r["value"]
+        end
+      end
+
+      def reverse_ip_search
+        res = client.dns_history_search(query)
+        (res.dig("records", "A") || []).filter_map do |r|
+          r["value"]
+        end
+      end
+
+      def client
+        Clients::Validin.new(api_key:, timeout:)
+      end
+
+      #
+      # Check whether a type is valid or not
+      #
+      # @return [Boolean]
+      #
+      def valid_type?
+        %w[ip domain].include? type
+      end
+    end
+  end
+end

lib/mihari/clients/validin.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mihari
+  module Clients
+    #
+    # Validin API client
+    #
+    class Validin < Base
+      #
+      # @param [String] base_url
+      # @param [String, nil] api_key
+      # @param [Hash] headers
+      # @param [Integer, nil] timeout
+      #
+      def initialize(
+        base_url = "https://app.validin.com",
+        api_key:,
+        headers: {},
+        timeout: nil
+      )
+        raise(ArgumentError, "api_key is required") if api_key.nil?
+
+        headers["Authorization"] = "Bearer #{api_key}"
+
+        super(base_url, headers:, timeout:)
+      end
+
+      #
+      # @param [String] domain
+      #
+      # @return [Hash]
+      #
+      def dns_history_search(domain)
+        get_json "/api/axon/domain/dns/history/#{domain}/A"
+      end
+
+      #
+      # @param [String] ip
+      #
+      # @return [Hash]
+      #
+      def search_reverse_ip(ip)
+        get_json "/api/axon/ip/dns/history/#{ip}"
+      end
+    end
+  end
+end

lib/mihari/config.rb

@@ -33,6 +33,7 @@ class Config < Anyway::Config
       thehive_api_key: nil,
       thehive_url: nil,
       urlscan_api_key: nil,
+      validin_api_key: nil,
       virustotal_api_key: nil,
       yeti_api_key: nil,
       yeti_url: nil,
@@ -122,6 +123,9 @@ class Config < Anyway::Config
     # @!attribute [r] urlscan_api_key
     #   @return [String, nil]
 
+    # @!attribute [r] validin_api_key
+    #   @return [String, nil]
+
     # @!attribute [r] virustotal_api_key
     #   @return [String, nil]
 

lib/mihari/schemas/analyzer.rb

@@ -15,6 +15,7 @@ module Analyzers
         Mihari::Analyzers::Onyphe.keys,
         Mihari::Analyzers::Shodan.keys,
         Mihari::Analyzers::Urlscan.keys,
+        Mihari::Analyzers::Validin.keys,
         Mihari::Analyzers::VirusTotalIntelligence.keys
       ].each do |keys|
         key = keys.first

spec/analyzers/validin_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe Mihari::Analyzers::Validin, :vcr do
+  subject(:analyzer) { described_class.new(query) }
+
+  context "with ip" do
+    let(:query) { "1.1.1.1" }
+
+    describe "#artifacts" do
+      it do
+        expect(analyzer.artifacts).to be_an(Array)
+      end
+    end
+  end
+
+  context "with domain" do
+    let(:query) { "example.com" }
+
+    describe "#artifacts" do
+      it do
+        expect(analyzer.artifacts).to be_an(Array)
+      end
+    end
+  end
+end