ronin-db-activerecord 0.1.0.beta1

data/lib/ronin/db/credential.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+#
+# ronin-db-activerecord - ActiveRecord backend for the Ronin Database.
+#
+# Copyright (c) 2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db-activerecord 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-activerecord 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-activerecord.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/db/model'
+require 'ronin/db/model/importable'
+
+require 'active_record'
+
+module Ronin
+  module DB
+    #
+    # Represents Credentials used to access services or websites.
+    #
+    class Credential < ActiveRecord::Base
+
+      include Model
+      include Model::Importable
+
+      # @!attribute [rw] id
+      #   Primary key of the credential.
+      #
+      #   @return [Integer]
+      attribute :id, :integer
+
+      # @!attribute [rw] user_name
+      #   User name of the credential.
+      #
+      #   @return [UserName, nil]
+      belongs_to :user_name, optional: true
+      validates :user_name, presence: true,
+                            if: ->(cred) { cred.email_address.nil? }
+
+      # @!attribute [rw] email_address
+      #   The optional email address associated with the Credential
+      #
+      #   @return [EmailAddress, nil]
+      belongs_to :email_address, optional: true
+      validates :email_address, presence: true,
+                                if: ->(cred) { cred.user_name.nil? }
+
+      # @!attribute [rw] password
+      #   Password of the credential.
+      #
+      #   @return [Password]
+      belongs_to :password, required: true
+
+      # @!attribute [rw] service_credentials
+      #   The service credentials.
+      #
+      #   @return [Array<ServiceCredential>]
+      has_many :service_credentials, dependent: :destroy
+
+      # @!attribute [rw] open_ports
+      #   The open ports that accept this credential pair.
+      #
+      #   @return [Array<OpenPort>]
+      has_many :open_ports, through: :service_credentials
+
+      # @!attribute [rw] web_credentials
+      #   The Web credentials.
+      #
+      #   @return [Array<WebCredential>]
+      has_many :web_credentials, dependent: :destroy
+
+      # @!attribute [rw] urls
+      #   The URLs that accept this credential pair.
+      #
+      #   @return [Array<URL>]
+      has_many :urls, through: :web_credentials
+
+      #
+      # Searches for all credentials for a specific user.
+      #
+      # @param [String] name
+      #   The name of the user.
+      #
+      # @return [Array<Credential>]
+      #   The credentials for the user.
+      #
+      # @api public
+      #
+      def self.for_user(name)
+        joins(:user_name).where(user_name: {name: name})
+      end
+
+      #
+      # Searches all web credentials that are associated with an
+      # email address.
+      #
+      # @param [String] email
+      #   The email address to search for.
+      #
+      # @return [Array<WebCredential>]
+      #   The web credentials associated with the email address.
+      #
+      # @raise [ArgumentError]
+      #   The given email address was not a valid email address.
+      #
+      # @api public
+      #
+      def self.with_email_address(email)
+        unless email.include?('@')
+          raise(ArgumentError,"invalid email address #{email.inspect}")
+        end
+
+        user, domain = email.split('@',2)
+
+        return joins(email_address: [:user_name, :host_name]).where(
+          email_address: {
+            ronin_user_names: {name: user},
+            ronin_host_names: {name: domain}
+          }
+        )
+      end
+
+      #
+      # Searches for all credentials with a common password.
+      #
+      # @param [String] password
+      #   The password to search for.
+      #
+      # @return [Array<Credential>]
+      #   The credentials with the common password.
+      #
+      # @api public
+      #
+      def self.with_password(password)
+        joins(:password).where(password: {plain_text: password})
+      end
+
+      #
+      # Looks up the given credential.
+      #
+      # @param [String] cred
+      #   The credential String
+      #   (ex: `user:password` or `user@example.com:password`).
+      #
+      # @return [Credential, nil]
+      #   The found credential.
+      #
+      def self.lookup(cred)
+        unless cred.include?(':')
+          raise(ArgumentError,"credential must be of the form user:password or email:password: #{cred.inspect}")
+        end
+
+        user_or_email, password = cred.split(':',2)
+
+        query = if user_or_email.include?('@')
+                  with_email_address(user_or_email)
+                else
+                  for_user(user_or_email)
+                end
+        query.with_password(password)
+        return query.first
+      end
+
+      #
+      # Imports the given credential.
+      #
+      # @param [String] cred
+      #   The credential String
+      #   (ex: `user:password` or `user@example.com:password`).
+      #
+      # @return [Credential]
+      #   The imported credential.
+      #
+      def self.import(cred)
+        unless cred.include?(':')
+          raise(ArgumentError,"credential must be of the form user:password or email:password: #{cred.inspect}")
+        end
+
+        user_or_email, password = cred.split(':',2)
+
+        if user_or_email.include?('@')
+          create(
+            email_address: EmailAddress.find_or_import(user_or_email),
+            password:      Password.find_or_import(password)
+          )
+        else
+          create(
+            user_name: UserName.find_or_import(user_or_email),
+            password:  Password.find_or_import(password)
+          )
+        end
+      end
+
+      #
+      # The user the credential belongs to.
+      #
+      # @return [String]
+      #   The user name.
+      #
+      # @api public
+      #
+      def user
+        self.user_name.name if self.user_name
+      end
+
+      #
+      # The clear-text password of the credential.
+      #
+      # @return [String]
+      #   The clear-text password.
+      #
+      # @api public
+      #
+      def plain_text
+        self.password.plain_text if self.password
+      end
+
+      #
+      # Converts the credentials to a String.
+      #
+      # @return [String]
+      #   The user name and the password.
+      #
+      # @api public
+      #
+      def to_s
+        "#{self.user_name}:#{self.password}"
+      end
+
+    end
+  end
+end
+
+require 'ronin/db/user_name'
+require 'ronin/db/email_address'
+require 'ronin/db/password'
+require 'ronin/db/service_credential'
+require 'ronin/db/web_credential'

data/lib/ronin/db/email_address.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+#
+# ronin-db-activerecord - ActiveRecord backend for the Ronin Database.
+#
+# Copyright (c) 2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db-activerecord 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-activerecord 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-activerecord.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/db/model'
+require 'ronin/db/model/importable'
+
+require 'active_record'
+require 'uri/mailto'
+
+module Ronin
+  module DB
+    #
+    # Represents email addresses and their associated {UserName user names} and
+    # {HostName host names}.
+    #
+    class EmailAddress < ActiveRecord::Base
+
+      include Model
+      include Model::Importable
+
+      # @!attribute [rw] id
+      #   The primary key of the email address.
+      #
+      #   @return [Integer]
+      attribute :id, :integer
+
+      # @!attribute [rw] address
+      #   The raw string of the email address.
+      #
+      #   @return [String]
+      attribute :address, :string
+      validates :address, presence: true,
+                          uniqueness: true,
+                          length: {maximum: 320},
+                          format: {
+                            with: URI::MailTo::EMAIL_REGEXP,
+                            message: 'Must be a valid email address'
+                          }
+
+      # @!attribute [rw] user_name
+      #   The user-name component of the email address.
+      #
+      #   @return [UserName]
+      belongs_to :user_name, required: true
+      validates :user_name, uniqueness: {scope: [:host_name_id]}
+
+      # @!attribute [rw] host_name
+      #   The host-name component of the email address.
+      #
+      #   @return [HostName]
+      belongs_to :host_name, required: true
+
+      # @!attribute [rw] ip_addresses
+      #   Any IP addresses associated with the host name.
+      #
+      #   @return [Array<IPAddress>]
+      has_many :ip_addresses, through:    :host_name,
+                              class_name: 'IPAddress'
+
+      # @!attribute [rw] credentials
+      #   Any web credentials that are associated with the email address.
+      #
+      #   @return [Array<Credential>]
+      has_many :credentials, dependent: :destroy
+
+      # @!attribute [rw] created_at
+      #   Tracks when the email address was created at.
+      #
+      #   @return [Time]
+      attribute :created_at, :time
+
+      #
+      # Searches for email addresses associated with the given host name(s).
+      #
+      # @param [Array<String>, String] name
+      #   The host name(s) to search for.
+      #
+      # @return [Array<EmailAddress>]
+      #   The matching email addresses.
+      #
+      # @api public
+      #
+      def self.with_host_name(name)
+        joins(:host_name).where(host_name: {name: name})
+      end
+
+      #
+      # Searches for email addresses associated with the given IP address(es).
+      #
+      # @param [Array<String>, String] ip
+      #   The IP address(es) to search for.
+      #
+      # @return [Array<EmailAddress>]
+      #   The matching email addresses.
+      #
+      # @api public
+      #
+      def self.with_ip_address(ip)
+        joins(:ip_addresses).where(ip_addresses: {address: ip})
+      end
+
+      #
+      # Searches for email addresses associated with the given user name(s).
+      #
+      # @param [Array<String>, String] name
+      #   The user name(s) to search for.
+      #
+      # @return [Array<EmailAddress>]
+      #   The matching email addresses.
+      #
+      # @api public
+      #
+      def self.with_user_name(name)
+        joins(:user_name).where(user_name: {name: name})
+      end
+
+      #
+      # Looks up the email address.
+      #
+      # @param [String] email
+      #   The raw email address string.
+      #
+      # @return [EmailAddress, nil]
+      #   The found email address.
+      #
+      def self.lookup(email)
+        find_by(address: email)
+      end
+
+      #
+      # Imports an email address.
+      #
+      # @param [String] email
+      #   The email address to parse.
+      #
+      # @return [EmailAddress]
+      #   A new or previously saved email address resource.
+      #
+      # @raise [ArgumentError]
+      #   The email address did not have a user name or a host name.
+      #
+      # @api public
+      #
+      def self.import(email)
+        if email =~ /\s/
+          raise(ArgumentError,"email address #{email.inspect} must not contain spaces")
+        end
+
+        normalized_email = email.downcase
+        user, host       = normalized_email.split('@',2)
+
+        if user.empty?
+          raise(ArgumentError,"email address #{email.inspect} must have a user name")
+        end
+
+        if host.empty?
+          raise(ArgumentError,"email address #{email.inspect} must have a host name")
+        end
+
+        return create(
+          address:   normalized_email,
+          user_name: UserName.find_or_import(user),
+          host_name: HostName.find_or_import(host)
+        )
+      end
+
+      #
+      # The user of the email address.
+      #
+      # @return [String]
+      #   The user name.
+      #
+      # @api public
+      #
+      def user
+        self.user_name.name if self.user_name
+      end
+
+      #
+      # The host of the email address.
+      #
+      # @return [String]
+      #   The host name.
+      #
+      # @api public
+      #
+      def host
+        self.host_name.name if self.host_name
+      end
+
+      #
+      # Converts the email address into a String.
+      #
+      # @return [String]
+      #   The raw email address.
+      #
+      # @api public
+      #
+      def to_s
+        "#{self.user_name}@#{self.host_name}"
+      end
+
+    end
+  end
+end
+
+require 'ronin/db/user_name'
+require 'ronin/db/host_name'

data/lib/ronin/db/host_name.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+#
+# ronin-db-activerecord - ActiveRecord backend for the Ronin Database.
+#
+# Copyright (c) 2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-db-activerecord 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-activerecord 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-activerecord.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/db/model'
+require 'ronin/db/model/importable'
+require 'ronin/db/model/last_scanned_at'
+
+require 'active_record'
+require 'uri/rfc2396_parser'
+require 'strscan'
+
+module Ronin
+  module DB
+    #
+    # Represents host names and their associated {IPAddress IP addresses}.
+    #
+    class HostName < ActiveRecord::Base
+
+      include Model
+      include Model::Importable
+      include Model::LastScannedAt
+
+      # @!attribute [rw] id
+      #   The primary ID of the host nmae.
+      #
+      #   @return [Integer]
+      attribute :id, :integer
+
+      # @!attribute [rw] name
+      #   The address of the host name.
+      #
+      #   @return [String]
+      attribute :name, :string
+      validates :name, presence: true,
+                       uniqueness: true,
+                       length: {maximum: 255},
+                       format: {
+                         with: /\A#{URI::RFC2396_REGEXP::PATTERN::HOSTNAME}\z/,
+                         message: 'Must be a valid host-name'
+                       }
+
+      # @!attribute [rw] created_at
+      #   When the host name was first created.
+      #
+      #   @return [Time]
+      attribute :created_at, :time
+
+      # @!attribute [rw] host_name_ip_addresses
+      #   The IP Address associations.
+      #
+      #   @return [Array<HostNameIPAddress>]
+      has_many :host_name_ip_addresses, dependent: :destroy,
+                                        class_name: 'HostNameIPAddress'
+
+      # @!attribute [rw] ip_addresses
+      #   The IP Addresses that host the host name.
+      #
+      #   @return [Array<IPAddress>]
+      has_many :ip_addresses, through:    :host_name_ip_addresses,
+                              class_name: 'IPAddress'
+
+      # @!attribute [rw] open_ports
+      #   The open ports of the host.
+      #
+      #   @return [Array<OpenPort>]
+      has_many :open_ports, through: :ip_addresses
+
+      # @!attribute [rw] ports
+      #   The ports of the host.
+      #
+      #   @return [Array<Port>]
+      has_many :ports, through: :ip_addresses
+
+      # @!attribute [rw] email_addresses
+      #   The email addresses that are associated with the host-name.
+      #
+      #   @return [Array<EmailAddress>]
+      has_many :email_addresses
+
+      # @!attribute [rw] urls
+      #   The URLs that point to this host name.
+      #
+      #   @return [Array<URL>]
+      has_many :urls, class_name: 'URL'
+
+      #
+      # Looks up the host name.
+      #
+      # @param [String] name
+      #   The raw host name.
+      #
+      # @return [HostName, nil]
+      #   The found host name.
+      #
+      def self.lookup(name)
+        find_by(name: name)
+      end
+
+      #
+      # Creates a new host name.
+      #
+      # @param [String] name
+      #   The host name.
+      #
+      # @return [HostName]
+      #   The created host name record.
+      #
+      def self.import(name)
+        create(name: name)
+      end
+
+      #
+      # Searches for host names associated with the given IP address(es).
+      #
+      # @param [Array<String>, String] ip
+      #   The IP address(es) to search for.
+      #
+      # @return [Array<HostName>]
+      #   The matching host names.
+      #
+      # @api public
+      #
+      def self.with_ip_address(ip)
+        joins(:ip_addresses).where(ip_addresses: {address: ip})
+      end
+
+      #
+      # Searches for host names with the given open port(s).
+      #
+      # @param [Array<Integer>, Integer] number
+      #   The open port(s) to search for.
+      #
+      # @return [Array<HostName>]
+      #   The matching host names.
+      #
+      # @api public
+      #
+      def self.with_port_number(number)
+        joins(:ports).where(ports: {number: number})
+      end
+
+      #
+      # Searches for all host names under the Top-Level Domain (TLD).
+      #
+      # @param [String] name
+      #   The Top-Level Domain (TLD).
+      #
+      # @return [Array<HostName>]
+      #   The matching host names.
+      #
+      # @api public
+      #
+      def self.with_tld(name)
+        name_column = self.arel_table[:name]
+
+        where(name_column.matches("%.#{sanitize_sql_like(name)}"))
+      end
+
+      #
+      # Searches for all host names sharing a canonical domain name.
+      #
+      # @param [String] name
+      #   The canonical domain name to search for.
+      #
+      # @return [Array<HostName>]
+      #   The matching host names.
+      #
+      # @api public
+      #
+      def self.with_domain(name)
+        name_column = self.arel_table[:name]
+
+        name = sanitize_sql_like(name)
+
+        where(name: name).or(where(name_column.matches("%.#{name}")))
+      end
+
+      #
+      # The IP Address that was most recently used by the host name.
+      #
+      # @return [IPAddress]
+      #   The IP Address that most recently used by the host name.
+      #
+      # @api public
+      #
+      def recent_ip_address
+        self.host_name_ip_addresses.order('created_at DESC').ip_addresses.first
+      end
+
+      #
+      # Converts the host name to a String.
+      #
+      # @return [String]
+      #   The host name.
+      #
+      # @api public
+      #
+      def to_s
+        self.name.to_s
+      end
+
+    end
+  end
+end
+
+require 'ronin/db/host_name_ip_address'
+require 'ronin/db/ip_address'