New API Objects Support

.travis.yml

@@ -1,5 +1,4 @@
 language: python
-sudo: false   # Since this is an older project, this is not the default.
 cache: pip
 dist: xenial
 python:
@@ -8,6 +7,7 @@ python:
   - "3.5"
   - "3.6"
   - "3.7"
+  - "3.8"
 install:
   - pip install -U pip setuptools
   - pip install tox-travis

cybox/__init__.py

@@ -1,13 +1,130 @@
-# Copyright (c) 2017, The MITRE Corporation. All rights reserved.
+# Copyright (c) 2020, The MITRE Corporation. All rights reserved.
 # See LICENSE.txt for complete terms.
 
 from mixbox import entities
 from mixbox.vendor import six
 
 from .version import __version__  # noqa
 
+#: Mapping of xsi:types to implementation/extension classes
+_EXTENSION_MAP = {}
 
-#TODO: Should this get moved to mixbox or not?
+
+def _lookup_unprefixed(typename):
+    """Attempts to resolve a class for the input XML type `typename`.
+
+    Args:
+        typename: The name of an CybOX XML type (e.g., UnixProcessStatusType)
+            without a namespace prefix.
+
+    Returns:
+        A stix.Entity implementation class for the `typename`.
+
+
+    Raises:
+        ValueError: If no class has been registered for the input `typename`.
+
+    """
+    for xsi_type, klass in six.iteritems(_EXTENSION_MAP):
+        if typename in xsi_type:
+            return klass
+
+    error = "Unregistered extension type: %s" % typename
+    raise ValueError(error)
+
+
+def _lookup_extension(xsi_type):
+    """Returns a Python class for the `xsi_type` value.
+
+    Args:
+        xsi_type: An xsi:type value string.
+
+    Returns:
+        An Entity implementation class for the `xsi_type`.
+
+    Raises:
+        ValueError: If no class has been registered for the `xsi_type`.
+
+    """
+    if xsi_type in _EXTENSION_MAP:
+        return _EXTENSION_MAP[xsi_type]
+
+    raise ValueError("Unregistered xsi:type %s" % xsi_type)
+
+
+def lookup_extension(typeinfo, default=None):
+    """Returns an Entity class for that has been registered for the
+    `typeinfo` value.
+
+    Note:
+        This is for internal use only.
+
+    Args:
+        typeinfo: An object or string containing type information. This can be
+            either an xsi:type attribute value or a stix.bindings object.
+        default: Return class if typeinfo is None or contains no xml type
+            information.
+
+    Returns:
+        An Entity implementation class for the `xsi_type`.
+
+    Raises:
+        ValueError: If no class has been registered for the `xsi_type`.
+
+    """
+    if typeinfo is None and default:
+        return default
+
+    # If the `typeinfo` was a string, consider it a  full xsi:type value.
+    if isinstance(typeinfo, six.string_types):
+        return _lookup_extension(typeinfo)
+
+    # Most extension bindings include this attribute.
+    if not hasattr(typeinfo, 'xml_type'):
+        if default:
+            return default
+
+        error = "Input %s is missing xml_type attribute. Cannot lookup class."
+        raise ValueError(error % type(typeinfo))
+
+    # Extension binding classes usually (always?) have an `xmlns_prefix`
+    # class attribute.
+    if hasattr(typeinfo, 'xmlns_prefix'):
+        xsi_type = "%s:%s" % (typeinfo.xmlns_prefix, typeinfo.xml_type)
+        return _lookup_extension(xsi_type)
+
+    # no xmlns_prefix found, try to resolve the class by just the `xml_type`
+    return _lookup_unprefixed(typeinfo.xml_type)
+
+
+def add_extension(cls):
+    """Registers an Entity class as an implementation of an xml type.
+
+    Classes must have an ``_XSI_TYPE`` class attributes to be registered. The
+    value of this attribute must be a valid xsi:type.
+
+    Note:
+        This was designed for internal use.
+
+    """
+    _EXTENSION_MAP[cls._XSI_TYPE] = cls  # noqa
+
+
+def register_extension(cls):
+    """Class decorator for registering a stix.Entity class as an implementation
+    of an xml type.
+
+    Classes must have an ``_XSI_TYPE`` class attributes to be registered.
+
+    Note:
+        This was designed for internal use.
+
+    """
+    add_extension(cls)
+    return cls
+
+
+# TODO: Should this get moved to mixbox or not?
 class Unicode(entities.Entity):
     """Shim class to allow xs:string's in EntityList"""
 

cybox/bindings/__init__.py

@@ -0,0 +1,96 @@
+# Copyright (c) 2020, The MITRE Corporation. All rights reserved.
+# See LICENSE.txt for complete terms.
+
+import collections
+
+import mixbox.xml
+
+TypeInfo = collections.namedtuple("TypeInfo", ('ns', 'typename'))
+
+
+def get_type_info(node):
+    """Returns a ``TypeInfo`` object for `node`.
+
+    This is accomplished by parsing the ``xsi:type`` attribute found on
+    `node`.
+
+    Args:
+        node: An lxml.etree element object.
+
+    Raises:
+        KeyError: If `node` does not have an ``xsi:type`` attribute.
+
+    """
+    xsi_type = node.attrib[mixbox.xml.TAG_XSI_TYPE]
+    typeinfo = xsi_type.split(":")
+
+    if len(typeinfo) == 2:
+        prefix, typename = typeinfo
+    else:
+        typename = typeinfo
+        prefix = None
+
+    ns = node.nsmap[prefix]
+    return TypeInfo(ns=ns, typename=typename)
+
+
+#: A mapping of namespace/type information to binding classes.
+_BINDING_EXTENSION_MAP = {}
+
+
+def add_extension(cls):
+    """Adds the binding class `cls` to the ``_EXTENSION_MAP``.
+
+    This enables the lookup and instantiation of classes during parse when
+    ``xsi:type`` attributes are encountered.
+
+    """
+    typeinfo = TypeInfo(ns=cls.xmlns, typename=cls.xml_type)
+    _BINDING_EXTENSION_MAP[typeinfo] = cls
+
+
+def register_extension(cls):
+    """Class decorator for registering a binding class as an implementation of
+    an xml type.
+
+    Classes must have ``xmlns`` and ``xml_type`` class attributes to be
+    registered.
+
+    """
+    add_extension(cls)
+    return cls
+
+
+def lookup_extension(typeinfo, default=None):
+    """Looks up the binding class for `typeinfo`, which is a namespace/typename
+    pairing.
+
+    Args:
+        typeinfo: An lxml Element node or a stix.bindings.TypeInfo namedtuple.
+        default: A binding class that will be returned if typeinfo is an
+            Element without an xsi:type attribute.
+
+    Returns:
+        A binding class that has been registered for the namespace and typename
+        found on `typeinfo`.
+
+    """
+    if not isinstance(typeinfo, TypeInfo):
+        if has_xsi_type(typeinfo):
+            typeinfo = get_type_info(typeinfo)
+        elif default:
+            return default
+
+    if typeinfo in _BINDING_EXTENSION_MAP:
+        return _BINDING_EXTENSION_MAP[typeinfo]
+
+    fmt = "No class implemented or registered for XML type '{%s}%s'"
+    error = fmt % (typeinfo.ns, typeinfo.typename)
+    raise NotImplementedError(error)
+
+
+def has_xsi_type(node):
+    """Returns ``True`` if `node` does not have an xsi:type attribute.
+
+    """
+    return mixbox.xml.TAG_XSI_TYPE in node.attrib