ronin-db 0.1.0.beta1

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/cli/ruby_shell'
+
+module Ronin
+  module DB
+    class CLI
+      #
+      # The interactive Ruby shell for {Ronin::DB}.
+      #
+      class RubyShell < Core::CLI::RubyShell
+
+        #
+        # Initializes the `ronin-db` Ruby shell.
+        #
+        # @param [String] name
+        #   The name of the IRB shell.
+        #
+        # @param [Object] context
+        #   Custom context to launch IRB from within.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for
+        #   `Ronin::Core::CLI::RubyShell#initialize`.
+        #
+        def initialize(name: 'ronin-db', context: Ronin::DB, **kwargs)
+          super(name: name, context: context, **kwargs)
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/db/cli/uri_methods.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/db/cli/command'
+require 'ronin/db'
+
+module Ronin
+  module DB
+    class CLI
+      module URIMethods
+        # Common database adapter names and their ActiveRecord equivalents.
+        ADAPTER_ALIASES = {
+          'sqlite'   => 'sqlite3',
+          'mysql'    => 'mysql2',
+          'pg'       => 'postgresql',
+          'psql'     => 'postgresql',
+          'postgres' => 'postgresql'
+        }
+
+        #
+        # Normalizes a database adapter name.
+        #
+        # @param [String] adapter
+        #   The adapter name to normalize.
+        #
+        # @return [String]
+        #   The normalized adapter.
+        #
+        def normalize_adapter(adapter)
+          ADAPTER_ALIASES.fetch(adapter,adapter)
+        end
+
+        #
+        # Normalizes a sqlite3 database path.
+        #
+        # @param [String] path
+        #   The path to the sqlite3 database.
+        #
+        # @return [String]
+        #   The expanded path or `":memory:"` if the path was `":memory:"`.
+        #
+        def normalize_sqlite3_path(path)
+          if path== ':memory:' then path
+          else                      File.expand_path(path)
+          end
+        end
+
+        #
+        # Parses a database URI.
+        #
+        # @param [String] uri
+        #   The database URI to parse.
+        #
+        # @return [Hash{Symbol => String,Integer,nil}]
+        #   The database configuration Hash.
+        #
+        def parse_uri(uri)
+          if (match = uri.match(/\Asqlite[3]?:(.+)\z/))
+            {
+              adapter: 'sqlite3',
+              database: normalize_sqlite3_path(match[1])
+            }
+          else
+            uri     = URI.parse(uri)
+            adapter = normalize_adapter(uri.scheme)
+
+            hash = {adapter: adapter}
+            hash[:host]     = uri.host if uri.host
+            hash[:port]     = uri.port if uri.port
+            hash[:username] = uri.user if uri.user
+            hash[:password] = uri.password if uri.password
+            hash[:database] = uri.path[1..]
+
+            return hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/db/cli.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'command_kit/commands'
+require 'command_kit/commands/auto_load'
+
+module Ronin
+  module DB
+    class CLI
+
+      include CommandKit::Commands
+      include CommandKit::Commands::AutoLoad.new(
+        dir:       "#{__dir__}/cli/commands",
+        namespace: "#{self}::Commands"
+      )
+
+      command_name 'ronin-db'
+
+    end
+  end
+end

data/lib/ronin/db/config_file.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/db/exceptions'
+require 'ronin/db/home'
+
+require 'yaml'
+require 'yaml/store'
+
+module Ronin
+  module DB
+    #
+    # Represents the `~/.config/ronin-db/databases.yml` configuration file.
+    #
+    # @api private
+    #
+    module ConfigFile
+      # Path to the `~/.config/ronin-db/databases.yml` configuration file.
+      PATH = File.join(DB::Home::CONFIG_DIR,'databases.yml')
+
+      # Path to the default sqlite3 database file.
+      DEFAULT_DB_FILE = File.join(DB::Home::LOCAL_SHARE_DIR,'default.sqlite3')
+
+      # Default database configuration.
+      DEFAULT_CONFIG = {
+        default: {
+          adapter: 'sqlite3',
+          database: DEFAULT_DB_FILE
+        }
+      }
+
+      #
+      # Validates the loaded configuration data from the given path.
+      #
+      # @param [String] path
+      #   The path the configuration data was loaded from.
+      #
+      # @param [Object] data
+      #   The loaded configuration data.
+      #
+      # @raise [InvalidConfig]
+      #   The configuration data is not a Hash, does not contain Symbol keys,
+      #   or does not contain Hashes.
+      #
+      # @return [true]
+      #   The configuration data is valid.
+      #
+      def self.validate(path,data)
+        unless data.kind_of?(Hash)
+          raise(InvalidConfig)
+        end
+
+        data.each do |key,value|
+          unless (key.kind_of?(Symbol) || key.kind_of?(String))
+            raise(InvalidConfig)
+          end
+
+          unless value.kind_of?(Hash)
+            raise(InvalidConfig)
+          end
+
+          value.each_key do |sub_key|
+            unless (sub_key.kind_of?(Symbol) || sub_key.kind_of?(String))
+              raise(InvalidConfig)
+            end
+          end
+        end
+
+        return true
+      end
+
+      #
+      # Loads configuration data from the given path.
+      #
+      # @param [String] path
+      #   The path to the configuration file.
+      #
+      # @return [Hash{Symbol => Hash}]
+      #   The loaded configuration data.
+      #
+      # @raise [InvalidConfig]
+      #   The configuration data is not a Hash, does not contain Symbol keys,
+      #   or does not contain Hashes.
+      #
+      def self.load(path=PATH)
+        if File.file?(path)
+          config = YAML.load_file(path, symbolize_names: true).tap do |data|
+            validate(path,data)
+          end
+
+          DEFAULT_CONFIG.merge(config)
+        else
+          DEFAULT_CONFIG
+        end
+      end
+
+      #
+      # Opens the configuration file and edits it's contents.
+      #
+      # @yield [yaml]
+      #   The given block will be given the loaded configuration data.
+      #   Once the block has returned, the YAML configuration data will be
+      #   written back to the file.
+      #
+      # @yieldparam [YAML::Store] yaml
+      #   The loaded YAML configuration data.
+      #
+      def self.edit(path=PATH,&block)
+        store = YAML::Store.new(path)
+
+        store.transaction(&block)
+      end
+    end
+  end
+end

data/lib/ronin/db/exceptions.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module DB
+    class UnknownDatabase < RuntimeError
+    end
+  end
+end

data/lib/ronin/db/home.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/home'
+
+module Ronin
+  module DB
+    module Home
+      # The path to the `~/.config/ronin-db/` directory.
+      CONFIG_DIR = File.join(Core::Home::CONFIG_DIR,'ronin-db')
+
+      # The path to the `~/.cache/ronin-db/` directory.
+      CACHE_DIR = File.join(Core::Home::CACHE_DIR,'ronin-db')
+
+      # The path to the `~/.local/share/ronin-db/` directory.
+      LOCAL_SHARE_DIR = File.join(Core::Home::LOCAL_SHARE_DIR,'ronin-db')
+    end
+  end
+end

data/lib/ronin/db/root.rb

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

data/lib/ronin/db/version.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module DB
+    # ronin-db version
+    VERSION = '0.1.0.beta1'
+  end
+end

data/lib/ronin/db.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+#
+# ronin-db - A common database library for managing and querying security data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db 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-db 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-db.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/db/exceptions'
+require 'ronin/db/config_file'
+require 'ronin/db/version'
+
+module Ronin
+  module DB
+    #
+    # Sets up the Database logger.
+    #
+    # @api semipublic
+    #
+    def self.logger=(new_logger)
+      require 'active_record'
+      ActiveRecord::Base.logger = new_logger
+    end
+
+    #
+    # `ronin-db` database(s) configuration.
+    #
+    # @return [Hash{Symbol => Hash}]
+    #
+    # @api private
+    #
+    def self.config
+      @config ||= ConfigFile.load
+    end
+
+    #
+    # Migrate the database up and apply any pending migrations.
+    #
+    def self.migrate!
+      require 'ronin/db/migrations'
+      Migrations.migrate
+    end
+
+    #
+    # Only migrate the database if the database is empty, otherwise warn the
+    # user that there are pending migrations.
+    #
+    def self.migrate
+      require 'ronin/db/migrations'
+
+      if Migrations.current_version == 0
+        # auto-run the migrations when the database is empty
+        Migrations.migrate
+      elsif Migrations.needs_migration?
+        # warn the user that there are pending migrations, instead of
+        # auto-running migrations each time
+        warn "WARNING: Database requires migrating!"
+      end
+    end
+
+    #
+    # Connects to the Database.
+    #
+    # @param [Symbol, Hash] uri
+    #   The optional default repository to setup instead of {repositories}.
+    #
+    # @param [Boolean] migrate
+    #   Specifies whether to hard or lazy migrate the database.
+    #
+    # @param [Boolean] load_models
+    #   Specifies whether to load all models or just connect to the database.
+    #
+    # @raise [UnknownDatabase]
+    #
+    # @raise [ArgumentError]
+    #
+    # @api semipublic
+    #
+    def self.connect(database=:default, migrate: nil, load_models: true)
+      config = case database
+               when Hash
+                 database
+               when Symbol
+                 self.config.fetch(database) do
+                   raise(UnknownDatabase,"unknown database: #{database.inspect}")
+                 end
+               else
+                 raise(ArgumentError,"#{self.class}.#{__method__} only accepts a Symbol or a Hash")
+               end
+
+      # load activerecord
+      require 'active_record'
+
+      # connect to the database
+      ActiveRecord::Base.establish_connection(config)
+
+      # migrate the database if necessary
+      if migrate == true then migrate!
+      else                    self.migrate
+      end
+
+      if load_models
+        # require and connect all models
+        require 'ronin/db/models'
+        Models.connect
+      end
+
+      return true
+    end
+  end
+end

data/man/ronin-db-add.1

@@ -0,0 +1,99 @@
+.\" Generated by kramdown-man 0.1.8
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-db-add 1 "2022-01-01" Ronin DB "User Manuals"
+.LP
+.SH SYNOPSIS
+.LP
+.HP
+\fBronin-db add\fR \[lB]\fIoptions\fP\[rB] \fINAME\fP \[lB]\fIURI\fP\[rB]
+.LP
+.SH DESCRIPTION
+.LP
+.PP
+Lists entries in the \fB~/.config/ronin-db/database.yml\fR configuration file\.
+.LP
+.SH ARGUMENTS
+.LP
+.TP
+\fINAME\fP
+The name of the database to add\.
+.LP
+.TP
+\fIURI\fP
+The optional URI to the database to add\.
+.LP
+.SH OPTIONS
+.LP
+.TP
+\fB-A\fR, \fB--adapter\fR \fBsqlite3|mysql2|postgres|...\fR
+The adapter of the database to add\.
+.LP
+.TP
+\fB--sqlite3\fR \fIFILE\fP
+Alias for \fB--adapter sqlite3 --database\fR \fIFILE\fP\.
+.LP
+.TP
+\fB--mysql2\fR
+Alias for \fB--adapter mysql2\fR\.
+.LP
+.TP
+\fB--postgresql\fR
+Alias for \fB--adapter postgresql\fR\.
+.LP
+.TP
+\fB-H\fR, \fB--host\fR \fIHOST\fP
+The host of the database to add\.
+.LP
+.TP
+\fB-p\fR, \fB--port\fR \fIPORT\fP
+The port of the database to add\.
+.LP
+.TP
+\fB-u\fR, \fB--username\fR \fIUSER\fP
+The username to authenticate with for the database\.
+.LP
+.TP
+\fB-P\fR, \fB--password\fR \fIPASSWORD\fP
+The password to authenticate with for the database\.
+.LP
+.TP
+\fB--read-password\fR
+Reads the database password from STDIN\.
+.LP
+.TP
+\fB-D\fR, \fB--database\fR \fINAME\fP\[or]\fIPATH\fP
+The database name to connect to\. If \fB--adapter sqlite3\fR is given then a path
+may be given instead\.
+.LP
+.TP
+\fB-h\fR, \fB--help\fR
+Print help information\.
+.LP
+.SH FILES
+.LP
+.TP
+\fI\[ti]\[sl]\.config\[sl]ronin\-db\[sl]database\.yml\fP
+The \fBronin-db\fR database(s) configuration file\.
+.LP
+.SH ENVIRONMENT
+.LP
+.PP
+HOME
+Specifies the home directory of the user\. Ronin will search for the
+\fI\[ti]\[sl]\.config\[sl]ronin\-db\fP cache directory within the home directory\.
+.LP
+.PP
+XDG\[ru]CONFIG\[ru]HOME
+Specifies the cache directory to use\. Defaults to \fI\[Do]HOME\[sl]\.config\fP\.
+.LP
+.SH AUTHOR
+.LP
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME
+.LP
+.SH SEE ALSO
+.LP
+.PP
+ronin\-db(1) ronin\-db\-list(1) ronin\-db\-edit(1) ronin\-db\-remove(1)