openc2lib.core.consumer

  1"""OpenC2 Consumer
  2
  3The `Consumer` implements the expected behaviour of an OpenC2 Consumer server that dispatches OpenC2 Commands
  4to the Actuators.
  5"""
  6
  7import logging
  8
  9from openc2lib.types.datatypes import DateTime, ResponseType
 10
 11from openc2lib.core.encoder import Encoder
 12from openc2lib.core.transfer import Transfer
 13from openc2lib.core.message import Message, Response
 14from openc2lib.core.response import StatusCode, StatusCodeDescription
 15
 16logger = logging.getLogger('openc2')
 17
 18class Consumer:
 19	"""OpenC2 Consumer
 20
 21		The `Consumer` is designed to dispatch OpenC2 `Message`s to the relevant `Actuator`. 
 22		The current implementation receives the configuration at initialization time. It is therefore
 23		not conceived to be runned itself as a service, but to be integrated in an external component 
 24		that reads the relevant configuration from file and passes it to the Consumer.
 25
 26		The `Consumer` has two main tasks:
 27		- creating the OpenC2 stack to process Messages (namely the combination of an Encoding format and
 28				a Transfer protocol);
 29		- dispatching incoming `Command`s to the relevant `Actuator`.
 30
 31		Each `Consumer` will only run a single `Transfer` protocol. All registered `Encoder`s can be used,
 32		and a default `Encoder` is explicitely given that will be used when no other selection is available 
 33		(e.g., to answer Messages that the Consumer does not understand).
 34		
 35	"""
 36	def __init__(self, consumer: str, actuators: [] =None, encoder: Encoder = None, transfer: Transfer = None):
 37		""" Create a `Consumer`
 38			:param consumer: This is a string that identifies the `Consumer` and is used in `from` 
 39				and `to` fields of the OpenC2 `Message` (see Table 3.1 of the Language Specification.
 40			:param actuators: This must be a list of available `Actuator`s. The list contains the
 41				`Actuator` instances that will be used by the `Consumer`.
 42			:param encoder: This is an instance of the `Encoder` that will be used by default.
 43			:param transfer: This is the `Transfer` protocol that will be used to send/receive `Message`s.
 44		"""
 45		self.consumer = consumer
 46		self.encoder = encoder
 47		self.transfer = transfer
 48		self.actuators = actuators
 49
 50		# TODO: Read configuration from file
 51
 52	# TODO: Manage non-blocking implementation of the Transfer.receive() function
 53	def run(self, encoder: Encoder = None, transfer: Transfer = None):
 54		"""Runs a `Consumer`
 55
 56			This is the entry point of the `Consumer`. It must be invoked to start operation of the `Consumer`.
 57			This method may be blocking, depending on the implementation of the `receive()` method of the 
 58			used `Transfer`.
 59
 60			The arguments of this method can be used to create multiple OpenC2 stacks (e.g., using 
 61			different `Encoder`s and `Transfer`s). This feature clearly requires the `Transfer` 
 62			implementation to be non-blocking.
 63
 64			:param encoder: A different `Encoder` that might be passed to overwrite what set at initialization time. 
 65			:param transfer: A different `Transfer` that might be passed to overwrite what set at initialization time.
 66			:return: None.
 67		"""
 68		if not encoder: encoder = self.encoder
 69		if not transfer: transfer = self.transfer
 70		if not transfer: raise ValueError('Missing transfer object')
 71
 72		transfer.receive(self.dispatch, self.encoder)
 73
 74
 75	def dispatch(self, msg):
 76		""" Dispatches Commands to Actuators
 77
 78			This method scans the actuator profile carried in the `Command` and select one or more
 79			`Actuator`s that will process the `Command`. 
 80			
 81			The current implementation is only meant to be used within the
 82			implementation of `Transfer` protocols as a callback for returning control to the main code.
 83			This approach is motivated by those Transfer protocols that replies to messages on the same 
 84			TCP connection, so to avoid errors with NAT and firewalls 
 85			(if a Command were passed back from the `Transfer.receive()` and processed within the `Consumer.run()`, 
 86			 the following `Transfer.send() would use a different TCP connection).
 87			
 88			:param msg: The full openc2lib `Message` that embeds the `Command` to be processed.
 89			:return: A `Message` that embeds the `Response` (from the `Actuator` or elaborated by the `Consumer` in
 90					case of errors).
 91		"""
 92		#TODO: The logic to select the actuator that matches the request
 93		# OC2 Architecture, Sec. 2.1:
 94		# The Profile field, if present, specifies the profile that defines the function 
 95		# to be performed. A Consumer executes the command if it supports the specified 
 96		# profile, otherwise the command is ignored. The Profile field may be omitted and 
 97		# typically will not be included in implementations where the functions of the 
 98		# recipients are unambiguous or when a high- level effects-based command is 
 99		# desired and tactical decisions on how the effect is achieved is left to the 
100		# recipient. If Profile is omitted and the recipient supports multiple profiles, 
101		# the command will be executed in the context of each profile that supports the 
102		# command's combination of action and target.
103		try:
104			profile = msg.content.actuator.getName()
105		except AttributeError:
106			# For a packet filter-only consumer, the following may apply:
107			# profile = slpf.nsid
108			# Default: execute in the context of multiple profiles
109			profile = None
110			# TODO: how to mix responses from multiple actuators?
111			# Workaround: strictly require a profile to be present
112			response = Response(status=StatusCode.BADREQUEST, status_text='Missing profile')
113			return self.__respmsg(msg, response)
114
115		try:
116			asset_id = msg.content.actuator.getObj()['asset_id']
117		except KeyError:
118			# assed_id = None means the default actuator that implements the required profile
119			asset_id = None
120
121		try:
122			if profile == None:
123				# Select all actuators
124				actuator = list(self.actuators.values())
125			elif asset_id == None:
126				# Select all actuators that implement the specific profile
127				actuator = list(dict(filter(lambda p: p[0][0]==profile, self.actuators.items())).values())
128			else:
129				# Only one instance is expected to be present in this case
130				actuator = [self.actuators[(profile,asset_id)]]
131		except KeyError:
132			response = Response(status=StatusCode.NOTFOUND, status_text='No actuator available')
133			return self.__respmsg(msg, response)
134
135		response_content = None
136		if msg.content.args:
137			if 'response_requested' in msg.content.args.keys():
138				match msg.content.args['response_requested']:
139					case ResponseType.none:
140						response_content = None
141					case ResponseType.ack:
142						response_content = Response(status=StatusCode.PROCESSING, status_text=StatusCodeDescription[StatusCode.PROCESSING])
143						# TODO: Spawn a process to run the process offline
144						logger.warn("Command: %s not run! -- Missing code")
145					case ResponseType.status:
146						response_content = Response(status=StatusCode.PROCESSING, status_text=StatusCodeDescription[StatusCode.PROCESSING])
147						# TODO: Spawn a process to run the process offline
148						logger.warn("Command: %s not run! -- Missing code")
149					case ResponseType.complete:
150						response_content = self.__runcmd(msg, actuator)
151					case _:
152						response_content = Response(status=StatusCode.BADREQUEST, status_text="Invalid response requested")
153
154		if not response_content:
155			# Default: ResponseType == complete. Return an answer after the command is executed.
156			response_content = self.__runcmd(msg, actuator)
157					
158		logger.debug("Actuator %s returned: %s", actuator, response_content)
159
160		# Add the metadata to be returned to the Producer
161		return self.__respmsg(msg, response_content)
162
163	def __runcmd(self, msg, actuator):
164		# Run the command and collect the response
165		# TODO: Define how to manage concurrent execution from more than one actuator
166		try:
167			# TODO: How to merge multiple responses?
168			# for a in actuators.items(): 
169			response_content = actuator[0].run(msg.content) 
170		except (IndexError,AttributeError):
171			response_content = Response(status=StatusCode.NOTFOUND, status_text='No actuator available')
172
173		return response_content
174
175	def __respmsg(self, msg, response):
176		if response:
177			respmsg = Message(response)
178			respmsg.from_=self.consumer
179			respmsg.to=[msg.from_]
180			respmsg.content_type=msg.content_type
181			respmsg.request_id=msg.request_id
182			respmsg.created=int(DateTime())
183			respmsg.status=response['status']
184		else:
185			respmsg = None
186		logger.debug("Response to be sent: %s", respmsg)
187
188		return respmsg
189
190
191
192# TODO: Add main to load configuration from file