EVOLUTION-MANAGER

Edit File: wsdd.lua

--- A library that enables scripts to send Web Service Dynamic Discovery probes
-- and perform some very basic decoding of responses. The library is in no way
-- a full WSDD implementation it's rather the result of some packet captures
-- and some creative coding.
--
-- The "general" probe was captured of the wire of a Windows 7 box while
-- connecting to the network. The "wcf" probe was captured from a custom tool
-- tool performing WCF discovery in .NET 4.0.
--
-- More information about the protocol can be found here:
-- * http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.pdf
-- * http://specs.xmlsoap.org/ws/2005/04/discovery/ws-discovery.pdf
--
-- The library contains the following classes
-- * <code>Comm</code>
-- ** A class that handles most communication 
-- * <code>Helper</code>
-- ** The helper class wraps the <code>Comm</code> class using functions with a more descriptive name.
-- * <code>Util</code>
-- ** The Util class contains a number of static functions mainly used to convert data.
-- * <code>Decoders</code>
-- ** The Decoders class contains static functions used for decoding probe matches
--
-- The following code snipplet shows how the library can be used:
-- <code>
--	local helper = wsdd.Helper:new()
--  helper:setMulticast(true)	
--  return stdnse.format_output( helper:discoverDevices() )
-- </code>
--
-- @author "Patrik Karlsson <patrik@cqure.net>"
-- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
--

local bin = require "bin"
local nmap = require "nmap"
local stdnse = require "stdnse"
local table = require "table"
local target = require "target"
_ENV = stdnse.module("wsdd", stdnse.seeall)

local HAVE_SSL, openssl = pcall(require,'openssl')

-- The different probes
local probes = {
	
	-- Detects devices supporting the WSDD protocol
	{ 
	name  = 'general',
	desc = 'Devices',
	data = '<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" ' ..
	        'xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" ' ..
	        'xmlns:wsd="http://schemas.xmlsoap.org/ws/2005/04/discovery">' ..
	  '<env:Header>' ..
	    '<wsd:AppSequence InstanceId="1285624958737" MessageNumber="1" ' ..
	                     'SequenceId="urn:uuid:#uuid#"/>' ..
	    '<wsa:To>urn:schemas-xmlsoap-org:ws:2005:04:discovery</wsa:To>' ..
	    '<wsa:Action>' ..
	      'http://schemas.xmlsoap.org/ws/2005/04/discovery/Probe' ..
	    '</wsa:Action><wsa:MessageID>urn:uuid:#uuid#</wsa:MessageID>' ..
	  '</env:Header><env:Body><wsd:Probe/></env:Body></env:Envelope>'
	},
	
	-- Detects Windows Communication Framework (WCF) web services
	{
	name = 'wcf',
	desc = 'WCF Services',
	data = '<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" ' ..
				'xmlns:a="http://www.w3.org/2005/08/addressing">' ..
	  '<s:Header>' ..
	    '<a:Action s:mustUnderstand="1">' ..
	      'http://docs.oasis-open.org/ws-dd/ns/discovery/2009/01/Probe' ..
	    '</a:Action>' ..
	    '<a:MessageID>urn:uuid:#uuid#</a:MessageID>' ..
	    '<a:To s:mustUnderstand="1">' ..
	      'urn:docs-oasis-open-org:ws-dd:ns:discovery:2009:01' ..
	    '</a:To>' ..
	  '</s:Header>' ..
	  '<s:Body>' ..
	    '<Probe xmlns="http://docs.oasis-open.org/ws-dd/ns/discovery/2009/01">' ..
	      '<Duration xmlns="http://schemas.microsoft.com/ws/2008/06/discovery">' ..
	        'PT20S' ..
	      '</Duration>' ..
	    '</Probe>' ..
	  '</s:Body>' ..
	'</s:Envelope>',
	}
}

-- A table that keeps track of received probe matches
local probe_matches = {}

Util = {
	
	--- Creates a UUID
	--
	-- @return uuid string containing a uuid
	generateUUID = function()
		local rnd_bytes = select(2, bin.unpack( "H16", openssl.rand_bytes( 16 ) ) ):lower()

return ("%s-%s-%s-%s-%s"):format( rnd_bytes:sub(1, 8), 
			rnd_bytes:sub(9, 12), rnd_bytes:sub( 13, 16 ), rnd_bytes:sub( 17, 20 ), 
			rnd_bytes:sub(21, 32) )
	end,

--- Retrieves a probe from the probes table by name
	--
	-- @param name string containing the name of the probe to retrieve
	-- @return probe table containing the probe or nil if not found
	getProbeByName = function( name )
		for _, probe in ipairs(probes) do
			if ( probe.name == name ) then
				return probe
			end
		end
		return
	end,
	
	getProbes = function() return probes end,

sha1sum = function(data) return openssl.sha1(data) end
	
}

Decoders = {
	
	--- Decodes a wcf probe response
	--
	-- @param data string containing the response as received over the wire
	-- @return status true on success, false on failure
	-- @return response table containing the following fields 
	--         <code>msgid</code>, <code>xaddrs</code>, <code>types</code>
	--         err string containing the error message
	['wcf'] = function( data )
		local response = {}

-- extracts the messagid, so we can check if we already got a response
		response.msgid = data:match("<.*:MessageID>urn:uuid:(.*)</.*:MessageID>")

-- if unable to parse msgid return nil
		if ( not(response.msgid) ) then
			return false, "No message id was found"
		end

response.xaddrs = data:match("<.*:*XAddrs>(.*)</.*:*XAddrs>")
		response.types = data:match("<.*:Types>[wsdp:]*(.*)</.*:Types>")

return true, response
	end,
	
	--- Decodes a general probe response
	--
	-- @param data string containing the response as received over the wire
	-- @return status true on success, false on failure
	-- @return response table containing the following fields 
	--         <code>msgid</code>, <code>xaddrs</code>, <code>types</code>
	--         err string containing the error message
	['general'] = function( data )
		return Decoders['wcf'](data)
	end,
	
	--- Decodes an error message received from the service
	--
	-- @param data string containing the response as received over the wire
	-- @return status true on success, false on failure
	-- @return err string containing the error message
	['error'] = function( data )
		local response = "Failed to decode response from device: "
		local err = data:match("<SOAP.-ENV:Reason><SOAP.-ENV:Text>(.-)<")
		response = response .. (err or "Unknown error")
		
		return true, response
	end,
	
}

Comm = {
	
	--- Creates a new Comm instance
	--
	-- @param host string containing the host name or ip
	-- @param port number containing the port to connect to
	-- @return o a new instance of Comm
	new = function( self, host, port, mcast )
		local o = {}
	   	setmetatable(o, self)
        self.__index = self
		o.host = host
		o.port = port
		o.mcast = mcast or false
		o.sendcount = 2
		o.timeout = 5000
		return o
	end,
	
	--- Sets the timeout for socket reads
	setTimeout = function( self, timeout ) self.timeout = timeout end,
	
	--- Sends a probe over the wire
	--
	-- @return status true on success, false on failure
	sendProbe = function( self )
		local status, err
		
		-- replace all instances of #uuid# in the probe
		local probedata = self.probe.data:gsub("#uuid#", Util.generateUUID())
		
		if ( self.mcast ) then
			self.socket = nmap.new_socket("udp")
			self.socket:set_timeout(self.timeout)
		else
			self.socket = nmap.new_socket()
			self.socket:set_timeout(self.timeout)
			status, err = self.socket:connect( self.host, self.port, "udp" )
			if ( not(status) ) then return err end
		end
		
		for i=1, self.sendcount do
			if ( self.mcast ) then
		 		status, err = self.socket:sendto( self.host, self.port, probedata )
			else
				status, err = self.socket:send( probedata )
			end
			if ( not(status) ) then	return err end
		end
		return true
	end,
	
	--- Sets a probe from the <code>probes</code> table to send
	--
	-- @param probe table containing a probe from <code>probes</code>
	setProbe = function( self, probe )
		self.probe = probe
	end,
	
	--- Receives one or more responses for a Probe
	--
	-- @return table containing decoded responses suitable for
	--         <code>stdnse.format_output</code>
	recvProbeMatches = function( self )
		local responses = {}
		repeat
			local data

local status, data = self.socket:receive()
			if ( not(status) ) then
				if ( data == "TIMEOUT" ) then 
					break
				else
					return false, data
				end
			end

local _, ip
			status, _, _, ip, _ = self.socket:get_info()
			if( not(status) ) then 
				stdnse.print_debug( 3, "wsdd.recvProbeMatches: ERROR: Failed to get socket info" )
				return false, "ERROR: Failed to get socket info"
			end

-- push the unparsed response to the response table
			local status, response = Decoders[self.probe.name]( data )
			local id, output
			-- if we failed to decode the response indicate this
			if ( status ) then
				output = {}
				table.insert(output, "Message id: " .. response.msgid)
				if ( response.xaddrs ) then
					table.insert(output, "Address: " .. response.xaddrs)
				end
				if ( response.types ) then
					table.insert(output, "Type: " .. response.types)
				end
				id = response.msgid
			else
				status, response = Decoders["error"](data)
				output = response
				id = Util.sha1sum(data)
			end
						
			if ( self.mcast and not(probe_matches[id]) ) then
				if target.ALLOW_NEW_TARGETS then target.add(ip)	end
				table.insert( responses, { name=ip, output } )
			elseif ( not(probe_matches[id]) ) then
				responses = output
			end
			
			-- avoid duplicates
			probe_matches[id] = true
		until( not(self.mcast) )
		
		-- we're done with the socket
		self.socket:close()
		
		return true, responses
	end

}

Helper = {
	
	--- Creates a new helper instance
	--
	-- @param host string containing the host name or ip
	-- @param port number containing the port to connect to
	-- @return o a new instance of Helper
	new = function( self, host, port )
		local o = {}
	   	setmetatable(o, self)
        self.__index = self
		o.host = host
		o.port = port
		o.mcast = false
		o.timeout = 5000
		return o
	end,
	
	--- Instructs the helper to use unconnected sockets supporting multicast
	--
	-- @param mcast boolean true if multicast is to be used, false otherwise
	setMulticast = function( self, mcast )
		assert( type(mcast)=="boolean", "mcast has to be either true or false")
		local family = nmap.address_family()
		self.mcast = mcast
		self.host = (family=="inet6" and "FF02::C" or "239.255.255.250")
		self.port = 3702
	end,
	
	--- Sets the timeout for socket reads
	setTimeout = function( self, timeout ) self.timeout = timeout end,
	
	--- Sends a probe, receives and decodes a probematch
	--
	-- @param probename string containing the name of the probe to send
	--        check <code>probes</code> for available probes
	-- @return status true on success, false on failure
	-- @return matches table containing responses, suitable for printing using
	--         the <code>stdnse.format_output</code> function
	discoverServices = function( self, probename )
		if ( not(HAVE_SSL) ) then return false, "The wsdd library requires OpenSSL"	end
	
		local comm = Comm:new(self.host, self.port, self.mcast)
		local probe = Util.getProbeByName(probename)
		comm:setProbe( probe )
		comm:setTimeout( self.timeout )

local status = comm:sendProbe()
		if ( not(status) ) then 
			return false, "ERROR: wcf.discoverServices failed"
		end

local status, matches = comm:recvProbeMatches()
		if ( not(status) ) then 
			return false, "ERROR: wcf.recvProbeMatches failed"
		end

if ( #matches > 0 ) then matches.name = probe.desc end
		return true, matches
	end,
	
	--- Sends a general probe to attempt to discover WSDD supporting devices
	--
	-- @return status true on success, false on failure
	-- @return matches table containing responses, suitable for printing using
	--         the <code>stdnse.format_output</code> function
	discoverDevices = function( self )
		return self:discoverServices('general')
	end,
	
	
	--- Sends a probe that attempts to discover WCF web services
	--
	-- @return status true on success, false on failure
	-- @return matches table containing responses, suitable for printing using
	--         the <code>stdnse.format_output</code> function
	discoverWCFServices = function( self )
		return self:discoverServices('wcf')
	end,
	
}

return _ENV;