
    <iG                     x    S r SSKrSSKJrJr  SSKJrJr  SSKJ	r	J
r
  SSKJr   " S S	\5      r " S
 S\5      rg)zPython STIX2 Environment API.    N   )CompositeDataSourceDataStoreMixin)graph_equivalencegraph_similarity)object_equivalenceobject_similarity)parsec                   V    \ rS rSrSr   SS jrSS jrSS jrSS jrSS jr	S	 r
S
rg)ObjectFactory
   a  Easily create STIX objects with default values for certain properties.

Args:
    created_by_ref (optional): Default created_by_ref value to apply to all
        objects created by this factory.
    created (optional): Default created value to apply to all
        objects created by this factory.
    external_references (optional): Default `external_references` value to apply
        to all objects created by this factory.
    object_marking_refs (optional): Default `object_marking_refs` value to apply
        to all objects created by this factory.
    list_append (bool, optional): When a default is set for a list property like
        `external_references` or `object_marking_refs` and a value for
        that property is passed into `create()`, if this is set to True,
        that value will be added to the list alongside the default. If
        this is set to False, the passed in value will replace the
        default. Defaults to True.
Nc                     0 U l         U(       a  U R                  U5        U(       a  U R                  U5        U(       a  U R                  U5        U(       a  U R	                  U5        XPl        SS/U l        g )Nexternal_referencesobject_marking_refs)	_defaultsset_default_creatorset_default_createdset_default_external_refsset_default_object_marking_refs_list_append_list_properties)selfcreated_by_refcreatedr   r   list_appends         K/home/james-whalen/.local/lib/python3.13/site-packages/stix2/environment.py__init__ObjectFactory.__init__   se     $$^4$$W-**+>?001DE'!68M N    c                      XR                   S'   g)z>Set default value for the `created_by_ref` property.

        r   Nr   )r   creators     r   r   !ObjectFactory.set_default_creator0   s     ,3'(r   c                 <    XR                   S'   XR                   S'   g)z7Set default value for the `created` property.

        r   modifiedNr!   )r   r   s     r   r   !ObjectFactory.set_default_created6   s     %,y! &-z"r   c                      XR                   S'   g)z*Set default external references.

        r   Nr!   )r   r   s     r   r   'ObjectFactory.set_default_external_refs?        1D,-r   c                      XR                   S'   g)z&Set default object markings.

        r   Nr!   )r   r   s     r   r   -ObjectFactory.set_default_object_marking_refsE   r)   r   c                    [         R                  " U R                  5      nU(       a  U R                  (       a  [	        U R
                  5      R                  UR                  5       UR                  5       5       Hv  nUR                  U5      nUc  X4	 M  [        X4   [        5      (       d  X4   /X4'   [        U[        5      (       a  X4   R                  U5        Mc  X4   R                  U5        Mx     UR                  " S0 UD6  U" S0 UD6$ )zCreate a STIX object using object factory defaults.

Args:
    cls: the python-stix2 class of the object to be created (eg. Indicator)
    **kwargs: The property/value pairs of the STIX object to be created
 )copydeepcopyr   r   setr   intersectionkeyspop
isinstancelistextendappendupdate)r   clskwargs
properties	list_prop
kwarg_props         r   createObjectFactory.createK   s     ]]4>>2
  !$T%:%:!;!H!HXbXgXgXi!jI!'I!6J!)&1 %j&;TBB1;1F0G
-!*d33"-44Z@"-44Z@ "k '' Z  r   )r   r   r   )NNNNTN)__name__
__module____qualname____firstlineno____doc__r   r   r   r   r   r>   __static_attributes__r-   r   r   r   r   
   s3    ( ,06:O$3-DD!r   r   c                      \ rS rSrSr\" 5       SSS4S jrS r\R                  R                  \l        S r\R                  R                  \l        S r	\R                  R                  \	l        S r
\R                  R                  \
l        S	 r\R                  R                  \l        S
 rS rS r\R                  \l        S r\0 SSSSS4S j5       r\0 SSSSSS4S j5       r\0 SSS4S j5       r\0 SSSS4S j5       rSrg)Environmentk   a  Abstract away some of the nasty details of working with STIX content.

Args:
    factory (ObjectFactory, optional): Factory for creating objects with common
        defaults for certain properties.
    store (DataStore, optional): Data store providing the source and sink for the
        environment.
    source (DataSource, optional): Source for retrieving STIX objects.
    sink (DataSink, optional): Destination for saving STIX objects.
        Invalid if `store` is also provided.

.. automethod:: get
.. automethod:: all_versions
.. automethod:: query
.. automethod:: creator_of
.. automethod:: relationships
.. automethod:: related_to
.. automethod:: add

Nc                 ,   Xl         [        5       U l        U(       a6  U R                  R                  UR                  5        UR                  U l        U(       a  U R                  R                  U5        U(       a  U(       a  [        S5      eX@l        g g )NzEData store already provided! Environment may only have one data sink.)factoryr   sourceadd_data_sourcesink
ValueError)r   rK   storerL   rN   s        r   r   Environment.__init__   sf    )+KK''5

DIKK''/ !hiiI r   c                 :    U R                   R                  " U0 UD6$ r@   )rK   r>   r   argsr:   s      r   r>   Environment.create   s    ||""D3F33r   c                 :    U R                   R                  " U0 UD6$ r@   )rK   r   rS   s      r   r   Environment.set_default_creator       ||//@@@r   c                 :    U R                   R                  " U0 UD6$ r@   )rK   r   rS   s      r   r   Environment.set_default_created   rX   r   c                 :    U R                   R                  " U0 UD6$ r@   )rK   r   rS   s      r   r   %Environment.set_default_external_refs   s    ||55tFvFFr   c                 :    U R                   R                  " U0 UD6$ r@   )rK   r   rS   s      r   r   +Environment.set_default_object_marking_refs   s    ||;;TLVLLr   c                 N    U R                   R                  R                  " U0 UD6$ r@   rL   filtersaddrS   s      r   add_filtersEnvironment.add_filters   "    {{""&&777r   c                 N    U R                   R                  R                  " U0 UD6$ r@   r`   rS   s      r   
add_filterEnvironment.add_filter   re   r   c                     [        U0 UD6$ r@   )_parserS   s      r   r
   Environment.parse   s    t&v&&r   c                 X    UR                  SS5      nU(       a  U R                  U5      $ g)aC  Retrieve the Identity refered to by the object's `created_by_ref`.

Args:
    obj: The STIX object whose `created_by_ref` property will be looked
        up.

Returns:
    str: The STIX object's creator, or None, if the object contains no
        `created_by_ref` property or the object's creator cannot be
        found.

r    N)get)r   obj
creator_ids      r   
creator_ofEnvironment.creator_of   s*     WW-r2
88J''r   Fr   c           
           [        XX#XEXg40 UD6$ )ae  This method returns a measure of how similar the two objects are.

Args:
    obj1: A stix2 object instance
    obj2: A stix2 object instance
    prop_scores: A dictionary that can hold individual property scores,
        weights, contributing score, matching score and sum of weights.
    ds1 (optional): A DataStore object instance from which to pull related objects
    ds2 (optional): A DataStore object instance from which to pull related objects
    ignore_spec_version: A boolean indicating whether to test object types
        that belong to different spec versions (STIX 2.0 and STIX 2.1 for example).
        If set to True this check will be skipped.
    versioning_checks: A boolean indicating whether to test multiple revisions
        of the same object (when present) to maximize similarity against a
        particular version. If set to True the algorithm will perform this step.
    max_depth: A positive integer indicating the maximum recursion depth the
        algorithm can reach when de-referencing objects and performing the
        object_similarity algorithm.
    weight_dict: A dictionary that can be used to override what checks are done
        to objects in the similarity process.

Returns:
    float: A number between 0.0 and 100.0 as a measurement of similarity.

Warning:
    Object types need to have property weights defined for the similarity process.
    Otherwise, those objects will not influence the final score. The WEIGHTS
    dictionary under `stix2.equivalence.object` can give you an idea on how to add
    new entries and pass them via the `weight_dict` argument. Similarly, the values
    or methods can be fine tuned for a particular use case.

Note:
    Default weight_dict:

    .. include:: ../similarity_weights.rst

Note:
    This implementation follows the Semantic Equivalence Committee Note.
    see `the Committee Note <link here>`__.

)r	   )	obj1obj2prop_scoresds1ds2ignore_spec_versionversioning_checks	max_depthweight_dicts	            r   r	   Environment.object_similarity   s$    ^ !#
,7
 	
r   F   c	                 "    [        XX#XEXgU4	0 U	D6$ )a  This method returns a true/false value if two objects are semantically equivalent.
Internally, it calls the object_similarity function and compares it against the given
threshold value.

Args:
    obj1: A stix2 object instance
    obj2: A stix2 object instance
    prop_scores: A dictionary that can hold individual property scores,
        weights, contributing score, matching score and sum of weights.
    threshold: A numerical value between 0 and 100 to determine the minimum
        score to result in successfully calling both objects equivalent. This
        value can be tuned.
    ds1 (optional): A DataStore object instance from which to pull related objects
    ds2 (optional): A DataStore object instance from which to pull related objects
    ignore_spec_version: A boolean indicating whether to test object types
        that belong to different spec versions (STIX 2.0 and STIX 2.1 for example).
        If set to True this check will be skipped.
    versioning_checks: A boolean indicating whether to test multiple revisions
        of the same object (when present) to maximize similarity against a
        particular version. If set to True the algorithm will perform this step.
    max_depth: A positive integer indicating the maximum recursion depth the
        algorithm can reach when de-referencing objects and performing the
        object_similarity algorithm.
    weight_dict: A dictionary that can be used to override what checks are done
        to objects in the similarity process.

Returns:
    bool: True if the result of the object similarity is greater than or equal to
        the threshold value. False otherwise.

Warning:
    Object types need to have property weights defined for the similarity process.
    Otherwise, those objects will not influence the final score. The WEIGHTS
    dictionary under `stix2.equivalence.object` can give you an idea on how to add
    new entries and pass them via the `weight_dict` argument. Similarly, the values
    or methods can be fine tuned for a particular use case.

Note:
    Default weight_dict:

    .. include:: ../similarity_weights.rst

Note:
    This implementation follows the Semantic Equivalence Committee Note.
    see `the Committee Note <link here>`__.

)r   )
rt   ru   rv   	thresholdrw   rx   ry   rz   r{   r|   s
             r   r   Environment.object_equivalence   s&    j "I
AL
 	
r   c                     [        XX#XE40 UD6$ )a  This method returns a similarity score for two given graphs.
Each DataStore can contain a connected or disconnected graph and the
final result is weighted over the amount of objects we managed to compare.
This approach builds on top of the object-based similarity process
and each comparison can return a value between 0 and 100.

Args:
    ds1: A DataStore object instance representing your graph
    ds2: A DataStore object instance representing your graph
    prop_scores: A dictionary that can hold individual property scores,
        weights, contributing score, matching score and sum of weights.
    ignore_spec_version: A boolean indicating whether to test object types
        that belong to different spec versions (STIX 2.0 and STIX 2.1 for example).
        If set to True this check will be skipped.
    versioning_checks: A boolean indicating whether to test multiple revisions
        of the same object (when present) to maximize similarity against a
        particular version. If set to True the algorithm will perform this step.
    max_depth: A positive integer indicating the maximum recursion depth the
        algorithm can reach when de-referencing objects and performing the
        object_similarity algorithm.
    weight_dict: A dictionary that can be used to override what checks are done
        to objects in the similarity process.

Returns:
    float: A number between 0.0 and 100.0 as a measurement of similarity.

Warning:
    Object types need to have property weights defined for the similarity process.
    Otherwise, those objects will not influence the final score. The WEIGHTS
    dictionary under `stix2.equivalence.graph` can give you an idea on how to add
    new entries and pass them via the `weight_dict` argument. Similarly, the values
    or methods can be fine tuned for a particular use case.

Note:
    Default weight_dict:

    .. include:: ../similarity_weights.rst

Note:
    This implementation follows the Semantic Equivalence Committee Note.
    see `the Committee Note <link here>`__.

)r   )rw   rx   rv   ry   rz   r{   r|   s          r   r   Environment.graph_similarity-  s"    `  k
,7
 	
r   c           	           [        XX#UXV40 UD6$ )aT  This method returns a true/false value if two graphs are semantically equivalent.
Internally, it calls the graph_similarity function and compares it against the given
threshold value.

Args:
    ds1: A DataStore object instance representing your graph
    ds2: A DataStore object instance representing your graph
    prop_scores: A dictionary that can hold individual property scores,
        weights, contributing score, matching score and sum of weights.
    threshold: A numerical value between 0 and 100 to determine the minimum
        score to result in successfully calling both graphs equivalent. This
        value can be tuned.
    ignore_spec_version: A boolean indicating whether to test object types
        that belong to different spec versions (STIX 2.0 and STIX 2.1 for example).
        If set to True this check will be skipped.
    versioning_checks: A boolean indicating whether to test multiple revisions
        of the same object (when present) to maximize similarity against a
        particular version. If set to True the algorithm will perform this step.
    max_depth: A positive integer indicating the maximum recursion depth the
        algorithm can reach when de-referencing objects and performing the
        object_similarity algorithm.
    weight_dict: A dictionary that can be used to override what checks are done
        to objects in the similarity process.

Returns:
    bool: True if the result of the graph similarity is greater than or equal to
        the threshold value. False otherwise.

Warning:
    Object types need to have property weights defined for the similarity process.
    Otherwise, those objects will not influence the final score. The WEIGHTS
    dictionary under `stix2.equivalence.graph` can give you an idea on how to add
    new entries and pass them via the `weight_dict` argument. Similarly, the values
    or methods can be fine tuned for a particular use case.

Note:
    Default weight_dict:

    .. include:: ../similarity_weights.rst

Note:
    This implementation follows the Semantic Equivalence Committee Note.
    see `the Committee Note <link here>`__.

)r   )rw   rx   rv   r   ry   rz   r{   r|   s           r   r   Environment.graph_equivalenceb  s%    f !k.A
,7
 	
r   )rK   rN   rL   )rA   rB   rC   rD   rE   r   r   r>   r   r   r   r   rc   rg   r
   rj   rq   staticmethodr	   r   r   r   rF   r-   r   r   rH   rH   k   sF   *  -d4d 4"))11FNA"/"C"C"K"KA"/"C"C"K"KG(5(O(O(W(W%M.;.[.[.c.c#+88'NNEM&  "$!U1
 1
f  "bd!U7
 7
r  e12
 2
h  B!U5
 5
r   rH   )rE   r.   	datastorer   r   equivalence.graphr   r   equivalence.objectr   r	   parsingr
   rj   objectr   rH   r-   r   r   <module>r      s4    #  : B E $^!F ^!Bm
. m
r   