wg-metasploit_data_models 4.1.4.01 → 4.1.4.02

data/app/models/metasploit_data_models/ip_address/v4/segment/single.rb

@@ -0,0 +1,123 @@
+# A segment number in an IPv4 address or the
+# {MetasploitDataModels::IPAddress::V4::Segment::Nmap::Range#begin} or
+# {MetasploitDataModels::IPAddress::V4::Segment::Nmap::Range#send}.
+class MetasploitDataModels::IPAddress::V4::Segment::Single < Metasploit::Model::Base
+  extend MetasploitDataModels::Match::Child
+
+  include Comparable
+
+  #
+  # CONSTANTS
+  #
+
+  # Number of bits in a IPv4 segment
+  BITS = 8
+
+  # Limit that {#value} can never reach
+  LIMIT = 1 << BITS
+
+  # Maximum segment {#value}
+  MAXIMUM = LIMIT - 1
+
+  # Minimum segment {#value}
+  MINIMUM = 0
+
+  # Regular expression for a segment (octet) of an IPv4 address in decimal dotted notation.
+  #
+  # @see http://stackoverflow.com/a/17871737/470451
+  REGEXP = /(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])/
+
+  #
+  # Attributes
+  #
+
+  # @!attribute value
+  #   The segment number.
+  #
+  #   @return [Integer, String]
+  attr_reader :value
+
+  #
+  # Validations
+  #
+
+  validates :value,
+            numericality: {
+                greater_than_or_equal_to: MINIMUM,
+                less_than_or_equal_to: MAXIMUM,
+                only_integer: true
+            }
+
+  #
+  # Class Methods
+  #
+
+  # (see BITS)
+  #
+  # @return [Integer] {BITS}
+  def self.bits
+    BITS
+  end
+
+  #
+  # Instance Methods
+  #
+
+  # Compare this segment to `other`.
+  #
+  # @param other [#value] another segent to compare against.
+  # @return [1] if this segment is greater than `other`.
+  # @return [0] if this segment is equal to `other`.
+  # @return [-1] if this segment is less than `other`.
+  def <=>(other)
+    value <=> other.value
+  end
+
+  # Full add (as in [full adder](https://en.wikipedia.org/wiki/Full_adder)) two (this segment and `other`) segments and
+  # a carry from the previous {#add_with_carry}.
+  #
+  # @param other [MetasploitDataModels:IPAddress::V4::Segment::Single] segment to add to this segment.
+  # @param carry [Integer] integer to add to this segment and other segment from a previous call to {#add_with_carry}
+  #   for lower segments.
+  # @return [Array<(MetasploitDataModels::IPAddress::V4::Segment::Single, Integer)>] Array containing a proper segment
+  #   (where {#value} is less than {LIMIT}) and a carry integer to pass to next call to {#add_with_carry}.
+  # @return (see #half_add)
+  def add_with_carry(other, carry=0)
+    improper_value = self.value + other.value + carry
+    proper_value = improper_value % LIMIT
+    carry = improper_value / LIMIT
+    segment = self.class.new(value: proper_value)
+
+    [segment, carry]
+  end
+
+  # The succeeding segment.  Used in `Range`s when walking the `Range`.
+  #
+  # @return [MetasploitDataModels::IPAddress::V4::Segment::Single] if {#value} responds to `#succ`.
+  # @return [nil] otherwise
+  def succ
+    if value.respond_to? :succ
+      self.class.new(value: value.succ)
+    end
+  end
+
+  delegate :to_s,
+           to: :value
+
+  # Sets {#value} by type casting String to Integer.
+  #
+  # @param formatted_value [#to_s]
+  # @return [Integer] if `formatted_value` contains only an Integer#to_s
+  # @return [#to_s] `formatted_value` if it does not contain an Integer#to_s
+  def value=(formatted_value)
+    @value_before_type_cast = formatted_value
+
+    begin
+      # use Integer() instead of String#to_i as String#to_i will ignore trailing letters (i.e. '1two' -> 1) and turn all
+      # string without an integer in it to 0.
+      @value = Integer(formatted_value.to_s)
+    rescue ArgumentError
+      @value = formatted_value
+    end
+  end
+end

data/app/models/metasploit_data_models/ip_address/v4/segmented.rb

@@ -0,0 +1,200 @@
+# @note {segment} must be called in subclasses to set the {segment_class_name}.
+#
+# An IPv4 address that is composed of {SEGMENT_COUNT 4} {#segments} separated by {SEPARATOR `'.'`}.
+#
+# @example Using single segments to make a single IPv4 address class
+#   class MetasploitDataModels::IPAddress::V4::Single < MetasploitDataModels::IPAddress::V4::Segmented
+#      #
+#      # Segments
+#      #
+#
+#      segment class_name: 'MetasploitDataModels::IPAddress::V4::Segment::Single'
+#   end
+#
+class MetasploitDataModels::IPAddress::V4::Segmented < Metasploit::Model::Base
+  extend MetasploitDataModels::Match::Child
+
+  include Comparable
+
+  #
+  # CONSTANTS
+  #
+
+  # The number of {#segments}
+  SEGMENT_COUNT = 4
+  # Separator between segments
+  SEPARATOR = '.'
+
+  #
+  # Attributes
+  #
+
+  # @!attribute value
+  #   Segments of IP address from high to low.
+  #
+  #   @return [Array<MetasploitDataModels::IPAddress:V4::Segment::Nmap>]
+  attr_reader :value
+
+  #
+  #
+  # Validations
+  #
+  #
+
+  #
+  # Validation Methods
+  #
+
+  validate :segments_valid
+
+  #
+  # Attribute Validations
+  #
+
+  validates :segments,
+            length: {
+              is: SEGMENT_COUNT
+            }
+
+  #
+  # Class methods
+  #
+
+  # @note Call {segment} with the {segment_class_name} before calling this method, as it uses {segment_class} to look
+  #   up the `REGEXP` of the {segment_class}.
+  #
+  # Regular expression that matches the part of a string that represents a IPv4 segmented IP address format.
+  #
+  # @return [Regexp]
+  def self.regexp
+    unless instance_variable_defined? :@regexp
+      separated_segment_count = SEGMENT_COUNT - 1
+
+      @regexp = %r{
+        (#{segment_class::REGEXP}#{Regexp.escape(SEPARATOR)}){#{separated_segment_count},#{separated_segment_count}}
+        #{segment_class::REGEXP}
+      }x
+    end
+
+    @regexp
+  end
+
+  # Sets up the {segment_class_name} for the subclass.
+  #
+  # @example Using {segment} to set {segment_class_name}
+  #   segment class_name: 'MetasploitDataModels::IPAddress::V4::Segment::Single'
+  #
+  # @param options [Hash{Symbol => String}]
+  # @option options [String] :class_name a `Class#name` to use for {segment_class_name}.
+  # @return [void]
+  def self.segment(options={})
+    options.assert_valid_keys(:class_name)
+
+    @segment_class_name = options.fetch(:class_name)
+  end
+
+  # @note Call {segment} to set the {segment_class_name} before calling {segment_class}, which will attempt to
+  #   String#constantize` {segment_class_name}.
+  #
+  # The `Class` used to parse each segment of the IPv4 address.
+  #
+  # @return [Class]
+  def self.segment_class
+    @segment_class = segment_class_name.constantize
+  end
+
+  # @note Call {segment} to set {segment_class_name}
+  #
+  # The name of {segment_class}
+  #
+  # @return [String] a `Class#name` for {segment_class}.
+  def self.segment_class_name
+    @segment_class_name
+  end
+
+  # (see SEGMENT_COUNT)
+  #
+  # @return [Integer]
+  def self.segment_count
+    SEGMENT_COUNT
+  end
+
+  #
+  # Instance methods
+  #
+
+  # Compare this segment IPv4 address to `other`.
+  #
+  # @return [1] if {#segments} are greater than {#segments} of `other`.
+  # @return [0] if {#segments} are equal to {#segments} of `other`.
+  # @return [-1] if {#segments} are less than {#segments} of `other`.
+  # @return [nil] if `other` isn't the same `Class`
+  def <=>(other)
+    if other.is_a? self.class
+      segments <=> other.segments
+    else
+      # The interface for <=> requires nil be returned if other is incomparable
+      nil
+    end
+  end
+
+  # Array of segments.
+  #
+  # @return [Array] if {#value} is an `Array`.
+  # @return [[]] if {#value} is not an `Array`.
+  def segments
+    if value.is_a? Array
+      value
+    else
+      []
+    end
+  end
+
+  # Set {#segments}.
+  #
+  # @param segments [Array] `Array` of {segment_class} instances
+  # @return [Array] `Array` of {segment_class} instances
+  def segments=(segments)
+    @value = segments
+  end
+
+  # Segments joined with {SEPARATOR}.
+  #
+  # @return [String]
+  def to_s
+    segments.map(&:to_s).join(SEPARATOR)
+  end
+
+  # @note Set {#segments} if value is not formatted, but already broken into an `Array` of {segment_class} instances.
+  #
+  # Sets {#value} by parsing its segments.
+  #
+  # @param formatted_value [#to_s]
+  def value=(formatted_value)
+    string = formatted_value.to_s
+    match = self.class.match_regexp.match(string)
+
+    if match
+      segments = string.split(SEPARATOR)
+
+      @value = segments.map { |segment|
+        self.class.segment_class.new(value: segment)
+      }
+    else
+      @value = formatted_value
+    end
+  end
+
+  private
+
+  # Validates that all segments in {#segments} are valid.
+  #
+  # @return [void]
+  def segments_valid
+    segments.each_with_index do |segment, index|
+      unless segment.valid?
+        errors.add(:segments, :segment_invalid, index: index, segment: segment)
+      end
+    end
+  end
+end

data/app/models/metasploit_data_models/ip_address/v4/single.rb

@@ -0,0 +1,53 @@
+# A single IPv4 address, in standard, dotted decimal notation.
+#
+# @example Dotted Decimal Notation
+#   '1.2.3.4'
+#
+class MetasploitDataModels::IPAddress::V4::Single < MetasploitDataModels::IPAddress::V4::Segmented
+  #
+  # Segments
+  #
+
+  segment class_name: 'MetasploitDataModels::IPAddress::V4::Segment::Single'
+
+  #
+  # Instance Methods
+  #
+
+  # Adds `other` IPv4 address to this IPv4 address.
+  #
+  # @return [MetasploitDataModels::IPAddress::V4::Single] a new IPv4 address contain the sum of the two addresses
+  #   segments with carries from lower to higher segments.
+  # @raise [TypeError] if `other` isn't the same class.
+  # @raise [ArgmentError] if `self` plus `other` yields an IP address greater than 255.255.255.255.
+  # @see succ
+  def +(other)
+    unless other.is_a? self.class
+      raise TypeError, "Cannot add #{other.class} to #{self.class}"
+    end
+
+    carry = 0
+    sum_segments = []
+    low_to_high_segments = segments.zip(other.segments).reverse
+
+    low_to_high_segments.each do |self_segment, other_segment|
+      segment, carry = self_segment.add_with_carry(other_segment, carry)
+      sum_segments.unshift segment
+    end
+
+    unless carry == 0
+      raise ArgumentError,
+            "#{self} + #{other} is not a valid IP address.  It is #{sum_segments.join('.')} with a carry (#{carry})"
+    end
+
+    self.class.new(segments: sum_segments)
+  end
+
+  # The succeeding IPv4 address.
+  #
+  # @see #+
+  # @raise (see #+)
+  def succ
+    self + self.class.new(value: '0.0.0.1')
+  end
+end

data/app/models/metasploit_data_models/module_run.rb

@@ -0,0 +1,213 @@
+# {MetasploitDataModels::ModuleRun} holds the record of having launched a piece of Metasploit content.
+# It has associations to {Mdm::User} for audit purposes, and makes polymorphic associations to things like
+# {Mdm::Vuln} and {Mdm::Host} for flexible record keeping about activity attacking either specific vulns or just
+# making mischief on specific remote targets w/out the context of a vuln or even a remote IP service.
+#
+# There are also associations to {Mdm::Session} for two use cases: a `spawned_session` is a
+# session created by the ModuleRun. A `target_session` is a session that the ModuleRun
+# is acting upon (e.g.) for running a post module.
+class MetasploitDataModels::ModuleRun < ApplicationRecord
+  #
+  # Constants
+  #
+
+  # Marks the module as having successfully run
+  SUCCEED     = 'succeeded'
+  # Marks the run as having not run successfully
+  FAIL        = 'failed'
+  # Marks the module as having had a runtime error
+  ERROR       = 'error'
+  # {ModuleRun} objects will be validated against these statuses
+  VALID_STATUSES = [SUCCEED, FAIL, ERROR]
+
+
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] attempted_at
+  #   The date/time when this module was run
+  #   @return [Datetime]
+
+  # @!attribute [rw] fail_detail
+  #   Arbitrary information captured by the module to give in-depth reason for failure
+  #   @return [String]
+
+  # @!attribute [rw] fail_reason
+  #   One of the values of the constants in `Msf::Module::Failure`
+  #   @return [String]
+
+  # @!attribute [rw] module_name
+  #   The Msf::Module#fullname of the module being run
+  #   @return [String]
+
+  # @!attribute [rw] port
+  #   The port that the remote host was attacked on, if any
+  #   @return [Fixnum]
+
+  # @!attribute [rw] proto
+  #   The name of the protocol that the host was attacked on, if any
+  #   @return [String]
+
+  # @!attribute [rw] session_id
+  #   The {Mdm::Session} that this was run with, in the case of a post module. In exploit modules, this field will
+  #   remain null.
+  #   @return [Datetime]
+
+  # @!attribute [rw] status
+  #   The result of running the module
+  #   @return [String]
+
+  # @!attribute [rw] username
+  #   The name of the user running this module
+  #   @return [String]
+
+
+
+  #
+  # Associations
+  #
+
+
+
+  # @!attribute [rw] loots
+  #  The sweet, sweet loot taken by this module_run
+  #
+  #  @return [ActiveRecord::Relation<Mdm::Loot>]
+  has_many :loots,
+           class_name: 'Mdm::Loot',
+           inverse_of: :module_run
+
+  # @!attribute [rw] module_detail
+  #  The cached module information
+  #
+  #  @return [ActiveRecord::Relation<Mdm::Module::Detail>]
+  belongs_to :module_detail,
+             class_name: 'Mdm::Module::Detail',
+             inverse_of: :module_runs,
+             foreign_key: :module_fullname,
+             primary_key: :fullname
+
+  # @!attribute [rw] spawned_session
+  #
+  #  The session created by running this module.
+  #  Note that this is NOT the session that modules are run on.
+  #
+  #  @return [Mdm::Session]
+  has_one :spawned_session,
+             class_name: 'Mdm::Session',
+             inverse_of: :originating_module_run
+
+
+  # @!attribute [rw] target_session
+  #
+  #  The session this module was run on, if any.
+  #  Note that this is NOT a session created by this module run
+  #  of exploit modules.
+  #
+  #  @return [Mdm::Session]
+  belongs_to :target_session,
+             class_name: 'Mdm::Session',
+             foreign_key: :session_id,
+             inverse_of: :target_module_runs
+
+
+
+  # @!attribute [rw] trackable
+  #
+  #  A polymorphic association that is tracked as being related to this module run.
+  #  {Mdm::Host} and {Mdm::Vuln} can each have {ModuleRun} objects.
+  #
+  #  @return [Mdm::Host, Mdm::Vuln]
+  belongs_to :trackable, polymorphic: true
+
+
+  # @!attribute [rw] user
+  #
+  #  The user that launched this module
+  #
+  #  @return [Mdm::User]
+  belongs_to :user,
+             class_name:  'Mdm::User',
+             foreign_key: 'user_id',
+             inverse_of: :module_runs
+
+
+
+  #
+  #
+  # Validations
+  #
+  #
+
+  #
+  # Method Validations
+  #
+
+
+  # spawned_session is only valid for *exploit modules*
+  validate :no_spawned_session_for_non_exploits_except_logins
+
+  # target_session is only valid for *non-exploit modules*
+  validate :no_target_session_for_exploits
+
+  # Can't save without information on what module has run
+  validate :module_information_is_present
+
+  #
+  # Attribute Validations
+  #
+
+  # When the module was run
+  validates :attempted_at,
+            presence: true
+  # Result of running the module
+  validates :status,
+            inclusion: VALID_STATUSES
+
+  # Splits strings formatted like Msf::Module#fullname into components
+  #
+  # @example
+  #   module_name = "exploit/windows/multi/mah-rad-exploit"
+  #   module_name_components  # => ["exploit","windows","multi","mah-rad-exploit"]
+  # @return [Array]
+  def module_name_components
+    module_fullname.split('/')
+  end
+
+  private
+
+  # Mark the object as invalid if there is no associated #module_name or {Mdm::ModuleDetail}
+  # @return [void]
+  def module_information_is_present
+    if module_fullname.blank?
+      errors.add(:base, "module_fullname cannot be blank")
+    end
+  end
+
+  # Mark the object as invalid if there is a spawned_session but the module is *not* an exploit
+  # and not an aux module with the word "login" in the final portion of `module_fullname`
+  #
+  # @return [void]
+  def no_spawned_session_for_non_exploits_except_logins
+    return true unless spawned_session.present?
+    return true if module_name_components.last.include?("login")
+
+    if module_name_components.first != 'exploit'
+      errors.add(:base, 'spawned_session cannot be set for non-exploit modules. Use target_session.')
+    end
+  end
+
+  # Mark the object as invalid if there is a target_session but the module is an exploit
+  # @return [void]
+  def no_target_session_for_exploits
+    return true unless target_session.present? # nothing to do unless target_session is set
+
+    if module_name_components.first == 'exploit'
+      return true if module_name_components[2] == 'local'
+      errors.add(:base, 'target_session cannot be set for exploit modules. Use spawned_session.')
+    end
+  end
+
+
+end

data/app/models/metasploit_data_models/search/operation/ip_address.rb

@@ -0,0 +1,60 @@
+# Searches an `inet` column in a PostgreSQL database using
+# {MetasploitDataModels::IPAddress::V4::Single a standard IPv4 address},
+# {MetasploitDataModels::IPAddress::V4::CIDR an IPv4 CIDR block}, or
+# {MetasploitDataModels::IPAddress::V4::Range an IPv4 address range}.
+class MetasploitDataModels::Search::Operation::IPAddress < Metasploit::Model::Search::Operation::Base
+  include MetasploitDataModels::Match::Parent
+
+  #
+  # Match Children
+  #
+
+  # in order of precedence, so simpler single IPv4 addresses are matched before the more complex ranges which may
+  # degenerate to equivalent formatted value
+  match_children_named %w{
+    MetasploitDataModels::IPAddress::V4::Single
+    MetasploitDataModels::IPAddress::V4::CIDR
+    MetasploitDataModels::IPAddress::V4::Range
+  }
+
+  #
+  #
+  # Validations
+  #
+  #
+
+  #
+  # Validation Methods
+  #
+
+  validate :value_valid
+
+  #
+  # Attribute Validations
+  #
+
+  validates :value,
+            presence: true
+
+  #
+  # Instance Method
+  #
+
+  # @param formatted_value [#to_s]
+  def value=(formatted_value)
+    @value = match_child(formatted_value) || formatted_value
+  end
+
+  private
+
+  # Validates that `#value` is valid.
+  #
+  # @return [void]
+  def value_valid
+    if value.present?
+      unless value.respond_to?(:valid?) && value.valid?
+        errors.add(:value, :invalid)
+      end
+    end
+  end
+end

data/app/models/metasploit_data_models/search/operation/port/number.rb

@@ -0,0 +1,25 @@
+# Search operation on an attribute that holds a port number and is being searched with a single Integer port number.
+class MetasploitDataModels::Search::Operation::Port::Number < Metasploit::Model::Search::Operation::Integer
+  #
+  # CONSTANTS
+  #
+
+  # The number of bits in a port number
+  BITS = 16
+  # The maximum port number
+  MAXIMUM = (1 << BITS) - 1
+  # The minimum port number
+  MINIMUM = 0
+
+  # The range of valid port numbers from {MINIMUM} to {MAXIMUM}, inclusive.
+  RANGE = (MINIMUM..MAXIMUM)
+
+  #
+  # Validations
+  #
+
+  validates :value,
+            inclusion: {
+                in: RANGE
+            }
+end