Class: Msf::OptBase

Inherits:
Object
  • Object
show all
Defined in:
lib/msf/core/opt_base.rb

Overview

The base class for all options.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(in_name, attrs = [], required: false, desc: nil, default: nil, conditions: [], enums: [], regex: nil, aliases: [], max_length: nil, fallbacks: []) ⇒ OptBase

Initializes a named option with the supplied attribute array. The array is composed of three values.

attrs = required (boolean type) attrs = description (string) attrs = default value attrs = possible enum values attrs = Regex to validate the option

Attrs can also be specified explicitly via named parameters, or attrs can also be a string as standin for the required description field.



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/msf/core/opt_base.rb', line 27

def initialize(in_name, attrs = [],
               required: false, desc: nil, default: nil, conditions: [], enums: [], regex: nil, aliases: [], max_length: nil,
               fallbacks: [])
  self.name     = in_name
  self.advanced = false
  self.evasion  = false
  self.aliases  = aliases
  self.max_length = max_length
  self.conditions = conditions
  self.fallbacks = fallbacks

  if attrs.is_a?(String) || attrs.length == 0
    self.required = required
    self.desc     = attrs.is_a?(String) ? attrs : desc
    self.enums    = [ *(enums) ].map { |x| x.to_s }
    if default.nil? && enums.length > 0
      self.default = enums[0]
    else
      self.default = default
    end
    regex_temp = regex
  else
    if attrs[0].nil?
      self.required = required
    else
      self.required = attrs[0]
    end
    self.desc     = attrs[1] || desc
    self.default  = attrs[2] || default
    self.enums    = attrs[3] || enums
    self.enums    = [ *(self.enums) ].map { |x| x.to_s }
    regex_temp    = attrs[4] || regex
  end

  unless max_length.nil?
    self.desc += " Max parameter length: #{max_length} characters"
  end

  if regex_temp
    # convert to string
    regex_temp = regex_temp.to_s if regex_temp.is_a? Regexp
    # remove start and end character, they will be added later
    regex_temp = regex_temp.sub(/^\^/, '').sub(/\$$/, '')
    # Add start and end marker to match the whole regex
    regex_temp = "^#{regex_temp}$"
    begin
      Regexp.compile(regex_temp)
      self.regex = regex_temp
    rescue RegexpError, TypeError => e
      raise("Invalid Regex #{regex_temp}: #{e}")
    end
  end
end

Instance Attribute Details

#advanced ⇒ Object

Whether or not this is an advanced option.



185
186
187
 
# File 'lib/msf/core/opt_base.rb', line 185

def advanced
  @advanced
end

#aliases ⇒ Array<String>

Array of aliases for this option for backward compatibility.

This is useful in the scenario of an existing option being renamed to a new value. Either the current option name or list of aliases can be used in modules for retrieving datastore values, or by a user when setting datastore values manually.

Returns:

  • (Array<String>) —

    the array of aliases



216
217
218
 
# File 'lib/msf/core/opt_base.rb', line 216

def aliases
  @aliases
end

#conditions ⇒ Object

The list of potential conditions



197
198
199
 
# File 'lib/msf/core/opt_base.rb', line 197

def conditions
  @conditions
end

#default ⇒ Object

The default value of the option.



177
178
179
 
# File 'lib/msf/core/opt_base.rb', line 177

def default
  @default
end

#desc ⇒ Object

The description of the option.



173
174
175
 
# File 'lib/msf/core/opt_base.rb', line 173

def desc
  @desc
end

#enums ⇒ Object

The list of potential valid values



201
202
203
 
# File 'lib/msf/core/opt_base.rb', line 201

def enums
  @enums
end

#evasion ⇒ Object

Whether or not this is an evasion option.



189
190
191
 
# File 'lib/msf/core/opt_base.rb', line 189

def evasion
  @evasion
end

#fallbacks ⇒ Array<String>

Array of fallbacks for this option.

This is useful in the scenario of wanting specialised option names such as SMBUser, but to also support gracefully checking a list of more generic fallbacks option names such as Username.

Returns:

  • (Array<String>) —

    the array of fallbacks



226
227
228
 
# File 'lib/msf/core/opt_base.rb', line 226

def fallbacks
  @fallbacks
end

#max_length ⇒ Object

The max length of the input value



231
232
233
 
# File 'lib/msf/core/opt_base.rb', line 231

def max_length
  @max_length
end

#name ⇒ Object

The name of the option.



165
166
167
 
# File 'lib/msf/core/opt_base.rb', line 165

def name
  @name
end

#owner ⇒ Object

The module or entity that owns this option.



193
194
195
 
# File 'lib/msf/core/opt_base.rb', line 193

def owner
  @owner
end

#regex ⇒ Object

A optional regex to validate the option value



205
206
207
 
# File 'lib/msf/core/opt_base.rb', line 205

def regex
  @regex
end

#required ⇒ Object

Whether or not the option is required.



169
170
171
 
# File 'lib/msf/core/opt_base.rb', line 169

def required
  @required
end

Instance Method Details

#advanced? ⇒ Boolean

Returns true if this is an advanced option.

Returns:

  • (Boolean) 


91
92
93
 
# File 'lib/msf/core/opt_base.rb', line 91

def advanced?
  advanced
end

#display_value(value) ⇒ Object

Returns a string representing a user-friendly display of the chosen value



149
150
151
 
# File 'lib/msf/core/opt_base.rb', line 149

def display_value(value)
  value.to_s
end

#empty_required_value?(value) ⇒ Boolean

Returns true if the value supplied is nil and it’s required to be a valid value

Returns:

  • (Boolean) 


134
135
136
 
# File 'lib/msf/core/opt_base.rb', line 134

def empty_required_value?(value)
  required? && value.nil?
end

#evasion? ⇒ Boolean

Returns true if this is an evasion option.

Returns:

  • (Boolean) 


98
99
100
 
# File 'lib/msf/core/opt_base.rb', line 98

def evasion?
  evasion
end

#invalid_value_length?(value) ⇒ Boolean

Returns true if the value supplied is longer then the max allowed length

Returns:

  • (Boolean) 


156
157
158
159
160
 
# File 'lib/msf/core/opt_base.rb', line 156

def invalid_value_length?(value)
  if !value.nil? && !max_length.nil?
    value.length > max_length
  end
end

#normalize(value) ⇒ Object

Normalizes the supplied value to conform with the type that the option is conveying.



142
143
144
 
# File 'lib/msf/core/opt_base.rb', line 142

def normalize(value)
  value
end

#required? ⇒ Boolean

Returns true if this is a required option.

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/msf/core/opt_base.rb', line 84

def required?
  required
end

#type?(in_type) ⇒ Boolean

Returns true if the supplied type is equivalent to this option’s type.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/msf/core/opt_base.rb', line 105

def type?(in_type)
  type == in_type
end

#valid?(value, check_empty: true) ⇒ Boolean

If it’s required and the value is nil or empty, then it’s not valid.

Returns:

  • (Boolean) 


119
120
121
122
123
124
125
126
127
128
 
# File 'lib/msf/core/opt_base.rb', line 119

def valid?(value, check_empty: true)
  if check_empty && required?
    # required variable not set
    return false if (value.nil? || value.to_s.empty?)
  end
  if regex && !value.nil?
    return !!value.match(regex)
  end
  true
end

#validate_on_assignment? ⇒ Boolean

Returns true if this option can be validated on assignment

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/msf/core/opt_base.rb', line 112

def validate_on_assignment?
  true
end