Version: 1.1.1.8
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 viamixbox.idgen.create_id()
. If set, this will unset theidref
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
orstr
. - 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 thealternative_id
list property.Parameters: value – An identifier value.
-
add_indicated_ttp
(v)¶ Adds an Indicated TTP to the
indicated_ttps
list property of thisIndicator
.The v parameter must be an instance of
stix.common.related.RelatedTTP
orstix.ttp.TTP
.If the v parameter is
None
, no item wil be added to theindicated_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
orstix.ttp.TTP
.Raises: ValueError
– If the v parameter cannot be converted into an instance ofstix.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 ofstix.common.vocabs.VocabString
.Note
If the value parameter is a
str
instance, an attempt will be made to convert it into an instance ofstix.common.vocabs.IndicatorType
Parameters: value – An instance of stix.common.vocabs.VocabString
orstr
.Raises: ValueError
– If the value param is astr
instance that cannot be converted into an instance ofstix.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 ancybox.core.Observable
layer.Parameters: object – An instance of cybox.core.Object
or an object that can be converted into an instance ofcybox.core.Observable
Raises: ValueError
– if the object_ param cannot be converted to an instance ofcybox.core.Observable
.
-
add_observable
(observable)¶ Adds an observable to the
observable
property of theIndicator
.If the observable parameter is
None
, no item will be added to theobservable
property.Note
The STIX Language dictates that an
Indicator
can have only oneObservable
under it. Because of this, when a user adds anotherObservable
a new, emptyObservable
will be crated and append the existing and newobservable
using theObservableComposition
property. To access the top levelObservable
can be achieved by theobservable
property .By default, theoperator
of the composition layer will be set to"OR"
. Theoperator
value can be changed via theobservable_composition_operator
property.Setting
observable
orobservables
with re-initialize the property and lose allObservable
in the composition layer.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 ofcybox.core.Observable
.
Adds a Related Campaign to this Indicator.
The value parameter must be an instance of
RelatedCampaignRef
orCampaignRef
.If the value parameter is
None
, no item wil be added to therelated_campaigns
collection.Calling this method is the same as calling
append()
on therelated_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
orCampaign
.Raises: ValueError
– If the value parameter cannot be converted into an instance ofRelatedCampaignRef
Adds an Related Indicator to the
related_indicators
list property of thisIndicator
.The indicator parameter must be an instance of
stix.common.related.RelatedIndicator
orIndicator
.If the indicator parameter is
None
, no item wil be added to therelated_indicators
list property.Calling this method is the same as calling
append()
on therelated_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
orstix.common.related.RelatedIndicator
.Raises: ValueError
– If the indicator parameter cannot be converted into an instance ofstix.common.related.RelatedIndicator
-
add_test_mechanism
(tm)¶ Adds an Test Mechanism to the
test_mechanisms
list property of thisIndicator
.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 thetest_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 ofstix.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 thevalue_time_positions
list.Parameters: value – An instance of stix.indicator.valid_time.ValidTime
.Raises: ValueError
– If the value argument is not an instance ofstix.indicator.valid_time.ValidTime
.
-
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 ofcybox.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 ofcybox.common.DateTimeWithPrecision
.
-
observables
¶ A list of
cybox.core.Observable
instances. This can be set to a single object instance or a list of objects.Note
If only one Observable is set, this property will return a list with the
observable
property.If multiple
cybox.core.Observable
this property will return Observables under thecybox.core.ObservableComposition
.Access to the top level
cybox.core.Observable
is made viaobservable
property.- Default Value:
- Empty
list
.
Returns: A list
ofcybox.core.Observable
instances.
-
set_produced_time
(produced_time)¶ Sets the
produced_time
property of theproducer
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
, orcybox.common.DateTimeWithPrecision
.Note
If produced_time is a
str
ordatetime.datetime
instance an attempt will be made to convert it into an instance ofcybox.common.DateTimeWithPrecision
.Parameters: produced_time – An instance of str
,datetime.datetime
, orcybox.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 isNone
, it will be initialized to an instance ofstix.common.information_source.InformationSource
.If the
identity
property of theproducer
instance isNone
, it will be initialized to an instance ofstix.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
orstix.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
, orcybox.common.DateTimeWithPrecision
.Parameters: received_time – An instance of str
,datetime.datetime
, orcybox.common.DateTimeWithPrecision
.Note
If received_time is a
str
ordatetime.datetime
instance an attempt will be made to convert it into an instance ofcybox.common.DateTimeWithPrecision
.
- id (optional) – An identifier. If
-
class
stix.indicator.indicator.
CompositeIndicatorExpression
(operator='OR', *args)¶ Bases:
mixbox.entities.EntityList
Implementation of the STIX
CompositeIndicatorExpressionType
.The
CompositeIndicatorExpression
class implements methods found oncollections.MutableSequence
and as such can be interacted with as alist
(e.g.,append()
).Note
The
append()
method can only accept instances ofIndicator
.Examples
Add a
Indicator
instance to an instance ofCompositeIndicatorExpression
:>>> i = Indicator() >>> comp = CompositeIndicatorExpression() >>> comp.append(i)
Create a
CompositeIndicatorExpression
from a list ofIndicator
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"
.
- operator (str, optional) – The logical composition operator. Must be
-
class
stix.indicator.indicator.
RelatedIndicators
(related_indicators=None, scope=None)¶ Bases:
stix.common.related.GenericRelationshipList
The
RelatedIndicators
class provides functionality for addingstix.common.related.RelatedIndicator
instances to anIndicator
instance.The
RelatedIndicators
class implements methods found oncollections.MutableSequence
and as such can be interacted with as alist
(e.g.,append()
).The
append()
method can accept instances ofstix.common.related.RelatedIndicator
orIndicator
as an argument.Note
Calling
append()
with an instance ofstix.coa.CourseOfAction
will wrap that instance in astix.common.related.RelatedIndicator
layer, withitem
set to theIndicator
instance.Examples
Append an instance of
Indicator
to theIndicator.related_indicators
property. The instance ofIndicator
will be wrapped in an instance ofstix.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 anIndicator
instance and print the ids of each underlyingIndicator`
instance:>>> for related in indicator.related_indicators: >>> print(related.item.id_)
Parameters: - related_indicators (list, optional) – A list of
Indicator
orstix.common.related.RelatedIndicator
instances. - scope (str, optional) – The scope of the items. Can be set to
"inclusive"
or"exclusive"
. Seestix.common.related.GenericRelationshipList
documentation for more information.
-
scope
¶ str
The scope of the items. Can be set to
"inclusive"
or"exclusive"
. Seestix.common.related.GenericRelationshipList
documentation for more information.
- related_indicators (list, optional) – A list of
-
class
stix.indicator.indicator.
SuggestedCOAs
(suggested_coas=None, scope=None)¶ Bases:
stix.common.related.GenericRelationshipList
The
SuggestedCOAs
class provides functionality for addingstix.common.related.RelatedCOA
instances to anIndicator
instance.The
SuggestedCOAs
class implements methods found oncollections.MutableSequence
and as such can be interacted with as alist
(e.g.,append()
).The
append()
method can accept instances ofstix.common.related.RelatedCOA
orstix.coa.CourseOfAction
as an argument.Note
Calling
append()
with an instance ofstix.coa.CourseOfAction
will wrap that instance in astix.common.related.RelatedCOA
layer, with theitem
set to thestix.coa.CourseOfAction
instance.Examples
Append an instance of
stix.coa.CourseOfAction
to theIndicator.suggested_coas
property. The instance ofstix.coa.CourseOfAction
will be wrapped in an instance ofstix.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 anIndicator
instance and print the ids of each underlyingstix.coa.CourseOfAction
instance.>>> for related_coa in indicator.suggested_coas: >>> print(related_coa.item.id_)
Parameters: - suggested_coas (list) – A list of
stix.coa.CourseOfAction
orstix.common.related.RelatedCOA
instances. - scope (str) – The scope of the items. Can be set to
"inclusive"
or"exclusive"
. Seestix.common.related.GenericRelationshipList
documentation for more information.
-
scope
¶ str
The scope of the items. Can be set to
"inclusive"
or"exclusive"
. Seestix.common.related.GenericRelationshipList
documentation for more information.
- suggested_coas (list) – A list of
-
class
stix.indicator.indicator.
IndicatorTypes
(*args)¶ Bases:
stix.base.TypedList
A
stix.common.vocabs.VocabString
collection which defaults tostix.common.vocabs.IndicatorType
. This class implements methods found oncollections.MutableSequence
and as such can be interacted with like alist
.Note
The
append()
method can acceptstr
orstix.common.vocabs.VocabString
instances. If astr
instance is passed in, an attempt will be made to convert it to an instance ofstix.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.