826 lines
29 KiB
Python
826 lines
29 KiB
Python
"""STIX 2.0 Cyber Observable Objects
|
|
|
|
Embedded observable object types, such as Email MIME Component, which is
|
|
embedded in Email Message objects, inherit from _STIXBase instead of Observable
|
|
and do not have a '_type' attribute.
|
|
"""
|
|
|
|
from .base import _Extension, _Observable, _STIXBase
|
|
from .exceptions import (AtLeastOnePropertyError, DependentPropertiesError,
|
|
ParseError)
|
|
from .properties import (BinaryProperty, BooleanProperty, DictionaryProperty,
|
|
EmbeddedObjectProperty, EnumProperty, FloatProperty,
|
|
HashesProperty, HexProperty, IntegerProperty,
|
|
ListProperty, ObjectReferenceProperty, Property,
|
|
StringProperty, TimestampProperty, TypeProperty)
|
|
from .utils import get_dict
|
|
|
|
|
|
class ObservableProperty(Property):
|
|
|
|
def clean(self, value):
|
|
try:
|
|
dictified = get_dict(value)
|
|
except ValueError:
|
|
raise ValueError("The observable property must contain a dictionary")
|
|
if dictified == {}:
|
|
raise ValueError("The observable property must contain a non-empty dictionary")
|
|
|
|
valid_refs = dict((k, v['type']) for (k, v) in dictified.items())
|
|
|
|
# from .__init__ import parse_observable # avoid circular import
|
|
for key, obj in dictified.items():
|
|
parsed_obj = parse_observable(obj, valid_refs)
|
|
dictified[key] = parsed_obj
|
|
|
|
return dictified
|
|
|
|
|
|
class ExtensionsProperty(DictionaryProperty):
|
|
""" Property for representing extensions on Observable objects
|
|
"""
|
|
|
|
def __init__(self, enclosing_type=None, required=False):
|
|
self.enclosing_type = enclosing_type
|
|
super(ExtensionsProperty, self).__init__(required)
|
|
|
|
def clean(self, value):
|
|
try:
|
|
dictified = get_dict(value)
|
|
except ValueError:
|
|
raise ValueError("The extensions property must contain a dictionary")
|
|
if dictified == {}:
|
|
raise ValueError("The extensions property must contain a non-empty dictionary")
|
|
|
|
if self.enclosing_type in EXT_MAP:
|
|
specific_type_map = EXT_MAP[self.enclosing_type]
|
|
for key, subvalue in dictified.items():
|
|
if key in specific_type_map:
|
|
cls = specific_type_map[key]
|
|
if type(subvalue) is dict:
|
|
dictified[key] = cls(**subvalue)
|
|
elif type(subvalue) is cls:
|
|
dictified[key] = subvalue
|
|
else:
|
|
raise ValueError("Cannot determine extension type.")
|
|
else:
|
|
raise ValueError("The key used in the extensions dictionary is not an extension type name")
|
|
else:
|
|
raise ValueError("The enclosing type '%s' has no extensions defined" % self.enclosing_type)
|
|
return dictified
|
|
|
|
|
|
class Artifact(_Observable):
|
|
_type = 'artifact'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'mime_type': StringProperty(),
|
|
'payload_bin': BinaryProperty(),
|
|
'url': StringProperty(),
|
|
'hashes': HashesProperty(),
|
|
}
|
|
|
|
def _check_object_constraints(self):
|
|
super(Artifact, self)._check_object_constraints()
|
|
self._check_mutually_exclusive_properties(["payload_bin", "url"])
|
|
self._check_properties_dependency(["hashes"], ["url"])
|
|
|
|
|
|
class AutonomousSystem(_Observable):
|
|
_type = 'autonomous-system'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'number': IntegerProperty(),
|
|
'name': StringProperty(),
|
|
'rir': StringProperty(),
|
|
}
|
|
|
|
|
|
class Directory(_Observable):
|
|
_type = 'directory'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'path': StringProperty(required=True),
|
|
'path_enc': StringProperty(),
|
|
# these are not the created/modified timestamps of the object itself
|
|
'created': TimestampProperty(),
|
|
'modified': TimestampProperty(),
|
|
'accessed': TimestampProperty(),
|
|
'contains_refs': ListProperty(ObjectReferenceProperty(valid_types=['file', 'directory'])),
|
|
}
|
|
|
|
|
|
class DomainName(_Observable):
|
|
_type = 'domain-name'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'value': StringProperty(required=True),
|
|
'resolves_to_refs': ListProperty(ObjectReferenceProperty(valid_types=['ipv4-addr', 'ipv6-addr', 'domain-name'])),
|
|
}
|
|
|
|
|
|
class EmailAddress(_Observable):
|
|
_type = 'email-addr'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'value': StringProperty(required=True),
|
|
'display_name': StringProperty(),
|
|
'belongs_to_ref': ObjectReferenceProperty(valid_types='user-account'),
|
|
}
|
|
|
|
|
|
class EmailMIMEComponent(_STIXBase):
|
|
_properties = {
|
|
'body': StringProperty(),
|
|
'body_raw_ref': ObjectReferenceProperty(valid_types=['artifact', 'file']),
|
|
'content_type': StringProperty(),
|
|
'content_disposition': StringProperty(),
|
|
}
|
|
|
|
def _check_object_constraints(self):
|
|
super(EmailMIMEComponent, self)._check_object_constraints()
|
|
self._check_at_least_one_property(["body", "body_raw_ref"])
|
|
|
|
|
|
class EmailMessage(_Observable):
|
|
_type = 'email-message'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'is_multipart': BooleanProperty(required=True),
|
|
'date': TimestampProperty(),
|
|
'content_type': StringProperty(),
|
|
'from_ref': ObjectReferenceProperty(valid_types='email-addr'),
|
|
'sender_ref': ObjectReferenceProperty(valid_types='email-addr'),
|
|
'to_refs': ListProperty(ObjectReferenceProperty(valid_types='email-addr')),
|
|
'cc_refs': ListProperty(ObjectReferenceProperty(valid_types='email-addr')),
|
|
'bcc_refs': ListProperty(ObjectReferenceProperty(valid_types='email-addr')),
|
|
'subject': StringProperty(),
|
|
'received_lines': ListProperty(StringProperty),
|
|
'additional_header_fields': DictionaryProperty(),
|
|
'body': StringProperty(),
|
|
'body_multipart': ListProperty(EmbeddedObjectProperty(type=EmailMIMEComponent)),
|
|
'raw_email_ref': ObjectReferenceProperty(valid_types='artifact'),
|
|
}
|
|
|
|
def _check_object_constraints(self):
|
|
super(EmailMessage, self)._check_object_constraints()
|
|
self._check_properties_dependency(["is_multipart"], ["body_multipart"])
|
|
if self.get("is_multipart") is True and self.get("body"):
|
|
# 'body' MAY only be used if is_multipart is false.
|
|
raise DependentPropertiesError(self.__class__, [("is_multipart", "body")])
|
|
|
|
|
|
class ArchiveExt(_Extension):
|
|
_type = 'archive-ext'
|
|
_properties = {
|
|
'contains_refs': ListProperty(ObjectReferenceProperty(valid_types='file'), required=True),
|
|
'version': StringProperty(),
|
|
'comment': StringProperty(),
|
|
}
|
|
|
|
|
|
class AlternateDataStream(_STIXBase):
|
|
_properties = {
|
|
'name': StringProperty(required=True),
|
|
'hashes': HashesProperty(),
|
|
'size': IntegerProperty(),
|
|
}
|
|
|
|
|
|
class NTFSExt(_Extension):
|
|
_type = 'ntfs-ext'
|
|
_properties = {
|
|
'sid': StringProperty(),
|
|
'alternate_data_streams': ListProperty(EmbeddedObjectProperty(type=AlternateDataStream)),
|
|
}
|
|
|
|
|
|
class PDFExt(_Extension):
|
|
_type = 'pdf-ext'
|
|
_properties = {
|
|
'version': StringProperty(),
|
|
'is_optimized': BooleanProperty(),
|
|
'document_info_dict': DictionaryProperty(),
|
|
'pdfid0': StringProperty(),
|
|
'pdfid1': StringProperty(),
|
|
}
|
|
|
|
|
|
class RasterImageExt(_Extension):
|
|
_type = 'raster-image-ext'
|
|
_properties = {
|
|
'image_height': IntegerProperty(),
|
|
'image_weight': IntegerProperty(),
|
|
'bits_per_pixel': IntegerProperty(),
|
|
'image_compression_algorithm': StringProperty(),
|
|
'exif_tags': DictionaryProperty(),
|
|
}
|
|
|
|
|
|
class WindowsPEOptionalHeaderType(_STIXBase):
|
|
_properties = {
|
|
'magic_hex': HexProperty(),
|
|
'major_linker_version': IntegerProperty(),
|
|
'minor_linker_version': IntegerProperty(),
|
|
'size_of_code': IntegerProperty(),
|
|
'size_of_initialized_data': IntegerProperty(),
|
|
'size_of_uninitialized_data': IntegerProperty(),
|
|
'address_of_entry_point': IntegerProperty(),
|
|
'base_of_code': IntegerProperty(),
|
|
'base_of_data': IntegerProperty(),
|
|
'image_base': IntegerProperty(),
|
|
'section_alignment': IntegerProperty(),
|
|
'file_alignment': IntegerProperty(),
|
|
'major_os_version': IntegerProperty(),
|
|
'minor_os_version': IntegerProperty(),
|
|
'major_image_version': IntegerProperty(),
|
|
'minor_image_version': IntegerProperty(),
|
|
'major_subsystem_version': IntegerProperty(),
|
|
'minor_subsystem_version': IntegerProperty(),
|
|
'win32_version_value_hex': HexProperty(),
|
|
'size_of_image': IntegerProperty(),
|
|
'size_of_headers': IntegerProperty(),
|
|
'checksum_hex': HexProperty(),
|
|
'subsystem_hex': HexProperty(),
|
|
'dll_characteristics_hex': HexProperty(),
|
|
'size_of_stack_reserve': IntegerProperty(),
|
|
'size_of_stack_commit': IntegerProperty(),
|
|
'size_of_heap_reserve': IntegerProperty(),
|
|
'size_of_heap_commit': IntegerProperty(),
|
|
'loader_flags_hex': HexProperty(),
|
|
'number_of_rva_and_sizes': IntegerProperty(),
|
|
'hashes': HashesProperty(),
|
|
}
|
|
|
|
def _check_object_constraints(self):
|
|
super(WindowsPEOptionalHeaderType, self)._check_object_constraints()
|
|
self._check_at_least_one_property()
|
|
|
|
|
|
class WindowsPESection(_STIXBase):
|
|
_properties = {
|
|
'name': StringProperty(required=True),
|
|
'size': IntegerProperty(),
|
|
'entropy': FloatProperty(),
|
|
'hashes': HashesProperty(),
|
|
}
|
|
|
|
|
|
class WindowsPEBinaryExt(_Extension):
|
|
_type = 'windows-pebinary-ext'
|
|
_properties = {
|
|
'pe_type': StringProperty(required=True), # open_vocab
|
|
'imphash': StringProperty(),
|
|
'machine_hex': HexProperty(),
|
|
'number_of_sections': IntegerProperty(),
|
|
'time_date_stamp': TimestampProperty(precision='second'),
|
|
'pointer_to_symbol_table_hex': HexProperty(),
|
|
'number_of_symbols': IntegerProperty(),
|
|
'size_of_optional_header': IntegerProperty(),
|
|
'characteristics_hex': HexProperty(),
|
|
'file_header_hashes': HashesProperty(),
|
|
'optional_header': EmbeddedObjectProperty(type=WindowsPEOptionalHeaderType),
|
|
'sections': ListProperty(EmbeddedObjectProperty(type=WindowsPESection)),
|
|
}
|
|
|
|
|
|
class File(_Observable):
|
|
_type = 'file'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'hashes': HashesProperty(),
|
|
'size': IntegerProperty(),
|
|
'name': StringProperty(),
|
|
'name_enc': StringProperty(),
|
|
'magic_number_hex': HexProperty(),
|
|
'mime_type': StringProperty(),
|
|
# these are not the created/modified timestamps of the object itself
|
|
'created': TimestampProperty(),
|
|
'modified': TimestampProperty(),
|
|
'accessed': TimestampProperty(),
|
|
'parent_directory_ref': ObjectReferenceProperty(valid_types='directory'),
|
|
'is_encrypted': BooleanProperty(),
|
|
'encryption_algorithm': StringProperty(),
|
|
'decryption_key': StringProperty(),
|
|
'contains_refs': ListProperty(ObjectReferenceProperty),
|
|
'content_ref': ObjectReferenceProperty(valid_types='artifact'),
|
|
}
|
|
|
|
def _check_object_constraints(self):
|
|
super(File, self)._check_object_constraints()
|
|
self._check_properties_dependency(["is_encrypted"], ["encryption_algorithm", "decryption_key"])
|
|
self._check_at_least_one_property(["hashes", "name"])
|
|
|
|
|
|
class IPv4Address(_Observable):
|
|
_type = 'ipv4-addr'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'value': StringProperty(required=True),
|
|
'resolves_to_refs': ListProperty(ObjectReferenceProperty(valid_types='mac-addr')),
|
|
'belongs_to_refs': ListProperty(ObjectReferenceProperty(valid_types='autonomous-system')),
|
|
}
|
|
|
|
|
|
class IPv6Address(_Observable):
|
|
_type = 'ipv6-addr'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'value': StringProperty(required=True),
|
|
'resolves_to_refs': ListProperty(ObjectReferenceProperty(valid_types='mac-addr')),
|
|
'belongs_to_refs': ListProperty(ObjectReferenceProperty(valid_types='autonomous-system')),
|
|
}
|
|
|
|
|
|
class MACAddress(_Observable):
|
|
_type = 'mac-addr'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'value': StringProperty(required=True),
|
|
}
|
|
|
|
|
|
class Mutex(_Observable):
|
|
_type = 'mutex'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'name': StringProperty(),
|
|
}
|
|
|
|
|
|
class HTTPRequestExt(_Extension):
|
|
_type = 'http-request-ext'
|
|
_properties = {
|
|
'request_method': StringProperty(required=True),
|
|
'request_value': StringProperty(required=True),
|
|
'request_version': StringProperty(),
|
|
'request_header': DictionaryProperty(),
|
|
'message_body_length': IntegerProperty(),
|
|
'message_body_data_ref': ObjectReferenceProperty(valid_types='artifact'),
|
|
}
|
|
|
|
|
|
class ICMPExt(_Extension):
|
|
_type = 'icmp-ext'
|
|
_properties = {
|
|
'icmp_type_hex': HexProperty(required=True),
|
|
'icmp_code_hex': HexProperty(required=True),
|
|
}
|
|
|
|
|
|
class SocketExt(_Extension):
|
|
_type = 'socket-ext'
|
|
_properties = {
|
|
'address_family': EnumProperty([
|
|
"AF_UNSPEC",
|
|
"AF_INET",
|
|
"AF_IPX",
|
|
"AF_APPLETALK",
|
|
"AF_NETBIOS",
|
|
"AF_INET6",
|
|
"AF_IRDA",
|
|
"AF_BTH",
|
|
], required=True),
|
|
'is_blocking': BooleanProperty(),
|
|
'is_listening': BooleanProperty(),
|
|
'protocol_family': EnumProperty([
|
|
"PF_INET",
|
|
"PF_IPX",
|
|
"PF_APPLETALK",
|
|
"PF_INET6",
|
|
"PF_AX25",
|
|
"PF_NETROM"
|
|
]),
|
|
'options': DictionaryProperty(),
|
|
'socket_type': EnumProperty([
|
|
"SOCK_STREAM",
|
|
"SOCK_DGRAM",
|
|
"SOCK_RAW",
|
|
"SOCK_RDM",
|
|
"SOCK_SEQPACKET",
|
|
]),
|
|
}
|
|
|
|
|
|
class TCPExt(_Extension):
|
|
_type = 'tcp-ext'
|
|
_properties = {
|
|
'src_flags_hex': HexProperty(),
|
|
'dst_flags_hex': HexProperty(),
|
|
}
|
|
|
|
|
|
class NetworkTraffic(_Observable):
|
|
_type = 'network-traffic'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'start': TimestampProperty(),
|
|
'end': TimestampProperty(),
|
|
'is_active': BooleanProperty(),
|
|
'src_ref': ObjectReferenceProperty(valid_types=['ipv4-addr', 'ipv6-addr', 'mac-addr', 'domain-name']),
|
|
'dst_ref': ObjectReferenceProperty(valid_types=['ipv4-addr', 'ipv6-addr', 'mac-addr', 'domain-name']),
|
|
'src_port': IntegerProperty(),
|
|
'dst_port': IntegerProperty(),
|
|
'protocols': ListProperty(StringProperty, required=True),
|
|
'src_byte_count': IntegerProperty(),
|
|
'dst_byte_count': IntegerProperty(),
|
|
'src_packets': IntegerProperty(),
|
|
'dst_packets': IntegerProperty(),
|
|
'ipfix': DictionaryProperty(),
|
|
'src_payload_ref': ObjectReferenceProperty(valid_types='artifact'),
|
|
'dst_payload_ref': ObjectReferenceProperty(valid_types='artifact'),
|
|
'encapsulates_refs': ListProperty(ObjectReferenceProperty(valid_types='network-traffic')),
|
|
'encapsulates_by_ref': ObjectReferenceProperty(valid_types='network-traffic'),
|
|
}
|
|
|
|
def _check_object_constraints(self):
|
|
super(NetworkTraffic, self)._check_object_constraints()
|
|
self._check_at_least_one_property(["src_ref", "dst_ref"])
|
|
|
|
|
|
class WindowsProcessExt(_Extension):
|
|
_type = 'windows-process-ext'
|
|
_properties = {
|
|
'aslr_enabled': BooleanProperty(),
|
|
'dep_enabled': BooleanProperty(),
|
|
'priority': StringProperty(),
|
|
'owner_sid': StringProperty(),
|
|
'window_title': StringProperty(),
|
|
'startup_info': DictionaryProperty(),
|
|
}
|
|
|
|
|
|
class WindowsServiceExt(_Extension):
|
|
_type = 'windows-service-ext'
|
|
_properties = {
|
|
'service_name': StringProperty(required=True),
|
|
'descriptions': ListProperty(StringProperty),
|
|
'display_name': StringProperty(),
|
|
'group_name': StringProperty(),
|
|
'start_type': EnumProperty([
|
|
"SERVICE_AUTO_START",
|
|
"SERVICE_BOOT_START",
|
|
"SERVICE_DEMAND_START",
|
|
"SERVICE_DISABLED",
|
|
"SERVICE_SYSTEM_ALERT",
|
|
]),
|
|
'service_dll_refs': ListProperty(ObjectReferenceProperty(valid_types='file')),
|
|
'service_type': EnumProperty([
|
|
"SERVICE_KERNEL_DRIVER",
|
|
"SERVICE_FILE_SYSTEM_DRIVER",
|
|
"SERVICE_WIN32_OWN_PROCESS",
|
|
"SERVICE_WIN32_SHARE_PROCESS",
|
|
]),
|
|
'service_status': EnumProperty([
|
|
"SERVICE_CONTINUE_PENDING",
|
|
"SERVICE_PAUSE_PENDING",
|
|
"SERVICE_PAUSED",
|
|
"SERVICE_RUNNING",
|
|
"SERVICE_START_PENDING",
|
|
"SERVICE_STOP_PENDING",
|
|
"SERVICE_STOPPED",
|
|
]),
|
|
}
|
|
|
|
|
|
class Process(_Observable):
|
|
_type = 'process'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'is_hidden': BooleanProperty(),
|
|
'pid': IntegerProperty(),
|
|
'name': StringProperty(),
|
|
# this is not the created timestamps of the object itself
|
|
'created': TimestampProperty(),
|
|
'cwd': StringProperty(),
|
|
'arguments': ListProperty(StringProperty),
|
|
'command_line': StringProperty(),
|
|
'environment_variables': DictionaryProperty(),
|
|
'opened_connection_refs': ListProperty(ObjectReferenceProperty(valid_types='network-traffic')),
|
|
'creator_user_ref': ObjectReferenceProperty(valid_types='user-account'),
|
|
'binary_ref': ObjectReferenceProperty(valid_types='file'),
|
|
'parent_ref': ObjectReferenceProperty(valid_types='process'),
|
|
'child_refs': ListProperty(ObjectReferenceProperty('process')),
|
|
}
|
|
|
|
def _check_object_constraints(self):
|
|
# no need to check windows-service-ext, since it has a required property
|
|
super(Process, self)._check_object_constraints()
|
|
try:
|
|
self._check_at_least_one_property()
|
|
if "windows-process-ext" in self.get('extensions', {}):
|
|
self.extensions["windows-process-ext"]._check_at_least_one_property()
|
|
except AtLeastOnePropertyError as enclosing_exc:
|
|
if 'extensions' not in self:
|
|
raise enclosing_exc
|
|
else:
|
|
if "windows-process-ext" in self.get('extensions', {}):
|
|
self.extensions["windows-process-ext"]._check_at_least_one_property()
|
|
|
|
|
|
class Software(_Observable):
|
|
_type = 'software'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'name': StringProperty(required=True),
|
|
'cpe': StringProperty(),
|
|
'languages': ListProperty(StringProperty),
|
|
'vendor': StringProperty(),
|
|
'version': StringProperty(),
|
|
}
|
|
|
|
|
|
class URL(_Observable):
|
|
_type = 'url'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'value': StringProperty(required=True),
|
|
}
|
|
|
|
|
|
class UNIXAccountExt(_Extension):
|
|
_type = 'unix-account-ext'
|
|
_properties = {
|
|
'gid': IntegerProperty(),
|
|
'groups': ListProperty(StringProperty),
|
|
'home_dir': StringProperty(),
|
|
'shell': StringProperty(),
|
|
}
|
|
|
|
|
|
class UserAccount(_Observable):
|
|
_type = 'user-account'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'user_id': StringProperty(required=True),
|
|
'account_login': StringProperty(),
|
|
'account_type': StringProperty(), # open vocab
|
|
'display_name': StringProperty(),
|
|
'is_service_account': BooleanProperty(),
|
|
'is_privileged': BooleanProperty(),
|
|
'can_escalate_privs': BooleanProperty(),
|
|
'is_disabled': BooleanProperty(),
|
|
'account_created': TimestampProperty(),
|
|
'account_expires': TimestampProperty(),
|
|
'password_last_changed': TimestampProperty(),
|
|
'account_first_login': TimestampProperty(),
|
|
'account_last_login': TimestampProperty(),
|
|
}
|
|
|
|
|
|
class WindowsRegistryValueType(_STIXBase):
|
|
_type = 'windows-registry-value-type'
|
|
_properties = {
|
|
'name': StringProperty(required=True),
|
|
'data': StringProperty(),
|
|
'data_type': EnumProperty([
|
|
'REG_NONE',
|
|
'REG_SZ',
|
|
'REG_EXPAND_SZ',
|
|
'REG_BINARY',
|
|
'REG_DWORD',
|
|
'REG_DWORD_BIG_ENDIAN',
|
|
'REG_LINK',
|
|
'REG_MULTI_SZ',
|
|
'REG_RESOURCE_LIST',
|
|
'REG_FULL_RESOURCE_DESCRIPTION',
|
|
'REG_RESOURCE_REQUIREMENTS_LIST',
|
|
'REG_QWORD',
|
|
'REG_INVALID_TYPE',
|
|
]),
|
|
}
|
|
|
|
|
|
class WindowsRegistryKey(_Observable):
|
|
_type = 'windows-registry-key'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'key': StringProperty(required=True),
|
|
'values': ListProperty(EmbeddedObjectProperty(type=WindowsRegistryValueType)),
|
|
# this is not the modified timestamps of the object itself
|
|
'modified': TimestampProperty(),
|
|
'creator_user_ref': ObjectReferenceProperty(valid_types='user-account'),
|
|
'number_of_subkeys': IntegerProperty(),
|
|
}
|
|
|
|
@property
|
|
def values(self):
|
|
# Needed because 'values' is a property on collections.Mapping objects
|
|
return self._inner['values']
|
|
|
|
|
|
class X509V3ExtenstionsType(_STIXBase):
|
|
_type = 'x509-v3-extensions-type'
|
|
_properties = {
|
|
'basic_constraints': StringProperty(),
|
|
'name_constraints': StringProperty(),
|
|
'policy_constraints': StringProperty(),
|
|
'key_usage': StringProperty(),
|
|
'extended_key_usage': StringProperty(),
|
|
'subject_key_identifier': StringProperty(),
|
|
'authority_key_identifier': StringProperty(),
|
|
'subject_alternative_name': StringProperty(),
|
|
'issuer_alternative_name': StringProperty(),
|
|
'subject_directory_attributes': StringProperty(),
|
|
'crl_distribution_points': StringProperty(),
|
|
'inhibit_any_policy': StringProperty(),
|
|
'private_key_usage_period_not_before': TimestampProperty(),
|
|
'private_key_usage_period_not_after': TimestampProperty(),
|
|
'certificate_policies': StringProperty(),
|
|
'policy_mappings': StringProperty(),
|
|
}
|
|
|
|
|
|
class X509Certificate(_Observable):
|
|
_type = 'x509-certificate'
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
'is_self_signed': BooleanProperty(),
|
|
'hashes': HashesProperty(),
|
|
'version': StringProperty(),
|
|
'serial_number': StringProperty(),
|
|
'signature_algorithm': StringProperty(),
|
|
'issuer': StringProperty(),
|
|
'validity_not_before': TimestampProperty(),
|
|
'validity_not_after': TimestampProperty(),
|
|
'subject': StringProperty(),
|
|
'subject_public_key_algorithm': StringProperty(),
|
|
'subject_public_key_modulus': StringProperty(),
|
|
'subject_public_key_exponent': IntegerProperty(),
|
|
'x509_v3_extensions': EmbeddedObjectProperty(type=X509V3ExtenstionsType),
|
|
}
|
|
|
|
|
|
OBJ_MAP_OBSERVABLE = {
|
|
'artifact': Artifact,
|
|
'autonomous-system': AutonomousSystem,
|
|
'directory': Directory,
|
|
'domain-name': DomainName,
|
|
'email-addr': EmailAddress,
|
|
'email-message': EmailMessage,
|
|
'file': File,
|
|
'ipv4-addr': IPv4Address,
|
|
'ipv6-addr': IPv6Address,
|
|
'mac-addr': MACAddress,
|
|
'mutex': Mutex,
|
|
'network-traffic': NetworkTraffic,
|
|
'process': Process,
|
|
'software': Software,
|
|
'url': URL,
|
|
'user-account': UserAccount,
|
|
'windows-registry-key': WindowsRegistryKey,
|
|
'x509-certificate': X509Certificate,
|
|
}
|
|
|
|
|
|
EXT_MAP = {
|
|
'file': {
|
|
'archive-ext': ArchiveExt,
|
|
'ntfs-ext': NTFSExt,
|
|
'pdf-ext': PDFExt,
|
|
'raster-image-ext': RasterImageExt,
|
|
'windows-pebinary-ext': WindowsPEBinaryExt
|
|
},
|
|
'network-traffic': {
|
|
'http-request-ext': HTTPRequestExt,
|
|
'icmp-ext': ICMPExt,
|
|
'socket-ext': SocketExt,
|
|
'tcp-ext': TCPExt,
|
|
},
|
|
'process': {
|
|
'windows-process-ext': WindowsProcessExt,
|
|
'windows-service-ext': WindowsServiceExt,
|
|
},
|
|
'user-account': {
|
|
'unix-account-ext': UNIXAccountExt,
|
|
},
|
|
}
|
|
|
|
|
|
def parse_observable(data, _valid_refs=[], allow_custom=False):
|
|
"""Deserialize a string or file-like object into a STIX Cyber Observable object.
|
|
|
|
Args:
|
|
data: The STIX 2 string to be parsed.
|
|
_valid_refs: A list of object references valid for the scope of the object being parsed.
|
|
allow_custom: Whether to allow custom properties or not. Default: False.
|
|
|
|
Returns:
|
|
An instantiated Python STIX Cyber Observable object.
|
|
"""
|
|
|
|
obj = get_dict(data)
|
|
obj['_valid_refs'] = _valid_refs
|
|
|
|
if 'type' not in obj:
|
|
raise ParseError("Can't parse observable with no 'type' property: %s" % str(obj))
|
|
try:
|
|
obj_class = OBJ_MAP_OBSERVABLE[obj['type']]
|
|
except KeyError:
|
|
raise ParseError("Can't parse unknown observable type '%s'! For custom observables, "
|
|
"use the CustomObservable decorator." % obj['type'])
|
|
|
|
if 'extensions' in obj and obj['type'] in EXT_MAP:
|
|
for name, ext in obj['extensions'].items():
|
|
if name not in EXT_MAP[obj['type']]:
|
|
raise ParseError("Can't parse Unknown extension type '%s' for observable type '%s'!" % (name, obj['type']))
|
|
ext_class = EXT_MAP[obj['type']][name]
|
|
obj['extensions'][name] = ext_class(allow_custom=allow_custom, **obj['extensions'][name])
|
|
|
|
return obj_class(allow_custom=allow_custom, **obj)
|
|
|
|
|
|
def _register_observable(new_observable):
|
|
"""Register a custom STIX Cyber Observable type.
|
|
"""
|
|
|
|
OBJ_MAP_OBSERVABLE[new_observable._type] = new_observable
|
|
|
|
|
|
def CustomObservable(type='x-custom-observable', properties={}):
|
|
"""Custom STIX Cyber Observable type decorator
|
|
"""
|
|
|
|
def custom_builder(cls):
|
|
|
|
class _Custom(cls, _Observable):
|
|
_type = type
|
|
_properties = {
|
|
'type': TypeProperty(_type),
|
|
}
|
|
_properties.update(properties)
|
|
|
|
def __init__(self, **kwargs):
|
|
_Observable.__init__(self, **kwargs)
|
|
cls.__init__(self, **kwargs)
|
|
|
|
_register_observable(_Custom)
|
|
return _Custom
|
|
|
|
return custom_builder
|
|
|
|
|
|
def _register_extension(observable, new_extension):
|
|
"""Register a custom extension to a STIX Cyber Observable type.
|
|
"""
|
|
|
|
try:
|
|
observable_type = observable._type
|
|
except AttributeError:
|
|
raise ValueError("Unknown observable type. Custom observables must be "
|
|
"created with the @CustomObservable decorator.")
|
|
|
|
try:
|
|
EXT_MAP[observable_type][new_extension._type] = new_extension
|
|
except KeyError:
|
|
if observable_type not in OBJ_MAP_OBSERVABLE:
|
|
raise ValueError("Unknown observable type '%s'. Custom observables "
|
|
"must be created with the @CustomObservable decorator."
|
|
% observable_type)
|
|
else:
|
|
EXT_MAP[observable_type] = {new_extension._type: new_extension}
|
|
|
|
|
|
def CustomExtension(observable=None, type='x-custom-observable', properties={}):
|
|
"""Decorator for custom extensions to STIX Cyber Observables
|
|
"""
|
|
|
|
if not observable or not issubclass(observable, _Observable):
|
|
raise ValueError("'observable' must be a valid Observable class!")
|
|
|
|
def custom_builder(cls):
|
|
|
|
class _Custom(cls, _Extension):
|
|
_type = type
|
|
_properties = {
|
|
'extensions': ExtensionsProperty(enclosing_type=_type),
|
|
}
|
|
_properties.update(properties)
|
|
|
|
def __init__(self, **kwargs):
|
|
_Extension.__init__(self, **kwargs)
|
|
cls.__init__(self, **kwargs)
|
|
|
|
_register_extension(observable, _Custom)
|
|
return _Custom
|
|
|
|
return custom_builder
|