chore: update examples to optionally use environment variables to read STIX bundles

Author: jondricek

examples/.env.example

@@ -0,0 +1,16 @@
+# These environment variables can be helpful when running scripts in the examples directory
+#
+# In order to use them, copy this file to .env and modify the values as needed
+# Two optional tools worth considering to automatically use the .env file are:
+# 1. `python-dotenv` python library: https://github.com/theskumar/python-dotenv
+# 2. `direnv` tool: https://direnv.net
+# Setting up these tools is out of scope for this example.
+#
+# if you have mitreattack-python installed, you can use the following command to download all STIX bundles:
+#
+#     download_attack_stix --all
+#
+# the default download directory from the above command is "attack-releases"
+
+STIX_BASE_DIR=attack-releases/stix-2.0/v17.1
+STIX_BUNDLE=attack-releases/stix-2.0/v17.1/enterprise-attack.json

examples/README.md

@@ -0,0 +1,79 @@
+# Examples Directory
+
+This directory contains example scripts demonstrating how to use the [`mitreattack-python`](https://github.com/mitre-attack/mitreattack-python)
+library to extract, analyze, and report on MITRE ATT&CK data.
+These scripts cover a variety of use cases, including querying STIX bundles, generating reports, and automating ATT&CK data analysis.
+
+## Full Example Listing & Documentation
+
+A complete, categorized list of example scripts, usage details, and direct links is maintained in the built documentation:
+
+- [mitreattack-python Examples Documentation](https://mitreattack-python.readthedocs.io/en/latest/mitre_attack_data/examples.html)
+
+## Setup
+
+Many example scripts allow optional configuration via environment variables for paths to STIX bundles.
+If you want to set this up you can follow these instructions.
+
+- Copy the provided [`examples/.env.example`](examples/.env.example:1) file to `.env`:
+
+  ```sh
+  cp .env.example .env
+  ```
+
+- Edit `.env` to set the correct paths and variables for your environment.
+
+Creating a .env file is not enough however. You will need to use a tool such as the following to help manage the environment variables:
+
+- [`python-dotenv`](https://pypi.org/project/python-dotenv/) (automatically loads `.env` in Python scripts)
+- [`direnv`](https://direnv.net/) (manages environment variables per directory)
+
+Setting up these tools is out of scope for this README.
+
+### Dependencies
+
+- [`mitreattack-python`](https://github.com/mitre-attack/mitreattack-python)
+- Python 3.x
+- ATT&CK STIX bundles
+
+### Downloading ATT&CK STIX Bundles
+
+Many example scripts require ATT&CK STIX bundles, which must be downloaded and placed in the directory specified in your `.env` file (e.g., `attack-releases/stix-2.0/v17.1`).
+You can download these bundles using the provided CLI command if you have mitreattack-python installed:
+
+```sh
+download_attack_stix --all
+```
+
+This will download all available ATT&CK releases in STIX format to the default directory (`attack-releases`).
+You can customize the download location and versions using additional options. For example:
+
+- Download the latest release (default):
+
+  ```sh
+  download_attack_stix
+  ```
+
+- Download specific versions:
+
+  ```sh
+  download_attack_stix -v 16.1 -v 17.1
+  ```
+
+- Download all releases in both STIX formats:
+
+  ```sh
+  download_attack_stix --all --stix21
+  ```
+
+## How to Run Scripts
+
+- Run individual scripts with Python:
+
+  ```sh
+  python get_all_techniques.py
+  ```
+
+## Contribution & Customization
+
+Feel free to adapt these scripts for your own use cases. Contributions and improvements are welcome!

examples/get_all_assets.py

@@ -1,8 +1,11 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("ics-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "ics-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
 
     assets = mitre_attack_data.get_assets(remove_revoked_deprecated=True)
 

examples/get_all_assets_targeted_by_all_techniques.py

@@ -1,8 +1,11 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("ics-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "ics-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
 
     # get all assets targeted by techniques
     assets_targeted_by_techniques = mitre_attack_data.get_all_assets_targeted_by_all_techniques()

examples/get_all_campaigns.py

@@ -1,8 +1,11 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("enterprise-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "enterprise-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
 
     campaigns = mitre_attack_data.get_campaigns(remove_revoked_deprecated=True)
 

examples/get_all_campaigns_attributed_to_all_groups.py

@@ -1,8 +1,11 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("enterprise-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "enterprise-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
 
     # get all campaigns related to groups
     campaigns_attributed = mitre_attack_data.get_all_campaigns_attributed_to_all_groups()

examples/get_all_campaigns_using_all_software.py

@@ -1,8 +1,11 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("enterprise-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "enterprise-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
 
     # get all campaigns related to software
     campaigns_using_software = mitre_attack_data.get_all_campaigns_using_all_software()

examples/get_all_campaigns_using_all_techniques.py

@@ -1,8 +1,11 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("enterprise-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "enterprise-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
 
     # get all campaigns related to techniques
     campaigns_using_techniques = mitre_attack_data.get_all_campaigns_using_all_techniques()

examples/get_all_datacomponents.py

@@ -1,8 +1,12 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("enterprise-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "enterprise-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
+
 
     datacomponents = mitre_attack_data.get_datacomponents(remove_revoked_deprecated=True)
 

examples/get_all_datacomponents_detecting_all_techniques.py

@@ -1,8 +1,11 @@
+import os
+
 from mitreattack.stix20 import MitreAttackData
 
 
 def main():
-    mitre_attack_data = MitreAttackData("enterprise-attack.json")
+    stix_filepath = os.environ.get("STIX_BUNDLE", "enterprise-attack.json")
+    mitre_attack_data = MitreAttackData(stix_filepath=stix_filepath)
 
     # get all data components related to techniques
     datacomponents_detecting = mitre_attack_data.get_all_datacomponents_detecting_all_techniques()