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

Add `allow_custom` to datastore docstrings

stix2.0
Chris Lenk 2017-10-24 09:15:09 -04:00
parent 476cd1ed5b
commit 5c28074364
4 changed files with 84 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
stix2/sources/__init__.py
View File

@ -51,6 +51,8 @@ class DataStore(object):
Args: Args:
stix_id (str): the id of the STIX object to retrieve. stix_id (str): the id of the STIX object to retrieve.
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
stix_obj: the single most recent version of the STIX stix_obj: the single most recent version of the STIX
@ -66,6 +68,8 @@ class DataStore(object):
Args: Args:
stix_id (str): the id of the STIX object to retrieve. stix_id (str): the id of the STIX object to retrieve.
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
stix_objs (list): a list of STIX objects stix_objs (list): a list of STIX objects
@ -82,6 +86,8 @@ class DataStore(object):
Args: Args:
query (list): a list of filters (which collectively are the query) query (list): a list of filters (which collectively are the query)
to conduct search on. to conduct search on.
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
stix_objs (list): a list of STIX objects stix_objs (list): a list of STIX objects
@ -96,6 +102,8 @@ class DataStore(object):
Args: Args:
stix_objs (list): a list of STIX objects stix_objs (list): a list of STIX objects
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
""" """
return self.sink.add(stix_objs, allow_custom=allow_custom) return self.sink.add(stix_objs, allow_custom=allow_custom)
@ -120,6 +128,8 @@ class DataSink(object):
Args: Args:
stix_objs (list): a list of STIX objects (where each object is a stix_objs (list): a list of STIX objects (where each object is a
STIX object) STIX object)
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
""" """
raise NotImplementedError() raise NotImplementedError()
@ -148,9 +158,10 @@ class DataSource(object):
stix_id (str): the id of the STIX 2.0 object to retrieve. Should stix_id (str): the id of the STIX 2.0 object to retrieve. Should
return a single object, the most recent version of the object return a single object, the most recent version of the object
specified by the "id". specified by the "id".
_composite_filters (set): set of filters passed from the parent _composite_filters (set): set of filters passed from the parent
the CompositeDataSource, not user supplied the CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
stix_obj: the STIX object stix_obj: the STIX object
@ -169,9 +180,10 @@ class DataSource(object):
stix_id (str): The id of the STIX 2.0 object to retrieve. Should stix_id (str): The id of the STIX 2.0 object to retrieve. Should
return a list of objects, all the versions of the object return a list of objects, all the versions of the object
specified by the "id". specified by the "id".
_composite_filters (set): set of filters passed from the parent _composite_filters (set): set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
stix_objs (list): a list of STIX objects stix_objs (list): a list of STIX objects
@ -187,9 +199,10 @@ class DataSource(object):
Args: Args:
query (list): a list of filters (which collectively are the query) query (list): a list of filters (which collectively are the query)
to conduct search on to conduct search on
_composite_filters (set): a set of filters passed from the parent _composite_filters (set): a set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
stix_objs (list): a list of STIX objects stix_objs (list): a list of STIX objects
@ -238,10 +251,11 @@ class CompositeDataSource(DataSource):
Args: Args:
stix_id (str): the id of the STIX object to retrieve. stix_id (str): the id of the STIX object to retrieve.
_composite_filters (list): a list of filters passed from a _composite_filters (list): a list of filters passed from a
CompositeDataSource (i.e. if this CompositeDataSource is attached CompositeDataSource (i.e. if this CompositeDataSource is attached
to another parent CompositeDataSource), not user supplied to another parent CompositeDataSource), not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
stix_obj: the STIX object to be returned. stix_obj: the STIX object to be returned.
@ -283,10 +297,11 @@ class CompositeDataSource(DataSource):
Args: Args:
stix_id (str): id of the STIX objects to retrieve stix_id (str): id of the STIX objects to retrieve
_composite_filters (list): a list of filters passed from a _composite_filters (list): a list of filters passed from a
CompositeDataSource (i.e. if this CompositeDataSource is attached CompositeDataSource (i.e. if this CompositeDataSource is attached
to a parent CompositeDataSource), not user supplied to a parent CompositeDataSource), not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
all_data (list): list of STIX objects that have the specified id all_data (list): list of STIX objects that have the specified id
@ -323,10 +338,11 @@ class CompositeDataSource(DataSource):
Args: Args:
query (list): list of filters to search on query (list): list of filters to search on
_composite_filters (list): a list of filters passed from a _composite_filters (list): a list of filters passed from a
CompositeDataSource (i.e. if this CompositeDataSource is attached CompositeDataSource (i.e. if this CompositeDataSource is attached
to a parent CompositeDataSource), not user supplied to a parent CompositeDataSource), not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
all_data (list): list of STIX objects to be returned all_data (list): list of STIX objects to be returned

11
stix2/sources/filesystem.py
View File

@ -67,6 +67,8 @@ class FileSystemSink(DataSink):
stix_data (STIX object OR dict OR str OR list): valid STIX 2.0 content stix_data (STIX object OR dict OR str OR list): valid STIX 2.0 content
in a STIX object (or list of), dict (or list of), or a STIX 2.0 in a STIX object (or list of), dict (or list of), or a STIX 2.0
json encoded string. json encoded string.
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
Note: Note:
``stix_data`` can be a Bundle object, but each object in it will be ``stix_data`` can be a Bundle object, but each object in it will be
@ -140,9 +142,10 @@ class FileSystemSource(DataSource):
Args: Args:
stix_id (str): The STIX ID of the STIX object to be retrieved. stix_id (str): The STIX ID of the STIX object to be retrieved.
composite_filters (set): set of filters passed from the parent composite_filters (set): set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(STIX object): STIX object that has the supplied STIX ID. (STIX object): STIX object that has the supplied STIX ID.
@ -169,9 +172,10 @@ class FileSystemSource(DataSource):
Args: Args:
stix_id (str): The STIX ID of the STIX objects to be retrieved. stix_id (str): The STIX ID of the STIX objects to be retrieved.
composite_filters (set): set of filters passed from the parent composite_filters (set): set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(list): of STIX objects that has the supplied STIX ID. (list): of STIX objects that has the supplied STIX ID.
@ -190,9 +194,10 @@ class FileSystemSource(DataSource):
Args: Args:
query (list): list of filters to search on query (list): list of filters to search on
composite_filters (set): set of filters passed from the composite_filters (set): set of filters passed from the
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(list): list of STIX objects that matches the supplied (list): list of STIX objects that matches the supplied

73
stix2/sources/memory.py
View File

@ -32,8 +32,10 @@ def _add(store, stix_data=None, allow_custom=False):
Args: Args:
stix_data (list OR dict OR STIX object): STIX objects to be added stix_data (list OR dict OR STIX object): STIX objects to be added
""" allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
"""
if isinstance(stix_data, _STIXBase): if isinstance(stix_data, _STIXBase):
# adding a python STIX object # adding a python STIX object
store._data[stix_data["id"]] = stix_data store._data[stix_data["id"]] = stix_data
@ -77,16 +79,15 @@ class MemoryStore(DataStore):
Args: Args:
stix_data (list OR dict OR STIX object): STIX content to be added stix_data (list OR dict OR STIX object): STIX content to be added
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
Attributes: Attributes:
_data (dict): the in-memory dict that holds STIX objects _data (dict): the in-memory dict that holds STIX objects
source (MemorySource): MemorySource source (MemorySource): MemorySource
sink (MemorySink): MemorySink sink (MemorySink): MemorySink
""" """
def __init__(self, stix_data=None, allow_custom=False): def __init__(self, stix_data=None, allow_custom=False):
super(MemoryStore, self).__init__() super(MemoryStore, self).__init__()
self._data = {} self._data = {}
@ -98,9 +99,29 @@ class MemoryStore(DataStore):
self.sink = MemorySink(stix_data=self._data, _store=True, allow_custom=allow_custom) self.sink = MemorySink(stix_data=self._data, _store=True, allow_custom=allow_custom)
def save_to_file(self, file_path, allow_custom=False): def save_to_file(self, file_path, allow_custom=False):
"""Write SITX objects from in-memory dictionary to JSON file, as a STIX
Bundle.
Args:
file_path (str): file path to write STIX data to
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
"""
return self.sink.save_to_file(file_path=file_path, allow_custom=allow_custom) return self.sink.save_to_file(file_path=file_path, allow_custom=allow_custom)
def load_from_file(self, file_path, allow_custom=False): def load_from_file(self, file_path, allow_custom=False):
"""Load STIX data from JSON file.
File format is expected to be a single JSON
STIX object or JSON STIX bundle.
Args:
file_path (str): file path to load STIX data from
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
"""
return self.source.load_from_file(file_path=file_path, allow_custom=allow_custom) return self.source.load_from_file(file_path=file_path, allow_custom=allow_custom)
@ -113,17 +134,18 @@ class MemorySink(DataSink):
Args: Args:
stix_data (dict OR list): valid STIX 2.0 content in stix_data (dict OR list): valid STIX 2.0 content in
bundle or a list. bundle or a list.
_store (bool): if the MemorySink is a part of a DataStore, _store (bool): if the MemorySink is a part of a DataStore,
in which case "stix_data" is a direct reference to in which case "stix_data" is a direct reference to
shared memory with DataSource. Not user supplied shared memory with DataSource. Not user supplied
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
Attributes: Attributes:
_data (dict): the in-memory dict that holds STIX objects. _data (dict): the in-memory dict that holds STIX objects.
If apart of a MemoryStore, dict is shared between with If apart of a MemoryStore, dict is shared between with
a MemorySource a MemorySource
"""
"""
def __init__(self, stix_data=None, _store=False, allow_custom=False): def __init__(self, stix_data=None, _store=False, allow_custom=False):
super(MemorySink, self).__init__() super(MemorySink, self).__init__()
self._data = {} self._data = {}
@ -134,25 +156,16 @@ class MemorySink(DataSink):
_add(self, stix_data, allow_custom=allow_custom) _add(self, stix_data, allow_custom=allow_custom)
def add(self, stix_data, allow_custom=False): def add(self, stix_data, allow_custom=False):
"""add STIX objects to in-memory dictionary maintained by
the MemorySink (MemoryStore)
see "_add()" for args documentation
"""
_add(self, stix_data, allow_custom=allow_custom) _add(self, stix_data, allow_custom=allow_custom)
add.__doc__ = _add.__doc__
def save_to_file(self, file_path, allow_custom=False): def save_to_file(self, file_path, allow_custom=False):
"""write SITX objects in in-memory dictionary to json file, as a STIX Bundle
Args:
file_path (str): file path to write STIX data to
"""
file_path = os.path.abspath(file_path) file_path = os.path.abspath(file_path)
if not os.path.exists(os.path.dirname(file_path)): if not os.path.exists(os.path.dirname(file_path)):
os.makedirs(os.path.dirname(file_path)) os.makedirs(os.path.dirname(file_path))
with open(file_path, "w") as f: with open(file_path, "w") as f:
f.write(str(Bundle(self._data.values(), allow_custom=allow_custom))) f.write(str(Bundle(self._data.values(), allow_custom=allow_custom)))
save_to_file.__doc__ = MemoryStore.save_to_file.__doc__
class MemorySource(DataSource): class MemorySource(DataSource):
@ -165,17 +178,18 @@ class MemorySource(DataSource):
Args: Args:
stix_data (dict OR list OR STIX object): valid STIX 2.0 content in stix_data (dict OR list OR STIX object): valid STIX 2.0 content in
bundle or list. bundle or list.
_store (bool): if the MemorySource is a part of a DataStore, _store (bool): if the MemorySource is a part of a DataStore,
in which case "stix_data" is a direct reference to shared in which case "stix_data" is a direct reference to shared
memory with DataSink. Not user supplied memory with DataSink. Not user supplied
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
Attributes: Attributes:
_data (dict): the in-memory dict that holds STIX objects. _data (dict): the in-memory dict that holds STIX objects.
If apart of a MemoryStore, dict is shared between with If apart of a MemoryStore, dict is shared between with
a MemorySink a MemorySink
"""
"""
def __init__(self, stix_data=None, _store=False, allow_custom=False): def __init__(self, stix_data=None, _store=False, allow_custom=False):
super(MemorySource, self).__init__() super(MemorySource, self).__init__()
self._data = {} self._data = {}
@ -190,9 +204,10 @@ class MemorySource(DataSource):
Args: Args:
stix_id (str): The STIX ID of the STIX object to be retrieved. stix_id (str): The STIX ID of the STIX object to be retrieved.
composite_filters (set): set of filters passed from the parent composite_filters (set): set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(dict OR STIX object): STIX object that has the supplied (dict OR STIX object): STIX object that has the supplied
@ -227,9 +242,10 @@ class MemorySource(DataSource):
Args: Args:
stix_id (str): The STIX ID of the STIX 2 object to retrieve. stix_id (str): The STIX ID of the STIX 2 object to retrieve.
composite_filters (set): set of filters passed from the parent composite_filters (set): set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(list): list of STIX objects that has the supplied ID. As the (list): list of STIX objects that has the supplied ID. As the
@ -249,15 +265,16 @@ class MemorySource(DataSource):
Args: Args:
query (list): list of filters to search on query (list): list of filters to search on
composite_filters (set): set of filters passed from the composite_filters (set): set of filters passed from the
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(list): list of STIX objects that matches the supplied (list): list of STIX objects that matches the supplied
query. As the MemoryStore(i.e. MemorySink) adds STIX objects to memory query. As the MemoryStore(i.e. MemorySink) adds STIX objects to memory
as they are supplied (either as python dictionary or STIX object), it as they are supplied (either as python dictionary or STIX object), it
is returned in the same form as it as added is returned in the same form as it as added.
""" """
if query is None: if query is None:
@ -281,15 +298,7 @@ class MemorySource(DataSource):
return all_data return all_data
def load_from_file(self, file_path, allow_custom=False): def load_from_file(self, file_path, allow_custom=False):
"""Load STIX data from json file.
File format is expected to be a single json
STIX object or json STIX bundle
Args:
file_path (str): file path to load STIX data from
"""
file_path = os.path.abspath(file_path) file_path = os.path.abspath(file_path)
stix_data = json.load(open(file_path, "r")) stix_data = json.load(open(file_path, "r"))
_add(self, stix_data, allow_custom=allow_custom) _add(self, stix_data, allow_custom=allow_custom)
load_from_file.__doc__ = MemoryStore.load_from_file.__doc__

23
stix2/sources/taxii.py
View File

@ -42,15 +42,16 @@ class TAXIICollectionSink(DataSink):
self.collection = collection self.collection = collection
def add(self, stix_data, allow_custom=False): def add(self, stix_data, allow_custom=False):
"""add/push STIX content to TAXII Collection endpoint """Add/push STIX content to TAXII Collection endpoint
Args: Args:
stix_data (STIX object OR dict OR str OR list): valid STIX 2.0 content stix_data (STIX object OR dict OR str OR list): valid STIX 2.0 content
in a STIX object (or Bundle), STIX onject dict (or Bundle dict), or a STIX 2.0 in a STIX object (or Bundle), STIX onject dict (or Bundle dict), or a STIX 2.0
json encoded string, or list of any of the following json encoded string, or list of any of the following
allow_custom (bool): whether to allow custom objects/properties or
not. Default: False.
""" """
if isinstance(stix_data, _STIXBase): if isinstance(stix_data, _STIXBase):
# adding python STIX object # adding python STIX object
bundle = dict(Bundle(stix_data, allow_custom=allow_custom)) bundle = dict(Bundle(stix_data, allow_custom=allow_custom))
@ -94,21 +95,21 @@ class TAXIICollectionSource(DataSource):
self.collection = collection self.collection = collection
def get(self, stix_id, _composite_filters=None, allow_custom=False): def get(self, stix_id, _composite_filters=None, allow_custom=False):
"""retrieve STIX object from local/remote STIX Collection """Retrieve STIX object from local/remote STIX Collection
endpoint. endpoint.
Args: Args:
stix_id (str): The STIX ID of the STIX object to be retrieved. stix_id (str): The STIX ID of the STIX object to be retrieved.
composite_filters (set): set of filters passed from the parent composite_filters (set): set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(STIX object): STIX object that has the supplied STIX ID. (STIX object): STIX object that has the supplied STIX ID.
The STIX object is received from TAXII has dict, parsed into The STIX object is received from TAXII has dict, parsed into
a python STIX object and then returned a python STIX object and then returned
""" """
# combine all query filters # combine all query filters
query = set() query = set()
@ -132,14 +133,15 @@ class TAXIICollectionSource(DataSource):
return stix_obj return stix_obj
def all_versions(self, stix_id, _composite_filters=None, allow_custom=False): def all_versions(self, stix_id, _composite_filters=None, allow_custom=False):
"""retrieve STIX object from local/remote TAXII Collection """Retrieve STIX object from local/remote TAXII Collection
endpoint, all versions of it endpoint, all versions of it
Args: Args:
stix_id (str): The STIX ID of the STIX objects to be retrieved. stix_id (str): The STIX ID of the STIX objects to be retrieved.
composite_filters (set): set of filters passed from the parent composite_filters (set): set of filters passed from the parent
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(see query() as all_versions() is just a wrapper) (see query() as all_versions() is just a wrapper)
@ -156,7 +158,7 @@ class TAXIICollectionSource(DataSource):
return all_data return all_data
def query(self, query=None, _composite_filters=None, allow_custom=False): def query(self, query=None, _composite_filters=None, allow_custom=False):
"""search and retreive STIX objects based on the complete query """Search and retreive STIX objects based on the complete query
A "complete query" includes the filters from the query, the filters A "complete query" includes the filters from the query, the filters
attached to MemorySource, and any filters passed from a attached to MemorySource, and any filters passed from a
@ -164,9 +166,10 @@ class TAXIICollectionSource(DataSource):
Args: Args:
query (list): list of filters to search on query (list): list of filters to search on
composite_filters (set): set of filters passed from the composite_filters (set): set of filters passed from the
CompositeDataSource, not user supplied CompositeDataSource, not user supplied
allow_custom (bool): whether to retrieve custom objects/properties
or not. Default: False.
Returns: Returns:
(list): list of STIX objects that matches the supplied (list): list of STIX objects that matches the supplied
@ -174,7 +177,6 @@ class TAXIICollectionSource(DataSource):
parsed into python STIX objects and then returned. parsed into python STIX objects and then returned.
""" """
if query is None: if query is None:
query = set() query = set()
else: else:
@ -225,7 +227,6 @@ class TAXIICollectionSource(DataSource):
for 'requests.get()'. for 'requests.get()'.
""" """
params = {} params = {}
for filter_ in query: for filter_ in query: