ronin-wordlists 0.1.0.rc1

data/lib/ronin/wordlists/wordlist_dir.rb

@@ -0,0 +1,194 @@
+# 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_file'
+require 'ronin/wordlists/wordlist_repo'
+require 'ronin/wordlists/exceptions'
+
+require 'wordlist'
+
+module Ronin
+  module Wordlists
+    #
+    # Represents a directory of wordlists.
+    #
+    # ## Example
+    #
+    #     wordlist_dir = Wordlists::WordlistDir.new('/path/to/wordlists')
+    #     wordlist_dir.find('passwords.txt')
+    #     # => "/path/to/wordlists/passwords.txt"
+    #     wordlist_dir.find('passwords')
+    #     # => "/path/to/wordlists/passwords.txt"
+    #     wordlist_dir.open('passwords.txt')
+    #     # => #<Wordlist::File:...>
+    #     wordlist_dir.open('passwords')
+    #     # => #<Wordlist::File:...>
+    #
+    # @api public
+    #
+    class WordlistDir
+
+      # The path to the wordlist directory.
+      #
+      # @return [String]
+      attr_reader :path
+
+      #
+      # Initializes the wordlist directory.
+      #
+      # @param [String] path
+      #   The path to the wordlist directory.
+      #
+      def initialize(path)
+        @path = path
+      end
+
+      #
+      # Enumerates over every wordlist in the wordlist directory.
+      #
+      # @yield [path]
+      #   The given block will be passed each path to each wordlist.
+      #
+      # @yieldparam [String] path
+      #   A path to a wordlist within the wordlist directory.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator will be returned.
+      #
+      def each(&block)
+        return enum_for unless block
+
+        Dir.glob(File.join(@path,'**','*.{txt,gz,bz2,xz}'),&block)
+      end
+
+      #
+      # Looks up a wordlist within the wordlist directory.
+      #
+      # @param [String] name
+      #   The wordlist file name.
+      #
+      # @return [String, nil]
+      #   The path to the wordlist or `nil` if the wordlist could not be found.
+      #
+      # @example
+      #   wordlist_dir.find('passwords.txt')
+      #   # => "/path/to/wordlists/passwords.txt"
+      #   wordlist_dir.find('passwords')
+      #   # => "/path/to/wordlists/passwords.txt"
+      #
+      def find(name)
+        path = File.join(@path,name)
+
+        # check for an exact filename match first
+        if File.file?(path)
+          path
+        else
+          # fallback to search for the wordlist file by name
+          Dir.glob(File.join(@path,'**',"#{name}.{txt,gz,bz2,xz}")).first
+        end
+      end
+
+      #
+      # Lists the wordlists in the wordlist directory.
+      #
+      # @param [String] name
+      #   Optional file name to search for.
+      #
+      # @return [Array<String>]
+      #   The wordlist files within the wordlist directory.
+      #
+      def list(name='*')
+        Dir.glob("{**/}#{name}.{txt,gz,bz2,xz}", base: @path)
+      end
+
+      #
+      # Opens a wordlist from the wordlist directory.
+      #
+      # @param [String] name
+      #   The wordlist file name.
+      #
+      # @return [Wordlist::File]
+      #   The opened wordlist file.
+      #
+      # @raise [WordlistNotFound]
+      #   No wordlist with the given name.
+      #
+      # @example
+      #   wordlist_dir.open('passwords.txt')
+      #   # => #<Wordlist::File:...>
+      #   wordlist_dir.open('passwords')
+      #   # => #<Wordlist::File:...>
+      #
+      def open(name)
+        if (path = find(name))
+          Wordlist.open(path)
+        else
+          raise(WordlistNotFound,"wordlist not found: #{name.inspect}")
+        end
+      end
+
+      #
+      # Downloads a wordlist from the given URL into the wordlist directory.
+      #
+      # @param [String, URI::HTTP] url
+      #   The URL of the wordlist to downloaded.
+      #
+      # @return [WordlistFile, WordlistRepo]
+      #   The downloaded wordlist. A {WordlistRepo} will be returned for git
+      #   URLs and {WordlistFile} for `http://` or `https://` URLs.
+      #
+      # @raise [DownloadFailed]
+      #   The download of the wordlist file or repository failed.
+      #
+      def download(url)
+        uri = URI(url)
+
+        wordlist_class = if uri.scheme == 'git' || uri.path.end_with?('.git')
+                           WordlistRepo
+                         else
+                           WordlistFile
+                         end
+
+        FileUtils.mkdir_p(@path)
+        return wordlist_class.download(url,@path)
+      end
+
+      #
+      # Deletes a wordlist file from the wordlist directory.
+      #
+      # @param [String] name
+      #   The wordlist name to delete.
+      #
+      # @raise [ArgumentError]
+      #   No wordlist with the given name.
+      #
+      def delete(name)
+        if (path = find(name))
+          File.unlink(path)
+
+          return path
+        else
+          raise(WordlistNotFound,"unknown wordlist: #{name.inspect}")
+        end
+      end
+
+    end
+  end
+end

data/lib/ronin/wordlists/wordlist_file.rb

@@ -0,0 +1,141 @@
+# 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_metadata'
+require 'ronin/wordlists/exceptions'
+require 'ronin/core/system'
+
+require 'net/https'
+require 'uri'
+
+module Ronin
+  module Wordlists
+    #
+    # Represents a wordlist file.
+    #
+    class WordlistFile
+
+      include WordlistMetadata
+
+      # The path to the wordlist file.
+      #
+      # @return [String]
+      attr_reader :path
+
+      # The name of the wordlist file.
+      #
+      # @return [String]
+      attr_reader :name
+
+      #
+      # Initializes the wordlist file.
+      #
+      # @param [String] path
+      #   The path to the wordlist file.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional metadata keyword arguments for
+      #   {WordlistMetadata#initialize}.
+      #
+      # @option kwargs [String, nil] :url
+      #   The optional URL for the wordlist file.
+      #
+      def initialize(path,**kwargs)
+        super(**kwargs)
+
+        @path = path
+        @name = File.basename(@path,File.extname(@path))
+      end
+
+      #
+      # Downloads a remote wordlist file.
+      #
+      # @param [String, URI::HTTP] url
+      #   The `http://` or `https://` URL for the wordlist file.
+      #
+      # @param [String] dest
+      #   The directory to download the wordlist file into.
+      #
+      # @raise [DownloadFailed]
+      #   Failed to download the wordlist file.
+      #
+      # @return [WordlistFile]
+      #   The wordlist file.
+      #
+      def self.download(url,dest=Dir.pwd)
+        dest_path = begin
+                      Core::System.download(url,dest)
+                    rescue Core::System::DownloadFailed => error
+                      raise(DownloadFailed,error.message)
+                    end
+
+        return new(dest_path, url: url.to_s)
+      end
+
+      #
+      # The wordlist type.
+      #
+      # @return [:file]
+      #
+      def type
+        :file
+      end
+
+      #
+      # The name of the wordlist file.
+      #
+      # @return [String]
+      #
+      def filename
+        File.basename(@path)
+      end
+
+      #
+      # Updates the wordlist file, if {#url} is set.
+      #
+      # @raise [DownloadFailed]
+      #   Failed to download the wordlist.
+      #
+      def update
+        if @url
+          self.class.download(@url,@path)
+        end
+      end
+
+      #
+      # Deletes the wordlist file.
+      #
+      def delete
+        File.unlink(@path)
+      end
+
+      #
+      # Converts the wordlist file to a String.
+      #
+      # @return [String]
+      #   The wordlist file's path.
+      #
+      def to_s
+        @path
+      end
+
+    end
+  end
+end

data/lib/ronin/wordlists/wordlist_metadata.rb

@@ -0,0 +1,43 @@
+# 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
+    #
+    # Common wordlist metadata attributes.
+    #
+    module WordlistMetadata
+      # The optional URL for the wordlist.
+      #
+      # @return [String, nil]
+      attr_reader :url
+
+      #
+      # Initializes the wordlist metadata attributes.
+      #
+      # @param [String, nil] url
+      #   The optional URL of the wordlist.
+      #
+      def initialize(url: nil)
+        @url = url
+      end
+    end
+  end
+end

data/lib/ronin/wordlists/wordlist_repo.rb

@@ -0,0 +1,167 @@
+# 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_metadata'
+require 'ronin/wordlists/exceptions'
+
+require 'fileutils'
+require 'uri'
+
+module Ronin
+  module Wordlists
+    #
+    # Represents a git repository of wordlists.
+    #
+    class WordlistRepo
+
+      include WordlistMetadata
+
+      # The path to the wordlist repository.
+      #
+      # @return [String]
+      attr_reader :path
+
+      # The name of the wordlist repository.
+      #
+      # @return [String]
+      attr_reader :name
+
+      #
+      # Initializes the wordlist repository.
+      #
+      # @param [String] path
+      #   The path to the wordlist repository.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional metadata keyword arguments for
+      #   {WordlistMetadata#initialize}.
+      #
+      # @option kwargs [String, nil] :url
+      #   The optional URL of the wordlist repository.
+      #   If no URL is given, {#url} will infer it from the git repository.
+      #
+      def initialize(path,**kwargs)
+        super(**kwargs)
+
+        @path = path
+        @name = File.basename(@path)
+      end
+
+      #
+      # Clones a wordlist repository from the given git URL.
+      #
+      # @param [String, URI::HTTP] url
+      #   The git URL for the wordlist repository.
+      #
+      # @param [String] dest_dir
+      #   The directory to clone the wordlist repository into.
+      #
+      # @return [WordlistRepo]
+      #   The newly cloned wordlist repository.
+      #
+      # @raise [DownloadFailed]
+      #   The `git clone --depth 1` command failed or `git` was not installed on
+      #   the system.
+      #
+      def self.download(url,dest_dir=Dir.pwd)
+        uri       = URI(url)
+        url       = url.to_s
+        repo_name = File.basename(uri.path,'.git')
+        repo_path = File.join(dest_dir,repo_name)
+
+        case system('git','clone','--depth','1','--',url,repo_path)
+        when true
+          new(repo_path, url: url)
+        when false
+          raise(DownloadFailed,"git command failed: git clone --depth 1 -- #{url} #{repo_path}")
+        when nil
+          raise(DownloadFailed,"git is not installed on the system")
+        end
+      end
+
+      #
+      # The wordlist type.
+      #
+      # @return [:git]
+      #
+      def type
+        :git
+      end
+
+      #
+      # Determines if the wordlist repository uses Git.
+      #
+      # @return [Boolean]
+      #
+      def git?
+        File.directory?(File.join(@path,'.git'))
+      end
+
+      #
+      # The name of the wordlist repository directory.
+      #
+      # @return [String]
+      #
+      def filename
+        File.basename(@path)
+      end
+
+      #
+      # The URL of the wordlist repository.
+      #
+      # @return [String, nil]
+      #
+      def url
+        @url ||= if git?
+                   Dir.chdir(@path) do
+                     `git config --get remote.origin.url`.chomp
+                   end
+                 end
+      end
+
+      #
+      # Updates the wordlist repository.
+      #
+      # @raise [DownloadFailed]
+      #   The `git pull -C` command failed or `git` was not installed on the
+      #   system.
+      #
+      def update
+        if git?
+          case system('git','pull','-C',@path)
+          when true then true
+          when false
+            raise(DownloadFailed,"git command failed: git pull -C #{@path}")
+          when nil
+            raise(DownloadFailed,"git is not installed on the system")
+          end
+        end
+      end
+
+      #
+      # Deletes the wordlist repository.
+      #
+      def delete
+        FileUtils.rm_rf(@path)
+      end
+
+    end
+  end
+end

data/lib/ronin/wordlists.rb

@@ -0,0 +1,96 @@
+# 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/cache_dir'
+require 'ronin/wordlists/search_paths'
+
+module Ronin
+  #
+  # Top-level methods for `ronin-wordlists`.
+  #
+  module Wordlists
+    @cache_dir    = CacheDir.new
+    @search_paths = SearchPaths[
+      @cache_dir.wordlist_dir.path,
+      '/usr/local/share/wordlists',
+      '/usr/share/wordlists'
+    ]
+
+    #
+    # Downloads a new wordlist.
+    #
+    # @param [String, URI::HTTP] url
+    #   The URL of the wordlist to download.
+    #
+    # @api public
+    #
+    def self.download(url)
+      @cache_dir.download(url)
+    end
+
+    #
+    # Finds a wordlist.
+    #
+    # @param [String] name
+    #   The wordlist file name.
+    #
+    # @return [String, nil]
+    #   The path to the wordlist file.
+    #
+    # @api public
+    #
+    def self.find(name)
+      @search_paths.find(name)
+    end
+
+    #
+    # 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
+    #
+    def self.list(pattern='*')
+      @search_paths.list(pattern)
+    end
+
+    #
+    # 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
+    #
+    def self.open(name)
+      @search_paths.open(name)
+    end
+  end
+end

data/man/ronin-wordlists-completion.1

@@ -0,0 +1,76 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-wordlists-completion 1 "2024-01-01" Ronin Wordlists "User Manuals"
+.SH NAME
+.PP
+ronin\-wordlists\-completion \- Manages shell completion rules for \fBronin\-wordlists\fR
+.SH SYNOPSIS
+.PP
+\fBronin\-wordlists completion\fR \[lB]\fIoptions\fP\[rB]
+.SH DESCRIPTION
+.PP
+The \fBronin\-wordlists completion\fR command can print, install, or uninstall shell
+completion rules for the \fBronin\-wordlists\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\-wordlists\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\-wordlists completion \-\-print\fR
+Prints the shell completion rules instead of installing them\.
+.TP
+\fBronin\-wordlists completion \-\-install\fR
+Installs the shell completion rules for \fBronin\-wordlists\fR\.
+.TP
+\fBronin\-wordlists completion \-\-uninstall\fR
+Uninstalls the shell completion rules for \fBronin\-wordlists\fR\.
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME