ronin-core 0.1.3 → 0.2.0.rc1

data/lib/ronin/core/cli/printing/params.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -61,6 +61,35 @@ module Ronin
             indent do
               print_table(rows,header: PARAM_TABLE_HEADER, border: :line)
             end
+
+            puts
+          end
+
+          #
+          # Returns a placeholder usage value for the given param.
+          #
+          # @param [Core::Params::Param] param
+          #   The param.
+          #
+          # @return [String]
+          #   The placeholder usage value.
+          #
+          # @note
+          #   This method is primarily used to help build example commands
+          #   that accept certain params.
+          #
+          # @since 0.2.0
+          #
+          def param_usage(param)
+            case param.type
+            when Core::Params::Types::Boolean then 'BOOL'
+            when Core::Params::Types::Integer then 'NUM'
+            when Core::Params::Types::Float   then 'FLOAT'
+            when Core::Params::Types::Regexp  then '/REGEX/'
+            when Core::Params::Types::URI     then 'URL'
+            else
+              param.name.upcase
+            end
           end
         end
       end

data/lib/ronin/core/cli/ruby_shell.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -16,8 +16,9 @@
 # along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
 #
 
-require 'command_kit/colors'
+require 'ronin/core/cli/banner'
 
+require 'command_kit/colors'
 require 'irb'
 
 module Ronin
@@ -30,6 +31,7 @@ module Ronin
       #
       class RubyShell
 
+        include Banner
         include CommandKit::Colors
 
         # The console name.
@@ -104,6 +106,8 @@ module Ronin
         # [irb]: https://github.com/ruby/irb#readme
         #
         def start
+          print_banner if STDOUT.tty?
+
           configure
 
           workspace = if @context then IRB::WorkSpace.new(@context)

data/lib/ronin/core/cli/shell.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -16,6 +16,8 @@
 # along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
 #
 
+require 'ronin/core/cli/banner'
+
 require 'command_kit/printing'
 require 'command_kit/colors'
 require 'reline'
@@ -28,6 +30,7 @@ module Ronin
       #
       class Shell
 
+        include Banner
         include CommandKit::Printing
         include CommandKit::Colors
 
@@ -89,6 +92,8 @@ module Ronin
           prev_completion_proc   = Reline.completion_proc
           Reline.completion_proc = shell.method(:complete)
 
+          shell.print_banner if shell.stdout.tty?
+
           begin
             loop do
               line = Reline.readline("#{shell.prompt} ", true)

data/lib/ronin/core/git.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published

data/lib/ronin/core/home.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published

data/lib/ronin/core/metadata/authors/author.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -65,6 +65,13 @@ module Ronin
           # @return [String, nil]
           attr_reader :twitter
 
+          # The author's Mastodon handle.
+          #
+          # @return [String, nil]
+          #
+          # @since 0.2.0
+          attr_reader :mastodon
+
           # The author's Discord handle.
           #
           # @return [String, nil]
@@ -97,27 +104,32 @@ module Ronin
           # @param [String, nil] twitter
           #   The author's Twitter handle.
           #
+          # @param [String, nil] mastodon
+          #   The author's Mastodon handle.
+          #
           # @param [String, nil] discord
           #   The author's Discord handle.
           #
-          def initialize(name, email:   nil,
-                               pgp:     nil,
-                               website: nil,
-                               blog:    nil,
-                               github:  nil,
-                               gitlab:  nil,
-                               twitter: nil,
-                               discord: nil)
+          def initialize(name, email:    nil,
+                               pgp:      nil,
+                               website:  nil,
+                               blog:     nil,
+                               github:   nil,
+                               gitlab:   nil,
+                               twitter:  nil,
+                               mastodon: nil,
+                               discord:  nil)
             @name  = name
             @email = email
             @pgp   = pgp
 
-            @website = website
-            @blog    = blog
-            @github  = github
-            @gitlab  = gitlab
-            @twitter = twitter
-            @discord = discord
+            @website  = website
+            @blog     = blog
+            @github   = github
+            @gitlab   = gitlab
+            @twitter  = twitter
+            @mastodon = mastodon
+            @discord  = discord
           end
 
           #
@@ -183,6 +195,17 @@ module Ronin
             @twitter != nil
           end
 
+          #
+          # Determines if the author has a {#mastodon} handle set.
+          #
+          # @return [Boolean]
+          #
+          # @since 0.2.0
+          #
+          def mastodon?
+            @mastodon != nil
+          end
+
           #
           # Determines if the author has a {#discord} handle set.
           #
@@ -225,6 +248,23 @@ module Ronin
             "https://twitter.com/#{@twitter.sub(/\A@/,'')}" if @twitter
           end
 
+          #
+          # Returns the URL to the author's Mastodon profile.
+          #
+          # @return [String, nil]
+          #   Returns the URL to the author's Mastodon profile, or `nil`
+          #   if no {#mastodon} user name has been set.
+          #
+          # @since 0.2.0
+          #
+          def mastodon_url
+            if @mastodon
+              username, host = @mastodon.sub(/\A@/,'').split('@',2)
+
+              "https://#{host}/@#{username}"
+            end
+          end
+
           #
           # Converts the author to a String.
           #

data/lib/ronin/core/metadata/authors.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -102,6 +102,9 @@ module Ronin
           # @option kwargs [String, nil] :twitter
           #   The author's Twitter handle.
           #
+          # @option kwargs [String, nil] :mastodon
+          #   The author's Mastodon handle.
+          #
           # @option kwargs [String, nil] :discord
           #   The author's Discord handle.
           #

data/lib/ronin/core/metadata/description.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published

data/lib/ronin/core/metadata/id.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published

data/lib/ronin/core/metadata/references.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published

data/lib/ronin/core/metadata/summary.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published

data/lib/ronin/core/metadata/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2021-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-core is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published

data/lib/ronin/core/output_formats/csv.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core 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-core 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-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/output_formats/output_file'
+
+require 'csv'
+
+module Ronin
+  module Core
+    module OutputFormats
+      #
+      # Represents a CSV (`.csv`) output format.
+      #
+      # @api semipublic
+      #
+      # @since 0.2.0
+      #
+      class CSV < OutputFile
+
+        #
+        # Appends a value to the CSV stream.
+        #
+        # @param [#to_csv] value
+        #   The value to append.
+        #
+        # @raise [NotImplementedError]
+        #   The given output value does not define a `to_csv` method.
+        #
+        def <<(value)
+          unless value.respond_to?(:to_csv)
+            raise(NotImplementedError,"output value must define a #to_csv method: #{value.inspect}")
+          end
+
+          @io.write(value.to_csv)
+          @io.flush
+
+          return self
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/core/output_formats/json.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core 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-core 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-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/output_formats/output_file'
+
+require 'json'
+
+module Ronin
+  module Core
+    module OutputFormats
+      #
+      # Represents a JSON (`.json`) output format.
+      #
+      # @api semipublic
+      #
+      # @since 0.2.0
+      #
+      class JSON < OutputFile
+
+        #
+        # Initializes the JSON output format.
+        #
+        # @param [IO] io
+        #   The JSON output stream.
+        #
+        def initialize(io)
+          super(io)
+
+          @first_value = true
+        end
+
+        #
+        # Appends a value to the JSON stream.
+        #
+        # @param [#to_json] value
+        #   The value to append.
+        #
+        # @return [self]
+        #
+        # @raise [NotImplementedError]
+        #   The given value object does not define a `to_json` method.
+        #
+        def <<(value)
+          unless value.respond_to?(:to_json)
+            raise(NotImplementedError,"output value does not define a #to_json method: #{value.inspect}")
+          end
+
+          if @first_value
+            @io.write("[#{value.to_json}")
+            @first_value = false
+          else
+            @io.write(",#{value.to_json}")
+          end
+
+          @io.flush
+          return self
+        end
+
+        #
+        # Closes the JSON output stream.
+        #
+        def close
+          if @first_value
+            @io.write("[]")
+          else
+            @io.write("]")
+          end
+
+          super
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/core/output_formats/ndjson.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core 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-core 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-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/output_formats/output_file'
+
+require 'json'
+
+module Ronin
+  module Core
+    module OutputFormats
+      #
+      # Represents a newline deliminated JSON (`.ndjson`) output format.
+      #
+      # @api semipublic
+      #
+      # @since 0.2.0
+      #
+      class NDJSON < OutputFile
+
+        #
+        # Appends a value to the NDJSON stream.
+        #
+        # @param [#to_json] value
+        #   The value to append.
+        #
+        # @return [self]
+        #
+        # @raise [NotImplementedError]
+        #   The given value object does not define a `to_json` method.
+        #
+        def <<(value)
+          @io.puts(value.to_json)
+          @io.flush
+          return self
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/core/output_formats/output_dir.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core 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-core 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-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/output_formats/output_format'
+
+require 'fileutils'
+
+module Ronin
+  module Core
+    module OutputFormats
+      #
+      # Base class that represents an output directory.
+      #
+      # @api semipublic
+      #
+      # @since 0.2.0
+      #
+      class OutputDir < OutputFormat
+
+        # The path to the output directory.
+        #
+        # @return [String]
+        attr_reader :path
+
+        #
+        # Initializes the output directory.
+        #
+        # @param [String] path
+        #   The path to the output directory.
+        #
+        def initialize(path)
+          super()
+
+          @path = File.expand_path(path)
+          FileUtils.mkdir_p(@path)
+        end
+
+        #
+        # Opens an output directory.
+        #
+        # @param [String] path
+        #   The path to the new output directory.
+        #
+        # @yield [output_dir]
+        #   If a block is given, it will be passed the initialized output
+        #   directory. Once the block returns, the output format will
+        #   automatically be closed.
+        #
+        # @yieldparam [Dir] output_dir
+        #   The newly opened output directory.
+        #
+        # @return [Dir]
+        #   If no block is given, the newly initialized output directory will be
+        #   returned.
+        #
+        def self.open(path)
+          output_dir = new(path)
+
+          if block_given?
+            yield output_dir
+            output_dir.close
+          else
+            return output_dir
+          end
+        end
+
+        #
+        # "Closes" the output directory.
+        #
+        # @note This method is mainly for compatibility with {OutputFile}.
+        #
+        def close
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/core/output_formats/output_file.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core 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-core 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-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/output_formats/output_format'
+
+module Ronin
+  module Core
+    module OutputFormats
+      #
+      # Base class for all output file formats.
+      #
+      # @api semipublic
+      #
+      # @since 0.2.0
+      #
+      class OutputFile < OutputFormat
+
+        # The output stream to write to.
+        #
+        # @return [IO]
+        attr_reader :io
+
+        #
+        # Initializes the output format.
+        #
+        # @param [IO] io
+        #   The output stream to write to.
+        #
+        def initialize(io)
+          super()
+
+          @io = io
+        end
+
+        #
+        # Opens an output file.
+        #
+        # @param [String] path
+        #   The path to the new output file.
+        #
+        # @yield [output_format]
+        #   If a block is given, it will be passed the initialized output
+        #   format. Once the block returns, the output format will automatically
+        #   be closed.
+        #
+        # @yieldparam [OutputFormat] output_format
+        #   The newly opened output format.
+        #
+        # @return [OutputFormat]
+        #   If no block is given, the newly initialized output format will be
+        #   returned.
+        #
+        def self.open(path)
+          output = new(File.open(path,'w'))
+
+          if block_given?
+            yield output
+            output.close
+          else
+            return output
+          end
+        end
+
+        #
+        # Closes the output file.
+        #
+        def close
+          @io.close unless @io == $stdout
+        end
+
+      end
+    end
+  end
+end