ronin-recon 0.1.0.rc1

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

@@ -0,0 +1,140 @@
+# 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/recon/values/domain'
+require 'ronin/recon/values/host'
+require 'ronin/recon/values/url'
+
+module Ronin
+  module Recon
+    module Values
+      #
+      # Represents a wildcard host-name (ex: `*.example.com`).
+      #
+      # @api public
+      #
+      class Wildcard < Value
+
+        # The wildcard host name.
+        #
+        # @return [String]
+        attr_reader :template
+
+        #
+        # Initializes the wildcard host object.
+        #
+        # @param [String] template
+        #
+        def initialize(template)
+          @template = template
+
+          @prefix, @suffix = template.split('*',2)
+        end
+
+        #
+        # Compares the value to another value.
+        #
+        # @param [Values::Value] other
+        #
+        # @return [Boolean]
+        #
+        def eql?(other)
+          other.kind_of?(self.class) && @template == other.template
+        end
+
+        #
+        # Case equality method used for fuzzy matching.
+        #
+        # @param [Wildcard, Domain, Host, 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} and shares the same domain name.
+        #
+        def ===(other)
+          case other
+          when Wildcard
+            eql?(other)
+          when Domain, Host
+            name = other.name
+
+            name.start_with?(@prefix) && name.end_with?(@suffix)
+          when URL
+            host = other.uri.host
+
+            host.start_with?(@prefix) && host.end_with?(@suffix)
+          else
+            false
+          end
+        end
+
+        #
+        # The "hash" value of the wildcard host name.
+        #
+        # @return [Integer]
+        #   The hash value of {#template}.
+        #
+        def hash
+          [self.class, @template].hash
+        end
+
+        #
+        # Converts the wildcard host object to a String.
+        #
+        # @return [String]
+        #   The wildcard host name.
+        #
+        def to_s
+          @template.to_s
+        end
+
+        alias to_str to_s
+
+        #
+        # Coerces the wildcard value into JSON.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   The Ruby Hash that will be converted into JSON.
+        #
+        def as_json
+          {type: :wildcard, template: @template}
+        end
+
+        #
+        # Returns the type or kind of recon value.
+        #
+        # @return [:wildcard]
+        #
+        # @note
+        #   This is used internally to map a recon value class to a printable
+        #   type.
+        #
+        # @api private
+        #
+        def self.value_type
+          :wildcard
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/recon/values.rb

@@ -0,0 +1,32 @@
+# 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/nameserver'
+require 'ronin/recon/values/mailserver'
+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/open_port'
+require 'ronin/recon/values/email_address'
+require 'ronin/recon/values/cert'
+require 'ronin/recon/values/website'
+require 'ronin/recon/values/url'

data/lib/ronin/recon/version.rb

@@ -0,0 +1,26 @@
+# 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
+    # ronin-recon version
+    VERSION = '0.1.0.rc1'
+  end
+end

data/lib/ronin/recon/web_worker.rb

@@ -0,0 +1,35 @@
+# 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/worker'
+require 'ronin/recon/mixins/http'
+
+module Ronin
+  module Recon
+    #
+    # Base class for all web related workers.
+    #
+    class WebWorker < Worker
+
+      include Mixins::HTTP
+
+    end
+  end
+end

data/lib/ronin/recon/worker.rb

@@ -0,0 +1,433 @@
+# 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/registry'
+require 'ronin/recon/values'
+require 'ronin/core/metadata/id'
+require 'ronin/core/metadata/authors'
+require 'ronin/core/metadata/summary'
+require 'ronin/core/metadata/description'
+require 'ronin/core/metadata/references'
+require 'ronin/core/params/mixin'
+
+require 'async'
+
+module Ronin
+  module Recon
+    #
+    # Base class for all recon workers.
+    #
+    # ## Philosophy
+    #
+    # Recon involves performing multiple strategies on input values
+    # (ex: a domain) in order to produce discovered output values
+    # (ex: sub-domains). These recon strategies can be defined as classes
+    # which have a `process` method that accepts certiain input {Values value}
+    # types and yield zero or more output {Values value types}.
+    #
+    # The {Worker} class defines three key parts:
+    #
+    # 1. Metadata - defines information about the recon worker.
+    # 2. [Params] - optional user configurable parameters.
+    # 3. {Worker#process process} - method which receives a {Values Value} class
+    #
+    # [Params]: https://ronin-rb.dev/docs/ronin-core/Ronin/Core/Params/Mixin.html
+    #
+    # ## Example
+    #
+    #     require 'ronin/recon/worker'
+    #
+    #     module Ronin
+    #       module Recon
+    #         module DNS
+    #           class FooBar
+    #
+    #             register 'dns/foo_bar'
+    #
+    #             summary 'My DNS recon technique'
+    #             description <<~DESC
+    #               This recon worker uses the foo-bar technique.
+    #               Bla bla bla bla.
+    #             DESC
+    #             author 'John Smith', email: '...'
+    #
+    #             accepts Domain
+    #             outputs Host
+    #             intensity :passive
+    #
+    #             param :wordlist, String, desc: 'Optional wordlist to use'
+    #
+    #             def process(value)
+    #               # ...
+    #               yield Host.new(discovered_host_name)
+    #               # ...
+    #             end
+    #
+    #           end
+    #         end
+    #       end
+    #     end
+    #
+    # ### register
+    #
+    # Registers the worker with {Recon}.
+    #
+    #     register 'dns/foo_bar'
+    #
+    # ### accepts
+    #
+    # Defines which {Values Value} types the worker accepts.
+    #
+    #     accepts Domain
+    #
+    # Available {Values Value} types are:
+    #
+    # * {Values::Domain Domain} - a domain name (ex: `example.com`).
+    # * {Values::Host Host} - a host-name (ex: `www.example.com`).
+    # * {Values::IP} - a single IP address (ex: `192.168.1.1').
+    # * {Values::IPRange} - a CIDR IP range (ex: `192.168.1.1/24`).
+    # * {Values::Mailserver} - represents a mailserver for a domain
+    #   (ex: `smtp.google.com`).
+    # * {Values::Nameserver} - represents a nameserver for a domain
+    #   (ex: `ns1.google.com`).
+    # * {Values::OpenPort} - represents a discovered open port on an IP address.
+    # * {Values::URL} - represents a discovered URL
+    #   (ex: `https://example.com/index.html`).
+    # * {Values::Website} - represents a discovered website
+    #   (ex: `https://example.com/`).
+    # * {Values::Wildcard} - represent a wildcard host name
+    #   (ex: `*.example.com`).
+    #
+    # **Note:** the recon worker may specify that it accepts multiple value
+    # types:
+    #
+    #     accepts Domain, Host, IP
+    #
+    # ### outputs
+    #
+    # Similar to `accepts`, but defines the possible output value types of the
+    # worker.
+    #
+    #     outputs Host
+    #
+    # **Note:** the recon worker may specify that it can output multiple
+    # different value types:
+    #
+    #     outputs Host, IP
+    #
+    # ### intensity
+    #
+    # Indicates the intensity level of the worker class.
+    #
+    #     intensity :passive
+    #
+    # The possible intensity levels are:
+    #
+    # * `:passive` - does not send any network traffic to the target system.
+    # * `:active` - sends a moderate amount of network traffic to the target
+    #   system.
+    # * `:aggressive` - sends an excessive amount of network traffic to the
+    #   target system and may trigger alerts.
+    #
+    # **Note:** if the intensity level of the worker class is not defined,
+    # it will default to `:active`.
+    #
+    # ### summary
+    #
+    # Defines a short one-sentence description of the recon worker.
+    #
+    #     summary 'My DNS recon technique'
+    #
+    # ### description
+    #
+    # Defines a longer multi-paragraph description of the recon worker.
+    #
+    #     description <<~DESC
+    #       This recon worker uses the foo-bar technique.
+    #       Bla bla bla bla.
+    #     DESC
+    #
+    # **Note:** that `<<~` heredoc, unlike the regular `<<` heredoc, removes
+    # leading whitespace.
+    #
+    # ### author
+    #
+    # Add an author's name and additional information to the recon worker.
+    #
+    #     author 'John Smith'
+    #
+    #     author 'doctor_doom', email: '...', twitter: '...'
+    #
+    # ### param
+    #
+    # Defines a user configurable param. Params may have a type class, but
+    # default to `String`. Params must have a one-line description.
+    #
+    #     param :str, desc: 'A basic string param'
+    #
+    #     param :feature_flag, Boolean, desc: 'A boolean param'
+    #
+    #     param :enum, Enum[:one, :two, :three],
+    #                  desc: 'An enum param'
+    #
+    #     param :num1, Integer, desc: 'An integer param'
+    #
+    #     param :num2, Integer, default: 42,
+    #                          desc: 'A param with a default value'
+    #
+    #     param :num3, Integer, default: ->{ rand(42) },
+    #                           desc: 'A param with a dynamic default value'
+    #
+    #     param :float, Float, 'Floating point param'
+    #
+    #     param :url, URI, desc: 'URL param'
+    #
+    #     param :pattern, Regexp, desc: 'Regular Expression param'
+    #
+    # Params may then be accessed in instance methods using `params` Hash.
+    #
+    #     param :retries, Integer, default: 4,
+    #                              desc:    'Number of retries'
+    #
+    #     def process(value)
+    #       retry_count = 0
+    #
+    #       begin
+    #         # ...
+    #       rescue => error
+    #         retry_count += 1
+    #
+    #         if retry_count < params[:retries]
+    #           retry
+    #         else
+    #           raise(error)
+    #         end
+    #       end
+    #     end
+    #
+    # @api public
+    #
+    class Worker
+
+      include Core::Metadata::ID
+      include Core::Metadata::Authors
+      include Core::Metadata::Summary
+      include Core::Metadata::Description
+      include Core::Metadata::References
+      include Core::Params::Mixin
+      include Values
+
+      #
+      # Registers the recon worker with the given name.
+      #
+      # @param [String] worker_id
+      #   The recon worker's `id`.
+      #
+      # @example
+      #   require 'ronin/recon/worker'
+      #
+      #   module Ronin
+      #     module Recon
+      #       module DNS
+      #         class SubdomainBruteforcer < Worker
+      #
+      #           register 'dns/subdomain_bruteforcer'
+      #
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @api public
+      #
+      def self.register(worker_id)
+        id(worker_id)
+        Recon.register(worker_id,self)
+      end
+
+      #
+      # Initializes the worker.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+      end
+
+      #
+      # Gets or sets the value class which the recon worker accepts.
+      #
+      # @param [Array<Class<Value>>] value_classes
+      #   The optional new value class(es) to accept.
+      #
+      # @return [Array<Class<Value>>]
+      #   the value class which the recon worker accepts.
+      #
+      # @raise [NotImplementedError]
+      #   No value class was defined for the recon worker.
+      #
+      # @example define that the recon worker accepts IP addresses:
+      #   accepts IP
+      #
+      def self.accepts(*value_classes)
+        unless value_classes.empty?
+          @accepts = value_classes
+        else
+          @accepts || if superclass < Worker
+                        superclass.accepts
+                      else
+                        raise(NotImplementedError,"#{self} did not set accepts")
+                      end
+        end
+      end
+
+      #
+      # Gets or sets the value class which the recon worker outputs.
+      #
+      # @param [Array<Class<Value>>] value_classes
+      #   The optional new value class(es) to outputs.
+      #
+      # @return [Array<Class<Value>>]
+      #   the value class which the recon worker outputs.
+      #
+      # @raise [NotImplementedError]
+      #   No value class was defined for the recon worker.
+      #
+      # @example define that the recon worker outputs Host values:
+      #   outputs Host
+      #
+      def self.outputs(*value_classes)
+        unless value_classes.empty?
+          @outputs = value_classes
+        else
+          @outputs || if superclass < Worker
+                        superclass.outputs
+                      else
+                        raise(NotImplementedError,"#{self} did not set outputs")
+                      end
+        end
+      end
+
+      #
+      # Gets or sets the worker's default concurrency.
+      #
+      # @param [Integer, nil] new_concurrency
+      #   The optional new concurrency to set.
+      #
+      # @return [Integer]
+      #   The worker's concurrency. Defaults to `1` if not set.
+      #
+      # @example sets the recon worker's default concurrency:
+      #   concurrency 3
+      #
+      def self.concurrency(new_concurrency=nil)
+        if new_concurrency
+          @concurrency = new_concurrency
+        else
+          @concurrency || if superclass < Worker
+                            superclass.concurrency
+                          else
+                            1
+                          end
+        end
+      end
+
+      #
+      # Gets or sets the worker's intensity level.
+      #
+      # @param [:passive, :active, :aggressive, nil] new_intensity
+      #   The optional new intensity level to set.
+      #
+      #   * `:passive` - does not send any network traffic to the target system.
+      #   * `:active` - sends a moderate amount of network traffic to the target
+      #     system.
+      #   * `:aggressive` - sends an excessive amount of network traffic to the
+      #     target system and may trigger alerts.
+      #
+      # @return [:passive, :active, :aggressive]
+      #   The worker's intensity level. Defaults to `:active` if not set.
+      #
+      # @raise [ArgumentError]
+      #   The new intensity level was not `:passive`, `:active`, or
+      #   `:aggressive`.
+      #
+      # @example sets the recon worker's intensity level:
+      #   intensity :passive
+      #
+      def self.intensity(new_intensity=nil)
+        if new_intensity
+          case new_intensity
+          when :passive, :active, :aggressive
+            @intensity = new_intensity
+          else
+            raise(ArgumentError,"intensity must be :passive, :active, or :aggressive: #{new_intensity.inspect}")
+          end
+        else
+          @intensity || if superclass < Worker
+                          superclass.intensity
+                        else
+                          :active
+                        end
+        end
+      end
+
+      #
+      # Initializes the worker and runs it with the single value.
+      #
+      # @param [Values::Value] value
+      #   The input value to process.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments to initialize the worker with.
+      #
+      # @note
+      #   This method is mainly for testing workers and running them
+      #   individually.
+      #
+      def self.run(value,**kwargs,&block)
+        worker = new(**kwargs)
+
+        Async do
+          worker.process(value,&block)
+        end
+      end
+
+      #
+      # Calls the recon worker with the given input value.
+      #
+      # @param [Values::Value] value
+      #   The input value.
+      #
+      # @yield [new_value]
+      #   The `call` method can then `yield` one or more newly discovered values
+      #
+      # @yieldparam [Values::Value] new_value
+      #   An newly discovered output value from the input value.
+      #
+      # @abstract
+      #
+      def process(value,&block)
+        raise(NotImplementedError,"#{self.class} did not define a #process method")
+      end
+
+    end
+  end
+end