openc2lib.core.response

  1""" OpenC2 Response elements
  2
  3	This module defines the elements beard by a `Response`.
  4"""
  5from openc2lib.types.basetypes import EnumeratedID, Map, ArrayOf
  6from openc2lib.types.datatypes import Version, ActionTargets, Nsid
  7
  8class StatusCode(EnumeratedID):
  9	""" Status codes
 10
 11		Status codes provide indication about the processing of the OpenC2 Command.
 12		They follow the same logic and values of HTTP status code, since they are copied
 13		in HTTP headers.
 14"""
 15	PROCESSING = 102
 16	OK = 200
 17	BADREQUEST = 400
 18	UNAUTHORIZED = 401
 19	FORBIDDEN = 403
 20	NOTFOUND = 404
 21	INTERNALERROR =500
 22	NOTIMPLEMENTED = 501
 23	SERVICEUNAVAILABLE = 503
 24
 25StatusCodeDescription = {StatusCode.PROCESSING: 'Processing', 
 26										StatusCode.OK: 'OK',
 27										StatusCode.BADREQUEST: 'Bad Request',
 28										StatusCode.UNAUTHORIZED: 'Unauthorized',
 29										StatusCode.FORBIDDEN: 'Forbidden',
 30										StatusCode.NOTFOUND: 'Not Found',
 31										StatusCode.INTERNALERROR: 'Internal Error',
 32										StatusCode.NOTIMPLEMENTED: 'Not Implemented',
 33										StatusCode.SERVICEUNAVAILABLE: 'Service Unavailable'}
 34""" Status code description
 35
 36	Human-readable description of `StatusCode`s. The values are only provided as base values, since any `Actuator`
 37	can freely use different descriptions.
 38"""
 39
 40class ExtResultsDict(dict):
 41	""" Extended Results
 42
 43		This class is used to extend the basic `Results` definition. If follows the same logic as 
 44		other extended class in the openc2lib. 
 45	"""
 46	def add(self, profile: str, extresults):
 47		""" Add extension
 48
 49			Add a new extension for a given `Profile`. The extension must be registered only once.
 50			:param profile: The name of the profile for which the extension is registered.
 51			:param extresults: The Extension to be registered.
 52			:return: None
 53		"""
 54		if profile in self:
 55			raise ValueError("ExtResults already registered")
 56		self[profile] = extresults
 57	
 58ExtendedResults = ExtResultsDict()
 59""" List of Extended Results
 60
 61	List of registered extensions to `Results`. It is only used internally the openc2lib to correctly
 62	parse incoming Rensponses.
 63"""
 64
 65class Results(Map):
 66	""" OpenC2 Response Results
 67
 68		This class implements the definition in Sec. 3.3.2.2 of the Language Specification. The `Results` carry
 69		the output of an OpenC2 Command. This definition only includes basic fields and it is expected to
 70		be extended for each `Profile`.
 71
 72		Extensions must be derived class that define the following member:
 73			- `fieldtypes`
 74			- `extend`
 75			- `nsid`
 76		`nsid` must be set to the profile name.
 77	"""
 78	fieldtypes = dict(versions= ArrayOf(Version), profiles= ArrayOf(Nsid), pairs= ActionTargets, rate_limit= int)
 79	""" Field types
 80	
 81		This is the definition of the fields beard by the `Results`. This definition is for internal use only,
 82		to parse OpenC2 messages. Extensions must include these fields and add additional definitions.
 83	"""
 84	extend = None
 85	""" Extension
 86
 87		This field must be set to None in the base class, and to `Results` in the derived class that defines an extension.
 88	"""
 89	regext = ExtendedResults
 90	""" Extended NameSpace
 91
 92		This field is for internal use only and must not be set by any derived class.
 93	"""
 94
 95	def set(self, version=None, profiles=None, pairs=None, rate_limit=None):
 96		""" Set values
 97
 98			This function may be used to set specific values of the `Results`, with a key=value syntax.
 99			:param version: List of OpenC2 Versions supported by the Actuator.
100			:param profiles: List of OpenC2 Profiles supported by the Actuator.
101			:param pairs: List of `Targets` applicable to each supported `Action`.
102			:param rate_limit: Maximum number of requests per minute supported by design or policy.
103			:return: None
104		"""
105		self['version']=version
106		self['profiles']=profiles
107		self['pairs']=pairs
108		self['rate_limit']=rate_limit