From d708537b85f99b2b9bb96757929c7fbefc268f6a Mon Sep 17 00:00:00 2001 From: Michael Chisholm Date: Tue, 10 Mar 2020 20:24:53 -0400 Subject: [PATCH 1/3] Add enforcement of a new STIX 2.1 SCO extension name requirement: that it must end with "-ext". --- stix2/core.py | 58 +++++++++++++++++++++++++++-------- stix2/custom.py | 29 +++++++++--------- stix2/test/v20/test_custom.py | 9 ++---- stix2/test/v21/test_custom.py | 29 ++++++++---------- stix2/utils.py | 1 + 5 files changed, 77 insertions(+), 49 deletions(-) diff --git a/stix2/core.py b/stix2/core.py index 0d1fee5..c4d7628 100644 --- a/stix2/core.py +++ b/stix2/core.py @@ -7,10 +7,10 @@ import re import stix2 -from .base import _STIXBase +from .base import _Observable, _STIXBase from .exceptions import ParseError from .markings import _MarkingsMixin -from .utils import _get_dict +from .utils import SCO21_EXT_REGEX, TYPE_REGEX, _get_dict STIX2_OBJ_MAPS = {} @@ -258,22 +258,54 @@ def _register_observable(new_observable, version=None): OBJ_MAP_OBSERVABLE[new_observable._type] = new_observable -def _register_observable_extension(observable, new_extension, version=None): +def _register_observable_extension( + observable, new_extension, version=stix2.DEFAULT_VERSION +): """Register a custom extension to a STIX Cyber Observable type. Args: - observable: An observable object + observable: An observable class or instance new_extension (class): A class to register in the Observables Extensions map. - version (str): Which STIX2 version to use. (e.g. "2.0", "2.1"). If - None, use latest version. + version (str): Which STIX2 version to use. (e.g. "2.0", "2.1"). + Defaults to the latest supported version. """ - if version: - v = 'v' + version.replace('.', '') - else: - # Use default version (latest) if no version was provided. - v = 'v' + stix2.DEFAULT_VERSION.replace('.', '') + obs_class = observable if isinstance(observable, type) else \ + type(observable) + ext_type = new_extension._type + + if not issubclass(obs_class, _Observable): + raise ValueError("'observable' must be a valid Observable class!") + + if version == "2.0": + if not re.match(TYPE_REGEX, ext_type): + raise ValueError( + "Invalid extension type name '%s': must only contain the " + "characters a-z (lowercase ASCII), 0-9, and hyphen (-)." % + ext_type, + ) + else: # 2.1+ + if not re.match(SCO21_EXT_REGEX, ext_type): + raise ValueError( + "Invalid extension type name '%s': must only contain the " + "characters a-z (lowercase ASCII), 0-9, hyphen (-), and end " + "with '-ext'." % ext_type, + ) + + if len(ext_type) < 3 or len(ext_type) > 250: + raise ValueError( + "Invalid extension type name '%s': must be between 3 and 250" + " characters." % ext_type, + ) + + if not new_extension._properties: + raise ValueError( + "Invalid extension: must define at least one property: " + + ext_type, + ) + + v = 'v' + version.replace('.', '') try: observable_type = observable._type @@ -287,7 +319,7 @@ def _register_observable_extension(observable, new_extension, version=None): EXT_MAP = STIX2_OBJ_MAPS[v]['observable-extensions'] try: - EXT_MAP[observable_type][new_extension._type] = new_extension + EXT_MAP[observable_type][ext_type] = new_extension except KeyError: if observable_type not in OBJ_MAP_OBSERVABLE: raise ValueError( @@ -296,7 +328,7 @@ def _register_observable_extension(observable, new_extension, version=None): % observable_type, ) else: - EXT_MAP[observable_type] = {new_extension._type: new_extension} + EXT_MAP[observable_type] = {ext_type: new_extension} def _collect_stix2_mappings(): diff --git a/stix2/custom.py b/stix2/custom.py index 802fd07..f3c89cf 100644 --- a/stix2/custom.py +++ b/stix2/custom.py @@ -1,6 +1,8 @@ from collections import OrderedDict import re +import six + from .base import _cls_init, _Extension, _Observable, _STIXBase from .core import ( STIXDomainObject, _register_marking, _register_object, @@ -113,24 +115,23 @@ def _custom_observable_builder(cls, type, properties, version, id_contrib_props= def _custom_extension_builder(cls, observable, type, properties, version): - if not observable or not issubclass(observable, _Observable): - raise ValueError("'observable' must be a valid Observable class!") + + try: + prop_dict = OrderedDict(properties) + except TypeError as e: + six.raise_from( + ValueError( + "Extension properties must be dict-like, e.g. a list " + "containing tuples. For example, " + "[('property1', IntegerProperty())]", + ), + e, + ) class _CustomExtension(cls, _Extension): - if not re.match(TYPE_REGEX, type): - raise ValueError( - "Invalid extension type name '%s': must only contain the " - "characters a-z (lowercase ASCII), 0-9, and hyphen (-)." % type, - ) - elif len(type) < 3 or len(type) > 250: - raise ValueError("Invalid extension type name '%s': must be between 3 and 250 characters." % type) - - if not properties or not isinstance(properties, list): - raise ValueError("Must supply a list, containing tuples. For example, [('property1', IntegerProperty())]") - _type = type - _properties = OrderedDict(properties) + _properties = prop_dict def __init__(self, **kwargs): _Extension.__init__(self, **kwargs) diff --git a/stix2/test/v20/test_custom.py b/stix2/test/v20/test_custom.py index ce1aac3..b986777 100644 --- a/stix2/test/v20/test_custom.py +++ b/stix2/test/v20/test_custom.py @@ -821,27 +821,24 @@ def test_custom_extension_invalid_type_name(): def test_custom_extension_no_properties(): - with pytest.raises(ValueError) as excinfo: + with pytest.raises(ValueError): @stix2.v20.CustomExtension(stix2.v20.DomainName, 'x-new-ext2', None) class BarExtension(): pass - assert "Must supply a list, containing tuples." in str(excinfo.value) def test_custom_extension_empty_properties(): - with pytest.raises(ValueError) as excinfo: + with pytest.raises(ValueError): @stix2.v20.CustomExtension(stix2.v20.DomainName, 'x-new-ext2', []) class BarExtension(): pass - assert "Must supply a list, containing tuples." in str(excinfo.value) def test_custom_extension_dict_properties(): - with pytest.raises(ValueError) as excinfo: + with pytest.raises(ValueError): @stix2.v20.CustomExtension(stix2.v20.DomainName, 'x-new-ext2', {}) class BarExtension(): pass - assert "Must supply a list, containing tuples." in str(excinfo.value) def test_custom_extension_no_init_1(): diff --git a/stix2/test/v21/test_custom.py b/stix2/test/v21/test_custom.py index b46288d..8b1a38c 100644 --- a/stix2/test/v21/test_custom.py +++ b/stix2/test/v21/test_custom.py @@ -800,7 +800,7 @@ def test_custom_extension_wrong_observable_type(): ) def test_custom_extension_with_list_and_dict_properties_observable_type(data): @stix2.v21.CustomExtension( - stix2.v21.UserAccount, 'some-extension', [ + stix2.v21.UserAccount, 'some-extension-ext', [ ('keys', stix2.properties.ListProperty(stix2.properties.DictionaryProperty, required=True)), ], ) @@ -876,32 +876,29 @@ def test_custom_extension_invalid_type_name(): def test_custom_extension_no_properties(): - with pytest.raises(ValueError) as excinfo: - @stix2.v21.CustomExtension(stix2.v21.DomainName, 'x-new-ext2', None) + with pytest.raises(ValueError): + @stix2.v21.CustomExtension(stix2.v21.DomainName, 'x-new2-ext', None) class BarExtension(): pass - assert "Must supply a list, containing tuples." in str(excinfo.value) def test_custom_extension_empty_properties(): - with pytest.raises(ValueError) as excinfo: - @stix2.v21.CustomExtension(stix2.v21.DomainName, 'x-new-ext2', []) + with pytest.raises(ValueError): + @stix2.v21.CustomExtension(stix2.v21.DomainName, 'x-new2-ext', []) class BarExtension(): pass - assert "Must supply a list, containing tuples." in str(excinfo.value) def test_custom_extension_dict_properties(): - with pytest.raises(ValueError) as excinfo: - @stix2.v21.CustomExtension(stix2.v21.DomainName, 'x-new-ext2', {}) + with pytest.raises(ValueError): + @stix2.v21.CustomExtension(stix2.v21.DomainName, 'x-new2-ext', {}) class BarExtension(): pass - assert "Must supply a list, containing tuples." in str(excinfo.value) def test_custom_extension_no_init_1(): @stix2.v21.CustomExtension( - stix2.v21.DomainName, 'x-new-extension', [ + stix2.v21.DomainName, 'x-new-extension-ext', [ ('property1', stix2.properties.StringProperty(required=True)), ], ) @@ -914,7 +911,7 @@ def test_custom_extension_no_init_1(): def test_custom_extension_no_init_2(): @stix2.v21.CustomExtension( - stix2.v21.DomainName, 'x-new-ext2', [ + stix2.v21.DomainName, 'x-new2-ext', [ ('property1', stix2.properties.StringProperty(required=True)), ], ) @@ -949,14 +946,14 @@ def test_custom_and_spec_extension_mix(): file_obs = stix2.v21.File( name="my_file.dat", extensions={ - "x-custom1": { + "custom1-ext": { "a": 1, "b": 2, }, "ntfs-ext": { "sid": "S-1-whatever", }, - "x-custom2": { + "custom2-ext": { "z": 99.9, "y": False, }, @@ -969,8 +966,8 @@ def test_custom_and_spec_extension_mix(): allow_custom=True, ) - assert file_obs.extensions["x-custom1"] == {"a": 1, "b": 2} - assert file_obs.extensions["x-custom2"] == {"y": False, "z": 99.9} + assert file_obs.extensions["custom1-ext"] == {"a": 1, "b": 2} + assert file_obs.extensions["custom2-ext"] == {"y": False, "z": 99.9} assert file_obs.extensions["ntfs-ext"].sid == "S-1-whatever" assert file_obs.extensions["raster-image-ext"].image_height == 1024 diff --git a/stix2/utils.py b/stix2/utils.py index b23b0e4..7b3b6cf 100644 --- a/stix2/utils.py +++ b/stix2/utils.py @@ -26,6 +26,7 @@ NOW = object() STIX_UNMOD_PROPERTIES = ['created', 'created_by_ref', 'id', 'type'] TYPE_REGEX = r'^\-?[a-z0-9]+(-[a-z0-9]+)*\-?$' +SCO21_EXT_REGEX = r'^\-?[a-z0-9]+(-[a-z0-9]+)*\-ext$' class STIXdatetime(dt.datetime): From 371bf0b9a445ee9d09308d1685bdd6f5aacb3b46 Mon Sep 17 00:00:00 2001 From: Michael Chisholm Date: Tue, 10 Mar 2020 21:21:53 -0400 Subject: [PATCH 2/3] Add trailing commas for git commit hook... --- stix2/core.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stix2/core.py b/stix2/core.py index c4d7628..b03e3d7 100644 --- a/stix2/core.py +++ b/stix2/core.py @@ -259,7 +259,7 @@ def _register_observable(new_observable, version=None): def _register_observable_extension( - observable, new_extension, version=stix2.DEFAULT_VERSION + observable, new_extension, version=stix2.DEFAULT_VERSION, ): """Register a custom extension to a STIX Cyber Observable type. From 15316e79333578285b7df9116bbaffacb33f01ae Mon Sep 17 00:00:00 2001 From: Michael Chisholm Date: Thu, 12 Mar 2020 16:20:32 -0400 Subject: [PATCH 3/3] Added "x-" to SCO extension names in unit tests, to illustrate best practice and follow a spec "should" rule. --- stix2/test/v21/test_custom.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/stix2/test/v21/test_custom.py b/stix2/test/v21/test_custom.py index 8b1a38c..1e6f629 100644 --- a/stix2/test/v21/test_custom.py +++ b/stix2/test/v21/test_custom.py @@ -800,7 +800,7 @@ def test_custom_extension_wrong_observable_type(): ) def test_custom_extension_with_list_and_dict_properties_observable_type(data): @stix2.v21.CustomExtension( - stix2.v21.UserAccount, 'some-extension-ext', [ + stix2.v21.UserAccount, 'x-some-extension-ext', [ ('keys', stix2.properties.ListProperty(stix2.properties.DictionaryProperty, required=True)), ], ) @@ -946,14 +946,14 @@ def test_custom_and_spec_extension_mix(): file_obs = stix2.v21.File( name="my_file.dat", extensions={ - "custom1-ext": { + "x-custom1-ext": { "a": 1, "b": 2, }, "ntfs-ext": { "sid": "S-1-whatever", }, - "custom2-ext": { + "x-custom2-ext": { "z": 99.9, "y": False, }, @@ -966,8 +966,8 @@ def test_custom_and_spec_extension_mix(): allow_custom=True, ) - assert file_obs.extensions["custom1-ext"] == {"a": 1, "b": 2} - assert file_obs.extensions["custom2-ext"] == {"y": False, "z": 99.9} + assert file_obs.extensions["x-custom1-ext"] == {"a": 1, "b": 2} + assert file_obs.extensions["x-custom2-ext"] == {"y": False, "z": 99.9} assert file_obs.extensions["ntfs-ext"].sid == "S-1-whatever" assert file_obs.extensions["raster-image-ext"].image_height == 1024