feat: add pytest command-line options for STIX bundles and update documentation

Author: jondricek

conftest.py

@@ -0,0 +1,36 @@
+"""Pytest command-line options for mitreattack-python."""
+
+
+def pytest_addoption(parser):
+    """Register pytest options for selecting ATT&CK STIX test data."""
+    parser.addoption(
+        "--stix-enterprise",
+        action="store",
+        default=None,
+        help="Path to an Enterprise ATT&CK STIX bundle to use in tests.",
+    )
+    parser.addoption(
+        "--stix-mobile",
+        action="store",
+        default=None,
+        help="Path to a Mobile ATT&CK STIX bundle to use in tests.",
+    )
+    parser.addoption(
+        "--stix-ics",
+        action="store",
+        default=None,
+        help="Path to an ICS ATT&CK STIX bundle to use in tests.",
+    )
+    parser.addoption(
+        "--attack-version",
+        action="store",
+        default=None,
+        help="ATT&CK release version to download and use for STIX-backed tests.",
+    )
+    parser.addoption(
+        "--stix-version",
+        action="store",
+        choices=("2.0", "2.1"),
+        default="2.0",
+        help="STIX version to download when --attack-version is used. Defaults to 2.0.",
+    )

docs/CONTRIBUTING.md

@@ -56,6 +56,21 @@ just test-cov      # Run tests with coverage report
 just build         # Build the package
 ```
 
+To run STIX-backed tests against specific local bundles, pass the bundle paths to pytest:
+
+```bash
+uv run pytest \
+  --stix-enterprise /path/to/enterprise-attack.json \
+  --stix-mobile /path/to/mobile-attack.json \
+  --stix-ics /path/to/ics-attack.json
+```
+
+To have pytest download a specific ATT&CK release instead, use:
+
+```bash
+uv run pytest --attack-version 16.1 --stix-version 2.1
+```
+
 ### Pull Requests
 
 When making a pull request, please make sure to:

examples/generate_multiple_attack_diffs.py

@@ -1,36 +1,75 @@
+"""Generate ATT&CK changelog outputs for multiple release pairs."""
+
+import argparse
+
 from mitreattack.diffStix.changelog_helper import get_new_changelog_md
 
+DOMAINS = ["enterprise-attack", "mobile-attack", "ics-attack"]
+VERSION_PAIRS = [
+    ("17.1", "18.0"),
+    ("18.0", "18.1"),
+]
+
+
+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."""
+    parser = argparse.ArgumentParser(description="Generate ATT&CK changelog outputs for multiple release pairs.")
+    parser.add_argument(
+        "-w",
+        "--attack-website-links",
+        action="store_true",
+        help="Use ATT&CK website paths for links to generated layers and changelog JSON.",
+    )
+    return parser.parse_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)
+    print(f"Generating ATT&CK Diffs between {old_version}-{new_version}: {output_folder}")
+
+    get_new_changelog_md(
+        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 = "",
+        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",
+    )
+
 
 def main():
-    version_pairs = [
-        ("17.1", "18.0"),
-        ("18.0", "18.1"),
-    ]
-    for version_pair in version_pairs:
-        old_version = version_pair[0]
-        new_version = version_pair[1]
-
-        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(
-            domains=["enterprise-attack", "mobile-attack", "ics-attack"],
-            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 = "",
-            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",
-            json_file=f"{output_folder}/changelog.json",
-        )
+    """Generate changelog outputs for all configured ATT&CK release pairs."""
+    args = get_parsed_args()
+    for old_version, new_version in VERSION_PAIRS:
+        generate_diff(old_version, new_version, attack_website_links=args.attack_website_links)
 
 
 if __name__ == "__main__":

mitreattack/diffStix/README.md

@@ -14,7 +14,7 @@ Print full usage instructions:
 # You must run `pip install mitreattack-python` in order to access the diff_stix command
 diff_stix --help
 usage: diff_stix [-h] [--old OLD] [--new NEW] [--domains {enterprise-attack,mobile-attack,ics-attack} [{enterprise-attack,mobile-attack,ics-attack} ...]] [--markdown-file MARKDOWN_FILE] [--html-file HTML_FILE] [--html-file-detailed HTML_FILE_DETAILED]
-                 [--json-file JSON_FILE] [--layers [LAYERS ...]] [--site_prefix SITE_PREFIX] [--unchanged] [--use-mitre-cti] [--show-key] [--contributors] [--no-contributors] [-v]
+                 [--json-file JSON_FILE] [--layers [LAYERS ...]] [--site_prefix SITE_PREFIX] [--additional-formats-prefix ADDITIONAL_FORMATS_PREFIX] [--unchanged] [--use-mitre-cti] [--show-key] [--contributors] [--no-contributors] [-v]
 
 Create changelog reports on the differences between two versions of the ATT&CK content. Takes STIX bundles as input. For default operation, put enterprise-attack.json, mobile-attack.json, and ics-attack.json bundles in 'old' and 'new' folders for the script to compare.
 
@@ -37,6 +37,8 @@ options:
                         output/January_2023_Updates_Mobile.json, output/January_2023_Updates_ICS.json, output/January_2023_Updates_Pre.json
   --site_prefix SITE_PREFIX
                         Prefix links in markdown output, e.g. [prefix]/techniques/T1484
+  --additional-formats-prefix ADDITIONAL_FORMATS_PREFIX
+                        Prefix detailed HTML links to generated layers and changelog JSON.
   --unchanged           Show objects without changes in the markdown output
   --use-mitre-cti       Use content from the MITRE CTI repo for the -old data
   --show-key            Add a key explaining the change types to the markdown

mitreattack/diffStix/changelog_helper.py

@@ -1871,7 +1871,14 @@ def layers_dict_to_files(outfiles, layers):
         json.dump(layers["ics-attack"], open(ics_attack_layer_file, "w"), indent=4)
 
 
-def write_detailed_html(html_file_detailed: str, diffStix: DiffStix):
+def _get_additional_format_href(filename: str, additional_formats_prefix: str = "") -> str:
+    """Return a link to an additional changelog output file."""
+    if not additional_formats_prefix:
+        return filename
+    return f"{additional_formats_prefix.rstrip('/')}/{filename}"
+
+
+def write_detailed_html(html_file_detailed: str, diffStix: DiffStix, additional_formats_prefix: str = ""):
     """Write a detailed HTML report of changes between ATT&CK versions.
 
     Parameters
@@ -1880,6 +1887,8 @@ def write_detailed_html(html_file_detailed: str, diffStix: DiffStix):
         File to write HTML for the detailed changelog.
     diffStix : DiffStix
         An instance of a DiffStix object.
+    additional_formats_prefix : str, optional
+        Prefix for links to generated layer and JSON files, by default "".
     """
     old_version = diffStix.data["old"]["enterprise-attack"]["attack_release_version"]
     new_version = diffStix.data["new"]["enterprise-attack"]["attack_release_version"]
@@ -1889,6 +1898,11 @@ def write_detailed_html(html_file_detailed: str, diffStix: DiffStix):
     else:
         header = f"<h1>ATT&CK Changes Between v{old_version} and new content</h1>"
 
+    enterprise_layer_href = _get_additional_format_href("layer-enterprise.json", additional_formats_prefix)
+    mobile_layer_href = _get_additional_format_href("layer-mobile.json", additional_formats_prefix)
+    ics_layer_href = _get_additional_format_href("layer-ics.json", additional_formats_prefix)
+    changelog_json_href = _get_additional_format_href("changelog.json", additional_formats_prefix)
+
     frontmatter = [
         textwrap.dedent(
             """\
@@ -1913,7 +1927,7 @@ def write_detailed_html(html_file_detailed: str, diffStix: DiffStix):
         header,
         markdown.markdown(diffStix.get_md_key()),
         textwrap.dedent(
-            """\
+            f"""\
         <table class=diff summary=Legends>
             <tr>
                 <td>
@@ -1929,11 +1943,11 @@ def write_detailed_html(html_file_detailed: str, diffStix: DiffStix):
         <h2>Additional formats</h2>
         <p>These ATT&CK Navigator layer files can be uploaded to ATT&CK Navigator manually.</p>
         <ul>
-            <li><a href="layer-enterprise.json">Enterprise changes</a></li>
-            <li><a href="layer-mobile.json">Mobile changes</a></li>
-            <li><a href="layer-ics.json">ICS changes</a></li>
+            <li><a href="{enterprise_layer_href}">Enterprise changes</a></li>
+            <li><a href="{mobile_layer_href}">Mobile changes</a></li>
+            <li><a href="{ics_layer_href}">ICS changes</a></li>
         </ul>
-        <p>This JSON file contains the machine readble output used to create this page: <a href="changelog.json">changelog.json</a></p>
+        <p>This JSON file contains the machine readble output used to create this page: <a href="{changelog_json_href}">changelog.json</a></p>
         """
         ),
     ]
@@ -2256,6 +2270,13 @@ def get_parsed_args():
         help="Prefix links in markdown output, e.g. [prefix]/techniques/T1484",
     )
 
+    parser.add_argument(
+        "--additional-formats-prefix",
+        type=str,
+        default="",
+        help="Prefix detailed HTML links to generated layers and changelog JSON.",
+    )
+
     parser.add_argument(
         "--unchanged",
         action="store_true",
@@ -2331,6 +2352,7 @@ def get_new_changelog_md(
     markdown_file: Optional[str] = None,
     html_file: Optional[str] = None,
     html_file_detailed: Optional[str] = None,
+    additional_formats_prefix: str = "",
     json_file: Optional[str] = None,
 ) -> str:
     """Get a Markdown string representation of differences between two ATT&CK versions.
@@ -2365,6 +2387,8 @@ def get_new_changelog_md(
         If set, writes an HTML file from the parsed markdown, by default None
     html_file_detailed : str, optional
         If set, writes a more detailed HTML page, by default None
+    additional_formats_prefix : str, optional
+        Prefix for detailed HTML links to generated layer and JSON files, by default "".
     json_file : str, optional
         If set, writes JSON file of the changes, by default None
 
@@ -2414,7 +2438,11 @@ def get_new_changelog_md(
     if html_file_detailed:
         Path(html_file_detailed).parent.mkdir(parents=True, exist_ok=True)
         logger.info("Writing detailed updates to file")
-        write_detailed_html(html_file_detailed=html_file_detailed, diffStix=diffStix)
+        write_detailed_html(
+            html_file_detailed=html_file_detailed,
+            diffStix=diffStix,
+            additional_formats_prefix=additional_formats_prefix,
+        )
 
     if layers:
         if len(layers) == 0:
@@ -2457,6 +2485,7 @@ def main():
         markdown_file=args.markdown_file,
         html_file=args.html_file,
         html_file_detailed=args.html_file_detailed,
+        additional_formats_prefix=args.additional_formats_prefix,
         json_file=args.json_file,
     )
 

pyproject.toml

@@ -79,6 +79,9 @@ package = true
 module-name = "mitreattack"
 module-root = ""
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
 [tool.ruff]
 line-length = 120
 extend-exclude = ["tests/resources/", "examples/", "__init__.py"]

tests/changelog/cli/test_argument_handling.py

@@ -38,6 +38,7 @@ def _assert_default_args(self, args):
         assert args.verbose is False
         assert args.use_mitre_cti is False
         assert args.site_prefix == ""
+        assert args.additional_formats_prefix == ""
 
     def test_get_parsed_args_default_values(self, monkeypatch):
         """Test default argument values."""
@@ -68,6 +69,8 @@ def test_get_parsed_args_all_options(self, monkeypatch):
             "layer3.json",
             "--site_prefix",
             "https://example.com",
+            "--additional-formats-prefix",
+            "/docs/changelogs/v16.1-v17.0",
             "--unchanged",
             "--show-key",
             "--no-contributors",
@@ -85,6 +88,7 @@ def test_get_parsed_args_all_options(self, monkeypatch):
         assert args.json_file == "test.json"
         assert args.layers == ["layer1.json", "layer2.json", "layer3.json"]
         assert args.site_prefix == "https://example.com"
+        assert args.additional_formats_prefix == "/docs/changelogs/v16.1-v17.0"
         assert args.unchanged is True
         assert args.show_key is True
         assert args.contributors is False
@@ -182,6 +186,8 @@ def test_get_parsed_args_boolean_flags(self, flag, expected_attr, expected_value
             ("--site_prefix", "https://custom.com", "site_prefix"),
             ("--site_prefix", "", "site_prefix"),  # Empty site prefix
             ("--site_prefix", "https://example.com/", "site_prefix"),  # With trailing slash
+            ("--additional-formats-prefix", "/docs/changelogs/v16.1-v17.0", "additional_formats_prefix"),
+            ("--additional-formats-prefix", "", "additional_formats_prefix"),
         ],
     )
     def test_get_parsed_args_string_options(self, option, value, expected_attr, monkeypatch):

tests/changelog/formatting/test_html_output.py

@@ -78,6 +78,40 @@ def test_write_detailed_html_basic(
         assert f"ATT&CK Changes Between v{old_version} and v{new_version}" in html_content
         assert "<h2>Techniques</h2>" in html_content or "<h1>" in html_content  # Should have some header structure
 
+    def test_write_detailed_html_additional_format_links_default_to_relative(self, tmp_path, lightweight_diffstix):
+        """Test detailed HTML links to generated artifacts with relative paths by default."""
+        html_file = tmp_path / "detailed.html"
+        lightweight_diffstix.data["old"]["enterprise-attack"]["attack_release_version"] = "16.1"
+        lightweight_diffstix.data["new"]["enterprise-attack"]["attack_release_version"] = "17.0"
+
+        write_detailed_html(str(html_file), lightweight_diffstix)
+
+        html_content = html_file.read_text(encoding="utf-8")
+        assert '<a href="layer-enterprise.json">Enterprise changes</a>' in html_content
+        assert '<a href="layer-mobile.json">Mobile changes</a>' in html_content
+        assert '<a href="layer-ics.json">ICS changes</a>' in html_content
+        assert '<a href="changelog.json">changelog.json</a>' in html_content
+
+    def test_write_detailed_html_additional_format_links_use_additional_formats_prefix(
+        self, tmp_path, lightweight_diffstix
+    ):
+        """Test detailed HTML links to generated artifacts can be prefixed for website releases."""
+        html_file = tmp_path / "detailed.html"
+        lightweight_diffstix.data["old"]["enterprise-attack"]["attack_release_version"] = "16.1"
+        lightweight_diffstix.data["new"]["enterprise-attack"]["attack_release_version"] = "17.0"
+
+        write_detailed_html(
+            str(html_file),
+            lightweight_diffstix,
+            additional_formats_prefix="/docs/changelogs/v16.1-v17.0/",
+        )
+
+        html_content = html_file.read_text(encoding="utf-8")
+        assert '<a href="/docs/changelogs/v16.1-v17.0/layer-enterprise.json">Enterprise changes</a>' in html_content
+        assert '<a href="/docs/changelogs/v16.1-v17.0/layer-mobile.json">Mobile changes</a>' in html_content
+        assert '<a href="/docs/changelogs/v16.1-v17.0/layer-ics.json">ICS changes</a>' in html_content
+        assert '<a href="/docs/changelogs/v16.1-v17.0/changelog.json">changelog.json</a>' in html_content
+
     def test_html_document_structure(self):
         """Test basic HTML document structure."""
         title = "ATT&CK Changes"