serialization

STIX2 core serialization methods.

class STIXJSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=False, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=False, ignore_nan=False, int_as_string_bitcount=None, iterable_as_array=False)

Custom JSONEncoder subclass for serializing Python stix2 objects.

If an optional property with a default value specified in the STIX 2 spec is set to that default value, it will be left out of the serialized output.

An example of this type of property include the revoked common property.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    return JSONEncoder.default(self, o)

class STIXJSONIncludeOptionalDefaultsEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=False, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=False, ignore_nan=False, int_as_string_bitcount=None, iterable_as_array=False)

Custom JSONEncoder subclass for serializing Python stix2 objects.

Differs from STIXJSONEncoder in that if an optional property with a default value specified in the STIX 2 spec is set to that default value, it will be included in the serialized output.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    return JSONEncoder.default(self, o)

find_property_index(obj, search_key, search_value)

Search (recursively) for the given key and value in the given object. Return an index for the key, relative to whatever object it’s found in.

Parameters:

• obj – The object to search (list, dict, or stix object)
• search_key – A search key
• search_value – A search value

Returns:

int – An index; -1 if the key and value aren’t found

fp_serialize(obj, fp, pretty=False, include_optional_defaults=False, **kwargs)

Serialize a STIX object to fp (a text stream file-like supporting object).

Parameters:

• obj – The STIX object to be serialized.
• fp – A text stream file-like object supporting .write().
• pretty (bool) – If True, output properties following the STIX specs formatting. This includes indentation. Refer to notes for more details. (Default: False)
• include_optional_defaults (bool) – Determines whether to include optional properties set to the default value defined in the spec.
• **kwargs – The arguments for a json.dumps() call.

Returns:

None

Note

The argument pretty=True will output the STIX object following spec order. Using this argument greatly impacts object serialization performance. If your use case is centered across machine-to-machine operation it is recommended to set pretty=False.

When pretty=True the following key-value pairs will be added or overridden: indent=4, separators=(“,”, “: “), item_sort_key=sort_by.

serialize(obj, pretty=False, include_optional_defaults=False, **kwargs)

Serialize a STIX object.

Parameters:

• obj – The STIX object to be serialized.
• pretty (bool) – If True, output properties following the STIX specs formatting. This includes indentation. Refer to notes for more details. (Default: False)
• include_optional_defaults (bool) – Determines whether to include optional properties set to the default value defined in the spec.
• **kwargs – The arguments for a json.dumps() call.

Returns:

str – The serialized JSON object.

Note

The argument pretty=True will output the STIX object following spec order. Using this argument greatly impacts object serialization performance. If your use case is centered across machine-to-machine operation it is recommended to set pretty=False.

When pretty=True the following key-value pairs will be added or overridden: indent=4, separators=(“,”, “: “), item_sort_key=sort_by.