Module: Msf::Simple::Auxiliary

Includes:
Module
Defined in:
lib/msf/base/simple/auxiliary.rb

Overview

A simplified auxiliary wrapper.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Module

#_import_extra_options, #init_simplified, #inspect, #load_config, #save_config

Class Method Details

.check_simple(mod, opts, job_listener: Msf::Simple::NoopJobListener.instance) ⇒ Object

Initiates a check, setting up the exploit to be used. The following options can be specified:

LocalInput

The local input handle that data can be read in from.

LocalOutput

The local output through which data can be displayed.



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/msf/base/simple/auxiliary.rb', line 112

def self.check_simple(mod, opts, job_listener: Msf::Simple::NoopJobListener.instance)
  Msf::Simple::Framework.simplify_module(mod)

  mod._import_extra_options(opts)
  if opts['LocalInput']
    mod.init_ui(opts['LocalInput'], opts['LocalOutput'])
  end

  unless mod.has_check?
    # Bail out early if the module doesn't have check
    raise ::NotImplementedError.new(Msf::Exploit::CheckCode::Unsupported.message)
  end

  # Validate the option container state so that options will
  # be normalized
  mod.validate

  run_uuid = Rex::Text.rand_text_alphanumeric(24)
  job_listener.waiting run_uuid
  ctx = [mod, run_uuid, job_listener]

  if opts['RunAsJob']
    mod.job_id = mod.framework.jobs.start_bg_job(
      "Auxiliary: #{mod.refname} check",
      ctx,
      Proc.new do |ctx_|
        self.job_run_proc(ctx_) do |m|
          m.check
        end
      end,
      Proc.new { |ctx_| self.job_cleanup_proc(ctx_) }
    )

    [run_uuid, mod.job_id]
  else
    # Run check if it exists
    result = self.job_run_proc(ctx) do |m|
      m.check
    end
    self.job_cleanup_proc(ctx)

    result
  end
end

.job_cleanup_proc(ctx) ⇒ Object (protected)

Clean up the module after the job completes.



233
234
235
236
237
238
 
# File 'lib/msf/base/simple/auxiliary.rb', line 233

def self.job_cleanup_proc(ctx)
  mod = ctx[0]
  mod.framework.events.on_module_complete(mod)
  # Allow the exploit to cleanup after itself, that messy bugger.
  mod.cleanup
end

.job_run_proc(ctx, &block) ⇒ Object (protected)

Job run proc, sets up the module and kicks it off.



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/msf/base/simple/auxiliary.rb', line 170

def self.job_run_proc(ctx, &block)
  mod = ctx[0]
  run_uuid = ctx[1]
  job_listener = ctx[2]
  begin
    begin
      job_listener.start run_uuid
      mod.setup
      mod.framework.events.on_module_run(mod)
      result = block.call(mod)
      job_listener.completed(run_uuid, result, mod)
    rescue ::Exception => e
      job_listener.failed(run_uuid, e, mod)
      raise
    end
  rescue Msf::Auxiliary::Complete
    mod.cleanup
    return
  rescue Msf::Auxiliary::Failed => e
    mod.error = e
    mod.print_error("Auxiliary aborted due to failure: #{e.message}")
    mod.cleanup
    return
  rescue ::Timeout::Error => e
    mod.error = e
    mod.print_error("Auxiliary triggered a timeout exception")
    mod.cleanup
    return
  rescue ::Interrupt => e
    mod.error = e
    mod.print_error("Stopping running against current target...")
    mod.cleanup
    mod.print_status("Control-C again to force quit all targets.")
    begin
      Rex.sleep(0.5)
    rescue ::Interrupt
      raise $!
    end
    return
  rescue ::Msf::OptionValidateError => e
    mod.error = e
    ::Msf::Ui::Formatter::OptionValidateError.print_error(mod, e)
  rescue ::Exception => e
    mod.error = e
    mod.print_error("Auxiliary failed: #{e.class} #{e}")
    if(e.class.to_s != 'Msf::OptionValidateError')
      mod.print_error("Call stack:")
      e.backtrace.each do |line|
        break if line =~ /lib.msf.base.simple.auxiliary.rb/
        mod.print_error("  #{line}")
      end
    end

    elog('Auxiliary failed', error: e)
    mod.cleanup

  end
  return result
end

.run_simple(omod, opts = {}, job_listener: Msf::Simple::NoopJobListener.instance) {|mod| ... } ⇒ Object

Wraps the auxiliary process in a simple single method. The options hash can have the following values passed in it:

Action

The selected action name.

OptionStr

A string of comma separated option values that should be imported into the datastore.

Options

A hash of values to be imported directly into the datastore.

LocalInput

The local input handle that data can be read in from.

LocalOutput

The local output through which data can be displayed.

RunAsJob

Whether or not the exploit should be run in the context of a background job.

Yields:

  • (mod) 


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
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/msf/base/simple/auxiliary.rb', line 44

def self.run_simple(omod, opts = {}, job_listener: Msf::Simple::NoopJobListener.instance, &block)

  # Clone the module to prevent changes to the original instance
  mod = omod.replicant
  Msf::Simple::Framework.simplify_module(mod)
  yield(mod) if block_given?

  # Import options from the OptionStr or Option hash.
  mod._import_extra_options(opts)

  mod.datastore['ACTION'] = opts['Action'] if opts['Action']

  # Verify the ACTION
  if (mod.actions.length > 0 and not mod.action)
    raise MissingActionError, "Please use: #{mod.actions.collect {|e| e.name} * ", "}"
  end

  # Verify the options
  mod.options.validate(mod.datastore)

  # Initialize user interaction
  if ! opts['Quiet']
    mod.init_ui(opts['LocalInput'] || mod.user_input, opts['LocalOutput'] || mod.user_output)
  else
    mod.init_ui(nil, nil)
  end

  run_uuid = Rex::Text.rand_text_alphanumeric(24)
  job_listener.waiting run_uuid
  ctx = [mod, run_uuid, job_listener]
  run_as_job = opts['RunAsJob'].nil? ? mod.passive? : opts['RunAsJob']
  if run_as_job
    mod.job_id = mod.framework.jobs.start_bg_job(
      "Auxiliary: #{mod.refname}",
      ctx,
      Proc.new { |ctx_| self.job_run_proc(ctx_, &:run) },
      Proc.new { |ctx_| self.job_cleanup_proc(ctx_) }
    )
    # Propagate this back to the caller for console mgmt
    omod.job_id = mod.job_id
    return [run_uuid, mod.job_id]
  else
    result = self.job_run_proc(ctx, &:run)
    self.job_cleanup_proc(ctx)

    return result
  end
end

Instance Method Details

#check_simple(opts) ⇒ Object

Calls the class method.



160
161
162
 
# File 'lib/msf/base/simple/auxiliary.rb', line 160

def check_simple(opts)
  Msf::Simple::Auxiliary.check_simple(self, opts)
end

#run_simple(opts = {}, &block) ⇒ Object

Calls the class method.



96
97
98
 
# File 'lib/msf/base/simple/auxiliary.rb', line 96

def run_simple(opts = {}, &block)
  Msf::Simple::Auxiliary.run_simple(self, opts, &block)
end