ronin-wordlists 0.1.0.rc1

data/lib/ronin/wordlists/cli/wordlist_index.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/wordlists/root'
+require 'ronin/wordlists/exceptions'
+
+require 'yaml'
+require 'set'
+
+module Ronin
+  module Wordlists
+    class CLI
+      #
+      # Represents an index of known wordlists.
+      #
+      class WordlistIndex
+
+        include Enumerable
+
+        #
+        # Represents an entry in the wordlist index file.
+        #
+        class Entry
+
+          # The name of the wordlist.
+          #
+          # @return [String]
+          attr_reader :name
+
+          # The download URL of the wordlist.
+          #
+          # @return [String]
+          attr_reader :url
+
+          # A brief summary of the wordlist.
+          #
+          # @return [String]
+          attr_reader :summary
+
+          # The categories the wordlist belongs to.
+          #
+          # @return [Set<String>]
+          attr_reader :categories
+
+          #
+          # Initializes the entry object.
+          #
+          # @param [String] name
+          #   The name of the wordlist.
+          #
+          # @param [String] url
+          #   The download URL of the wordlist.
+          #
+          # @param [String] summary
+          #   A brief summary of the wordlist.
+          #
+          # @param [Array<String>] categories
+          #   The categories the wordlist belongs to.
+          #
+          def initialize(name, url: , summary: , categories: [])
+            @name = name
+            @url  = url
+
+            @summary    = summary
+            @categories = categories.to_set
+          end
+
+        end
+
+        # The entries in the wordlist index.
+        #
+        # @return [Hash{String => Entry}]
+        attr_reader :entries
+
+        #
+        # Initializes the wordlist index.
+        #
+        # @param [Hash{String => Entry}] entries
+        #   The entries for the wordlist index.
+        #
+        def initialize(entries)
+          @entries = entries
+        end
+
+        #
+        # Indicates that the wordlist index file has an invalid schema.
+        #
+        class InvalidSchema < Wordlists::Exception
+        end
+
+        # Path to the builtin `wordlists.yml` index file.
+        PATH = File.join(ROOT,'data','wordlists.yml')
+
+        #
+        # Loads the wordlist index file from the given path.
+        #
+        # @param [String] path
+        #   The path of the wordlit index file.
+        #
+        # @return [WordlistIndex]
+        #   The parsed wordlist index file.
+        #
+        # @raise [InvalidSchema]
+        #   The wordlist index file has an invalid schema.
+        #
+        def self.load(path=PATH)
+          yaml = YAML.load_file(path)
+
+          unless yaml.kind_of?(Hash)
+            raise(InvalidSchema,"wordlist index file does not contain a Hash: #{path.inspect}")
+          end
+
+          entries = yaml.to_h do |name,attributes|
+            unless attributes[:url]
+              raise(InvalidSchema,"wordlist index entry does not have a URL: #{name.inspect}")
+            end
+
+            unless attributes[:summary]
+              raise(InvalidSchema,"wordlist index entry does not have a summary: #{name.inspect}")
+            end
+
+            [name, Entry.new(name,**attributes)]
+          end
+
+          return new(entries)
+        end
+
+        #
+        # Looks up the wordlist by name within the wordlist index.
+        #
+        # @param [String] name
+        #   The wordlist name.
+        #
+        # @return [Entry, nil]
+        #   The entry for the wordlist.
+        #
+        def [](name)
+          @entries[name]
+        end
+
+        #
+        # Enumerates over every entry in the wordlist index.
+        #
+        # @yield [entry]
+        #   If a block is given, it will be passed every entry in the wordlist
+        #   index.
+        #
+        # @yieldparam [Entry] entry
+        #   An entry in the wordlist index.
+        #
+        # @return [Enumerator]
+        #   If no block is given, an Enumerator object will be returned instead.
+        #
+        def each(&block)
+          @entries.each_value(&block)
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/wordlists/cli/wordlist_option.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/wordlists'
+
+module Ronin
+  module Wordlists
+    class CLI
+      #
+      # Adds the `-W,--wordlist {NAME | PATH}` option to a command that includes
+      # {WordlistOption}.
+      #
+      # @api public
+      #
+      module WordlistOption
+        #
+        # Adds the `-W,--wordlist {NAME | PATH}` option to the command including
+        # {WordlistOption}.
+        #
+        # @param [Class<Command>] command
+        #   The command class including {WordlistOption}.
+        #
+        # @api private
+        #
+        def self.included(command)
+          command.option :wordlist, short: '-W',
+                                    value: {
+                                      type:  String,
+                                      usage: '{NAME | PATH}'
+                                    },
+                                    desc: 'The wordlist name or file' do |path_or_name|
+                                      @wordlist = if File.file?(path_or_name)
+                                                    Wordlist.open(path_or_name)
+                                                  else
+                                                    Wordlists.open(path_or_name)
+                                                  end
+                                    rescue WordlistNotFound => error
+                                      raise(OptionParser::InvalidArgument,"unknown wordlist: #{error.message}")
+                                    end
+        end
+
+        # The opened wordlist file.
+        #
+        # @return [::Wordlist, nil]
+        attr_reader :wordlist
+      end
+    end
+  end
+end

data/lib/ronin/wordlists/cli.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/wordlists/version'
+require 'ronin/core/cli/help/banner'
+
+require 'command_kit/commands'
+require 'command_kit/commands/auto_load'
+require 'command_kit/options/version'
+
+module Ronin
+  module Wordlists
+    #
+    # The `ronin-wordlists` command-line interface (CLI).
+    #
+    # @api private
+    #
+    class CLI
+
+      include CommandKit::Commands
+      include CommandKit::Commands::AutoLoad.new(
+        dir:       "#{__dir__}/cli/commands",
+        namespace: "#{self}::Commands"
+      )
+      include CommandKit::Options::Version
+      include Core::CLI::Help::Banner
+
+      command_name 'ronin-wordlists'
+      version Ronin::Wordlists::VERSION
+
+      command_aliases['install'] = 'download'
+
+      command_aliases['ls'] = 'list'
+      command_aliases['up'] = 'update'
+      command_aliases['rm'] = 'remove'
+
+    end
+  end
+end

data/lib/ronin/wordlists/exceptions.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Wordlists
+    #
+    # Base class for all `ronin-wordlists` exceptions.
+    #
+    class Exception < RuntimeError
+    end
+
+    #
+    # Indicates that a download of a wordlist failed.
+    #
+    class DownloadFailed < Wordlists::Exception
+    end
+
+    #
+    # Indicates that a requests wordlist does not exist.
+    #
+    class WordlistNotFound < Wordlists::Exception
+    end
+
+    #
+    # Indicates that the `manifest.yml` file is invalid or is missing data.
+    #
+    class InvalidManifestFile < Wordlists::Exception
+    end
+  end
+end

data/lib/ronin/wordlists/mixin.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/wordlists'
+
+module Ronin
+  module Wordlists
+    #
+    # Wordlist helper methods.
+    #
+    module Mixin
+      #
+      # Downloads a new wordlist.
+      #
+      # @param [String, URI::HTTP] url
+      #   The URL of the wordlist to download.
+      #
+      # @api public
+      #
+      # @see Wordlists.download
+      #
+      def wordlists_download(url)
+        Wordlists.download(url)
+      end
+
+      alias download_wordlist wordlists_download
+
+      #
+      # Finds a wordlist.
+      #
+      # @param [String] name
+      #   The wordlist file name.
+      #
+      # @return [String, nil]
+      #   The path to the wordlist file.
+      #
+      # @api public
+      #
+      # @see Wordlists.find
+      #
+      def wordlists_find(name)
+        Wordlists.find(name)
+      end
+
+      alias find_wordlist wordlists_find
+
+      #
+      # Lists all wordlists on the system.
+      #
+      # @param [String] pattern
+      #   Optional glob pattern to search for within the wordlist directory.
+      #
+      # @return [Set<String>]
+      #   The wordlist files within the wordlist directories.
+      #
+      # @api public
+      #
+      # @see Wordlists.list
+      #
+      def wordlists_list(pattern='*')
+        Wordlists.list(pattern)
+      end
+
+      alias list_wordlists wordlists_list
+
+      #
+      # Opens a wordlist.
+      #
+      # @param [String] name
+      #   The wordlist file name.
+      #
+      # @return [Wordlist::File]
+      #   The opened wordlist file.
+      #
+      # @raise [WordlistNotFound]
+      #   No wordlist with the given name.
+      #
+      # @api public
+      #
+      # @see Wordlists.open
+      #
+      def wordlists_open(name)
+        Wordlists.open(name)
+      end
+
+      alias open_wordlist wordlists_open
+    end
+  end
+end

data/lib/ronin/wordlists/root.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Wordlists
+    # Path to `ronin-wordlists` root directory.
+    #
+    # @api private
+    ROOT = File.expand_path(File.join(__dir__,'..','..','..'))
+  end
+end

data/lib/ronin/wordlists/search_paths.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/wordlists/wordlist_dir'
+
+require 'set'
+
+module Ronin
+  module Wordlists
+    #
+    # Represents the wordlist directories to search for wordlists within.
+    #
+    # @api private
+    #
+    class SearchPaths
+
+      include Enumerable
+
+      # The paths of the wordlist directories.
+      #
+      # @return [Array<WordlistDir>]
+      attr_reader :paths
+
+      #
+      # Initializes the wordlist search paths.
+      #
+      # @param [Array<String>] paths
+      #   The paths to the wordlist directories to search.
+      #
+      def initialize(paths=[])
+        @paths = []
+
+        paths.each do |path|
+          self << path
+        end
+      end
+
+      #
+      # Initializes the wordlist search paths.
+      #
+      # @param [Array<String>] paths
+      #   The paths to the wordlist directories to search.
+      #
+      # @return [SearchPaths]
+      #   The wordlist search paths.
+      #
+      def self.[](*paths)
+        new(paths)
+      end
+
+      #
+      # Enumerates over each wordlist directory within the search paths.
+      #
+      # @yield [wordlist_dir]
+      #   If a block is given, each wordlist directory will be yielded.
+      #
+      # @yieldparam [WordlistDir] wordlist_dir
+      #   A wordlist directory within the search paths.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator will be returned.
+      #
+      def each(&block)
+        @paths.each(&block)
+      end
+
+      #
+      # Adds a new wordlist directory to the search paths.
+      #
+      # @param [String] new_dir
+      #   A new wordlist directory to add to the search directories.
+      #
+      # @return [self]
+      #
+      def <<(new_dir)
+        @paths.unshift(WordlistDir.new(new_dir))
+        return self
+      end
+
+      #
+      # Finds a wordlist within one of the wordlist directories.
+      #
+      # @param [String] name
+      #   The wordlist file name.
+      #
+      # @return [String, nil]
+      #   The path to the wordlist or `nil` if the wordlist could not be found.
+      #
+      def find(name)
+        @paths.each do |wordlist_dir|
+          if (wordlist_path = wordlist_dir.find(name))
+            return wordlist_path
+          end
+        end
+
+        return nil
+      end
+
+      #
+      # Lists all wordlists in the wordlist directories.
+      #
+      # @param [String] name
+      #   Optional file name to search for.
+      #
+      # @return [Set<String>]
+      #   The wordlist files within the wordlist directories.
+      #
+      def list(name='*')
+        each_with_object(Set.new) do |wordlist_dir,files|
+          files.merge(wordlist_dir.list(name))
+        end
+      end
+
+      #
+      # Opens a wordlist from one of the wordlist directories.
+      #
+      # @param [String] name
+      #   The wordlist file name.
+      #
+      # @return [Wordlist::File]
+      #   The opened wordlist file.
+      #
+      # @raise [WordlistNotFound]
+      #   No wordlist with the given name.
+      #
+      def open(name)
+        if (path = find(name))
+          Wordlist.open(path)
+        else
+          raise(WordlistNotFound,"wordlist not found: #{name.inspect}")
+        end
+      end
+
+    end
+  end
+end

data/lib/ronin/wordlists/version.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+#
+# ronin-wordlists - A library and tool for managing wordlists.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-wordlists 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-wordlists 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-wordlists.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Wordlists
+    # ronin-wordlists version
+    VERSION = '0.1.0.rc1'
+  end
+end