2018-11-28 22:51:00 +01:00
|
|
|
"""STIX 2.0 Common Data Types and Properties."""
|
2017-11-02 12:48:37 +01:00
|
|
|
|
|
|
|
from collections import OrderedDict
|
2018-10-25 19:58:21 +02:00
|
|
|
import copy
|
2017-11-02 12:48:37 +01:00
|
|
|
|
2019-09-13 16:51:28 +02:00
|
|
|
import six
|
|
|
|
|
2018-07-11 14:11:47 +02:00
|
|
|
from ..custom import _custom_marking_builder
|
2017-11-02 12:48:37 +01:00
|
|
|
from ..markings import _MarkingsMixin
|
2019-05-08 16:35:53 +02:00
|
|
|
from ..markings.utils import check_tlp_marking
|
2018-07-13 17:10:05 +02:00
|
|
|
from ..properties import (
|
|
|
|
HashesProperty, IDProperty, ListProperty, Property, ReferenceProperty,
|
|
|
|
SelectorProperty, StringProperty, TimestampProperty, TypeProperty,
|
|
|
|
)
|
2018-06-26 18:23:53 +02:00
|
|
|
from ..utils import NOW, _get_dict
|
2020-03-22 03:22:36 +01:00
|
|
|
from .base import _STIXBase20
|
2017-11-02 12:48:37 +01:00
|
|
|
|
|
|
|
|
2019-09-11 16:55:09 +02:00
|
|
|
def _should_set_millisecond(cr, marking_type):
|
2019-09-13 16:51:28 +02:00
|
|
|
# TLP instances in the 2.0 spec have millisecond precision unlike other markings
|
2019-09-11 18:22:55 +02:00
|
|
|
if marking_type == TLPMarking:
|
|
|
|
return True
|
2019-09-13 16:51:28 +02:00
|
|
|
# otherwise, precision is kept from how it was given
|
2019-09-13 18:09:02 +02:00
|
|
|
if isinstance(cr, six.string_types):
|
2019-09-11 18:22:55 +02:00
|
|
|
if '.' in cr:
|
2019-09-11 16:55:09 +02:00
|
|
|
return True
|
2019-09-11 18:22:55 +02:00
|
|
|
else:
|
|
|
|
return False
|
|
|
|
if cr.precision == 'millisecond':
|
|
|
|
return True
|
|
|
|
return False
|
2019-09-11 16:55:09 +02:00
|
|
|
|
2019-09-11 18:12:26 +02:00
|
|
|
|
2020-03-22 03:22:36 +01:00
|
|
|
class ExternalReference(_STIXBase20):
|
2018-02-21 22:42:25 +01:00
|
|
|
"""For more detailed information on this object's properties, see
|
|
|
|
`the STIX 2.0 specification <http://docs.oasis-open.org/cti/stix/v2.0/cs01/part1-stix-core/stix-v2.0-cs01-part1-stix-core.html#_Toc496709261>`__.
|
|
|
|
"""
|
2017-11-02 12:48:37 +01:00
|
|
|
|
2018-06-30 00:38:04 +02:00
|
|
|
_properties = OrderedDict([
|
2017-11-02 12:48:37 +01:00
|
|
|
('source_name', StringProperty(required=True)),
|
|
|
|
('description', StringProperty()),
|
|
|
|
('url', StringProperty()),
|
|
|
|
('hashes', HashesProperty()),
|
|
|
|
('external_id', StringProperty()),
|
|
|
|
])
|
|
|
|
|
|
|
|
def _check_object_constraints(self):
|
|
|
|
super(ExternalReference, self)._check_object_constraints()
|
2018-06-30 00:38:04 +02:00
|
|
|
self._check_at_least_one_property(['description', 'external_id', 'url'])
|
2017-11-02 12:48:37 +01:00
|
|
|
|
|
|
|
|
2020-03-22 03:22:36 +01:00
|
|
|
class KillChainPhase(_STIXBase20):
|
2018-02-21 22:42:25 +01:00
|
|
|
"""For more detailed information on this object's properties, see
|
|
|
|
`the STIX 2.0 specification <http://docs.oasis-open.org/cti/stix/v2.0/cs01/part1-stix-core/stix-v2.0-cs01-part1-stix-core.html#_Toc496709267>`__.
|
|
|
|
"""
|
2017-11-02 12:48:37 +01:00
|
|
|
|
2018-06-30 00:38:04 +02:00
|
|
|
_properties = OrderedDict([
|
2017-11-02 12:48:37 +01:00
|
|
|
('kill_chain_name', StringProperty(required=True)),
|
|
|
|
('phase_name', StringProperty(required=True)),
|
|
|
|
])
|
|
|
|
|
|
|
|
|
2020-03-22 03:22:36 +01:00
|
|
|
class GranularMarking(_STIXBase20):
|
2018-02-21 22:42:25 +01:00
|
|
|
"""For more detailed information on this object's properties, see
|
|
|
|
`the STIX 2.0 specification <http://docs.oasis-open.org/cti/stix/v2.0/cs01/part1-stix-core/stix-v2.0-cs01-part1-stix-core.html#_Toc496709290>`__.
|
|
|
|
"""
|
2017-11-02 12:48:37 +01:00
|
|
|
|
2018-06-30 00:38:04 +02:00
|
|
|
_properties = OrderedDict([
|
2019-08-27 23:36:45 +02:00
|
|
|
('marking_ref', ReferenceProperty(valid_types='marking-definition', spec_version='2.0', required=True)),
|
2017-11-02 12:48:37 +01:00
|
|
|
('selectors', ListProperty(SelectorProperty, required=True)),
|
|
|
|
])
|
|
|
|
|
|
|
|
|
2020-03-22 03:22:36 +01:00
|
|
|
class TLPMarking(_STIXBase20):
|
2018-02-21 22:42:25 +01:00
|
|
|
"""For more detailed information on this object's properties, see
|
|
|
|
`the STIX 2.0 specification <http://docs.oasis-open.org/cti/stix/v2.0/cs01/part1-stix-core/stix-v2.0-cs01-part1-stix-core.html#_Toc496709287>`__.
|
|
|
|
"""
|
2017-11-02 12:48:37 +01:00
|
|
|
|
2017-08-11 22:18:20 +02:00
|
|
|
# TODO: don't allow the creation of any other TLPMarkings than the ones below
|
2017-11-02 12:48:37 +01:00
|
|
|
_type = 'tlp'
|
2018-06-30 00:38:04 +02:00
|
|
|
_properties = OrderedDict([
|
2018-07-13 17:10:05 +02:00
|
|
|
('tlp', StringProperty(required=True)),
|
2017-11-02 12:48:37 +01:00
|
|
|
])
|
|
|
|
|
|
|
|
|
2020-03-22 03:22:36 +01:00
|
|
|
class StatementMarking(_STIXBase20):
|
2018-02-21 22:42:25 +01:00
|
|
|
"""For more detailed information on this object's properties, see
|
|
|
|
`the STIX 2.0 specification <http://docs.oasis-open.org/cti/stix/v2.0/cs01/part1-stix-core/stix-v2.0-cs01-part1-stix-core.html#_Toc496709286>`__.
|
|
|
|
"""
|
2017-11-02 12:48:37 +01:00
|
|
|
|
|
|
|
_type = 'statement'
|
2018-06-30 00:38:04 +02:00
|
|
|
_properties = OrderedDict([
|
2018-07-13 17:10:05 +02:00
|
|
|
('statement', StringProperty(required=True)),
|
2017-11-02 12:48:37 +01:00
|
|
|
])
|
|
|
|
|
|
|
|
def __init__(self, statement=None, **kwargs):
|
|
|
|
# Allow statement as positional args.
|
|
|
|
if statement and not kwargs.get('statement'):
|
|
|
|
kwargs['statement'] = statement
|
|
|
|
|
|
|
|
super(StatementMarking, self).__init__(**kwargs)
|
|
|
|
|
|
|
|
|
|
|
|
class MarkingProperty(Property):
|
|
|
|
"""Represent the marking objects in the ``definition`` property of
|
|
|
|
marking-definition objects.
|
|
|
|
"""
|
|
|
|
|
|
|
|
def clean(self, value):
|
|
|
|
if type(value) in OBJ_MAP_MARKING.values():
|
|
|
|
return value
|
|
|
|
else:
|
|
|
|
raise ValueError("must be a Statement, TLP Marking or a registered marking.")
|
|
|
|
|
|
|
|
|
2020-03-22 03:22:36 +01:00
|
|
|
class MarkingDefinition(_STIXBase20, _MarkingsMixin):
|
2018-02-21 22:42:25 +01:00
|
|
|
"""For more detailed information on this object's properties, see
|
|
|
|
`the STIX 2.0 specification <http://docs.oasis-open.org/cti/stix/v2.0/cs01/part1-stix-core/stix-v2.0-cs01-part1-stix-core.html#_Toc496709284>`__.
|
|
|
|
"""
|
2017-11-02 12:48:37 +01:00
|
|
|
|
|
|
|
_type = 'marking-definition'
|
2018-06-30 00:38:04 +02:00
|
|
|
_properties = OrderedDict([
|
2020-04-02 03:52:04 +02:00
|
|
|
('type', TypeProperty(_type, spec_version='2.0')),
|
2019-06-14 23:58:51 +02:00
|
|
|
('id', IDProperty(_type, spec_version='2.0')),
|
2019-08-27 23:36:45 +02:00
|
|
|
('created_by_ref', ReferenceProperty(valid_types='identity', spec_version='2.0')),
|
2017-11-02 12:48:37 +01:00
|
|
|
('created', TimestampProperty(default=lambda: NOW)),
|
|
|
|
('external_references', ListProperty(ExternalReference)),
|
2019-08-27 23:36:45 +02:00
|
|
|
('object_marking_refs', ListProperty(ReferenceProperty(valid_types='marking-definition', spec_version='2.0'))),
|
2017-11-02 12:48:37 +01:00
|
|
|
('granular_markings', ListProperty(GranularMarking)),
|
|
|
|
('definition_type', StringProperty(required=True)),
|
|
|
|
('definition', MarkingProperty(required=True)),
|
|
|
|
])
|
|
|
|
|
|
|
|
def __init__(self, **kwargs):
|
|
|
|
if set(('definition_type', 'definition')).issubset(kwargs.keys()):
|
|
|
|
# Create correct marking type object
|
|
|
|
try:
|
|
|
|
marking_type = OBJ_MAP_MARKING[kwargs['definition_type']]
|
|
|
|
except KeyError:
|
|
|
|
raise ValueError("definition_type must be a valid marking type")
|
|
|
|
|
2019-09-13 20:54:52 +02:00
|
|
|
if 'created' in kwargs:
|
2019-09-13 16:51:28 +02:00
|
|
|
if _should_set_millisecond(kwargs['created'], marking_type):
|
|
|
|
self._properties = copy.deepcopy(self._properties)
|
|
|
|
self._properties.update([
|
|
|
|
('created', TimestampProperty(default=lambda: NOW, precision='millisecond')),
|
|
|
|
])
|
2018-10-25 19:58:21 +02:00
|
|
|
|
2017-11-02 12:48:37 +01:00
|
|
|
if not isinstance(kwargs['definition'], marking_type):
|
2018-04-13 17:08:03 +02:00
|
|
|
defn = _get_dict(kwargs['definition'])
|
2017-11-02 12:48:37 +01:00
|
|
|
kwargs['definition'] = marking_type(**defn)
|
|
|
|
|
|
|
|
super(MarkingDefinition, self).__init__(**kwargs)
|
|
|
|
|
2019-05-03 15:59:07 +02:00
|
|
|
def _check_object_constraints(self):
|
|
|
|
super(MarkingDefinition, self)._check_object_constraints()
|
|
|
|
check_tlp_marking(self, '2.0')
|
|
|
|
|
|
|
|
def serialize(self, pretty=False, include_optional_defaults=False, **kwargs):
|
|
|
|
check_tlp_marking(self, '2.0')
|
|
|
|
return super(MarkingDefinition, self).serialize(pretty, include_optional_defaults, **kwargs)
|
|
|
|
|
2017-11-02 12:48:37 +01:00
|
|
|
|
|
|
|
OBJ_MAP_MARKING = {
|
|
|
|
'tlp': TLPMarking,
|
|
|
|
'statement': StatementMarking,
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
def CustomMarking(type='x-custom-marking', properties=None):
|
|
|
|
"""Custom STIX Marking decorator.
|
|
|
|
|
|
|
|
Example:
|
2018-07-10 21:07:08 +02:00
|
|
|
>>> from stix2 import CustomMarking
|
|
|
|
>>> from stix2.properties import IntegerProperty, StringProperty
|
2017-11-02 12:48:37 +01:00
|
|
|
>>> @CustomMarking('x-custom-marking', [
|
|
|
|
... ('property1', StringProperty(required=True)),
|
|
|
|
... ('property2', IntegerProperty()),
|
|
|
|
... ])
|
|
|
|
... class MyNewMarkingObjectType():
|
|
|
|
... pass
|
|
|
|
|
|
|
|
"""
|
2018-07-10 21:07:08 +02:00
|
|
|
def wrapper(cls):
|
2020-03-22 03:22:36 +01:00
|
|
|
return _custom_marking_builder(cls, type, properties, '2.0', _STIXBase20)
|
2018-07-10 21:07:08 +02:00
|
|
|
return wrapper
|
2017-11-02 12:48:37 +01:00
|
|
|
|
|
|
|
|
|
|
|
# TODO: don't allow the creation of any other TLPMarkings than the ones below
|
|
|
|
|
|
|
|
TLP_WHITE = MarkingDefinition(
|
2018-06-30 00:38:04 +02:00
|
|
|
id='marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9',
|
|
|
|
created='2017-01-20T00:00:00.000Z',
|
|
|
|
definition_type='tlp',
|
2018-07-13 17:10:05 +02:00
|
|
|
definition=TLPMarking(tlp='white'),
|
2017-11-02 12:48:37 +01:00
|
|
|
)
|
|
|
|
|
|
|
|
TLP_GREEN = MarkingDefinition(
|
2018-06-30 00:38:04 +02:00
|
|
|
id='marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da',
|
|
|
|
created='2017-01-20T00:00:00.000Z',
|
|
|
|
definition_type='tlp',
|
2018-07-13 17:10:05 +02:00
|
|
|
definition=TLPMarking(tlp='green'),
|
2017-11-02 12:48:37 +01:00
|
|
|
)
|
|
|
|
|
|
|
|
TLP_AMBER = MarkingDefinition(
|
2018-06-30 00:38:04 +02:00
|
|
|
id='marking-definition--f88d31f6-486f-44da-b317-01333bde0b82',
|
|
|
|
created='2017-01-20T00:00:00.000Z',
|
|
|
|
definition_type='tlp',
|
2018-07-13 17:10:05 +02:00
|
|
|
definition=TLPMarking(tlp='amber'),
|
2017-11-02 12:48:37 +01:00
|
|
|
)
|
|
|
|
|
|
|
|
TLP_RED = MarkingDefinition(
|
2018-06-30 00:38:04 +02:00
|
|
|
id='marking-definition--5e57c739-391a-4eb3-b6be-7d15ca92d5ed',
|
|
|
|
created='2017-01-20T00:00:00.000Z',
|
|
|
|
definition_type='tlp',
|
2018-07-13 17:10:05 +02:00
|
|
|
definition=TLPMarking(tlp='red'),
|
2017-11-02 12:48:37 +01:00
|
|
|
)
|