chore: merge with master

Author: adpare

.github/workflows/lint-and-test.yml

@@ -47,4 +47,4 @@ jobs:
         run: uv sync --all-extras
 
       - name: Run pytest
-        run: uv run pytest --cov=mitreattack
+        run: uv run --extra dev pytest -n 2 --cov=mitreattack --durations=20

.github/workflows/release-and-publish.yml

@@ -56,7 +56,7 @@ jobs:
         id: app-token
         uses: actions/create-github-app-token@v3
         with:
-          app-id: ${{ vars.ATTACK_AUTOBOT_APP_ID }}
+          client-id: ${{ vars.ATTACK_AUTOBOT_CLIENT_ID }}
           private-key: ${{ secrets.ATTACK_AUTOBOT_PRIVATE_KEY }}
 
       # Note: We checkout the repository at the branch that triggered the workflow.

.readthedocs.yaml

@@ -12,7 +12,8 @@ build:
       - pip install uv
       - uv sync --extra docs
     build:
-      - uv run sphinx-build -b html docs $READTHEDOCS_OUTPUT/html
+      html:
+        - uv run sphinx-build -b html docs $READTHEDOCS_OUTPUT/html
 
 sphinx:
   configuration: docs/conf.py

AGENTS.md

@@ -16,7 +16,9 @@
 - Before committing, run `just lint`.
 - `just lint`: run pre-commit hooks across the repo.
 - `just test`: run the pytest suite.
+- `just test-xdist`: run the pytest suite in parallel.
 - `just test-cov`: run tests with coverage for `mitreattack`.
+- `just test-cov-xdist`: run tests with coverage in parallel.
 - `just build`: build distributions with `uv build`.
 - Without `just`, run the same tools through `uv run ...`.
 
@@ -32,6 +34,10 @@
 - Framework: `pytest` (with `pytest-cov` for coverage checks).
 - Place tests under `tests/` and name files/functions `test_*.py` / `test_*`.
 - Add or update tests for behavior changes, especially around STIX parsing and changelog/diff output paths.
+- Tests that need real ATT&CK STIX data should use the shared STIX fixtures instead of downloading or
+  preparing bundles directly.
+- Parallel runs warm the shared STIX cache before workers start; update `DEFAULT_ATTACK_STIX_PREP` in
+  `tests/conftest.py` if a new xdist-backed test needs another ATT&CK release.
 - Run `just test` locally before opening a PR; use `just test-cov` for larger changes.
 
 ## Commit & Pull Request Guidelines

README.md

@@ -1,5 +1,7 @@
 # mitreattack-python
 
+[![PyPI version](https://img.shields.io/pypi/v/mitreattack-python.svg)](https://pypi.org/project/mitreattack-python/) [![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/) [![License](https://img.shields.io/pypi/l/mitreattack-python.svg)](https://github.com/mitre-attack/mitreattack-python/blob/main/LICENSE) [![Docs](https://img.shields.io/readthedocs/mitreattack-python.svg)](https://mitreattack-python.readthedocs.io/) [![Lint and Test](https://img.shields.io/github/actions/workflow/status/mitre-attack/mitreattack-python/lint-and-test.yml?label=lint%20%26%20test)](https://github.com/mitre-attack/mitreattack-python/actions/workflows/lint-and-test.yml) [![Release and Publish](https://img.shields.io/github/actions/workflow/status/mitre-attack/mitreattack-python/release-and-publish.yml?branch=main&label=release)](https://github.com/mitre-attack/mitreattack-python/actions/workflows/release-and-publish.yml)
+
 This repository contains a library of Python tools and utilities for working with ATT&CK data.
 For more information, see the [full documentation](https://mitreattack-python.readthedocs.io/) on ReadTheDocs.
 

conftest.py

@@ -51,11 +51,21 @@ Run `just` with no arguments to see all available commands. Here are the most co
 
 ```bash
 just lint          # Run pre-commit hooks (ruff format) on all files
-just test          # Run tests
+just test          # Run the full test suite, matching CI expectations
+just test-fast     # Run the fast local subset, excluding integration and slow tests
+just test-xdist    # Run tests in parallel
 just test-cov      # Run tests with coverage report
+just test-cov-xdist  # Run tests with coverage in parallel
 just build         # Build the package
 ```
 
+Use `just test-fast` while iterating locally on changes that do not need full STIX-backed export or other slow integration coverage. Tests or setup steps that normally take longer than 10 seconds should be marked `slow`, so they are skipped by `just test-fast`. Before opening a PR, run `just test`; GitHub Actions also runs the full suite with coverage.
+
+Tests that need real ATT&CK STIX data should use the shared STIX fixtures instead of downloading or
+preparing bundles directly. Parallel test runs warm the shared STIX cache before workers start; if a
+new xdist-backed test needs an additional ATT&CK release, update the cache warmup list in
+`tests/conftest.py`.
+
 To run STIX-backed tests against specific local bundles, pass the bundle paths to pytest:
 
 ```bash

docs/CONTRIBUTING.md

@@ -1,42 +1,65 @@
 """Generate ATT&CK Excel exports from local STIX bundles."""
 
 import argparse
-import os
+from os import environ
+from pathlib import Path
 
 from stix2 import MemoryStore
 
 from mitreattack.attackToExcel import attackToExcel
 
 # Pass attack version via the command line or update the variable below
 DEFAULT_ATTACK_VERSION = "v19.0"
+# Parent directory where ATT&CK version export folders are written.
+OUTPUT_DIR = Path("output")
 # Set to true if you want the parent subfolder of the excel files to have a version.
 # Example - If you want the folder to be named enterprise-attack-v19.0 instead of enterprise-attack, set to True
 VERSIONED_OUTPUT_DIR = False
 
 
 def move_versioned_exports_to_domain_dir(output_dir, domain, version):
     """Move versioned Excel exports into the unversioned domain folder."""
-    versioned_dir = os.path.join(output_dir, f"{domain}-{version}")
-    domain_dir = os.path.join(output_dir, domain)
+    output_dir = Path(output_dir)
+    versioned_dir = output_dir / f"{domain}-{version}"
+    domain_dir = output_dir / domain
 
-    if not os.path.isdir(versioned_dir):
+    if not versioned_dir.is_dir():
         return
 
-    os.makedirs(domain_dir, exist_ok=True)
+    domain_dir.mkdir(parents=True, exist_ok=True)
 
-    for filename in os.listdir(versioned_dir):
-        source_path = os.path.join(versioned_dir, filename)
-        target_path = os.path.join(domain_dir, filename)
-
-        if not os.path.isfile(source_path):
+    for source_path in versioned_dir.iterdir():
+        if not source_path.is_file():
             continue
 
-        if os.path.exists(target_path):
-            os.remove(target_path)
+        target_path = domain_dir / source_path.name
+        if target_path.exists():
+            target_path.unlink()
+
+        source_path.replace(target_path)
+
+    versioned_dir.rmdir()
+
+
+def format_missing_stix_bundle_error(stix_file, attack_version):
+    """Format a concise missing STIX bundle error."""
+    message = (
+        f"STIX bundle not found: {stix_file}\n"
+        "Download the STIX bundles before running this script, or set STIX_BASE_DIR to the directory containing "
+        "enterprise-attack.json, mobile-attack.json, and ics-attack.json."
+    )
+
+    if attack_version and not attack_version.startswith("v"):
+        message = f"{message}\nDid you mean -a v{attack_version}?"
+
+    return message
 
-        os.replace(source_path, target_path)
 
-    os.rmdir(versioned_dir)
+def validate_stix_files(stix_files, attack_version):
+    """Exit with a clean error if any expected STIX bundle is missing."""
+    for stix_file in stix_files.values():
+        if not stix_file.is_file():
+            raise SystemExit(format_missing_stix_bundle_error(stix_file, attack_version))
 
 
 def parse_args(argv=None):
@@ -49,10 +72,7 @@ def parse_args(argv=None):
         "-a",
         "--attack-version",
         default=DEFAULT_ATTACK_VERSION,
-        help=(
-            "ATT&CK version to export, such as v19.0. "
-            f"Defaults to {DEFAULT_ATTACK_VERSION}."
-        ),
+        help=(f"ATT&CK version to export, such as v19.0. Defaults to {DEFAULT_ATTACK_VERSION}."),
     )
     return parser.parse_args(args=argv)
 
@@ -64,15 +84,16 @@ def main(argv=None):
 
     # List of domains and version to process
     domains = ["enterprise-attack", "mobile-attack", "ics-attack"]
-    output_dir = f"{attack_version}/"
+    output_dir = OUTPUT_DIR / attack_version
 
     # Path to the STIX bundles for each domain (assumes STIX files are downloaded)
-    stix_base_dir = os.environ.get("STIX_BASE_DIR", f"attack-releases/stix-2.0/{attack_version}")
+    stix_base_dir = Path(environ.get("STIX_BASE_DIR", Path("attack-releases") / "stix-2.0" / attack_version))
     stix_files = {
-        "enterprise-attack": os.path.join(stix_base_dir, "enterprise-attack.json"),
-        "mobile-attack": os.path.join(stix_base_dir, "mobile-attack.json"),
-        "ics-attack": os.path.join(stix_base_dir, "ics-attack.json"),
+        "enterprise-attack": stix_base_dir / "enterprise-attack.json",
+        "mobile-attack": stix_base_dir / "mobile-attack.json",
+        "ics-attack": stix_base_dir / "ics-attack.json",
     }
+    validate_stix_files(stix_files, attack_version)
 
     for domain in domains:
         stix_file = stix_files[domain]

examples/generate_excel_files.py

@@ -2,7 +2,7 @@
 
 import argparse
 
-from mitreattack.diffStix.changelog_helper import get_new_changelog_md
+from mitreattack.diffStix.attack_changelog import generate_attack_changelog
 
 DOMAINS = ["enterprise-attack", "mobile-attack", "ics-attack"]
 VERSION_PAIRS = [
@@ -11,17 +11,6 @@
 ]
 
 
-def get_release_output_folder(old_version: str, new_version: str) -> str:
-    """Return the output folder for a release comparison."""
-    return f"output/v{old_version}-v{new_version}"
-
-
-def get_artifact_link_prefix(old_version: str, new_version: str, *, attack_website_links: bool = False) -> str:
-    """Return the link prefix for generated layers and changelog JSON."""
-    if not attack_website_links:
-        return ""
-    return f"/docs/changelogs/v{old_version}-v{new_version}"
-
 
 def get_parsed_args():
     """Parse command line arguments for the example script."""
@@ -37,31 +26,18 @@ def get_parsed_args():
 
 def generate_diff(old_version: str, new_version: str, *, attack_website_links: bool = False):
     """Generate changelog outputs for a single ATT&CK release pair."""
-    output_folder = get_release_output_folder(old_version, new_version)
+    output_folder = f"output/v{old_version}-v{new_version}"
     print(f"Generating ATT&CK Diffs between {old_version}-{new_version}: {output_folder}")
 
-    get_new_changelog_md(
+    generate_attack_changelog(
+        old_version=old_version,
+        new_version=new_version,
         domains=DOMAINS,
-        layers=[
-            f"{output_folder}/layer-enterprise.json",
-            f"{output_folder}/layer-mobile.json",
-            f"{output_folder}/layer-ics.json",
-        ],
-        old=f"attack-releases/stix-2.0/v{old_version}",
-        new=f"attack-releases/stix-2.0/v{new_version}",
-        show_key=True,
-        # site_prefix: str = "",
+        output_dir=output_folder,
         verbose=True,
-        include_contributors=True,
-        markdown_file=f"{output_folder}/changelog.md",
-        html_file=f"{output_folder}/index.html",
-        html_file_detailed=f"{output_folder}/changelog-detailed.html",
-        additional_formats_prefix=get_artifact_link_prefix(
-            old_version,
-            new_version,
-            attack_website_links=attack_website_links,
-        ),
-        json_file=f"{output_folder}/changelog.json",
+        markdown_file=True,
+        html_file=True,
+        attack_website_links=attack_website_links,
     )
 
 

examples/generate_multiple_attack_diffs.py

@@ -5,6 +5,8 @@ default:
 # Install development dependencies
 install:
     uv sync --all-extras
+    uv run pre-commit install
+    uv run pre-commit install --hook-type commit-msg
 
 # Upgrade all uv dependencies
 upgrade:
@@ -35,6 +37,22 @@ ruff-format:
 test:
     uv run pytest
 
+# Run the fast local test subset, excluding integration and slow tests
+test-fast:
+    uv run pytest -m "not integration and not slow"
+
+# Run the fast local test subset in parallel
+test-fast-xdist workers="auto":
+    uv run --extra dev pytest -n {{ workers }} -m "not integration and not slow"
+
+# Run tests in parallel
+test-xdist workers="auto":
+    uv run --extra dev pytest -n {{ workers }}
+
+# Run tests with coverage in parallel
+test-cov-xdist workers="auto":
+    uv run --extra dev pytest -n {{ workers }} --cov=mitreattack
+
 # Run tests with coverage
 test-cov:
     uv run pytest --cov=mitreattack