object¶
Python APIs for STIX 2 Object-based Semantic Equivalence.
-
check_property_present(prop, obj1, obj2)¶ Helper method checks if a property is present on both objects.
-
custom_pattern_based(pattern1, pattern2)¶ Performs a matching on Indicator Patterns.
Parameters: - pattern1 – An Indicator pattern
- pattern2 – An Indicator pattern
Returns: float – Number between 0.0 and 1.0 depending on match criteria.
-
exact_match(val1, val2)¶ Performs an exact value match based on two values
Parameters: - val1 – A value suitable for an equality test.
- val2 – A value suitable for an equality test.
Returns: float – 1.0 if the value matches exactly, 0.0 otherwise.
-
list_reference_check(refs1, refs2, ds1, ds2, **weights)¶ For objects that contain multiple references (i.e., object_refs) perform the same de-reference procedure and perform object-based semantic equivalence. The score influences the objects containing these references. The result is weighted on the amount of unique objects that could 1) be de-referenced 2)
-
partial_external_reference_based(refs1, refs2)¶ Performs a matching on External References.
Parameters: - refs1 – A list of external references.
- refs2 – A list of external references.
Returns: float – Number between 0.0 and 1.0 depending on matches.
-
partial_list_based(l1, l2)¶ Performs a partial list matching via finding the intersection between common values.
Parameters: - l1 – A list of values.
- l2 – A list of values.
Returns: float – 1.0 if the value matches exactly, 0.0 otherwise.
-
partial_location_distance(lat1, long1, lat2, long2, threshold)¶ Given two coordinates perform a matching based on its distance using the Haversine Formula.
Parameters: - lat1 – Latitude value for first coordinate point.
- lat2 – Latitude value for second coordinate point.
- long1 – Longitude value for first coordinate point.
- long2 – Longitude value for second coordinate point.
- threshold (float) – A kilometer measurement for the threshold distance between these two points.
Returns: float – Number between 0.0 and 1.0 depending on match.
-
partial_string_based(str1, str2)¶ Performs a partial string match using the Jaro-Winkler distance algorithm.
Parameters: - str1 – A string value to check.
- str2 – A string value to check.
Returns: float – Number between 0.0 and 1.0 depending on match criteria.
-
partial_timestamp_based(t1, t2, tdelta)¶ Performs a timestamp-based matching via checking how close one timestamp is to another.
Parameters: - t1 – A datetime string or STIXdatetime object.
- t2 – A datetime string or STIXdatetime object.
- tdelta (float) – A given time delta. This number is multiplied by 86400 (1 day) to extend or shrink your time change tolerance.
Returns: float – Number between 0.0 and 1.0 depending on match criteria.
-
reference_check(ref1, ref2, ds1, ds2, **weights)¶ For two references, de-reference the object and perform object-based semantic equivalence. The score influences the result of an edge check.
-
semantically_equivalent(obj1, obj2, prop_scores={}, **weight_dict)¶ This method verifies if two objects of the same type are semantically equivalent.
Parameters: - 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.
- weight_dict – A dictionary that can be used to override settings in the semantic equivalence process
Returns: float – A number between 0.0 and 100.0 as a measurement of equivalence.
Warning
Object types need to have property weights defined for the equivalence 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 weights_dict:
{ "attack-pattern": { "name": [ 30, partial_string_based ], "external_references": [ 70, partial_external_reference_based ] }, "campaign": { "name": [ 60, partial_string_based ], "aliases": [ 40, partial_list_based ] }, "course-of-action": { "name": [ 60, partial_string_based ], "external_references": [ 40, partial_external_reference_based ] }, "identity": { "name": [ 60, partial_string_based ], "identity_class": [ 20, exact_match ], "sectors": [ 20, partial_list_based ] }, "indicator": { "indicator_types": [ 15, partial_list_based ], "pattern": [ 80, custom_pattern_based ], "valid_from": [ 5, partial_timestamp_based ], "tdelta": 1 }, "intrusion-set": { "name": [ 20, partial_string_based ], "external_references": [ 60, partial_external_reference_based ], "aliases": [ 20, partial_list_based ] }, "location": { "longitude_latitude": [ 34, partial_location_distance ], "region": [ 33, exact_match ], "country": [ 33, exact_match ], "threshold": 1000.0 }, "malware": { "malware_types": [ 20, partial_list_based ], "name": [ 80, partial_string_based ] }, "marking-definition": { "name": [ 20, exact_match ], "definition": [ 60, exact_match ], "definition_type": [ 20, exact_match ] }, "threat-actor": { "name": [ 60, partial_string_based ], "threat_actor_types": [ 20, partial_list_based ], "aliases": [ 20, partial_list_based ] }, "tool": { "tool_types": [ 20, partial_list_based ], "name": [ 80, partial_string_based ] }, "vulnerability": { "name": [ 30, partial_string_based ], "external_references": [ 70, partial_external_reference_based ] }, "_internal": { "ignore_spec_version": false } }
Note
This implementation follows the Semantic Equivalence Committee Note. see the Committee Note.