1
# -*- coding: binary -*-
2

3
module Msf
4

5
###
6
#
7
# The auxiliary class acts as a base class for all modules that perform
8
# reconnaissance, retrieve data, brute force logins, or any other action
9
# that doesn't fit our concept of an 'exploit' (involving payloads and
10
# targets and whatnot).
11
#
12
###
13
class Auxiliary < Msf::Module
14

15
  class Complete < RuntimeError
16
  end
17

18
  class Failed < RuntimeError
19
  end
20

21

22
  include HasActions
23

24
  #
25
  # Returns MODULE_AUX to indicate that this is an auxiliary module.
26
  #
27
  def self.type
28
    Msf::MODULE_AUX
29
  end
30

31
  #
32
  # Returns MODULE_AUX to indicate that this is an auxiliary module.
33
  #
34
  def type
35
    Msf::MODULE_AUX
36
  end
37

38
  #
39
  # Creates an instance of the auxiliary module.
40
  #
41
  def initialize(info = {})
42

43
    # Call the parent constructor after making any necessary modifications
44
    # to the information hash.
45
    super(info)
46

47
    self.sockets = Array.new
48
    self.queue   = Array.new
49
    self.fail_reason = Msf::Module::Failure::None
50
  end
51

52
  #
53
  # Creates a singleton instance of this auxiliary class
54
  #
55
  def self.create(info = {})
56
    return @@aux_singleton if @@aux_singleton
57
    @@aux_singleton = self.new(info)
58
  end
59

60
  def run
61
    print_status("Running the default Auxiliary handler")
62
  end
63

64
  def auxiliary_commands
65
    return { }
66
  end
67

68
  #
69
  # Performs last-minute sanity checking of auxiliary parameters. This method
70
  # is called during automated exploitation attempts and allows an
71
  # auxiliary module to filter bad attempts, obtain more information, and choose
72
  # better parameters based on the available data. Returning anything that
73
  # evaluates to "false" will cause this specific auxiliary attempt to
74
  # be skipped. This method can and will change datastore values and
75
  # may interact with the backend database. The default value for auxiliary
76
  # modules is false, since not all auxiliary modules actually attempt
77
  # to exploit a vulnerability.
78
  #
79
  def autofilter
80
    false
81
  end
82

83
  #
84
  # Provides a list of ports that can be used for matching this module
85
  # against target systems.
86
  #
87
  def autofilter_ports
88
    @autofilter_ports || []
89
  end
90

91
  #
92
  # Provides a list of services that can be used for matching this module
93
  # against target systems.
94
  #
95
  def autofilter_services
96
    @autofilter_services || []
97
  end
98

99
  #
100
  # Adds a port into the list of ports
101
  #
102
  def register_autofilter_ports(ports=[])
103
    @autofilter_ports ||= []
104
    @autofilter_ports << ports
105
    @autofilter_ports.flatten!
106
    @autofilter_ports.uniq!
107
  end
108

109
  def register_autofilter_services(services=[])
110
    @autofilter_services ||= []
111
    @autofilter_services << services
112
    @autofilter_services.flatten!
113
    @autofilter_services.uniq!
114
  end
115

116

117
  #
118
  # Called directly before 'run'
119
  #
120
  def setup
121
    alert_user
122
  end
123

124
  #
125
  # Called after 'run' returns
126
  #
127
  def cleanup
128
    abort_sockets()
129
  end
130

131
  #
132
  # Adds a socket to the list of sockets opened by this exploit.
133
  #
134
  def add_socket(sock)
135
    self.sockets << sock
136
  end
137

138
  #
139
  # Removes a socket from the list of sockets.
140
  #
141
  def remove_socket(sock)
142
    self.sockets.delete(sock)
143
  end
144

145
  #
146
  # This method is called once a new session has been created on behalf of
147
  # this module instance and all socket connections created by this
148
  # module should be closed.
149
  #
150
  def abort_sockets
151
    sockets.delete_if { |sock|
152

153
      begin
154
        sock.close
155
      rescue ::Exception
156
      end
157
      true
158
    }
159
  end
160

161
  # Override Msf::Module#fail_with for Msf::Simple::Auxiliary::job_run_proc
162
  def fail_with(reason, msg = nil)
163
    allowed_values = Msf::Module::Failure.constants.collect {|e| Msf::Module::Failure.const_get(e)}
164
    if allowed_values.include?(reason)
165
      self.fail_reason = reason
166
    else
167
      self.fail_reason = Msf::Module::Failure::Unknown
168
    end
169

170
    self.fail_detail = msg
171
    raise Msf::Auxiliary::Failed, "#{reason.to_s}: #{(msg || "No failure message given")}"
172
  end
173

174
  #
175
  # The reason why the module was not successful (one of the constant defined above)
176
  #
177
  attr_accessor  :fail_reason
178

179
  #
180
  # Detailed exception string indicating why the module was not successful
181
  #
182
  attr_accessor  :fail_detail
183

184
  attr_accessor :queue
185

186
protected
187

188
  attr_accessor :sockets
189
  attr_writer :passive
190

191
end
192

193
end
194

195

196