ronin-recon 0.1.0.rc1

data/lib/ronin/recon/worker_pool.rb

@@ -0,0 +1,203 @@
+# 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/message/value'
+require 'ronin/recon/message/worker_started'
+require 'ronin/recon/message/worker_stopped'
+require 'ronin/recon/message/job_started'
+require 'ronin/recon/message/job_completed'
+require 'ronin/recon/message/job_failed'
+require 'ronin/recon/message/shutdown'
+require 'ronin/core/params/mixin'
+
+require 'async/queue'
+
+module Ronin
+  module Recon
+    #
+    # Contains the `Async::Task` objects for a worker, that process messages
+    # from the input queue and sends messages to the output queue.
+    #
+    # @api private
+    #
+    class WorkerPool
+
+      # The recon worker's ID.
+      #
+      # @return [String]
+      attr_reader :id
+
+      # The number of async worker tasks to spawn.
+      #
+      # @return [Integer]
+      attr_reader :concurrency
+
+      # The worker object.
+      #
+      # @return [Worker]
+      attr_reader :worker
+
+      # The input queue for the worker(s).
+      #
+      # @return [Async::Queue]
+      attr_reader :input_queue
+
+      # The output queue for the worker(s).
+      #
+      # @return [Async::Queue]
+      attr_reader :output_queue
+
+      # The logger for debug messages.
+      #
+      # @return [Console::Logger]
+      attr_reader :logger
+
+      #
+      # Initializes the worker pool.
+      #
+      # @param [Worker] worker
+      #   The initialized worker object.
+      #
+      # @param [Integer, nil] concurrency
+      #   The number of async tasks to spawn.
+      #
+      # @param [Async::Queue] output_queue
+      #   The output queue to send discovered values to.
+      #
+      # @param [Console::Logger] logger
+      #   The console logger object.
+      #
+      def initialize(worker, concurrency:  nil,
+                             output_queue: ,
+                             params: nil,
+                             logger: Console.logger)
+        @worker      = worker
+        @concurrency = concurrency || worker.class.concurrency
+
+        @input_queue  = Async::Queue.new
+        @output_queue = output_queue
+
+        @logger = logger
+
+        @tasks  = nil
+      end
+
+      #
+      # Routes a message to the worker.
+      #
+      # @param [Message::Value, Message::STOP] mesg
+      #   The message to route.
+      #
+      def enqueue_mesg(mesg)
+        case mesg
+        when Message::SHUTDOWN
+          # push the Stop message for each worker task
+          @concurrency.times do
+            @input_queue.enqueue(mesg)
+          end
+        else
+          @input_queue.enqueue(mesg)
+        end
+      end
+
+      #
+      # Runs the worker.
+      #
+      def run
+        # HACK: for some reason `until (mesg = ...) == Message::SHUTDOWn)`
+        # causes `Message::SHUTDOWN` objects to slip by. Changing it to a
+        # `loop do` fixes this for some reason.
+        loop do
+          if (mesg = @input_queue.dequeue) == Message::SHUTDOWN
+            break
+          end
+
+          value = mesg.value
+
+          enqueue(Message::JobStarted.new(@worker,value))
+
+          begin
+            @worker.process(value) do |result|
+              @logger.debug("Output value yielded: #{@worker} #{value.inspect} -> #{result.inspect}")
+
+              new_value = Message::Value.new(result, worker: @worker,
+                                                     parent: value,
+                                                     depth:  mesg.depth + 1)
+
+              enqueue(new_value)
+            end
+
+            enqueue(Message::JobCompleted.new(@worker,value))
+          rescue StandardError => error
+            enqueue(Message::JobFailed.new(@worker,value,error))
+          end
+        end
+
+        stopped!
+      end
+
+      #
+      # Starts the worker pool.
+      #
+      # @param [Async::Task] task
+      #   The optional async task to register the worker under.
+      #
+      def start(task=Async::Task.current)
+        # mark the worker as running
+        started!
+
+        @tasks = []
+
+        @concurrency.times do
+          @tasks << task.async { run }
+        end
+      end
+
+      #
+      # Marks the worker pool as running.
+      #
+      def started!
+        # send a message to the engine that the worker pool has started
+        enqueue(Message::WorkerStarted.new(@worker))
+      end
+
+      #
+      # Marks the worker pool as stopped.
+      #
+      def stopped!
+        # send a message to the engine that the worker pool has stopped
+        enqueue(Message::WorkerStopped.new(@worker))
+      end
+
+      private
+
+      #
+      # Sends a message to the output queue.
+      #
+      # @param [Message::JobStarted, Message::JobCompleted, Message::JobFailed, Message::Value] mesg
+      #   The message object to enqueue.
+      #
+      def enqueue(mesg)
+        @output_queue.enqueue(mesg)
+      end
+
+    end
+  end
+end

data/lib/ronin/recon/workers.rb

@@ -0,0 +1,260 @@
+# 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 'set'
+
+module Ronin
+  module Recon
+    #
+    # Represents a set of recon worker classes.
+    #
+    # @api private
+    #
+    class Workers
+
+      include Enumerable
+
+      # The worker classes in the set.
+      #
+      # @return [Set<Class<Worker>>]
+      attr_reader :classes
+
+      #
+      # Initializes the workers.
+      #
+      # @param [Array<Class<Worker>>, Set<Class<Worker>>] workers
+      #   The set of worker classes.
+      #
+      def initialize(workers=Set.new)
+        @classes = workers.to_set
+      end
+
+      #
+      # Loads the worker classes.
+      #
+      # @param [Enumerable<String>] worker_ids
+      #   The list of worker IDs to load.
+      #
+      # @return [Workers]
+      #
+      def self.load(worker_ids)
+        workers = new
+
+        worker_ids.each do |worker_id|
+          workers.load(worker_id)
+        end
+
+        return workers
+      end
+
+      #
+      # Alias for {load}.
+      #
+      # @param [Array<String>] worker_ids
+      #   The array of worker IDs to load.
+      #
+      # @return [Workers]
+      #
+      def self.[](*worker_ids)
+        load(worker_ids)
+      end
+
+      #
+      # Loads all workers.
+      #
+      # @return [Workers]
+      #
+      def self.all
+        load(Recon.list_files)
+      end
+
+      #
+      # Loads all workers under a specific category.
+      #
+      # @param [String] name
+      #   The category name.
+      #
+      # @return [Workers]
+      #
+      def self.category(name)
+        load(
+          Recon.list_files.select { |worker_id|
+            worker_id.start_with?("#{name}/")
+          }
+        )
+      end
+
+      #
+      # Enumerates over the worker classes within the set.
+      #
+      # @yield [worker]
+      #   If a block is given, it will be passed every worker class within the
+      #   set.
+      #
+      # @yieldparam [Class<Worker>] worker
+      #   A worker class within the set.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      def each(&block)
+        @classes.each(&block)
+      end
+
+      #
+      # Adds another set of workers to the workers.
+      #
+      # @param [Workers, Array<Class<Worker>>] other
+      #
+      # @return [Workers]
+      #
+      def +(other)
+        other_workers = other.to_set
+
+        self.class.new((@classes + other_workers).uniq)
+      end
+
+      #
+      # Adds the worker class to the workers.
+      #
+      # @param [Class<Worker>] worker
+      #   The worker class to add.
+      #
+      # @return [self]
+      #
+      def <<(worker)
+        @classes << worker
+        return self
+      end
+
+      #
+      # Loads a worker and adds it to the workers.
+      #
+      # @param [String] worker_id
+      #   The worker ID to load.
+      #
+      # @return [self]
+      #
+      def load(worker_id)
+        self << Recon.load_class(worker_id)
+      end
+
+      #
+      # Loads a worker from a file and adds it to the workers.
+      #
+      # @param [String] path
+      #   The path to the file.
+      #
+      # @return [self]
+      #
+      def load_file(path)
+        self << Recon.load_class_from_file(path)
+      end
+
+      #
+      # Removes a worker class from the workers.
+      #
+      # @param [Class<Worker>] worker
+      #   The worker class to remove.
+      #
+      # @return [self, nil]
+      #   If the worker class was in the workers, than `self` is returned.
+      #   If the worker class was not in the workers, then `nil` will be
+      #   returned.
+      #
+      def delete(worker)
+        if @classes.delete?(worker)
+          self
+        end
+      end
+
+      #
+      # Removes a worker with the ID from the workers.
+      #
+      # @param [String] worker_id
+      #   The worker ID to remove.
+      #
+      # @return [self, nil]
+      #   If the worker ID was in the workers, than `self` is returned.
+      #   If the worker ID was not in the workers, then `nil` will be
+      #   returned.
+      #
+      def remove(worker_id)
+        if @classes.reject! { |worker| worker.id == worker_id }
+          self
+        end
+      end
+
+      # Intensity levels sorted by their intensity.
+      #
+      # @api private
+      INTENSITY_LEVELS = [
+        :passive,
+        :active,
+        :aggressive
+      ]
+
+      #
+      # Filters the workers by their {Worker.intensity intensity} level.
+      #
+      # @param [:passive, :active, :aggressive] level
+      #   The maximum intensity level to filter by.
+      #
+      # @return [Workers]
+      #
+      def intensity(level)
+        level_index = INTENSITY_LEVELS.index(level)
+
+        self.class.new(
+          @classes.select { |worker|
+            if (intensity_index = INTENSITY_LEVELS.index(worker.intensity))
+              intensity_index <= level_index
+            end
+          }
+        )
+      end
+
+      #
+      # Determines if the workers is equal to another workers.
+      #
+      # @param [Object] other
+      #   The other workers.
+      #
+      # @return [Boolean]
+      #
+      def ==(other)
+        self.class == other.class &&
+          @classes == other.classes
+      end
+
+      #
+      # Converts the workers into a Set.
+      #
+      # @return [Set<Class<Worker>>]
+      #
+      def to_set
+        @classes
+      end
+
+    end
+  end
+end

data/lib/ronin/recon.rb

@@ -0,0 +1,22 @@
+# 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/engine'
+require 'ronin/recon/version'

data/man/ronin-recon-completion.1

@@ -0,0 +1,76 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-recon-completion 1 "2024-01-01" Ronin Recon "User Manuals"
+.SH NAME
+.PP
+ronin\-recon\-completion \- Manages shell completion rules for \fBronin\-recon\fR
+.SH SYNOPSIS
+.PP
+\fBronin\-recon completion\fR \[lB]\fIoptions\fP\[rB]
+.SH DESCRIPTION
+.PP
+The \fBronin\-recon completion\fR command can print, install, or uninstall shell
+completion rules for the \fBronin\-recon\fR command\.
+.PP
+Supports installing completion rules for Bash or Zsh shells\.
+Completion rules for the Fish shell is currently not supported\.
+.SS ZSH SUPPORT
+.PP
+Zsh users will have to add the following lines to their \fB\[ti]\[sl]\.zshrc\fR file in
+order to enable Zsh\[cq]s Bash completion compatibility layer:
+.PP
+.RS 4
+.EX
+autoload \-Uz \[pl]X compinit && compinit
+autoload \-Uz \[pl]X bashcompinit && bashcompinit
+.EE
+.RE
+.SH OPTIONS
+.TP
+\fB\-\-print\fR
+Prints the shell completion file\.
+.TP
+\fB\-\-install\fR
+Installs the shell completion file\.
+.TP
+\fB\-\-uninstall\fR
+Uninstalls the shell completion file\.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Prints help information\.
+.SH ENVIRONMENT
+.TP
+\fIPREFIX\fP
+Specifies the root prefix for the file system\.
+.TP
+\fIHOME\fP
+Specifies the home directory of the user\. Ronin will search for the
+\fB\[ti]\[sl]\.cache\[sl]ronin\-recon\fR cache directory within the home directory\.
+.TP
+\fIXDG\[ru]DATA\[ru]HOME\fP
+Specifies the data directory to use\. Defaults to \fB\[Do]HOME\[sl]\.local\[sl]share\fR\.
+.SH FILES
+.TP
+\fB\[ti]\[sl]\.local\[sl]share\[sl]bash\-completion\[sl]completions\[sl]\fR
+The user\-local installation directory for Bash completion files\.
+.TP
+\fB\[sl]usr\[sl]local\[sl]share\[sl]bash\-completion\[sl]completions\[sl]\fR
+The system\-wide installation directory for Bash completions files\.
+.TP
+\fB\[sl]usr\[sl]local\[sl]share\[sl]zsh\[sl]site\-functions\[sl]\fR
+The installation directory for Zsh completion files\.
+.SH EXAMPLES
+.TP
+\fBronin\-recon completion \-\-print\fR
+Prints the shell completion rules instead of installing them\.
+.TP
+\fBronin\-recon completion \-\-install\fR
+Installs the shell completion rules for \fBronin\-recon\fR\.
+.TP
+\fBronin\-recon completion \-\-uninstall\fR
+Uninstalls the shell completion rules for \fBronin\-recon\fR\.
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME

data/man/ronin-recon-completion.1.md

@@ -0,0 +1,78 @@
+# ronin-recon-completion 1 "2024-01-01" Ronin Recon "User Manuals"
+
+## NAME
+
+ronin-recon-completion - Manages shell completion rules for `ronin-recon`
+
+## SYNOPSIS
+
+`ronin-recon completion` [*options*]
+
+## DESCRIPTION
+
+The `ronin-recon completion` command can print, install, or uninstall shell
+completion rules for the `ronin-recon` command.
+
+Supports installing completion rules for Bash or Zsh shells.
+Completion rules for the Fish shell is currently not supported.
+
+### ZSH SUPPORT
+
+Zsh users will have to add the following lines to their `~/.zshrc` file in
+order to enable Zsh's Bash completion compatibility layer:
+
+    autoload -Uz +X compinit && compinit
+    autoload -Uz +X bashcompinit && bashcompinit
+
+## OPTIONS
+
+`--print`
+: Prints the shell completion file.
+
+`--install`
+: Installs the shell completion file.
+
+`--uninstall`
+: Uninstalls the shell completion file.
+
+`-h`, `--help`
+: Prints help information.
+
+## ENVIRONMENT
+
+*PREFIX*
+: Specifies the root prefix for the file system.
+
+*HOME*
+: Specifies the home directory of the user. Ronin will search for the
+  `~/.cache/ronin-recon` cache directory within the home directory.
+
+*XDG_DATA_HOME*
+: Specifies the data directory to use. Defaults to `$HOME/.local/share`.
+
+## FILES
+
+`~/.local/share/bash-completion/completions/`
+: The user-local installation directory for Bash completion files.
+
+`/usr/local/share/bash-completion/completions/`
+: The system-wide installation directory for Bash completions files.
+
+`/usr/local/share/zsh/site-functions/`
+: The installation directory for Zsh completion files.
+
+## EXAMPLES
+
+`ronin-recon completion --print`
+: Prints the shell completion rules instead of installing them.
+
+`ronin-recon completion --install`
+: Installs the shell completion rules for `ronin-recon`.
+
+`ronin-recon completion --uninstall`
+: Uninstalls the shell completion rules for `ronin-recon`.
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+

data/man/ronin-recon-irb.1

@@ -0,0 +1,27 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-recon-irb 1 "2023-02-01" Ronin Recon "User Manuals"
+.SH NAME
+.PP
+ronin\-recon\-irb \- Starts an interactive Ruby shell with ronin\-recon loaded
+.SH SYNOPSIS
+.PP
+\fBronin\-recon irb\fR \[lB]\fIoptions\fP\[rB]
+.SH DESCRIPTION
+.PP
+Starts an interactive Ruby shell with \fBronin\[sl]recon\fR loaded\.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help information
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME
+.SH SEE ALSO
+.PP
+.BR ronin\-recon\-workers (1)
+.BR ronin\-recon\-worker (1)
+.BR ronin\-recon\-run (1)
+.BR ronin\-recon\-test (1)

data/man/ronin-recon-irb.1.md

@@ -0,0 +1,26 @@
+# ronin-recon-irb 1 "2023-02-01" Ronin Recon "User Manuals"
+
+## NAME
+
+ronin-recon-irb - Starts an interactive Ruby shell with ronin-recon loaded
+
+## SYNOPSIS
+
+`ronin-recon irb` [*options*]
+
+## DESCRIPTION
+
+Starts an interactive Ruby shell with `ronin/recon` loaded.
+
+## OPTIONS
+
+`-h`, `--help`
+: Print help information
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+
+## SEE ALSO
+
+[ronin-recon-workers](ronin-recon-workers.1.md) [ronin-recon-worker](ronin-recon-worker.1.md) [ronin-recon-run](ronin-recon-run.1.md) [ronin-recon-test](ronin-recon-test.1.md)