Renamed the ronin-wordlists available command to search (closes #33…

…).

* Added the `-c,--category CATEGORY` option.
* Added the `KEYWORD` argument.
* Added the ability to filter wordlists via a keyword or category.
* Added specs for the `ronin-wordlists search` command.

README.md

@@ -39,20 +39,20 @@ Arguments:
     [ARGS ...]                       Additional arguments for the command
 
 Commands:
-    available
     completion
     download, install
     help
     list, ls
     purge
     remove, rm
+    search
     update, up
 ```
 
 List popular wordlists available for download or installation:
 
 ```shell
-$ ronin-wordlists available
+$ ronin-wordlists search
 [ alexa-top-1000 ]
 
   * URL: https://github.com/urbanadventurer/WhatWeb/blob/master/plugin-development/alexa-top-1000.txt

gemspec.yml

@@ -21,7 +21,7 @@ metadata:
 generated_files:
  - data/completions/ronin-wordlists
  - man/ronin-wordlists.1
- - man/ronin-wordlists-available.1
+ - man/ronin-wordlists-search.1
  - man/ronin-wordlists-completion.1
  - man/ronin-wordlists-download.1
  - man/ronin-wordlists-list.1

lib/ronin/wordlists/cli/commands/search.rb

@@ -0,0 +1,145 @@
+# 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/cli/command'
+require 'ronin/wordlists/cli/wordlist_index'
+
+require 'set'
+
+module Ronin
+  module Wordlists
+    class CLI
+      module Commands
+        #
+        # Lists wordlists available for download or installation.
+        #
+        # ## Usage
+        #
+        #     ronin-wordlists search [options]
+        #
+        # ## Options
+        #
+        #     -c, --category NAME              Filters wordlists by a specific category
+        #     -h, --help                       Print help information
+        #
+        # Arguments:
+        #     [KEYWORD]                        Optional search keyword
+        #
+        class Search < Command
+
+          usage '[options] [KEYWORD]'
+
+          option :category, short: '-c',
+                            value: {
+                              type:  String,
+                              usage: 'NAME'
+                            },
+                            desc: 'Filters wordlists by a specific category' do |category|
+                              @categories << category
+                            end
+
+          argument :keyword, required: false,
+                             desc:     'Optional search keyword'
+
+          description 'Lists wordlists available for download or installation'
+
+          man_page 'ronin-wordlists-search.1'
+
+          # Wordlist categories to filter by.
+          #
+          # @return [Set<String>]
+          attr_reader :categories
+
+          #
+          # Initializes the `ronin-wordlists search` command.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for the command.
+          #
+          def initialize(**kwargs)
+            super(**kwargs)
+
+            @categories = Set.new
+          end
+
+          #
+          # Runs the `ronin-wordlists search` command.
+          #
+          # @param [String, nil] keyword
+          #   The optional search keyword.
+          #
+          def run(keyword=nil)
+            search(keyword, categories: @categories).each do |entry|
+              print_entry(entry)
+            end
+          end
+
+          #
+          # Searches for matching entries in the wordlist index file.
+          #
+          # @param [String, nil] keyword
+          #   The optional search keyword.
+          #
+          # @param [Set<String>, nil] categories
+          #   The optional set of categories to filter by.
+          #
+          # @return [Enumerator::Lazy]
+          #   The filtered wordlist index entries.
+          #
+          def search(keyword=nil, categories: Set.new)
+            entries = WordlistIndex.load.lazy
+
+            unless categories.empty?
+              entries = entries.filter do |entry|
+                categories.subset?(entry.categories)
+              end
+            end
+
+            if keyword
+              entries = entries.filter do |entry|
+                entry.name.include?(keyword)      ||
+                  entry.summary.include?(keyword) ||
+                  entry.categories.include?(keyword)
+              end
+            end
+
+            return entries
+          end
+
+          #
+          # Prints an entry from the wordlist index file.
+          #
+          # @param [WordlistIndex::Entry] entry
+          #   An entry from the wordlist index file.
+          #
+          def print_entry(entry)
+            puts "[ #{entry.name} ]"
+            puts
+            puts "  * URL: #{entry.url}"
+            puts "  * Categories: #{entry.categories.join(', ')}"
+            puts "  * Summary: #{entry.summary}"
+            puts
+          end
+
+        end
+      end
+    end
+  end
+end

man/ronin-wordlists-search.1.md

@@ -0,0 +1,37 @@
+# ronin-wordlists-search 1 "2023-01-01" Ronin Wordlists "User Manuals"
+
+## NAME
+
+ronin-wordlists-search - Lists the search wordlists
+
+## SYNOPSIS
+
+`ronin-wordlists` `search` [*options*] [*KEYWORD*]
+
+## DESCRIPTION
+
+Lists popular wordlists that are search for download or installation,
+by the `ronin-wordlists download` or `ronin-wordlists install` commands.
+
+## ARGUMENTS
+
+*KEYWORD*
+: Optional keyword to search wordlists by.
+
+## OPTIONS
+
+`-c`, `--category` *CATEGORY*
+: Filters wordlists by the given category name. If the option is specified
+  multiple times then the wordlists belonging to all of the categories will be
+  displayed.
+
+`-h`, `--help`
+: Prints help information.
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+
+## SEE ALSO
+
+[ronin-wordlists-download](ronin-wordlists-download.1.md) [ronin-wordlists-list](ronin-wordlists-list.1.md) [ronin-wordlists-remove](ronin-wordlists-remove.1.md) [ronin-wordlists-update](ronin-wordlists-update.1.md)

man/ronin-wordlists.1.md

@@ -20,7 +20,7 @@ Command suite that manages wordlists.
 
 ## COMMANDS
 
-`available`
+`search`
 : Lists wordlists available for download or installation.
 
 `completion`
@@ -61,4 +61,4 @@ Postmodern <postmodern.mod3@gmail.com>
 
 ## SEE ALSO
 
-[ronin-wordlists-available](ronin-wordlists-available.1.md) [ronin-wordlists-completion](ronin-wordlists-completion.1.md) [ronin-wordlists-download](ronin-wordlists-download.1.md) [ronin-wordlists-list](ronin-wordlists-list.1.md) [ronin-wordlists-remove](ronin-wordlists-remove.1.md) [ronin-wordlists-update](ronin-wordlists-update.1.md) [ronin-wordlists-purge](ronin-wordlists-purge.1.md)
+[ronin-wordlists-search](ronin-wordlists-search.1.md) [ronin-wordlists-completion](ronin-wordlists-completion.1.md) [ronin-wordlists-download](ronin-wordlists-download.1.md) [ronin-wordlists-list](ronin-wordlists-list.1.md) [ronin-wordlists-remove](ronin-wordlists-remove.1.md) [ronin-wordlists-update](ronin-wordlists-update.1.md) [ronin-wordlists-purge](ronin-wordlists-purge.1.md)