ronin-core 0.1.0.beta1

data/README.md

@@ -0,0 +1,299 @@
+# ronin-core
+
+[![CI](https://github.com/ronin-rb/ronin-core/actions/workflows/ruby.yml/badge.svg)](https://github.com/ronin-rb/ronin-core/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/ronin-rb/ronin-core.svg)](https://codeclimate.com/github/ronin-rb/ronin-core)
+
+* [Website](https://ronin-rb.dev/)
+* [Source](https://github.com/ronin-rb/ronin-core)
+* [Issues](https://github.com/ronin-rb/ronin-core/issues)
+* [Documentation](https://ronin-rb.dev/docs/ronin-core/frames)
+* [Discord](https://discord.gg/6WAb3PsVX9) |
+  [Twitter](https://twitter.com/ronin_rb) |
+  [Mastodon](https://infosec.exchange/@ronin_rb)
+
+## Description
+
+ronin-core is a core library providing common functionality for all ronin
+libraries.
+
+ronin-core is part of the [ronin-rb] project, a toolkit for security research
+and development.
+
+## Features
+
+* Provides access to the XDG directories (`~/.config/`, `~/.cache/`,
+  `~/.local/share`).
+* Allows querying `~/.gitconfig` for common git settings.
+* Provides a common `Command` base class for all ronin libraries.
+* Provides a `Shell` and `CommandShell` base classes for writing interactive
+  shells.
+* Provides a `Params` API for adding user configurable parameters to classes.
+* Has 85% documentation coverage.
+* Has 99% test coverage.
+
+## Requirements
+
+* [Ruby] >= 3.0.0
+* [reline] ~> 0.1
+* [command_kit] ~> 0.4
+* [irb] ~> 1.0
+
+## Install
+
+### Gemfile
+
+```ruby
+gem 'ronin-core', '~> 0.1'
+```
+
+### gemspec
+
+```ruby
+gem.add_depedency 'ronin-core', '~> 0.1'
+```
+
+### [gemspec.yml]
+
+```yaml
+dependencies:
+  ronin-core: ~> 0.1
+```
+
+## Examples
+
+### Params
+
+```ruby
+class BaseClass
+
+  include Ronin::Core::Params::Mixin
+
+end
+```
+
+```ruby
+class MyModule < BaseClass
+
+  param :str, desc: 'A basic string param'
+
+  param :feature_flag, Boolean, desc: 'A boolean param'
+
+  param :enum, Enum[:one, :two, :three],
+               desc: 'An enum param'
+
+  param :num1, Integer, desc: 'An integer param'
+
+  param :num2, Integer, default: 42,
+                       desc: 'A param with a default value'
+
+  param :num3, Integer, default: ->{ rand(42) },
+                        desc: 'A param with a dynamic default value'
+
+  param :float, Float, 'Floating point param'
+
+  param :url, URI, desc: 'URL param'
+
+  param :pattern, Regexp, desc: 'Regular Expression param'
+
+end
+
+mod = MyModule.new(params: {num1: 1, enum: :two})
+mod.params
+# => {:num2=>42, :num3=>25, :num1=>1, :enum=>:two}
+```
+
+### CLI
+
+Define a main command for `ronin-foo`:
+
+```ruby
+# lib/ronin/foo/cli.rb
+require 'command_kit/commands'
+require 'command_kit/commands/auto_load'
+
+module Ronin
+  module Foo
+    class CLI
+
+      include CommandKit::Commands
+      include CommandKit::Commands::AutoLoad.new(
+        dir:       "#{__dir__}/cli/commands",
+        namespace: "#{self}::Commands"
+      )
+
+      command_name 'ronin-foo'
+
+      command_aliases['ls'] = 'list'
+      # ...
+
+    end
+  end
+end
+```
+
+Add a `bin/ronin-foo` file (don't forget to `chmod +x` it) that invokes the
+main command:
+
+```ruby
+#!/usr/bin/env ruby
+
+root = File.expand_path(File.join(__dir__,'..'))
+if File.file?(File.join(root,'Gemfile.lock'))
+  Dir.chdir(root) do
+    begin
+      require 'bundler/setup'
+    rescue LoadError => e
+      warn e.message
+      warn "Run `gem install bundler` to install Bundler"
+      exit -1
+    end
+  end
+end
+
+require 'ronin/foo/cli'
+Ronin::Foo::CLI.start
+```
+
+Define a common command class for all `ronin-foo`'s commands:
+
+```ruby
+# lib/ronin/foo/cli/command.rb
+require 'ronin/core/cli/command'
+
+module Ronin
+  module Foo
+    class CLI
+      class Command < Core::CLI::Command
+
+        man_dir File.join(__dir__,'..','..','..','..','man')
+
+      end
+    end
+  end
+end
+```
+
+Define a `list` sub-command under the `ronin-foo` main command:
+
+```ruby
+# lib/ronin/foo/cli/commands/list.rb
+require 'ronin/foo/cli/command'
+
+module Ronin
+  module Foo
+    class CLI
+      module Commands
+        class List < Command
+
+          usage '[options] [NAME]'
+
+          argument :name, required: false,
+                          desc:     'Optional name to list'
+
+          description 'Lists all things'
+
+          man_page 'ronin-foo-list.1'
+
+          def run(name=nil)
+            # ...
+          end
+
+        end
+      end
+    end
+  end
+end
+```
+
+Test it out:
+
+```shell
+$ ./bin/ronin-foo
+Usage: ronin-foo [options] [COMMAND [ARGS...]]
+
+Options:
+    -h, --help                       Print help information
+
+Arguments:
+    [COMMAND]                        The command name to run
+    [ARGS ...]                       Additional arguments for the command
+
+Commands:
+    help
+    list, ls
+$ ./bin/ronin-foo ls
+```
+
+### CLI::CommandShell
+
+Define a custom command shell:
+
+```ruby
+class HTTPShell < Ronin::Core::CLI::CommandShell
+
+  shell_name 'http'
+
+  command :get, usage: 'PATH [HEADERS...]',
+                summary: 'Sends a GET request'
+  def get(path,*headers)
+    # ...
+  end
+
+  command :post, usage: 'PATH DATA [HEADERS...]',
+                 summary: 'Sends a POST request'
+  def post(path,data,*headers)
+    # ...
+  end
+
+end
+```
+
+Then start it:
+
+```ruby
+HTTPShell.start
+```
+
+```
+http> get /foo
+...
+http> post /foo var=bar
+...
+```
+
+## Development
+
+1. [Fork It!](https://github.com/ronin-rb/ronin-core/fork)
+2. Clone It!
+3. `cd ronin-core/`
+4. `bundle install`
+5. `git checkout -b my_feature`
+6. Code It!
+7. `bundle exec rake spec`
+8. `git push origin my_feature`
+
+## License
+
+Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3@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/>.
+
+[ronin-rb]: https://ronin-rb.dev/
+
+[Ruby]: https://www.ruby-lang.org
+[command_kit]: https://github.com/postmodern/command_kit.rb#readme
+[reline]: https://github.com/ruby/reline#readme
+[irb]: https://github.com/ruby/irb#readme
+
+[gemspec.yml]: https://github.com/postmodern/gemspec.yml#readme

data/Rakefile

@@ -0,0 +1,34 @@
+require 'rubygems'
+
+begin
+  require 'bundler'
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install bundler` to install Bundler"
+  exit(-1)
+end
+
+begin
+  Bundler.setup(:development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'rubygems/tasks'
+Gem::Tasks.new(sign: {checksum: true, pgp: true})
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task :docs => :yard
+
+require 'kramdown/man/task'
+Kramdown::Man::Task.new

data/examples/ruby_shell.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+
+require 'ronin/core/cli/ruby_shell'
+
+module Ronin
+  module Test
+  end
+end
+
+Ronin::Core::CLI::RubyShell.start(name: 'ronin-test', context: Ronin::Test)

data/gemspec.yml

@@ -0,0 +1,28 @@
+name: ronin-core
+summary: A core library for all ronin libraries.
+description: |
+  ronin-core is a core library providing common functionality for all ronin
+  libraries.
+
+license: LGPL-3.0
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://ronin-rb.dev/
+has_yard: true
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/ronin-core
+  source_code_uri:   https://github.com/ronin-rb/ronin-core
+  bug_tracker_uri:   https://github.com/ronin-rb/ronin-core/issues
+  changelog_uri:     https://github.com/ronin-rb/ronin-core/blob/main/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+required_ruby_version: ">= 3.0.0"
+
+dependencies:
+  reline: ~> 0.1
+  command_kit: ~> 0.4
+  irb: ~> 1.0
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/ronin/core/class_registry.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 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/>.
+#
+
+module Ronin
+  module Core
+    #
+    # A mixin that adds a class registry to a library:
+    #
+    # ### Example
+    #
+    # `lib/ronin/exploits.rb`:
+    #
+    #     require 'ronin/core/class_registry'
+    #     
+    #     module Ronin
+    #       module Exploits
+    #         include Ronin::Core::ClassRegistry
+    #     
+    #         class_dir "#{__dir__}/classes"
+    #       end
+    #     end
+    #
+    # `lib/ronin/exploits/exploit.rb`:
+    #
+    #     module Ronin
+    #       module Exploits
+    #         class Exploit
+    #     
+    #           def self.register(name)
+    #             Exploits.register(name,self)
+    #           end
+    #     
+    #         end
+    #       end
+    #     end
+    #
+    # `lib/ronin/exploits/my_exploit.rb`:
+    #
+    #     require 'ronin/exploits/exploit'
+    #     
+    #     module Ronin
+    #       module Exploits
+    #         class MyExploit < Exploit
+    #     
+    #           register 'my_exploit'
+    #     
+    #         end
+    #       end
+    #     end
+    #
+    # @api semipublic
+    #
+    module ClassRegistry
+      class ClassNotFound < RuntimeError
+      end
+
+      #
+      # Extends {ClassMethods}.
+      #
+      # @param [Module] namespace
+      #   The module that is including {ClassRegistry}.
+      #
+      def self.included(namespace)
+        namespace.extend ClassMethods
+      end
+
+      module ClassMethods
+        #
+        # Gets or sets the class directory path.
+        #
+        # @param [String, nil] new_dir
+        #   The new class directory path.
+        #
+        # @return [String]
+        #   The class directory path.
+        # 
+        # @raise [NotImplementedError]
+        #   The `class_dir` method was not defined in the module.
+        #
+        # @example
+        #   class_dir "#{__dir__}/classes"
+        #
+        def class_dir(new_dir=nil)
+          if new_dir
+            @class_dir = new_dir
+          else
+            @class_dir || raise(NotImplementedError,"#{self} did not define a class_dir")
+          end
+        end
+
+        #
+        # Lists all class files within {#class_dir}.
+        #
+        # @return [Array<String>]
+        #   The list of class paths within {#class_dir}.
+        #
+        def list_files
+          paths = Dir.glob('{**/}*.rb', base: class_dir)
+          paths.each { |path| path.chomp!('.rb') }
+          return paths
+        end
+
+        #
+        # The class registry.
+        #
+        # @return [Hash{String => Class}]
+        #   The mapping of class `id` and classes.
+        #
+        def registry
+          @registry ||= {}
+        end
+
+        #
+        # Registers a class with the registry.
+        #
+        # @param [String] id
+        #   The class `id` to be registered.
+        #
+        # @param [Class] mod
+        #   The class to be registered.
+        #
+        # @example
+        #   Exploits.register('myexploit',MyExploit)
+        #
+        def register(id,mod)
+          registry[id] = mod
+        end
+
+        #
+        # Finds the path for the class `id`.
+        #
+        # @param [String] id
+        #   The class `id`.
+        #
+        # @return [String, nil]
+        #   The path for the module. If the module file does not exist in
+        #   {#class_dir} then `nil` will be returned.
+        #
+        # @example
+        #   Exploits.path_for('my_exploit')
+        #   # => "/path/to/lib/ronin/exploits/classes/my_exploit.rb"
+        #
+        def path_for(id)
+          path = File.join(class_dir,"#{id}.rb")
+
+          if File.file?(path)
+            return path
+          end
+        end
+
+        #
+        # Loads a class from a file.
+        #
+        # @param [String] file
+        #   The file to load.
+        #
+        # @return [Class]
+        #   The loaded class.
+        #
+        # @raise [ClassNotFound]
+        #   The file does not exist or the class `id` was not found within the
+        #   file.
+        #
+        # @raise [LoadError]
+        #   A load error curred while requiring the other files required by
+        #   the class file.
+        #
+        def load_class_from_file(file)
+          file = File.expand_path(file)
+
+          unless File.file?(file)
+            raise(ClassNotFound,"no such file or directory: #{file.inspect}")
+          end
+
+          previous_entries = registry.keys
+          require(file)
+          new_entries = registry.keys - previous_entries
+
+          if new_entries.empty?
+            raise(ClassNotFound,"file did not register a class: #{file.inspect}")
+          end
+
+          return registry[new_entries.last]
+        end
+
+        #
+        # Loads a class from the {#class_dir}.
+        #
+        # @param [String] id
+        #   The class `id` to load.
+        #
+        # @return [Class]
+        #   The loaded class.
+        #
+        # @raise [ClassNotFound]
+        #   The class file could not be found within {#class_dir}.or has
+        #   a file/registered-name mismatch.
+        #
+        # @raise [LoadError]
+        #   A load error curred while requiring the other files required by
+        #   the class file.
+        #
+        def load_class(id)
+          # short-circuit if the module is already loaded
+          if (klass = registry[id])
+            return klass
+          end
+
+          unless (path = path_for(id))
+            raise(ClassNotFound,"could not find file for #{id.inspect}")
+          end
+
+          previous_entries = registry.keys
+          require(path)
+
+          unless (klass = registry[id])
+            new_entries = registry.keys - previous_entries
+
+            if new_entries.empty?
+              raise(ClassNotFound,"file did not register a class: #{path.inspect}")
+            else
+              raise(ClassNotFound,"file registered a class with a different id (#{new_entries.map(&:inspect).join(', ')}): #{path.inspect}")
+            end
+          end
+
+          return klass
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 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 'command_kit/command'
+require 'command_kit/help/man'
+require 'command_kit/bug_report'
+
+module Ronin
+  module Core
+    module CLI
+      #
+      # Common base class for all CLI commands.
+      #
+      # ## Example
+      #
+      # Define a common CLI command base class for all commands in the
+      # `ronin-foo` library:
+      #
+      #     # lib/ronin/foo/cli/command.rb
+      #     require 'ronin/core/cli/command'
+      #
+      #     module Ronin
+      #       module Foo
+      #         class CLI
+      #           class Command < Core::CLI::Command
+      #     
+      #             man_dir File.join(__dir__,'..','..','..','..','man')
+      #     
+      #           end
+      #         end
+      #       end
+      #     end
+      #
+      # Define a sub-command named `list` under the `ronin-foo` main command:
+      #
+      #     # lib/ronin/foo/cli/commands/list.rb
+      #     require 'ronin/foo/cli/command'
+      #     
+      #     module Ronin
+      #       module Foo
+      #         class CLI
+      #           module Commands
+      #             class List < Command
+      #     
+      #               usage '[options] [NAME]'
+      #     
+      #               argument :name, required: false,
+      #                               desc:     'Optional name to list'
+      #     
+      #               description 'Lists all things'
+      #     
+      #               man_page 'ronin-foo-list.1'
+      #     
+      #               def run(name=nil)
+      #                 # ...
+      #               end
+      #     
+      #             end
+      #           end
+      #         end
+      #       end
+      #     end
+      #
+      class Command < CommandKit::Command
+
+        include CommandKit::Help::Man
+        include CommandKit::BugReport
+
+      end
+    end
+  end
+end