openc2lib.core.message

  1"""OpenC2 Message structures
  2
  3This module defines the OpenC2 Message structure and its content type, as defined
  4in Sec. 3.2 of the Language Specification.
  5
  6The definition include: `Message`, `Content`, `Command`, and `Response`.
  7"""
  8
  9
 10import enum
 11import dataclasses
 12import uuid
 13
 14from openc2lib.types.datatypes import DateTime, Version
 15from openc2lib.types.basetypes import Record, Map
 16
 17from openc2lib.core.actions import Actions 
 18from openc2lib.core.target import Target
 19from openc2lib.core.response import StatusCode, Results
 20from openc2lib.core.args import Args
 21
 22from openc2lib.core.actuator import Actuator
 23
 24_OPENC2_CONTENT_TYPE = "openc2"
 25_OPENC2_VERSION = Version(1,0)
 26
 27class MessageType(enum.Enum):
 28	"""OpenC2 Message Type
 29	
 30	Message type can be either `command` or `response`.
 31	"""
 32	command = 1
 33	response = 2
 34
 35
 36class Content:
 37	""" Content of the OpenC2 Message
 38
 39		A content is the base class to derive either a `Command` or a `Response`. 
 40	"""
 41	msg_type: MessageType = None
 42	"The type of Content (`MessageType`)"
 43
 44	def getType(self):
 45		""" Returns the Content type """
 46		return self.msg_type
 47
 48@dataclasses.dataclass
 49class Message:
 50	"""OpenC2 Message
 51	
 52	The Message class embeds all Message fields that are defined in Table 3.1 of the
 53	Language Specification. It is just an internal structure that is not automatically
 54	serialized, since the use of the fields depends on the specific transport protocol.
 55	"""
 56	content: Content
 57	""" Message body as specified by `content_type` and `msg_type`. """
 58	content_type: str = _OPENC2_CONTENT_TYPE
 59	""" Media Type that identifies the format of the content, including major version."""
 60	msg_type: MessageType = None
 61	"""The type of OpenC2 Message."""
 62	status: int = None
 63	"""Populated with a numeric status code in Responses."""
 64	request_id: str = None
 65	"""A unique identifier created by the Producer and copied by Consumer into all Responses."""
 66	created: int = None
 67	"""Creation date/time of the content."""
 68	from_: str = None
 69	"""Authenticated identifier of the creator of or authority for execution of a message. 
 70
 71	This field is named `from` in the Specification.
 72	"""
 73	to: [] = None
 74	""" Authenticated identifier(s) of the authorized recipient(s) of a message."""
 75	version: Version = _OPENC2_VERSION
 76	"""OpenC2 version used to encode the `Message`.
 77
 78	This is is an additional field not envisioned by the Language Specification.
 79	"""
 80	encoding: object = None
 81	"""Encoding format used to serialize the `Message`.
 82
 83	This is is an additional field not envisioned by the Language Specification.
 84	"""
 85	
 86	def __post_init__(self ):
 87		self.request_id = str(uuid.uuid4()) 
 88		self.created = int(DateTime())
 89		try:
 90			self.msg_type = self.content.msg_type
 91		except AttributeError:
 92			pass
 93
 94#todo
 95	def todict(self):
 96		""" Serialization to dictionary."""
 97#dict = {"headers
 98		dic = self.__dict__
 99		return dic
100
101
102# Init and other standard methods are automatically created
103@dataclasses.dataclass
104class Command(Content, Record):
105	"""OpenC2 Command
106
107	This class defines the structure of the OpenC2 Command. The name, meaning, and restrictions for
108	the fields are described in Sec. 3.3.1 of the Specification.
109
110	The `target` object is implicitely initialized by passing any valid `Target`.
111	"""
112	action: Actions
113	target: Target
114	args: Args = None
115	actuator: Actuator = None
116	command_id: str = None
117	msg_type = MessageType.command
118
119	# Mind that the __post_init__ hides Exceptions!!!! 
120	# If something fails in its code, it returns with no errors but does 
121	# not complete the code
122	def __post_init__(self):
123		if not isinstance(self.target, Target):
124			self.target = Target(self.target)
125		if not isinstance(self.actuator, Actuator) and self.actuator is not None:
126			self.actuator = Actuator(self.actuator)
127
128
129class Response(Content, Map):
130	"""OpenC2 Response
131
132		This class defines the structure of the OpenC2 Response. According to the definition
133			in Sec. 3.3.2 of the Language Specification, the `Response` contains a list of
134		  <key, value> pair. This allows for extensions by the Profiles.
135
136			Extensions to `Response` must extend `fieldtypes` according to the allowed field
137	 		names and types. `fieldtypes` is used to parse incoming OpenC2 messages and to build
138		   and initialize	the
139			correct Python objects for each \<key, value\> pair.		
140	"""
141		
142	fieldtypes = dict(status= StatusCode, status_text= str, results= Results)
143	"""The list of allowed \<key,value\> pair expected in a `Response`"""
144	msg_type = MessageType.response