MISP
/
cti-python-stix2
mirror of https://github.com/MISP/cti-python-stix2
2
0
Fork 0
Code Issues Releases Wiki Activity

Reformat methods documentation

stix2.1
Emmanuelle Vargas-Gonzalez 2018-06-25 10:06:07 -04:00
parent 0ddb7b3807
commit b852b91652
2 changed files with 48 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
stix2/core.py
View File

@ -25,12 +25,14 @@ def parse(data, allow_custom=False, version=None):
Returns: Returns:
An instantiated Python STIX object. An instantiated Python STIX object.
WARNING: 'allow_custom=True' will allow for the return of any supplied STIX Warnings:
dict(s) that cannot be found to map to any known STIX object types (both STIX2 'allow_custom=True' will allow for the return of any supplied STIX
domain objects or defined custom STIX2 objects); NO validation is done. This is dict(s) that cannot be found to map to any known STIX object types
done to allow the processing of possibly unknown custom STIX objects (example (both STIX2 domain objects or defined custom STIX2 objects); NO
scenario: I need to query a third-party TAXII endpoint that could provide custom validation is done. This is done to allow the processing of possibly
STIX objects that I dont know about ahead of time) unknown custom STIX objects (example scenario: I need to query a
third-party TAXII endpoint that could provide custom STIX objects that
I don't know about ahead of time)
""" """
# convert STIX object to dict, if not already # convert STIX object to dict, if not already
@ -49,9 +51,10 @@ def dict_to_stix2(stix_dict, allow_custom=False, version=None):
stix_dict (dict): a python dictionary of a STIX object stix_dict (dict): a python dictionary of a STIX object
that (presumably) is semantically correct to be parsed that (presumably) is semantically correct to be parsed
into a full python-stix2 obj into a full python-stix2 obj
allow_custom (bool): Whether to allow custom properties as well unknown allow_custom (bool): Whether to allow custom properties as well
custom objects. Note that unknown custom objects cannot be parsed unknown custom objects. Note that unknown custom objects cannot
into STIX objects, and will be returned as is. Default: False. be parsed into STIX objects, and will be returned as is.
Default: False.
version: Only used for bundles. If the spec_version property is version: Only used for bundles. If the spec_version property is
missing, it is ambiguous what spec should be used to parse the missing, it is ambiguous what spec should be used to parse the
bundle. In this case, this version parameter gives the spec bundle. In this case, this version parameter gives the spec
@ -60,12 +63,14 @@ def dict_to_stix2(stix_dict, allow_custom=False, version=None):
Returns: Returns:
An instantiated Python STIX object An instantiated Python STIX object
WARNING: 'allow_custom=True' will allow for the return of any supplied STIX Warnings:
dict(s) that cannot be found to map to any known STIX object types (both STIX2 'allow_custom=True' will allow for the return of any supplied STIX
domain objects or defined custom STIX2 objects); NO validation is done. This is dict(s) that cannot be found to map to any known STIX object types
done to allow the processing of possibly unknown custom STIX objects (example (both STIX2 domain objects or defined custom STIX2 objects); NO
scenario: I need to query a third-party TAXII endpoint that could provide custom validation is done. This is done to allow the processing of
STIX objects that I dont know about ahead of time) possibly unknown custom STIX objects (example scenario: I need to
query a third-party TAXII endpoint that could provide custom STIX
objects that I don't know about ahead of time)
""" """
if 'type' not in stix_dict: if 'type' not in stix_dict:

47
stix2/utils.py
View File

@ -170,9 +170,12 @@ def _find(seq, val):
Search sequence 'seq' for val. This behaves like str.find(): if not found, Search sequence 'seq' for val. This behaves like str.find(): if not found,
-1 is returned instead of throwing an exception. -1 is returned instead of throwing an exception.
:param seq: The sequence to search Args:
:param val: The value to search for seq: The sequence to search
:return: The index of the value if found, or -1 if not found val: The value to search for
Returns:
int: The index of the value if found, or -1 if not found
""" """
try: try:
return seq.index(val) return seq.index(val)
@ -185,10 +188,13 @@ def _find_property_in_seq(seq, search_key, search_value):
Helper for find_property_index(): search for the property in all elements Helper for find_property_index(): search for the property in all elements
of the given sequence. of the given sequence.
:param seq: The sequence Args:
:param search_key: Property name to find seq: The sequence
:param search_value: Property value to find search_key: Property name to find
:return: A property index, or -1 if the property was not found search_value: Property value to find
Returns:
int: A property index, or -1 if the property was not found
""" """
idx = -1 idx = -1
for elem in seq: for elem in seq:
@ -204,10 +210,13 @@ def find_property_index(obj, search_key, search_value):
Search (recursively) for the given key and value in the given object. 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. Return an index for the key, relative to whatever object it's found in.
:param obj: The object to search (list, dict, or stix object) Args:
:param search_key: A search key obj: The object to search (list, dict, or stix object)
:param search_value: A search value search_key: A search key
:return: An index; -1 if the key and value aren't found search_value: A search value
Returns:
int: An index; -1 if the key and value aren't found
""" """
from .base import _STIXBase from .base import _STIXBase
@ -302,14 +311,14 @@ def get_class_hierarchy_names(obj):
def remove_custom_stix(stix_obj): def remove_custom_stix(stix_obj):
"""Remove any custom STIX objects or properties. """Remove any custom STIX objects or properties.
Warning: This function is a best effort utility, in that Warnings:
it will remove custom objects and properties based on the This function is a best effort utility, in that it will remove custom
type names; i.e. if "x-" prefixes object types, and "x\\_" objects and properties based on the type names; i.e. if "x-" prefixes
prefixes property types. According to the STIX2 spec, object types, and "x\\_" prefixes property types. According to the
those naming conventions are a SHOULDs not MUSTs, meaning STIX2 spec, those naming conventions are a SHOULDs not MUSTs, meaning
that valid custom STIX content may ignore those conventions that valid custom STIX content may ignore those conventions and in
and in effect render this utility function invalid when used effect render this utility function invalid when used on that STIX
on that STIX content. content.
Args: Args:
stix_obj (dict OR python-stix obj): a single python-stix object stix_obj (dict OR python-stix obj): a single python-stix object