get procedure examples by technique (#172)

* get procedure examples by technique

* update changelog

* fix fn docs

* typo

CHANGELOG.md

@@ -1,3 +1,7 @@
+# v3.0.5 - Changes staged
+
+- Added functionality to `MitreAttackData` to retrieve a list of Procedure Examples by technique. [#172](https://github.com/mitre-attack/mitreattack-python/pull/172)
+
 # v3.0.4 - 4/23/2024
 
 ## Features

docs/mitre_attack_data/examples.rst

@@ -49,6 +49,9 @@ Getting Multiple ATT&CK Objects
 Related Objects
 -------------------
 
+Technique:Procedure Examples
+* `get_procedure_examples_by_technique.py <https://github.com/mitre-attack/mitreattack-python/tree/master/examples/get_procedure_examples_by_technique.py>`_
+
 Technique:Group Relationships
 
 * `get_all_groups_using_all_techniques.py <https://github.com/mitre-attack/mitreattack-python/tree/master/examples/get_all_groups_using_all_techniques.py>`_

examples/get_procedure_examples_by_technique.py

@@ -0,0 +1,20 @@
+from mitreattack.stix20 import MitreAttackData
+
+
+def main():
+    mitre_attack_data = MitreAttackData("enterprise-attack.json")
+    technique_id = "attack-pattern--03259939-0b57-482f-8eb5-87c0e0d54334"
+
+    procedure_examples = mitre_attack_data.get_procedure_examples_by_technique(technique_id)
+
+    print(f"Retrieved {len(procedure_examples)} procedure example(s):")
+
+    for procedure_example in procedure_examples:
+        source_object = mitre_attack_data.get_object_by_stix_id(procedure_example.source_ref)
+        source_attack_id = mitre_attack_data.get_attack_id(source_object.id)
+
+        print(f"[{source_attack_id}] {source_object.name}: {procedure_example.description}")
+
+
+if __name__ == "__main__":
+    main()

mitreattack/stix20/MitreAttackData.py

@@ -490,6 +490,28 @@ def get_tactics_by_technique(self, stix_id) -> list:
                 technique_tactics.append(tactic)
 
         return technique_tactics
+
+    def get_procedure_examples_by_technique(self, stix_id) -> list:
+        """Retrieve the list of procedure examples by technique.
+
+        Parameters
+        ----------
+        stix_id : str
+            the stix id of the technique.
+
+        Returns
+        -------
+        list
+            a list of stix2.v20.Relationship objects describing the software, groups, and campaigns using the technique.
+        """
+        procedures = self.src.query(
+            [
+                Filter("type", "=", "relationship"),
+                Filter("relationship_type", "=", "uses"),
+                Filter("target_ref", "=", stix_id),
+            ]
+        )
+        return procedures
 
     def get_objects_created_after(self, timestamp: str, remove_revoked_deprecated=False) -> list:
         """Retrieve objects which have been created after a given time.