feat: update CLI commands and README for attack-to-excel and attack-changelog

jondricek · jondricek · commit 9a5c541ed464 · 2026-05-06T13:03:35.000-05:00
diff --git a/mitreattack/attackToExcel/README.md b/mitreattack/attackToExcel/README.md
@@ -10,34 +10,40 @@ It also provides a means to access ATT&CK data as [Pandas](https://pandas.pydata
 Print full usage instructions:
 
 ```shell
-python3 attackToExcel.py -h
+attack-to-excel --help
 ```
 
 Example execution:
 
 ```shell
-python3 attackToExcel.py
+attack-to-excel from-stix
 ```
 
 Build a excel files corresponding to a specific domain and version of ATT&CK:
 
 ```shell
-python3 attackToExcel -domain mobile-attack -version v5.0
+attack-to-excel from-stix --domain mobile-attack --version v5.0
 ```
 
 Build Excel files for all ATT&CK domains from a release. If local STIX files
 are missing under `attack-releases/stix-2.0/v19.0`, they are downloaded
 temporarily for the export:
 
 ```shell
-attackToExcel_cli --all-domains -version v19.0
+attack-to-excel from-release --version v19.0
 ```
 
 To persist release STIX files before exporting, use `download_attack_stix`:
 
 ```shell
 download_attack_stix -v 19.0
-attackToExcel_cli --all-domains -version v19.0
+attack-to-excel from-release --version v19.0
+```
+
+Build Excel files for selected ATT&CK domains from a release:
+
+```shell
+attack-to-excel from-release --version v19.0 --domains mobile-attack --domains ics-attack
 ```
 
 ### Module
diff --git a/mitreattack/attackToExcel/attackToExcel.py b/mitreattack/attackToExcel/attackToExcel.py
@@ -1,6 +1,5 @@
-"""Functions to convert ATT&CK STIX data to Excel, as well as entrypoint for attackToExcel_cli."""
+"""Functions to convert ATT&CK STIX data to Excel, as well as entrypoint for attack-to-excel."""
 
-import argparse
 import os
 import re
 import tempfile
@@ -10,8 +9,10 @@
 
 import pandas as pd
 import requests
+import typer
 from loguru import logger
 from stix2 import MemoryStore
+from typing_extensions import Annotated
 
 from mitreattack import release_info
 
@@ -38,6 +39,11 @@ class DomainConfig:
 }
 ATTACK_DOMAINS = tuple(DOMAIN_CONFIGS)
 VALID_STIX_VERSIONS = ("2.0", "2.1")
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Download ATT&CK data from MITRE/CTI and convert it to excel spreadsheets.",
+)
 
 
 def normalize_attack_version(version: str) -> str:
@@ -586,99 +592,135 @@ def export(
     write_excel(dataframes=dataframes, domain=domain, src=mem_store, version=version, output_dir=output_dir)
 
 
-def main(argv=None):
-    """Entrypoint for attackToExcel_cli."""
-    parser = argparse.ArgumentParser(
-        description="Download ATT&CK data from MITRE/CTI and convert it to excel spreadsheets"
-    )
-    parser.add_argument(
-        "--all-domains",
-        action="store_true",
-        help="export Excel files for all ATT&CK domains from a local or downloaded release",
-    )
-    parser.add_argument(
-        "-domain",
-        type=str,
-        choices=ATTACK_DOMAINS,
-        default="enterprise-attack",
-        help="which domain of ATT&CK to convert",
-    )
-    parser.add_argument(
-        "--domains",
-        type=str,
-        nargs="+",
-        choices=ATTACK_DOMAINS,
-        help="which ATT&CK domains to convert in --all-domains mode",
-    )
-    parser.add_argument(
-        "-version",
-        type=str,
-        help="which version of ATT&CK to convert. If omitted, builds the latest version",
-    )
-    parser.add_argument(
-        "--stix-version",
-        type=str,
-        choices=VALID_STIX_VERSIONS,
-        default="2.0",
-        help="STIX release tree to use in --all-domains mode",
-    )
-    parser.add_argument(
-        "-output",
-        type=str,
-        default=None,
-        help="output directory. If omitted writes to a subfolder of the current directory depending on "
-        "the domain and version",
-    )
-    parser.add_argument(
-        "-remote",
-        type=str,
-        default=None,
-        help="remote url of an ATT&CK workbench server.",
-    )
-    parser.add_argument(
-        "-stix-file",
-        type=str,
-        default=None,
-        help="Path to a local STIX file containing ATT&CK data for a domain, by default None",
-    )
-    parser.add_argument(
-        "--stix-base-dir",
-        type=str,
-        default=None,
-        help="directory containing release STIX files for --all-domains mode",
-    )
-    parser.add_argument(
-        "--versioned-output-dir",
-        action="store_true",
-        help="preserve domain-version output folders in --all-domains mode",
-    )
-    args = parser.parse_args(args=argv)
-
-    if args.domains and not args.all_domains:
-        parser.error("--domains can only be used with --all-domains")
-
-    if args.all_domains:
-        if args.remote or args.stix_file:
-            parser.error("--all-domains cannot be combined with -remote or -stix-file")
-
-        export_release(
-            version=args.version,
-            stix_version=args.stix_version,
-            output_dir=args.output or "output",
-            stix_base_dir=args.stix_base_dir,
-            domains=args.domains,
-            versioned_output_dir=args.versioned_output_dir,
-        )
-        return
+def _validate_cli_value(value: str, allowed_values: tuple[str, ...], label: str) -> str:
+    """Return a CLI value after validating it against an allowed set."""
+    if value not in allowed_values:
+        allowed_values_text = ", ".join(allowed_values)
+        raise typer.BadParameter(f"Invalid {label}: {value}. Expected one of: {allowed_values_text}")
+    return value
+
+
+@app.command("from-stix")
+def from_stix_cli(
+    domain: Annotated[
+        str,
+        typer.Option(
+            "--domain",
+            help="ATT&CK domain STIX bundle to convert.",
+        ),
+    ] = "enterprise-attack",
+    version: Annotated[
+        Optional[str],
+        typer.Option(
+            "--version",
+            help="Which version of ATT&CK to convert. If omitted, builds the latest version.",
+        ),
+    ] = None,
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            help=(
+                "Output directory. If omitted writes to a subfolder of the current directory depending on the domain "
+                "and version."
+            ),
+        ),
+    ] = ".",
+    remote: Annotated[
+        Optional[str],
+        typer.Option(
+            "--remote",
+            help="Remote URL of an ATT&CK Workbench server.",
+        ),
+    ] = None,
+    stix_file: Annotated[
+        Optional[str],
+        typer.Option(
+            "--stix-file",
+            help="Path to a local STIX file containing ATT&CK data for a domain.",
+        ),
+    ] = None,
+):
+    """Convert one ATT&CK domain STIX bundle to Excel."""
+    domain = _validate_cli_value(domain, ATTACK_DOMAINS, "ATT&CK domain")
+
+    if remote and stix_file:
+        raise typer.BadParameter("--remote and --stix-file are mutually exclusive")
 
     export(
-        domain=args.domain,
-        version=args.version,
-        output_dir=args.output or ".",
-        remote=args.remote,
-        stix_file=args.stix_file,
+        domain=domain,
+        version=version,
+        output_dir=output,
+        remote=remote,
+        stix_file=stix_file,
+    )
+
+
+@app.command("from-release")
+def from_release_cli(
+    version: Annotated[
+        Optional[str],
+        typer.Option(
+            "--version",
+            help="Which ATT&CK release version to convert. If omitted, builds the latest version.",
+        ),
+    ] = None,
+    domains: Annotated[
+        Optional[List[str]],
+        typer.Option(
+            "--domains",
+            help="ATT&CK release domain to include. Can be specified multiple times.",
+        ),
+    ] = None,
+    stix_version: Annotated[
+        str,
+        typer.Option(
+            "--stix-version",
+            help="STIX release tree to use.",
+        ),
+    ] = "2.0",
+    stix_base_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            "--stix-base-dir",
+            help="Directory containing release STIX files.",
+        ),
+    ] = None,
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            help="Parent output directory.",
+        ),
+    ] = "output",
+    versioned_output_dir: Annotated[
+        bool,
+        typer.Option(
+            "--versioned-output-dir",
+            help="Preserve domain-version output folders.",
+        ),
+    ] = False,
+):
+    """Convert ATT&CK release domain bundles to Excel."""
+    stix_version = _validate_cli_value(stix_version, VALID_STIX_VERSIONS, "STIX version")
+    selected_domains = [
+        _validate_cli_value(selected_domain, ATTACK_DOMAINS, "ATT&CK domain") for selected_domain in domains or []
+    ]
+
+    export_release(
+        version=version,
+        stix_version=stix_version,
+        output_dir=output,
+        stix_base_dir=stix_base_dir,
+        domains=selected_domains or None,
+        versioned_output_dir=versioned_output_dir,
     )
 
 
+def main(argv=None):
+    """Entrypoint for attack-to-excel."""
+    app(args=argv, prog_name="attack-to-excel")
+
+
 if __name__ == "__main__":
     main()
diff --git a/mitreattack/diffStix/README.md b/mitreattack/diffStix/README.md
@@ -56,17 +56,17 @@ diff_stix -v --show-key --html-file output/changelog.html --html-file-detailed o
 Generate release changelog artifacts for one ATT&CK version pair:
 
 ```shell
-attack_changelog --old-version 17.1 --new-version 18.0
+attack-changelog --old-version 17.1 --new-version 18.0
 ```
 
-The `attack_changelog` command reads local release data from `attack-releases/stix-2.0/v{version}` by default.
+The `attack-changelog` command reads local release data from `attack-releases/stix-2.0/v{version}` by default.
 If either requested release is missing, it downloads the needed STIX bundles into a temporary directory and
 removes them when generation is complete.
 It always writes detailed HTML, JSON, and Navigator layer artifacts under `output/v{old_version}-v{new_version}`.
 It can also generate `changelog.md` or `index.html` if needed by passing the corresponding flags:
 
 ```shell
-attack_changelog --old-version 17.1 --new-version 18.0 \
+attack-changelog --old-version 17.1 --new-version 18.0 \
   --markdown-file \
   --html-file
 ```
diff --git a/mitreattack/diffStix/attack_changelog.py b/mitreattack/diffStix/attack_changelog.py
@@ -159,7 +159,7 @@ def get_artifact_link_prefix(old_version: str, new_version: str, *, attack_websi
 
 
 def get_parsed_args():
-    """Parse command line arguments for the attack_changelog command."""
+    """Parse command line arguments for the attack-changelog command."""
     parser = argparse.ArgumentParser(
         description="Generate ATT&CK changelog artifacts for a single ATT&CK release pair."
     )
@@ -359,7 +359,7 @@ def generate_attack_changelog(
 
 
 def main():
-    """Entrypoint for the attack_changelog console command."""
+    """Entrypoint for the attack-changelog console command."""
     args = get_parsed_args()
     generate_attack_changelog(
         old_version=args.old_version,
diff --git a/pyproject.toml b/pyproject.toml
@@ -41,13 +41,13 @@ repository = "https://github.com/mitre-attack/mitreattack-python/"
 documentation = "https://mitreattack-python.readthedocs.io/"
 
 [project.scripts]
-attackToExcel_cli = 'mitreattack.attackToExcel.attackToExcel:main'
+attack-to-excel = 'mitreattack.attackToExcel.attackToExcel:main'
 layerExporter_cli = 'mitreattack.navlayers.layerExporter_cli:main'
 layerGenerator_cli = 'mitreattack.navlayers.layerGenerator_cli:main'
 indexToMarkdown_cli = 'mitreattack.collections.index_to_markdown:main'
 collectionToIndex_cli = 'mitreattack.collections.collection_to_index:main'
 diff_stix = 'mitreattack.diffStix.changelog_helper:main'
-attack_changelog = 'mitreattack.diffStix.attack_changelog:main'
+attack-changelog = 'mitreattack.diffStix.attack_changelog:main'
 download_attack_stix = 'mitreattack.download_stix:app'
 
 [project.optional-dependencies]
diff --git a/tests/changelog/cli/test_attack_changelog.py b/tests/changelog/cli/test_attack_changelog.py
@@ -1,4 +1,4 @@
-"""Tests for the attack_changelog CLI wrapper."""
+"""Tests for the attack-changelog CLI wrapper."""
 
 import argparse
 import sys
@@ -17,7 +17,7 @@ def test_normalize_release_version_accepts_plain_and_prefixed_versions():
 
 def test_get_parsed_args_requires_release_versions(monkeypatch):
     """The command requires exactly one old and one new ATT&CK release version."""
-    monkeypatch.setattr(sys, "argv", ["attack_changelog"])
+    monkeypatch.setattr(sys, "argv", ["attack-changelog"])
 
     with pytest.raises(SystemExit):
         attack_changelog.get_parsed_args()
@@ -29,7 +29,7 @@ def test_get_parsed_args_defaults_and_options(monkeypatch):
         sys,
         "argv",
         [
-            "attack_changelog",
+            "attack-changelog",
             "--old-version",
             "17.1",
             "--new-version",
@@ -67,7 +67,7 @@ def test_get_parsed_args_allows_markdown_and_html_flags_without_values(monkeypat
         sys,
         "argv",
         [
-            "attack_changelog",
+            "attack-changelog",
             "--old-version",
             "17.1",
             "--new-version",
@@ -88,7 +88,7 @@ def test_get_parsed_args_defaults_output_dir_and_omits_optional_outputs(monkeypa
     monkeypatch.setattr(
         sys,
         "argv",
-        ["attack_changelog", "--old-version", "17.1", "--new-version", "18.0"],
+        ["attack-changelog", "--old-version", "17.1", "--new-version", "18.0"],
     )
 
     args = attack_changelog.get_parsed_args()
diff --git a/tests/test_cli.py b/tests/test_cli.py
