API Reference

class stixmarx.container.MarkingContainer(package)[source]

Enables the operation of data markings on STIX, CybOX and MAEC objects.

A MarkingContainer provides interfaces for applying, accessing, clearing and removing data marking information from its wrapped STIX Package. A MarkingContainer has methods for processing marking information and serialization which translate the marked object model into XPath controlled structures.

Note

A MarkingContainer should not be created directly. Instead, use stixmarx.parse() or stixmarx.new() to create MarkingContainer instances.

package

stix.core.STIXPackage – The package object (from python-stix) wrapped by this container.

global_markings

list of MarkingSpecification – List of markings that apply to the container package as a whole (every descendant).

field_markings

dict, maps markable objects to MarkingSpecification – Dictionary where keys are markable entities and the values are a list that contain tuples of MarkingSpecification and descendants (True/False) option.

null_markings

(list of MarkingSpecification): List of markings that apply to this container but, will NOT mark anything inside. This means, no controlled structure will be resolved for this objects.

add_global(marking)[source]

Add the marking MarkingSpecification object to the set of globally applicable markings (markings that apply to this container’s package and all of its descendants).

Markings added here will be included in the set returned from get_markings() for any valid field.

Parameters:

marking – A MarkingSpecification object.

Raises:
  • TypeError – If marking is not a MarkingSpecification object.
  • MarkingPathNotEmpty – If marking controlled_structure is set.
  • DuplicateMarkingError – If marking is already present in global_markings collection.
add_marking(markable, marking, descendants=False)[source]

Add the marking to the markable field/object. If markable is a built-in immutable Python type, it will be coerced into a stixmarx.api.types datatype.

Note

The add_marking() function may not always be able to apply the markings in-place. Users should set the input field to the return object after calling add_marking().

Note

Use this method to apply null markings. This is, markings that are present within the document but, do not apply to any field. The markable parameter MUST be None.

Example

>>> print type(indicator.title)
<type 'str'>
>>> marked_title = add_marking(indicator.title, marking)
>>> print type(marked_title)
<class 'stixmarx.api.types.MarkableBytes'>
>>> indicator.title = marked_title  # set the title to the return value

Example

>>> print type(indicator.timestamp)
<type 'datetime.datetime'>
>>> marked_timestamp = add_marking(indicator.timestamp, marking)
>>> print type(marked_timestamp)
<class 'stixmarx.api.types.MarkableDateTime'>
>>> indicator.timestamp = marked_timestamp # set timestamp to the return value

Example

>>> print type(indicator)
<class 'stix.indicator.indicator.Indicator'>
>>> marked_indicator = add_marking(indicator, marking, descendants=True) # The equivalent of a component marking
>>> print type(marked_indicator)
<class 'stix.indicator.indicator.Indicator'>
>>> indicator = marked_indicator
Parameters:
  • markable – An object to mark (e.g., an Indicator.title string).
  • marking – A python-stix MarkingSpecification object.
  • descendants – If true, add the marking to all descendants markable.
Returns:

The markable object with data marking information attached. If markable is a built-in immutable Python type (e.g., str), it will be changed to a stixmarx.api.types datatype.

Raises:
  • UnmarkableError – If markable is a STIXPackage object.
  • DuplicateMarkingError – If markable is already marked by marking.
  • MarkingPathNotEmpty – If marking controlled_structure is set.
clear_markings(markable, descendants=False)[source]

Remove all markings from the markable marked object.

Parameters:
  • markable – A marked object (e.g., indicator.title)
  • descendants – If True, clear markings from markable and its descendants.
Raises:

UnmarkableError – If markable is not an markable entity.

field_markings

Return the field markings that have been set via add_marking().

Note

This property DOES NOT return markings that were applied by MarkingParser.

Returns:Dictionary where keys are markable entities and values are a list of tuples with MarkingSpecification objects and their corresponding (True/False) descendants option.
Return type:dict
flush()[source]

Flush markings onto package object.

Markings are buffered in the MarkingContainer until explicitly flushed out to the MarkingContainer’s package through this method.

Note

The global and fields collection will reset after this call.

Returns:
A STIX Package with all makings explicitly
applied from the container.
Return type:stix.core.STIXPackage
get_markings(markable, descendants=False, null_markings=False)[source]

Return the markings associated with the input markable object.

Note

This will include any global markings that have not been explicitly applied to this field.

Parameters:
  • markable – A markable object (e.g., indicator.title).
  • descendants – If True, return markings which apply to the input field and all of its descendants.
  • null_markings – If True, return internal markings that do NOT apply to any markable. This null markings have not been explicitly set to the wrapped document. Use utils.get_null_markings(...) to find null markings that have been explicitly set in the document.
Returns:

A list of MarkingSpecification objects.

Return type:

list

global_markings

Return the global markings that have been set via add_global().

Note

This property DOES NOT return markings that were applied by MarkingParser (even markings that were applied to all nodes in the parsed document).

Returns:Tuple containing MarkingSpecification objects.
Return type:tuple
is_marked(markable, marking=None, descendants=False)[source]

Return True if markable contains marking information.

Parameters:
  • markable – An markable object.
  • marking – A MarkingSpecification object.
  • descendants – If set, inspect descendant fields for marking information.
Raises:
  • UnmarkableError – If markable is not an markable entity.
  • UnknownMarkingError – If marking is not a MarkingSpecification object.
Returns:

True under the following conditions: if markable contains

marking information, if markable is marked by marking, if markable descendants contain markings or if global markings have been added through add_global(). Otherwise False.

Return type:

bool

null_markings

Return the null markings that have been set via add_markings(). Where markable is None.

Note

This property DOES NOT return markings that were applied by MarkingParser.

Returns:Tuple containing MarkingSpecification objects.
Return type:tuple
package

Package wrapped by this MarkingContainer

remove_global(marking)[source]

Remove a globally-applied marking from the internal collection or from a parsed document that contain globally-applied markings.

Parameters:marking (MarkingSpecification) – marking to un-apply from global
Raises:MarkingNotFoundError – If marking is not found in the global markings registry.
remove_marking(markable, marking, descendants=False)[source]

Remove the marking MarkingSpecification from markable.

Note

Use remove_global to remove globally applied markings.

Parameters:
  • markable – An object which contains data markings.
  • marking – A MarkingSpecification object.
  • descendants – If True, remove marking from any descendants.
Raises:
  • UnmarkableError – If markable is not an markable entity.
  • MarkingNotFoundError – If markable (or descendant of markable if descendants is True) is marked by marking. If marking was not found in the internal marking collection.
  • MarkingRemovalError – If marking is inherited from an ancestor OR if markable is STIXPackage object.
  • UnknownMarkingError – If marking is not a MarkingSpecification object.
to_dict(*args, **kwargs)[source]

Return a dictionary of the STIX Package represented by the Package object, with markings applied through the MarkingContainer.

Uses the same arguments as stix.Entity.to_dict().

to_xml(*args, **kwargs)[source]

Return an XML string of the STIX package represented by the Package object, with markings applied through the MarkingContainer.

Uses the same arguments as stix.Entity.to_xml().