ronin-recon 0.1.0.rc1

data/lib/ronin/recon/scope.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+#
+# ronin-recon - A micro-framework and tool for performing reconnaissance.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-recon is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-recon is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-recon.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/recon/values/wildcard'
+require 'ronin/recon/values/domain'
+require 'ronin/recon/values/host'
+require 'ronin/recon/values/ip_range'
+require 'ronin/recon/values/ip'
+
+module Ronin
+  module Recon
+    #
+    # Defines which domains, hosts, IP addresses are considered "in scope".
+    #
+    # @api private
+    #
+    class Scope
+
+      # List of domain or IP range values which are considered "in scope".
+      #
+      # @return [Array<Values::Domain, Values::Host, Values::IPRange, Values::IP>]
+      attr_reader :values
+
+      # The list of values to ignore and are not considered "in scope".
+      #
+      # @return [Array<Value>]
+      attr_reader :ignore
+
+      #
+      # Initializes the scope.
+      #
+      # @param [Array<Values::Wildcard, Values::Domain, Values::Host, Values::IPRange, Values::IP>] values
+      #   The list of "in scope" values.
+      #
+      # @param [Array<Value>] ignore
+      #   The recon values to ignore and are not "in scope".
+      #
+      # @raise [NotImplementedError]
+      #   An unsupported value object was given.
+      #
+      def initialize(values, ignore: [])
+        @values = values
+        @ignore = ignore
+
+        @host_values = []
+        @ip_values   = []
+
+        values.each do |value|
+          case value
+          when Values::Wildcard, Values::Domain, Values::Host
+            @host_values << value
+          when Values::IP, Values::IPRange
+            @ip_values << value
+          else
+            raise(NotImplementedError,"scope value type not supported: #{value.inspect}")
+          end
+        end
+      end
+
+      #
+      # Determines if a value is "in scope".
+      #
+      # @param [Value] value
+      #   The value to check.
+      #
+      # @return [Boolean]
+      #   Indicates whether the value is "in scope" or not.
+      #   If the given value is not a {Values::Domain Domain},
+      #   {Values::Host Host}, {Values::IPRange IPRange}, or {Values::IP IP}
+      #   then `true` is returned by default.
+      #
+      def include?(value)
+        scope_values = case value
+                       when Values::Wildcard,
+                            Values::Domain,
+                            Values::Host,
+                            Values::URL
+                         @host_values
+                       when Values::IP,
+                            Values::IPRange
+                         @ip_values
+                       end
+
+        return false if @ignore.any? { |ignore| ignore === value }
+
+        if (scope_values && !scope_values.empty?)
+          scope_values.any? { |scope_value| scope_value === value }
+        else
+          true
+        end
+      end
+
+    end
+  end
+end

data/lib/ronin/recon/value/parser.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+#
+# ronin-recon - A micro-framework and tool for performing reconnaissance.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-recon is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-recon is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-recon.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/recon/values/host'
+require 'ronin/recon/values/domain'
+require 'ronin/recon/values/wildcard'
+require 'ronin/recon/values/ip'
+require 'ronin/recon/values/ip_range'
+require 'ronin/recon/values/website'
+require 'ronin/recon/exceptions'
+
+require 'ronin/support/network/ip'
+require 'ronin/support/network/ip_range'
+require 'ronin/support/text/patterns/network'
+require 'ronin/support/network/public_suffix'
+
+require 'ipaddr'
+require 'uri'
+
+module Ronin
+  module Recon
+    #
+    # Base class for all {Values} classes.
+    #
+    class Value
+
+      #
+      # Module that parses strings into {Values::IP}, {Values::IPRange},
+      # {Values::Domain}, {Values::Host}, or {Values::Website}.
+      #
+      module Parser
+        # Regular expression to match IPv4 and IPv6 addresses.
+        IP_REGEX = Support::Network::IP::REGEX
+
+        # Regular expression to match IPv4 and IPv6 CIDR ranges.
+        IP_RANGE_REGEX = Support::Network::IPRange::REGEX
+
+        # Regular expression to match sub-domain host-names.
+        HOSTNAME_REGEX = /\A(?:[a-zA-Z0-9_-]{1,63}\.)+#{Support::Text::Patterns::DOMAIN}\z/
+
+        # Regular expression to match domain host-names.
+        DOMAIN_REGEX = /\A#{Support::Text::Patterns::DOMAIN}\z/
+
+        # Regular expression to match wildcard host-names.
+        WILDCARD_REGEX = /\A\*(?:\.[a-z0-9_-]+)+\z/
+
+        # Regular expression to match https:// and http:// website base URLs.
+        WEBSITE_REGEX = %r{\Ahttp(?:s)?://[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*(?::\d+)?/?\z}
+
+        #
+        # Parses a value string.
+        #
+        # @param [String] string
+        #   The string to parse.
+        #
+        # @return [Values::IP, Values::IPRange, Values::Host, Values::Domain, Values::Wildcard, Values::Website]
+        #   The parsed value.
+        #
+        # @raise [UnknownValue]
+        #   Could not identify what value the string represents.
+        #
+        def self.parse(string)
+          case string
+          when IP_REGEX       then Values::IP.new(string)
+          when IP_RANGE_REGEX then Values::IPRange.new(string)
+          when WEBSITE_REGEX  then Values::Website.parse(string)
+          when WILDCARD_REGEX then Values::Wildcard.new(string)
+          when HOSTNAME_REGEX then Values::Host.new(string)
+          when DOMAIN_REGEX   then Values::Domain.new(string)
+          else
+            raise(UnknownValue,"unrecognized recon value: #{string.inspect}")
+          end
+        end
+      end
+
+      #
+      # Parses a value string.
+      #
+      # @param [String] string
+      #   The string to parse.
+      #
+      # @return [Values::IP, Values::IPRange, Values::Host, Values::Domain, Values::Wildcard, Values::Website]
+      #   The parsed value.
+      #
+      # @raise [UnknownValue]
+      #   Could not identify what value the string represents.
+      #
+      # @see Parser.parse
+      #
+      def self.parse(string)
+        Parser.parse(string)
+      end
+
+    end
+  end
+end

data/lib/ronin/recon/value.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+#
+# ronin-recon - A micro-framework and tool for performing reconnaissance.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-recon is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-recon is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-recon.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'json'
+require 'csv'
+
+module Ronin
+  module Recon
+    #
+    # Base class for all {Values} classes.
+    #
+    class Value
+
+      #
+      # Returns the type or kind of recon value.
+      #
+      # @return [Symbol]
+      #
+      # @note
+      #   This is used internally to map a recon value class to a printable
+      #   type.
+      #
+      # @abstract
+      #
+      # @api private
+      #
+      def self.value_type
+        raise(NotImplementedError,"#{self}.value_type was not defined")
+      end
+
+      #
+      # Compares the value to another value.
+      #
+      # @param [Object] other
+      #   The other value.
+      #
+      # @return [Boolean]
+      #   Indicates that the value matches the other value.
+      #
+      def ==(other)
+        eql?(other)
+      end
+
+      #
+      # Coerces the value into JSON.
+      #
+      # @return [Hash{Symbol => Object}]
+      #   The Ruby Hash that will be converted into JSON.
+      #
+      # @abstract
+      #
+      def as_json
+        raise(NotImplementedError,"#{self.class}#as_json was not implemented")
+      end
+
+      #
+      # Converts the value to a String.
+      #
+      # @return [String]
+      #   The string value of the value.
+      #
+      # @abstract
+      #
+      def to_s
+        raise(NotImplementedError,"#{self.class}#to_s was not implemented")
+      end
+
+      #
+      # Converts the value into JSON.
+      #
+      # @param [Array] args
+      #   Additional arguments for `Hash#to_json`.
+      #
+      # @return [String]
+      #   The raw JSON string.
+      #
+      def to_json(*args)
+        as_json.to_json(*args)
+      end
+
+      #
+      # Converts the value to a CSV row.
+      #
+      # @return [String]
+      #   The CSV row.
+      #
+      def to_csv
+        CSV.generate_line([self.class.value_type,to_s])
+      end
+
+    end
+  end
+end

data/lib/ronin/recon/value_status.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+#
+# ronin-recon - A micro-framework and tool for performing reconnaissance.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-recon is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-recon is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-recon.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Recon
+    #
+    # Represents the status of every value across all queues and workers.
+    #
+    class ValueStatus
+
+      attr_reader :values
+
+      def initialize
+        @values = {}
+      end
+
+      #
+      # Records that a value was enqueued for the given worker class.
+      #
+      # @param [Values::Value] value
+      #
+      # @param [Class<Worker>] worker_class
+      #
+      def value_enqueued(worker_class,value)
+        (@values[value] ||= {})[worker_class] = :enqueued
+      end
+
+      #
+      # Records that a worker has dequeued the value and started processing it.
+      #
+      # @param [Values::Value] value
+      #
+      # @param [Class<Worker>] worker_class
+      #
+      def job_started(worker_class,value)
+        (@values[value] ||= {})[worker_class] = :working
+      end
+
+      #
+      # Records that a worker has completed processing the value.
+      #
+      # @param [Values::Value] value
+      #
+      # @param [Class<Worker>] worker_class
+      #
+      def job_completed(worker_class,value)
+        if (worker_statuses = @values[value])
+          worker_statuses.delete(worker_class)
+
+          if worker_statuses.empty?
+            @values.delete(value)
+          end
+        end
+      end
+
+      alias job_failed job_completed
+
+      #
+      # Determines if there are no more values within the queue or being
+      # processed by any of the workers.
+      #
+      # @return [Boolean]
+      #
+      def empty?
+        @values.empty?
+      end
+
+    end
+  end
+end

data/lib/ronin/recon/values/cert.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+#
+# ronin-recon - A micro-framework and tool for performing reconnaissance.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-recon is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-recon is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-recon.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/recon/value'
+require 'ronin/support/crypto'
+
+module Ronin
+  module Recon
+    module Values
+      #
+      # Represents a SSL/TLS certificate.
+      #
+      class Cert < Value
+
+        # The certificate object.
+        #
+        # @return [Ronin::Support::Crypto::Cert]
+        #
+        # @api private
+        attr_reader :cert
+
+        #
+        # Initializes the certificate value.
+        #
+        # @param [OpenSSL::X509::Certificate] cert
+        #   The decoded X509 certificate.
+        #
+        def initialize(cert)
+          @cert = Support::Crypto::Cert(cert)
+        end
+
+        #
+        # The serial number of the SSL/TLS certificate.
+        #
+        # @return [OpenSSL::BN]
+        #
+        def serial
+          @cert.serial
+        end
+
+        #
+        # When the certificate begins being valid.
+        #
+        # @return [Time]
+        #
+        def not_before
+          @cert.not_before
+        end
+
+        #
+        # When the certificate expires.
+        #
+        # @return [Time]
+        #
+        def not_after
+          @cert.not_after
+        end
+
+        #
+        # The certificate issuer's information.
+        #
+        # @return [OpenSSL::X509::Name]
+        #
+        def issuer
+          @cert.issuer
+        end
+
+        #
+        # The certificate subject's information.
+        #
+        # @return [OpenSSL::X509::Name]
+        #
+        def subject
+          @cert.subject
+        end
+
+        #
+        # Additional certificate extensions.
+        #
+        # @return [Array<OpenSSL::X509::Extensions>]
+        #
+        def extensions
+          @cert.extensions
+        end
+
+        #
+        # Compares the certificate to another value.
+        #
+        # @param [Object] other
+        #
+        # @return [Boolean]
+        #
+        def eql?(other)
+          self.class == other.class && serial == other.serial
+        end
+
+        #
+        # The "hash" value of the certificate.
+        #
+        # @return [Integer]
+        #
+        def hash
+          [self.class, @cert.serial].hash
+        end
+
+        #
+        # Converts the certificate to a string.
+        #
+        # @return [String]
+        #
+        def to_s
+          @cert.to_s
+        end
+
+        #
+        # Converts the certificate to a hash of attributes
+        #
+        # @return [Hash{Symbol => Object}]
+        #
+        def as_json
+          {
+            serial:            @cert.serial,
+            not_before:        @cert.not_before,
+            not_after:         @cert.not_after,
+            subject:           @cert.subject.to_h,
+            issuer:            @cert.issuer.to_h,
+            extensions:        @cert.extensions_hash,
+            subject_alt_names: @cert.subject_alt_names,
+            pem:               @cert.to_pem
+          }
+        end
+
+        #
+        # Returns the type or kind of recon value.
+        #
+        # @return [:cert]
+        #
+        # @note
+        #   This is used internally to map a recon value class to a printable
+        #   type.
+        #
+        # @api private
+        #
+        def self.value_type
+          :cert
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/recon/values/domain.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+#
+# ronin-recon - A micro-framework and tool for performing reconnaissance.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-recon is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-recon is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-recon.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/recon/values/host'
+require 'ronin/recon/values/ip'
+require 'ronin/recon/values/website'
+require 'ronin/recon/values/url'
+
+module Ronin
+  module Recon
+    module Values
+      #
+      # Represents a domain name (ex: `example.com`).
+      #
+      class Domain < Host
+
+        #
+        # Case equality method used for fuzzy matching.
+        #
+        # @param [Value] other
+        #   The other value to compare.
+        #
+        # @return [Boolean]
+        #   Imdicates whether the other value is either a {Domain} and has the
+        #   same domain name, or a {Host}, {IP}, {Website}, {URL} with the same
+        #   domain name.
+        #
+        def ===(other)
+          case other
+          when Domain
+            @name == other.name
+          when Host
+            other.name.end_with?(".#{@name}")
+          when IP, Website, URL
+            if (other_host = other.host)
+              other_host == @name || other_host.end_with?(".#{@name}")
+            end
+          else
+            false
+          end
+        end
+
+        #
+        # Coerces the domain value into JSON.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   The Ruby Hash that will be converted into JSON.
+        #
+        def as_json
+          {type: :domain, name: @name}
+        end
+
+        #
+        # Returns the type or kind of recon value.
+        #
+        # @return [:domain]
+        #
+        # @note
+        #   This is used internally to map a recon value class to a printable
+        #   type.
+        #
+        # @api private
+        #
+        def self.value_type
+          :domain
+        end
+
+      end
+    end
+  end
+end