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

Improve markings docstrings 

Including a note that the markings functions can be used as methods on
SDO/SRO/MarkingDefinition objects.
stix2.0
Chris Lenk 2017-11-09 10:10:19 -05:00
parent ef6dade6f6
commit c38483b631
4 changed files with 43 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
stix2/markings/__init__.py
View File

@ -1,9 +1,14 @@
""" """
Functions and classes for working with STIX 2 Data Markings. Functions for working with STIX 2 Data Markings.
These high level functions will operate on both object level markings and These high level functions will operate on both object-level markings and
granular markings unless otherwise noted in each of the functions. granular markings unless otherwise noted in each of the functions.
Note:
These functions are also available as methods on SDOs, SROs, and Marking
Definitions. The corresponding methods on those classes are identical to
these functions except that the `obj` parameter is omitted.
.. autosummary:: .. autosummary::
:toctree: markings :toctree: markings
@ -20,7 +25,7 @@ from stix2.markings import granular_markings, object_markings
def get_markings(obj, selectors=None, inherited=False, descendants=False): def get_markings(obj, selectors=None, inherited=False, descendants=False):
""" """
Get all markings associated to the field(s). Get all markings associated to the field(s) specified by selectors.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
@ -57,15 +62,15 @@ def get_markings(obj, selectors=None, inherited=False, descendants=False):
def set_markings(obj, marking, selectors=None): def set_markings(obj, marking, selectors=None):
""" """
Removes all markings associated with selectors and appends a new granular Remove all markings associated with selectors and appends a new granular
marking. Refer to `clear_markings` and `add_markings` for details. marking. Refer to `clear_markings` and `add_markings` for details.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
marking: identifier or list of marking identifiers that apply to the marking: identifier or list of marking identifiers that apply to the
properties selected by `selectors`. properties selected by `selectors`.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
Returns: Returns:
A new version of the given SDO or SRO with specified markings removed A new version of the given SDO or SRO with specified markings removed
@ -84,14 +89,14 @@ def set_markings(obj, marking, selectors=None):
def remove_markings(obj, marking, selectors=None): def remove_markings(obj, marking, selectors=None):
""" """
Removes granular_marking from the granular_markings collection. Remove a marking from this object.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
marking: identifier or list of marking identifiers that apply to the marking: identifier or list of marking identifiers that apply to the
properties selected by `selectors`. properties selected by `selectors`.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
Raises: Raises:
InvalidSelectorError: If `selectors` fail validation. InvalidSelectorError: If `selectors` fail validation.
@ -114,14 +119,14 @@ def remove_markings(obj, marking, selectors=None):
def add_markings(obj, marking, selectors=None): def add_markings(obj, marking, selectors=None):
""" """
Appends a granular_marking to the granular_markings collection. Append a marking to this object.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
marking: identifier or list of marking identifiers that apply to the marking: identifier or list of marking identifiers that apply to the
properties selected by `selectors`. properties selected by `selectors`.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
Raises: Raises:
InvalidSelectorError: If `selectors` fail validation. InvalidSelectorError: If `selectors` fail validation.
@ -142,7 +147,7 @@ def add_markings(obj, marking, selectors=None):
def clear_markings(obj, selectors=None): def clear_markings(obj, selectors=None):
""" """
Removes all granular_marking associated with the selectors. Remove all markings associated with the selectors.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
@ -170,14 +175,14 @@ def clear_markings(obj, selectors=None):
def is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False): def is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False):
""" """
Checks if field(s) is marked by any marking or by specific marking(s). Check if field(s) is marked by any marking or by specific marking(s).
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the field(s) appear(s).
marking: identifier or list of marking identifiers that apply to the marking: identifier or list of marking identifiers that apply to the
properties selected by `selectors`. properties selected by `selectors`.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the field(s) appear(s).
inherited: If True, include object level markings and granular markings inherited: If True, include object level markings and granular markings
inherited to determine if the properties is/are marked. inherited to determine if the properties is/are marked.
descendants: If True, include granular markings applied to any children descendants: If True, include granular markings applied to any children

26
stix2/markings/granular_markings.py
View File

@ -8,7 +8,7 @@ from stix2.utils import new_version
def get_markings(obj, selectors, inherited=False, descendants=False): def get_markings(obj, selectors, inherited=False, descendants=False):
""" """
Get all markings associated to with the properties. Get all granular markings associated to with the properties.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
@ -50,8 +50,8 @@ def get_markings(obj, selectors, inherited=False, descendants=False):
def set_markings(obj, marking, selectors): def set_markings(obj, marking, selectors):
""" """
Removes all markings associated with selectors and appends a new granular Remove all granular markings associated with selectors and append a new
marking. Refer to `clear_markings` and `add_markings` for details. granular marking. Refer to `clear_markings` and `add_markings` for details.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
@ -71,14 +71,14 @@ def set_markings(obj, marking, selectors):
def remove_markings(obj, marking, selectors): def remove_markings(obj, marking, selectors):
""" """
Removes granular_marking from the granular_markings collection. Remove a granular marking from the granular_markings collection.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
marking: identifier or list of marking identifiers that apply to the marking: identifier or list of marking identifiers that apply to the
properties selected by `selectors`. properties selected by `selectors`.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
Raises: Raises:
InvalidSelectorError: If `selectors` fail validation. InvalidSelectorError: If `selectors` fail validation.
@ -123,14 +123,14 @@ def remove_markings(obj, marking, selectors):
def add_markings(obj, marking, selectors): def add_markings(obj, marking, selectors):
""" """
Appends a granular_marking to the granular_markings collection. Append a granular marking to the granular_markings collection.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
selectors: list of type string, selectors must be relative to the TLO
in which the properties appear.
marking: identifier or list of marking identifiers that apply to the marking: identifier or list of marking identifiers that apply to the
properties selected by `selectors`. properties selected by `selectors`.
selectors: list of type string, selectors must be relative to the TLO
in which the properties appear.
Raises: Raises:
InvalidSelectorError: If `selectors` fail validation. InvalidSelectorError: If `selectors` fail validation.
@ -157,7 +157,7 @@ def add_markings(obj, marking, selectors):
def clear_markings(obj, selectors): def clear_markings(obj, selectors):
""" """
Removes all granular_markings associated with the selectors. Remove all granular markings associated with the selectors.
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
@ -214,14 +214,14 @@ def clear_markings(obj, selectors):
def is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False): def is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False):
""" """
Checks if field is marked by any marking or by specific marking(s). Check if field is marked by any marking or by specific marking(s).
Args: Args:
obj: An SDO or SRO object. obj: An SDO or SRO object.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
marking: identifier or list of marking identifiers that apply to the marking: identifier or list of marking identifiers that apply to the
properties selected by `selectors`. properties selected by `selectors`.
selectors: string or list of selectors strings relative to the SDO or
SRO in which the properties appear.
inherited: If True, return markings inherited from the given selector. inherited: If True, return markings inherited from the given selector.
descendants: If True, return granular markings applied to any children descendants: If True, return granular markings applied to any children
of the given selector. of the given selector.

10
stix2/markings/object_markings.py
View File

@ -23,7 +23,7 @@ def get_markings(obj):
def add_markings(obj, marking): def add_markings(obj, marking):
""" """
Appends an object level marking to the object_marking_refs collection. Append an object level marking to the object_marking_refs collection.
Args: Args:
obj: A SDO or SRO object. obj: A SDO or SRO object.
@ -42,7 +42,7 @@ def add_markings(obj, marking):
def remove_markings(obj, marking): def remove_markings(obj, marking):
""" """
Removes object level marking from the object_marking_refs collection. Remove an object level marking from the object_marking_refs collection.
Args: Args:
obj: A SDO or SRO object. obj: A SDO or SRO object.
@ -76,7 +76,7 @@ def remove_markings(obj, marking):
def set_markings(obj, marking): def set_markings(obj, marking):
""" """
Removes all object level markings and appends new object level markings to Remove all object level markings and append new object level markings to
the collection. Refer to `clear_markings` and `add_markings` for details. the collection. Refer to `clear_markings` and `add_markings` for details.
Args: Args:
@ -94,7 +94,7 @@ def set_markings(obj, marking):
def clear_markings(obj): def clear_markings(obj):
""" """
Removes all object level markings from the object_marking_refs collection. Remove all object level markings from the object_marking_refs collection.
Args: Args:
obj: A SDO or SRO object. obj: A SDO or SRO object.
@ -108,7 +108,7 @@ def clear_markings(obj):
def is_marked(obj, marking=None): def is_marked(obj, marking=None):
""" """
Checks if SDO or SRO is marked by any marking or by specific marking(s). Check if SDO or SRO is marked by any marking or by specific marking(s).
Args: Args:
obj: A SDO or SRO object. obj: A SDO or SRO object.

8
stix2/markings/utils.py
View File

@ -9,7 +9,7 @@ from stix2 import exceptions
def _evaluate_expression(obj, selector): def _evaluate_expression(obj, selector):
"""Walks an SDO or SRO generating selectors to match against ``selector``. """Walk an SDO or SRO generating selectors to match against ``selector``.
If a match is found and the the value of this property is present in the If a match is found and the the value of this property is present in the
objects. Matching value of the property will be returned. objects. Matching value of the property will be returned.
@ -32,7 +32,7 @@ def _evaluate_expression(obj, selector):
def _validate_selector(obj, selector): def _validate_selector(obj, selector):
"""Internal method to evaluate each selector.""" """Evaluate each selector against an object."""
results = list(_evaluate_expression(obj, selector)) results = list(_evaluate_expression(obj, selector))
if len(results) >= 1: if len(results) >= 1:
@ -132,7 +132,7 @@ def compress_markings(granular_markings):
def expand_markings(granular_markings): def expand_markings(granular_markings):
"""Expands granular markings list. """Expand granular markings list.
If there is more than one selector per granular marking. It will be If there is more than one selector per granular marking. It will be
expanded using the same marking_ref. expanded using the same marking_ref.
@ -187,7 +187,7 @@ def expand_markings(granular_markings):
def build_granular_marking(granular_marking): def build_granular_marking(granular_marking):
"""Returns a dictionary with the required structure for a granular marking. """Return a dictionary with the required structure for a granular marking.
""" """
return {"granular_markings": expand_markings(granular_marking)} return {"granular_markings": expand_markings(granular_marking)}