openc2lib.types.datatypes

  1""" OpenC2 data types
  2
  3	Definition of the data types in the OpenC2 DataModels (Sec. 3.4.2).
  4	The naming strictly follows the definition of the Language Specification
  5	as close as possible. The relevant exception is represented by hyphens
  6	that are always dropped.
  7"""
  8
  9import ipaddress
 10import aenum
 11import datetime 
 12import dataclasses
 13
 14from openc2lib.types.basetypes import MapOf, Enumerated, ArrayOf
 15from openc2lib.core.actions import Actions
 16
 17
 18""" IPv4 Address
 19
 20	This class implements an IPv4 Address as described in Sec. 3.4.2.8.
 21
 22The usage of the ipaddress module is compliant to what required in the
 23language specification for IPv4 addresses, especially the following points:
 24a) The IPv4 address should be available both in string and binary form
 25b) The network representation is an array according to RFC 4632 Sec. 3.1
 26   (host/prefix, host/mask, host/hostmask, etc.)
 27"""
 28class IPv4Addr:
 29	"""OpenC2 IPv4 Address"
 30
 31		This class implements an IPv4 Address as described in Sec. 3.4.2.8.
 32
 33		The usage of the ipaddress module is compliant to what required in the
 34		language specification for IPv4 addresses, especially the following points:
 35		a) The IPv4 address should be available both in string and binary form
 36		b) The network representation is an array according to RFC 4632 Sec. 3.1
 37		   (host/prefix, host/mask, host/hostmask, etc.)
 38
 39"""
 40	__ipv4_addr = ipaddress.IPv4Address("0.0.0.0")
 41	""" Internal representation of the IPv4 address"""
 42	
 43	def __init__(self, ipaddr=None):
 44		""" Initialize IPv4 Address 
 45
 46			An IPv4 address is built from a string that uses the common dotted notation.
 47			If no IPv4 address is provided, the null address is used ("0.0.0.0").
 48
 49			:param ipaddr: Quad-dotted representation of the IPv4 address.
 50		"""
 51		if ipaddr == None:
 52			self.__ipv4_addr = ipaddress.IPv4Address("0.0.0.0")
 53		else:
 54			self.__ipv4_addr = ipaddress.IPv4Address(ipaddr)
 55
 56	def __str__(self):
 57		return self.__ipv4_addr.exploded
 58
 59	def __repr__(self):
 60		return self.__ipv4_addr.exploded
 61
 62class L4Protocol(Enumerated):
 63	""" OpenC2 L4 Protocol
 64
 65		This is an enumeration for all known transport protocols. The numeric identifier
 66		is set to the protocol number defined for IP.
 67	"""
 68	icmp = 1
 69	tcp = 6
 70	udp = 17
 71	sctp = 132
 72
 73class DateTime:
 74	""" OpenC2 Date-Time
 75
 76		This is used to represents dates and times according to Sec. 3.4.2.2.
 77		 According to OpenC2 specification, this is the time in milliseconds from the epoch.
 78		Be careful that the `timedate` functions work with float timestamps expressed 
 79		in seconds from the epoch, hence conversion is needed.
 80	"""
 81	def __init__(self, timestamp=None):
 82		""" Initialize Date-Time
 83			
 84			The instance is initialized with the provided timestamp, or to the current time if no 
 85			argument is given. The timestamp is expressed in milliseconds
 86				from the epoch, according to the Language Specification.
 87			:param timestamp: The timestamp to initialize the instance.
 88		"""
 89		self.update(timestamp)
 90
 91	def __str__(self):
 92		return str(self.time)
 93
 94	def __int__(self):
 95		return self.time
 96
 97	def update(self, timestamp=None):
 98		""" Change Date-Time
 99
100			Change the timestamp beard by the instance. The timestamp is expressed in milliseconds
101			from the epoch. If no `timestamp` is given, sets to the current time.
102			:param timestamp: The timestamp to initialize the instance.
103		"""
104		if timestamp == None:
105			# datetime.timestamp() returns a float in seconds
106			self.time = int(datetime.datetime.now(datetime.timezone.utc).timestamp()*1000)
107		else:
108			self.time = timestamp
109
110	# RFC 7231       
111	def httpdate(self, timestamp=None):
112		""" Format  to HTTP headers
113
114			Formats the timestamp according to the requirements of HTTP headers (RFC 7231).
115			Use either the `timestamp`, if provided,  or the current time.
116			:param timestamp: The timestamp to format, expressed in milliseconds from the epoch.
117			:return RFC 7231 representation of the `timestamp`.
118		"""
119			
120		if timestamp is None:
121			timestamp = self.time
122
123		return datetime.datetime.fromtimestamp(timestamp/1000).strftime('%a, %d %b %Y %H:%M:%S %Z')
124
125class Duration(int):
126	""" OpenC2 Duration
127
128		 A time (positive number) expressed in milliseconds (Sec. 3.4.2.3).
129	""" 
130	def __init__(self, dur):
131		""" Initialization
132
133			Initialize to `dur` if greater or equal to zero, raise an exception if negative.
134		"""
135		if int(dur) < 0:
136			raise ValueError("Duration must be a positive number")
137		self=int(dur)
138
139class Version(str):
140	""" OpenC2 Version
141
142		Version of the OpenC2 protocol (Sec. 3.4.2.16). Currently a *<major>.<minor>* format is used.
143	"""
144	def __new__(cls, major, minor):
145		""" Create `Version` instance
146
147			Create a Version instance from major and minor numbers, expressed as numbers.
148			:param major: Major number of OpenC2 version.
149			:param minor: Minor number of OpenC2 version.
150			:return: `Version` instance.
151		"""
152		vers = str(major) + '.' + str(minor)
153		instance = super().__new__(cls, vers)
154		return instance
155
156	def __init__(self, major, minor):
157		""" Initialize `Version` instance
158
159			Initialize with major and minor numbers.
160			:param major: Major number of OpenC2 version.
161			:param minor: Minor number of OpenC2 version.
162			:return: `Version` instance.
163		"""
164		self.major = major
165		self.minor = minor
166
167	@staticmethod
168	def fromstr(v):
169		""" Create `Version` instance
170
171			Create `Version` instance from string (in the *<major>.<minor>* notation.
172			:param v: Text string with the Version.
173			:return: `Version` instance.
174		"""
175		vers = v.split('.',2)
176		return Version(vers[0], vers[1])
177	
178	@classmethod
179	def fromdict(cls, vers, e=None):
180		""" Create `Version` instance
181
182			Create `Version` instance from string (in the *<major>.<minor>* notation.
183			This method is provided to deserialize an OpenC2 message according to the openc2lib approach.
184			This method should only be used internally the openc2lib.
185			:param vers: Text string with the Version.
186			:param e: `Encoder` instance to be used (only included to be compliance with the function footprint.
187			:return: `Version` instance.
188		"""
189		return Version.fromstr(vers)
190
191class Feature(Enumerated):
192	""" OpenC2 Feature
193
194		An enumeration for the fields that can be included in the `Results` (see Sec. 3.4.2.4).
195	"""
196	versions   = 1
197	profiles   = 2
198	pairs      = 3
199	rate_limit = 4
200
201
202		
203class Nsid(str):
204	""" OpenC2 Namespace Identifier
205
206		Namespace identifiers are described in Sec. 3.1.4. This class implements the required
207			controls on the string length.
208	"""
209	def __init__(self, nsid):
210		""" Initialize `Nsid`
211
212			:param nsid: Text string (must be more than 1 and less than 16 characters.
213		"""
214		if len(nsid) > 16 or len(nsid) < 1:
215			raise ValueError("Nsid must be between 1 and 16 characters")
216		self = nsid
217
218	@classmethod
219	def fromdict(cls, name, e):
220		""" Create `Nsid` instance
221
222			Create `Nsid` instance from string.
223			This method is provided to deserialize an OpenC2 message according to the openc2lib approach.
224			This method should only be used internally the openc2lib.
225			:param name: Text string with the namespace identifier..
226			:param e: `Encoder` instance to be used (only included to be compliance with the function footprint.
227			:return: `Version` instance.
228		"""
229		return Nsid(name)
230	
231class ResponseType(Enumerated):
232	""" OpenC2 Response-Type
233
234		Enumerates the Response-Types according to Sec. 3.4.2.15.	
235	"""	
236	none=0
237	ack=1
238	status=2
239	complete=3
240
241class TargetEnum(Enumerated):
242	""" OpenC2 Targets names
243	
244		The Language Specification defines a *Targets* subtypes only used in Sec. 3.4.2.1.
245		The openc2lib uses this class to keep a record of all registered Target names, while
246		the *Targets* type is never defined (it is build in an unnamed way to create the 
247		`ActionTargets`.
248
249		This class is only expected to be used internally by the openc2lib.
250	"""
251	def __repr__(self):
252		return self.name
253
254class ActionTargets(MapOf(Actions, ArrayOf(TargetEnum))):
255	""" OpenC2 Action-Targets
256
257		Map of each action supported by an actuator to the list of targets applicable to 
258		that action (Sec. 3.4.2.1).
259		They must be defined by each Profile.
260	"""
261	pass
262
263class ActionArguments(MapOf(Actions, ArrayOf(str))):
264	""" OpenC2 Action-Arguments mapping
265
266		Map of each action supported by an actuator to the list of arguments applicable to
267		that action. 
268		This is not defined in the Language Specification, but used e.g., by the SLPF Profile.
269	"""
270	pass