Version: 1.2.0.0

stix.indicator.indicator Module

Overview

The stix.indicator.indicator module implements IndicatorType STIX Language construct. The IndicatorType characterizes a cyber threat indicator made up of a pattern identifying certain observable conditions as well as contextual information about the patterns meaning, how and when it should be acted on, etc.

Documentation Resources

Classes

class stix.indicator.indicator.Indicator(id_=None, idref=None, timestamp=None, title=None, description=None, short_description=None)

Bases: stix.base.BaseCoreComponent

Implementation of the STIX Indicator.

Parameters:
  • id_ (optional) – An identifier. If None, a value will be generated via stix.utils.create_id(). If set, this will unset the idref property.
  • idref (optional) – An identifier reference. If set this will unset the id_ property.
  • title (optional) – A string title.
  • timestamp (optional) – A timestamp value. Can be an instance of datetime.datetime or str.
  • description (optional) – A string description.
  • short_description (optional) – A string short description.
add_alternative_id(value)

Adds an alternative id to the alternative_id list property.

Note

If None is passed in no value is added to the alternative_id list property.

Parameters:value – An identifier value.
add_description(description)

Adds a description to the descriptions collection.

This is the same as calling “foo.descriptions.add(bar)”.

add_indicated_ttp(v)

Adds an Indicated TTP to the indicated_ttps list property of this Indicator.

The v parameter must be an instance of stix.common.related.RelatedTTP or stix.ttp.TTP.

If the v parameter is None, no item wil be added to the indicated_ttps list property.

Note

If the v parameter is not an instance of stix.common.related.RelatedTTP an attempt will be made to convert it to one.

Parameters:v – An instance of stix.common.related.RelatedTTP or stix.ttp.TTP.
Raises:ValueError – If the v parameter cannot be converted into an instance of stix.common.related.RelatedTTP
add_indicator_type(value)

Adds a value to the indicator_types list property.

The value parameter can be a str or an instance of stix.common.vocabs.VocabString.

Note

If the value parameter is a str instance, an attempt will be made to convert it into an instance of stix.common.vocabs.IndicatorType

Parameters:value – An instance of stix.common.vocabs.VocabString or str.
Raises:ValueError – If the value param is a str instance that cannot be converted into an instance of stix.common.vocabs.IndicatorType.
add_kill_chain_phase(value)

Add a new Kill Chain Phase reference to this Indicator.

Parameters:value – a stix.common.kill_chains.KillChainPhase or a str representing the phase_id of. Note that you if you are defining a custom Kill Chain, you need to add it to the STIX package separately.
add_object(object_)

Adds a python-cybox Object instance to the observables list property.

This is the same as calling indicator.add_observable(object_).

Note

If the object param is not an instance of cybox.core.Object an attempt will be made to to convert it into one before wrapping it in an cybox.core.Observable layer.

Parameters:object_ – An instance of cybox.core.Object or an object that can be converted into an instance of cybox.core.Observable
Raises:ValueError – if the object_ param cannot be converted to an instance of cybox.core.Observable.
add_observable(observable)

Adds an observable to the observables list property of the Indicator.

If the observable parameter is None, no item will be added to the observables list.

Note

The STIX Language dictates that an Indicator can have only one Observable under it. Because of this, the to_xml() method will convert the observables list into an cybox.core.ObservableComposition instance, in which each item in the observables list will be added to the composition. By default, the operator of the composition layer will be set to "OR". The operator value can be changed via the observable_composition_operator property.

Parameters:observable – An instance of cybox.core.Observable or an object type that can be converted into one.
Raises:ValueError – If the observable param cannot be converted into an instance of cybox.core.Observable.

Adds a Related Campaign to this Indicator.

The value parameter must be an instance of RelatedCampaignRef or CampaignRef.

If the value parameter is None, no item wil be added to the related_campaigns collection.

Calling this method is the same as calling append() on the related_campaigns property.

See also

The RelatedCampaignRef documentation.

Note

If the value parameter is not an instance of RelatedCampaignRef an attempt will be made to convert it to one.

Parameters:value – An instance of RelatedCampaignRef or Campaign.
Raises:ValueError – If the value parameter cannot be converted into an instance of RelatedCampaignRef

Adds an Related Indicator to the related_indicators list property of this Indicator.

The indicator parameter must be an instance of stix.common.related.RelatedIndicator or Indicator.

If the indicator parameter is None, no item wil be added to the related_indicators list property.

Calling this method is the same as calling append() on the related_indicators proeprty.

See also

The RelatedIndicators documentation.

Note

If the tm parameter is not an instance of stix.common.related.RelatedIndicator an attempt will be made to convert it to one.

Parameters:indicator – An instance of Indicator or stix.common.related.RelatedIndicator.
Raises:ValueError – If the indicator parameter cannot be converted into an instance of stix.common.related.RelatedIndicator
add_short_description(description)

Adds a description to the short_descriptions collection.

This is the same as calling “foo.short_descriptions.add(bar)”.

add_test_mechanism(tm)

Adds an Test Mechanism to the test_mechanisms list property of this Indicator.

The tm parameter must be an instance of a stix.indicator.test_mechanism._BaseTestMechanism implementation.

If the tm parameter is None, no item will be added to the test_mechanisms list property.

See also

Test Mechanism implementations are found under the stix.extensions.test_mechanism package.

Parameters:tm – An instance of a stix.indicator.test_mechanism._BaseTestMechanism implementation.
Raises:ValueError – If the tm parameter is not an instance of stix.indicator.test_mechanism._BaseTestMechanism
add_valid_time_position(value)

Adds an valid time position to the valid_time_positions property list.

If value is None, no item is added to the value_time_positions list.

Parameters:value – An instance of stix.indicator.valid_time.ValidTime.
Raises:ValueError – If the value argument is not an instance of stix.indicator.valid_time.ValidTime.
alternative_id

An alternative identifi er for this Indicator

This property can be set to a single string identifier or a list of identifiers. If set to a single object, the object will be inserted into an empty list internally.

Default Value: Empty list

Returns:A list of alternative ids.
confidence

The confidence for this Indicator.

This property can be set to an instance of str, stix.common.vocabs.VocabString, or stix.common.confidence.Confidence.

Default Value: None

Note

If set to an instance of str or stix.common.vocabs.VocabString, that value will be wrapped in an instance of stix.common.confidence.Confidence.

Returns:An instance of of stix.common.confidence.Confidence.
Raises:ValueError – If set to a str value that cannot be converted into an instance of stix.common.confidence.Confidence.
description

A single description about the contents or purpose of this object.

Default Value: None

Note

If this object has more than one description set, this will return the description with the lowest ordinality value.

Returns:An instance of – class:.StructuredText
descriptions

A StructuredTextList object, containing descriptions about the purpose or intent of this object.

This is typically used for the purpose of providing multiple descriptions with different classificaton markings.

Iterating over this object will yield its contents sorted by their ordinality value.

Default Value: Empty StructuredTextList object.

Note

IF this is set to a value that is not an instance of StructuredText, an effort will ne made to convert it. If this is set to an iterable, any values contained that are not an instance of StructuredText will be be converted.

Returns:An instance of StructuredTextList
find(id_)

Searches the children of a Entity implementation for an object with an id_ property that matches id_.

get_produced_time()

Gets the produced time for this Indicator.

This is the same as calling produced_time = indicator.producer.time.produced_time.

Returns:None or an instance of cybox.common.DateTimeWithPrecision.
get_received_time()

Gets the received time for this Indicator.

This is the same as calling received_time = indicator.producer.time.received_time.

Returns:None or an instance of cybox.common.DateTimeWithPrecision.
id_

The id_ property serves as an identifier. This is automatically set during __init__().

Default Value: None

Note

Both the id_ and idref properties cannot be set at the same time. Setting one will unset the other!

Returns:A string id.
idref

The idref property must be set to the id_ value of another object instance of the same type. An idref does not need to resolve to a local object instance.

Default Value: None.

Note

Both the id_ and idref properties cannot be set at the same time. Setting one will unset the other!

Returns:The value of the idref property
indicator_types

A list of indicator types for this Indicator.

This property can be set to lists or single instances of str or stix.common.vocabs.VocabString or an instance of IndicatorTypes.

Note

If an instance of str is passed in (or a list containing str values) an attempt will be made to convert that string value to an instance of stix.common.vocabs.IndicatorType.

Default Value: An empty IndicatorTypes instance.

See also

Documentation for IndicatorTypes.

Returns:An instance of IndicatorTypes.
information_source

Contains information about the source of this object.

Default Value: None

Returns:An instance of InformationSource
Raises:ValueError – If set to a value that is not None and not an instance of InformationSource
observable

A convenience property for accessing or setting the only cybox.core.Observable instance held by this Indicator.

Default Value: Empty list.

Setting this property results in the observables property being reinitialized to an empty list and appending the input value, resulting in a list containing one value.

Note

If the observables list contains more than one item, this property will only return the first item in the list.

Returns:An instance of cybox.core.Observable.
Raises:ValueError – If set to a value that cannot be converted to an instance of cybox.core.Observable.
observables

A list of cybox.core.Observable instances. This can be set to a single object instance or a list of objects.

Note

If the input value or values are not instance(s) of cybox.core.Observable, an attempt will be made to convert the value to an instance of cybox.core.Observable.

Default Value: Empty list

Returns:A list of cybox.core.Observable instances.
Raises:ValueError – If set to a value that cannot be converted to an instance of cybox.core.Observable.
producer

Contains information about the source of the Indicator.

Default Value: None

Returns:An instance of stix.common.information_source.InformationSource
Raises:ValueError – If set to a value that is not None and not an instance of stix.common.information_source.InformationSource
set_produced_time(produced_time)

Sets the produced_time property of the producer property instance fo produced_time.

This is the same as calling indicator.producer.time.produced_time = produced_time.

The produced_time parameter must be an instance of str, datetime.datetime, or cybox.common.DateTimeWithPrecision.

Note

If produced_time is a str or datetime.datetime instance an attempt will be made to convert it into an instance of cybox.common.DateTimeWithPrecision.

Parameters:produced_time – An instance of str, datetime.datetime, or cybox.common.DateTimeWithPrecision.
set_producer_identity(identity)

Sets the name of the producer of this indicator.

This is the same as calling indicator.producer.identity.name = identity.

If the producer property is None, it will be initialized to an instance of stix.common.information_source.InformationSource.

If the identity property of the producer instance is None, it will be initialized to an instance of stix.common.identity.Identity.

Note

if the identity parameter is not an instance stix.common.identity.Identity an attempt will be made to convert it to one.

Parameters:identity – An instance of str or stix.common.identity.Identity.
set_received_time(received_time)

Sets the received time for this Indicator.

This is the same as calling indicator.producer.time.produced_time = produced_time.

The received_time parameter must be an instance of str, datetime.datetime, or cybox.common.DateTimeWithPrecision.

Parameters:received_time – An instance of str, datetime.datetime, or cybox.common.DateTimeWithPrecision.

Note

If received_time is a str or datetime.datetime instance an attempt will be made to convert it into an instance of cybox.common.DateTimeWithPrecision.

short_description

A single short description about the contents or purpose of this object.

Default Value: None

Note

If this object has more than one short description set, this will return the description with the lowest ordinality value.

Returns:An instance of – class:.StructuredText
short_descriptions

A StructuredTextList object, containing short descriptions about the purpose or intent of this object.

This is typically used for the purpose of providing multiple short descriptions with different classificaton markings.

Iterating over this object will yield its contents sorted by their ordinality value.

Default Value: Empty StructuredTextList object.

Note

IF this is set to a value that is not an instance of StructuredText, an effort will ne made to convert it. If this is set to an iterable, any values contained that are not an instance of StructuredText will be be converted.

Returns:An instance of – class:.StructuredTextList
timestamp

The timestam property declares the time of creation and is automatically set in __init__().

This property can accept datetime.datetime or str values. If an str value is supplied, a best-effort attempt is made to parse it into an instance of datetime.datetime.

Default Value: A datetime.dateime instance with a value of the date/time when __init__() was called.

Note

If an idref is set during __init__(), the value of timestamp will not automatically generated and instead default to the timestamp parameter, which has a default value of None.

Returns:An instance of datetime.datetime.
valid_time_positions

A list of valid time positions for this Indicator.

This property can be set to a single instance or a list of stix.indicator.valid_time.ValidTime instances. If set to a single instance, that object is converted into a list containing one item.

Default Value: Empty list

Returns:A list of stix.indicator.valid_time.ValidTime instances.
version

The schematic version of this component. This property will always return None unless it is set to a value different than self.__class__._version.

Note

This property refers to the version of the schema component type and should not be used for the purpose of content versioning.

Default Value: None

Returns:The value of the version property if set to a value different than self.__class__._version
class stix.indicator.indicator.CompositeIndicatorExpression(operator='OR', *args)

Bases: stix.base.EntityList

Implementation of the STIX CompositeIndicatorExpressionType.

The CompositeIndicatorExpression class implements methods found on collections.MutableSequence and as such can be interacted with as a list (e.g., append()).

Note

The append() method can only accept instances of Indicator.

Examples

Add a Indicator instance to an instance of CompositeIndicatorExpression:

>>> i = Indicator()
>>> comp = CompositeIndicatorExpression()
>>> comp.append(i)

Create a CompositeIndicatorExpression from a list of Indicator instances using *args argument list:

>>> list_indicators = [Indicator() for i in xrange(10)]
>>> comp = CompositeIndicatorExpression(CompositeIndicatorExpression.OP_OR, *list_indicators)
>>> len(comp)
10
Parameters:
  • operator (str, optional) – The logical composition operator. Must be "AND" or "OR".
  • *args – Variable length argument list of Indicator instances.
OP_AND str

String "AND"

OP_OR str

String "OR"

OPERATORS tuple

Tuple of allowed operator values.

operator str

The logical composition operator. Must be "AND" or "OR".

class stix.indicator.indicator.RelatedIndicators(related_indicators=None, scope=None)

Bases: stix.common.related.GenericRelationshipList

The RelatedIndicators class provides functionality for adding stix.common.related.RelatedIndicator instances to an Indicator instance.

The RelatedIndicators class implements methods found on collections.MutableSequence and as such can be interacted with as a list (e.g., append()).

The append() method can accept instances of stix.common.related.RelatedIndicator or Indicator as an argument.

Note

Calling append() with an instance of stix.coa.CourseOfAction will wrap that instance in a stix.common.related.RelatedIndicator layer, with item set to the Indicator instance.

Examples

Append an instance of Indicator to the Indicator.related_indicators property. The instance of Indicator will be wrapped in an instance of stix.common.related.RelatedIndicator:

>>> related = Indicator()
>>> parent_indicator = Indicator()
>>> parent_indicator.related_indicators.append(related)
>>> print type(indicator.related_indicators[0])
<class 'stix.common.related.RelatedIndicator'>

Iterate over the related_indicators property of an Indicator instance and print the ids of each underlying Indicator` instance:

>>> for related in indicator.related_indicators:
>>>     print related.item.id_
Parameters:
scope str

The scope of the items. Can be set to "inclusive" or "exclusive". See stix.common.related.GenericRelationshipList documentation for more information.

class stix.indicator.indicator.RelatedCampaignRefs(related_campaign_refs=None, scope=None)

Bases: stix.common.related.GenericRelationshipList

class stix.indicator.indicator.SuggestedCOAs(suggested_coas=None, scope=None)

Bases: stix.common.related.GenericRelationshipList

The SuggestedCOAs class provides functionality for adding stix.common.related.RelatedCOA instances to an Indicator instance.

The SuggestedCOAs class implements methods found on collections.MutableSequence and as such can be interacted with as a list (e.g., append()).

The append() method can accept instances of stix.common.related.RelatedCOA or stix.coa.CourseOfAction as an argument.

Note

Calling append() with an instance of stix.coa.CourseOfAction will wrap that instance in a stix.common.related.RelatedCOA layer, with the item set to the stix.coa.CourseOfAction instance.

Examples

Append an instance of stix.coa.CourseOfAction to the Indicator.suggested_coas property. The instance of stix.coa.CourseOfAction will be wrapped in an instance of stix.common.related.RelatedCOA.

>>> coa = CourseOfAction()
>>> indicator = Indicator()
>>> indicator.suggested_coas.append(coa)
>>> print type(indicator.suggested_coas[0])
<class 'stix.common.related.RelatedCOA'>

Iterate over the suggested_coas property of an Indicator instance and print the ids of each underlying stix.coa.CourseOfAction instance.

>>> for related_coa in indicator.suggested_coas:
>>>     print related_coa.item.id_
Parameters:
scope str

The scope of the items. Can be set to "inclusive" or "exclusive". See stix.common.related.GenericRelationshipList documentation for more information.

class stix.indicator.indicator.IndicatorTypes(*args)

Bases: stix.base.TypedList

A stix.common.vocabs.VocabString collection which defaults to stix.common.vocabs.IndicatorType. This class implements methods found on collections.MutableSequence and as such can be interacted with like a list.

Note

The append() method can accept str or stix.common.vocabs.VocabString instances. If a str instance is passed in, an attempt will be made to convert it to an instance of stix.common.vocabs.IndicatorType.

Examples

Add an instance of stix.common.vocabs.IndicatorType:

>>> from stix.common.vocabs import IndicatorType
>>> itypes = IndicatorTypes()
>>> type_ = IndicatorType(IndicatorType.TERM_IP_WATCHLIST)
>>> itypes.append(type_)
>>> print len(itypes)
1

Add a string value:

>>> from stix.common.vocabs import IndicatorType
>>> itypes = IndicatorTypes()
>>> type(IndicatorType.TERM_IP_WATCHLIST)
<type 'str'>
>>> itypes.append(IndicatorType.TERM_IP_WATCHLIST)
>>> print len(itypes)
1
Parameters:*args – Variable length argument list of strings or stix.common.vocabs.VocabString instances.