metasploit-framework/lib/msf/core/framework.rb

# -*- coding: binary -*-
require 'msf/core'
require 'msf/util'

module Msf

###
#
# This class is the primary context that modules, scripts, and user
# interfaces interact with.  It ties everything together.
#
###
class Framework

	#
	# Versioning information
	#

	Major    = 4
	Minor    = 8
	Point    = 0
	Release  = "-dev"

	if(Point)
		Version  = "#{Major}.#{Minor}.#{Point}#{Release}"
	else
		Version  = "#{Major}.#{Minor}#{Release}"
	end

	Revision = "$Revision$"


	# Repository information
	RepoRevision        = ::Msf::Util::SVN.revision
	RepoUpdated         = ::Msf::Util::SVN.updated
	RepoUpdatedDays     = ::Msf::Util::SVN.days_since_update
	RepoUpdatedDaysNote = ::Msf::Util::SVN.last_updated_friendly
	RepoUpdatedDate     = ::Msf::Util::SVN.last_updated_date
	RepoRoot            = ::Msf::Util::SVN.root

	# EICAR canary
	EICARCorrupted      = ::Msf::Util::EXE.is_eicar_corrupted?

	# API Version
	APIMajor = 1
	APIMinor = 0

	# Base/API Version
	VersionCore  = Major + (Minor / 10.0)
	VersionAPI   = APIMajor + (APIMinor / 10.0)

	#
	# Mixin meant to be included into all classes that can have instances that
	# should be tied to the framework, such as modules.
	#
	module Offspring

		#
		# A reference to the framework instance from which this offspring was
		# derived.
		#
		attr_accessor :framework
	end

	require 'msf/core/thread_manager'
	require 'msf/core/module_manager'
	require 'msf/core/session_manager'
	require 'msf/core/plugin_manager'
	require 'msf/core/db_manager'
	require 'msf/core/event_dispatcher'


	#
	# Creates an instance of the framework context.
	#
	def initialize(opts={})

		# Allow specific module types to be loaded
		types = opts[:module_types] || MODULE_TYPES

		self.threads   = ThreadManager.new(self)
		self.events    = EventDispatcher.new(self)
		self.modules   = ModuleManager.new(self,types)
		self.sessions  = SessionManager.new(self)
		self.datastore = DataStore.new
		self.jobs      = Rex::JobContainer.new
		self.plugins   = PluginManager.new(self)
		self.db        = DBManager.new(self, opts)

		# Configure the thread factory
		Rex::ThreadFactory.provider = self.threads

		subscriber = FrameworkEventSubscriber.new(self)
		events.add_exploit_subscriber(subscriber)
		events.add_session_subscriber(subscriber)
		events.add_general_subscriber(subscriber)
		events.add_db_subscriber(subscriber)
		events.add_ui_subscriber(subscriber)
	end

	def inspect
		"#<Framework (#{sessions.length} sessions, #{jobs.length} jobs, #{plugins.length} plugins#{db.active ? ", #{db.driver} database active" : ""})>"
	end

	#
	# Returns the module set for encoders.
	#
	def encoders
		return modules.encoders
	end

	#
	# Returns the module set for exploits.
	#
	def exploits
		return modules.exploits
	end

	#
	# Returns the module set for nops
	#
	def nops
		return modules.nops
	end

	#
	# Returns the module set for payloads
	#
	def payloads
		return modules.payloads
	end

	#
	# Returns the module set for auxiliary modules
	#
	def auxiliary
		return modules.auxiliary
	end

	#
	# Returns the module set for post modules
	#
	def post
		return modules.post
	end

	#
	# Returns the framework version in Major.Minor format.
	#
	def version
		Version
	end

	#
	# Event management interface for registering event handler subscribers and
	# for interacting with the correlation engine.
	#
	attr_reader   :events
	#
	# Module manager that contains information about all loaded modules,
	# regardless of type.
	#
	attr_reader   :modules
	#
	# Session manager that tracks sessions associated with this framework
	# instance over the course of their lifetime.
	#
	attr_reader   :sessions
	#
	# The global framework datastore that can be used by modules.
	#
	attr_reader   :datastore
	#
	# The framework instance's aux manager.  The aux manager is responsible
	# for collecting and catalogging all aux information that comes in from
	# aux modules.
	#
	attr_reader   :auxmgr
	#
	# Background job management specific to things spawned from this instance
	# of the framework.
	#
	attr_reader   :jobs
	#
	# The framework instance's plugin manager.  The plugin manager is
	# responsible for exposing an interface that allows for the loading and
	# unloading of plugins.
	#
	attr_reader   :plugins
	#
	# The framework instance's db manager. The db manager
	# maintains the database db and handles db events
	#
	attr_reader   :db
	#
	# The framework instance's thread manager. The thread manager
	# provides a cleaner way to manage spawned threads
	#
	attr_reader   :threads

protected

	attr_writer   :events # :nodoc:
	attr_writer   :modules # :nodoc:
	attr_writer   :sessions # :nodoc:
	attr_writer   :datastore # :nodoc:
	attr_writer   :auxmgr # :nodoc:
	attr_writer   :jobs # :nodoc:
	attr_writer   :plugins # :nodoc:
	attr_writer   :db # :nodoc:
	attr_writer   :threads # :nodoc:
end

class FrameworkEventSubscriber
	include Framework::Offspring
	def initialize(framework)
		self.framework = framework
	end

	def report_event(data)
		if framework.db.active
			framework.db.report_event(data)
		end
	end

	include GeneralEventSubscriber

	#
	# Generic handler for module events
	#
	def module_event(name, instance, opts={})
		if framework.db.active
			event = {
				:workspace => framework.db.find_workspace(instance.workspace),
				:name      => name,
				:username  => instance.owner,
				:info => {
					:module_name => instance.fullname,
					:module_uuid => instance.uuid
				}.merge(opts)
			}

			report_event(event)
		end
	end

	##
	# :category: ::Msf::GeneralEventSubscriber implementors
	def on_module_run(instance)
		opts = { :datastore => instance.datastore.to_h }
		module_event('module_run', instance, opts)
	end

	##
	# :category: ::Msf::GeneralEventSubscriber implementors
	def on_module_complete(instance)
		module_event('module_complete', instance)
	end

	##
	# :category: ::Msf::GeneralEventSubscriber implementors
	def on_module_error(instance, exception=nil)
		module_event('module_error', instance, :exception => exception.to_s)
	end

	include ::Msf::UiEventSubscriber
	##
	# :category: ::Msf::UiEventSubscriber implementors
	def on_ui_command(command)
		if framework.db.active
			report_event(:name => "ui_command", :info => {:command => command})
		end
	end

	##
	# :category: ::Msf::UiEventSubscriber implementors
	def on_ui_stop()
		if framework.db.active
			report_event(:name => "ui_stop")
		end
	end

	##
	# :category: ::Msf::UiEventSubscriber implementors
	def on_ui_start(rev)
		#
		# The database is not active at startup time unless msfconsole was
		# started with a database.yml, so this event won't always be saved to
		# the db.  Not great, but best we can do.
		#
		info = { :revision => rev }
		report_event(:name => "ui_start", :info => info)
	end

	require 'msf/core/session'

	include ::Msf::SessionEvent

	#
	# Generic handler for session events
	#
	def session_event(name, session, opts={})
		address = session.session_host

		if not (address and address.length > 0)
			elog("Session with no session_host/target_host/tunnel_peer")
			dlog("#{session.inspect}", LEV_3)
			return
		end

		if framework.db.active
			ws = framework.db.find_workspace(session.workspace)
			event = {
				:workspace => ws,
				:username  => session.username,
				:name => name,
				:host => address,
				:info => {
					:session_id   => session.sid,
					:session_info => session.info,
					:session_uuid => session.uuid,
					:session_type => session.type,
					:username     => session.username,
					:target_host  => address,
					:via_exploit  => session.via_exploit,
					:via_payload  => session.via_payload,
					:tunnel_peer  => session.tunnel_peer,
					:exploit_uuid => session.exploit_uuid
				}.merge(opts)
			}
			report_event(event)
		end
	end


	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_open(session)
		opts = { :datastore => session.exploit_datastore.to_h, :critical => true }
		session_event('session_open', session, opts)
		framework.db.report_session(:session => session)
	end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_upload(session, lpath, rpath)
		session_event('session_upload', session, :local_path => lpath, :remote_path => rpath)
		framework.db.report_session_event({
			:etype => 'upload',
			:session => session,
			:local_path => lpath,
			:remote_path => rpath
		})
	end
	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_download(session, rpath, lpath)
		session_event('session_download', session, :local_path => lpath, :remote_path => rpath)
		framework.db.report_session_event({
			:etype => 'download',
			:session => session,
			:local_path => lpath,
			:remote_path => rpath
		})
	end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_close(session, reason='')
		session_event('session_close', session)
		if session.db_record
			# Don't bother saving here, the session's cleanup method will take
			# care of that later.
			session.db_record.close_reason = reason
			session.db_record.closed_at = Time.now.utc
		end
	end

	#def on_session_interact(session)
	#	$stdout.puts('session_interact', session.inspect)
	#end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_command(session, command)
		session_event('session_command', session, :command => command)
		framework.db.report_session_event({
			:etype => 'command',
			:session => session,
			:command => command
		})
	end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_output(session, output)
		# Break up the output into chunks that will fit into the database.
		buff = output.dup
		chunks = []
		if buff.length > 1024
			while buff.length > 0
				chunks << buff.slice!(0,1024)
			end
		else
			chunks << buff
		end
		chunks.each { |chunk|
			session_event('session_output', session, :output => chunk)
			framework.db.report_session_event({
				:etype => 'output',
				:session => session,
				:output => chunk
			})
		}
	end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_route(session, route)
		framework.db.report_session_route(session, route)
	end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_route_remove(session, route)
		framework.db.report_session_route_remove(session, route)
	end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_script_run(session, script)
		framework.db.report_session_event({
			:etype => 'script_run',
			:session => session,
			:local_path => script
		})
	end

	##
	# :category: ::Msf::SessionEvent implementors
	def on_session_module_run(session, mod)
		framework.db.report_session_event({
			:etype => 'module_run',
			:session => session,
			:local_path => mod.fullname
		})
	end

	#
	# This is covered by on_module_run and on_session_open, so don't bother
	#
	#require 'msf/core/exploit'
	#include ExploitEvent
	#def on_exploit_success(exploit, session)
	#end

end
end