Merge branch 'main' into semantic-release

seansica · seansica · commit 61f4ffd24af7 · 2026-02-13T14:18:29.000-05:00
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -8,7 +8,7 @@ updates:
   - package-ecosystem: "pip" # See documentation for possible values
     directory: "/" # Location of package manifests
     schedule:
-      interval: "weekly"
+      interval: "monthly"
       day: "saturday"
       time: "09:00"
       timezone: "America/New_York"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,21 @@
 # Changelog
 
+## 5.4.1 (2026-02-11)
+
+### Refactor
+- update relationships for detection strategies, analytics and log sources in the excel files
+- add typing-extensions dependency
+
+## 5.4.0 (2026-01-27)
+
+### Feat
+
+- add relationships for detection strategies, analytics and log sources in the excel files
+
+### Fix
+
+- **PR184**: reduce typeChecker noise when passing a float to score()
+
 ## 5.3.0 (2025-11-13)
 
 ### Feat
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
@@ -16,6 +16,7 @@ and [GitHub Actions](https://github.com/mitre-attack/mitreattack-python/actions)
   - It will also update the `CHANGELOG.md` with all commit messages that are compatible with [Conventional Commits](https://www.conventionalcommits.org).
   - NOTE: You should double-check the generated `CHANGELOG.md` file and make sure it looks good.
 - Update other metadata as needed in `pyproject.toml` (dependencies, etc.).
+  - `poetry update --with dev --with docs`
 
 ## 3. Local Validation (Recommended)
 
@@ -36,6 +37,13 @@ poetry install --with=dev
 poetry run ruff check
 poetry run ruff format --check
 
+# Build docs
+# This is managed directly by the Readthedocs site which is configured to watch our repository, but we should test it locally too
+# https://app.readthedocs.org/projects/mitreattack-python/
+cd docs/
+poetry run python -m sphinx -T -b html -d _build/doctrees -D language=en . _build/html
+cd ..
+
 # Run tests
 poetry run pytest --cov=mitreattack --cov-report html
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,9 +12,9 @@
 
 # -- Project information -----------------------------------------------------
 project = "mitreattack-python"
-copyright = "2025, The MITRE Corporation"
-version = "5.3.0"
-release = "5.3.0"
+copyright = "2026, The MITRE Corporation"
+version = "5.4.1"
+release = "5.4.1"
 
 # -- General configuration ---------------------------------------------------
 extensions = [
diff --git a/mitreattack/__init__.py b/mitreattack/__init__.py
@@ -5,7 +5,7 @@
 from PIL import __version__
 from . import attackToExcel, collections, navlayers
 
-__version__ = "5.3.0"
+__version__ = "5.4.1"
 
 __all__ = [
     "attackToExcel",
diff --git a/mitreattack/attackToExcel/attackToExcel.py b/mitreattack/attackToExcel/attackToExcel.py
@@ -147,7 +147,27 @@ def build_dataframes(src: MemoryStore, domain: str) -> Dict:
     return df
 
 
-def write_excel(dataframes: Dict, domain: str, version: Optional[str] = None, output_dir: str = ".") -> List:
+def build_ds_an_lg_relationships(dataframes: Dict) -> Dict[str, pd.DataFrame]:
+    """Build detection-mappings.xlsx with a single DS → Analytic → LogSource sheet."""
+    ds_an = dataframes["detectionstrategies"].get("detectionstrategies-analytic", pd.DataFrame())
+
+    an_ls = dataframes["analytics"].get("analytic-logsource", pd.DataFrame())
+
+    if ds_an.empty or an_ls.empty:
+        combined = pd.DataFrame()
+    else:
+        combined = ds_an.merge(
+            an_ls,
+            on=["analytic_id", "analytic_name", "platforms"],
+            how="left",
+        )
+
+    return {"ds_an_ls": combined}
+
+
+def write_excel(
+    dataframes: Dict, domain: str, src: MemoryStore, version: Optional[str] = None, output_dir: str = "."
+) -> List:
     """Given a set of dataframes from build_dataframes, write the ATT&CK dataset to output directory.
 
     Parameters
@@ -156,6 +176,9 @@ def write_excel(dataframes: Dict, domain: str, version: Optional[str] = None, ou
         A dictionary of pandas dataframes as built by build_dataframes()
     domain : str
         Domain of ATT&CK the dataframes correspond to, e.g "enterprise-attack"
+    src : stix2.MemoryStore
+        A STIX bundle containing ATT&CK data for a domain already loaded into memory.
+        Mutually exclusive with `remote` and `stix_file`.
     version : str, optional
         The version of ATT&CK the dataframes correspond to, e.g "v8.1".
         If omitted, the output files will not be labelled with the version number, by default None
@@ -181,6 +204,10 @@ def write_excel(dataframes: Dict, domain: str, version: Optional[str] = None, ou
         os.makedirs(output_directory)
     # master dataset file
     master_fp = os.path.join(output_directory, f"{domain_version_string}.xlsx")
+
+    ds_an_ls_df = stixToDf.detectionStrategiesAnalyticsLogSourcesDf(src)
+    add_ds_an_ls_to = {"detectionstrategies", "analytics", "datacomponents"}
+
     with pd.ExcelWriter(path=master_fp, engine="xlsxwriter") as master_writer:
         # master list of citations
         citations = pd.DataFrame()
@@ -199,6 +226,14 @@ def write_excel(dataframes: Dict, domain: str, version: Optional[str] = None, ou
                     for sheet_name in object_data:
                         logger.debug(f"Writing sheet to {fp}: {sheet_name}")
                         object_data[sheet_name].to_excel(object_writer, sheet_name=sheet_name, index=False)
+
+                    # Write Detection strategy - Analytics - Log sources file
+                    if (
+                        object_type in add_ds_an_ls_to
+                        and isinstance(ds_an_ls_df, pd.DataFrame)
+                        and not ds_an_ls_df.empty
+                    ):
+                        ds_an_ls_df.to_excel(object_writer, sheet_name="defensive mappings", index=False)
                 written_files.append(fp)
 
                 # add citations to master citations list
@@ -285,13 +320,16 @@ def write_excel(dataframes: Dict, domain: str, version: Optional[str] = None, ou
 
                 written_files.append(fp)
 
+        if isinstance(ds_an_ls_df, pd.DataFrame) and not ds_an_ls_df.empty:
+            ds_an_ls_df.to_excel(master_writer, sheet_name="defensive mappings", index=False)
         # remove duplicate citations and add sheet to master file
         logger.debug(f"Writing sheet to {master_fp}: citations")
         citations.drop_duplicates(subset="reference", ignore_index=True).sort_values("reference").to_excel(
             master_writer, sheet_name="citations", index=False
         )
 
     written_files.append(master_fp)
+
     for thefile in written_files:
         logger.info(f"Excel file created: {thefile}")
     return written_files
@@ -364,11 +402,11 @@ def export(
             major_version = int(match.group(1))
             if major_version < 18:
                 dataframes = build_dataframes_pre_v18(src=mem_store, domain=domain)
-                write_excel(dataframes=dataframes, domain=domain, version=version, output_dir=output_dir)
+                write_excel(dataframes=dataframes, domain=domain, src=mem_store, version=version, output_dir=output_dir)
                 return
 
     dataframes = build_dataframes(src=mem_store, domain=domain)
-    write_excel(dataframes=dataframes, domain=domain, version=version, output_dir=output_dir)
+    write_excel(dataframes=dataframes, domain=domain, src=mem_store, version=version, output_dir=output_dir)
 
 
 def main():
diff --git a/mitreattack/attackToExcel/stixToDf.py b/mitreattack/attackToExcel/stixToDf.py
@@ -367,16 +367,67 @@ def analyticsToDf(src):
     analytics = src.query([Filter("type", "=", "x-mitre-analytic")])
     analytics = remove_revoked_deprecated(analytics)
 
+    # Detection strategies (needed for analytics to detection strategies relationship)
+    detection_strategies = src.query([Filter("type", "=", "x-mitre-detection-strategy")])
+    detection_strategies = remove_revoked_deprecated(detection_strategies)
+
     dataframes = {}
     if analytics:
         analytic_rows = []
+        logsource_rows = []
+        analytic_to_ds_rows = []
+
+        # analytics to detection strategies
+        analytic_to_ds_map = {}
+        for ds in detection_strategies:
+            for analytic_id in ds.get("x_mitre_analytic_refs", []):
+                analytic_to_ds_map.setdefault(analytic_id, []).append(
+                    {
+                        "detection_strategy_attack_id": ds["external_references"][0]["external_id"],
+                        "detection_strategy_id": ds["id"],
+                        "detection_strategy_name": ds.get("name", ""),
+                    }
+                )
+
         for analytic in tqdm(analytics, desc="parsing analytics"):
             analytic_rows.append(parseBaseStix(analytic))
 
+            # log-source relationship table rows
+            for logsrc in analytic.get("x_mitre_log_source_references", []):
+                data_comp_id = logsrc.get("x_mitre_data_component_ref", "")
+                data_comp = src.get(data_comp_id)
+                data_comp_name = data_comp.get("name", "") if data_comp else ""
+                data_comp_attack_id = data_comp["external_references"][0]["external_id"]
+
+                logsource_rows.append(
+                    {
+                        "analytic_id": analytic["id"],
+                        "analytic_name": analytic["external_references"][0]["external_id"],
+                        "data_component_id": data_comp_id,
+                        "data_component_name": data_comp_name,
+                        "data_component_attack_id": data_comp_attack_id,
+                        "log_source_name": logsrc.get("name", ""),
+                        "channel": logsrc.get("channel", ""),
+                        "platforms": ", ".join(sorted(analytic.get("x_mitre_platforms", []))),
+                    }
+                )
+
+            # detection strategies relationship table rows
+            for ds_info in analytic_to_ds_map.get(analytic["id"], []):
+                analytic_to_ds_rows.append(
+                    {
+                        "analytic_id": analytic["id"],
+                        "analytic_name": analytic["external_references"][0]["external_id"],
+                        "detection_strategy_id": ds_info["detection_strategy_id"],
+                        "detection_strategy_attack_id": ds_info["detection_strategy_attack_id"],
+                        "detection_strategy_name": ds_info["detection_strategy_name"],
+                        "platforms": ", ".join(sorted(analytic.get("x_mitre_platforms", []))),
+                    }
+                )
+
+        dataframes["analytics"] = pd.DataFrame(analytic_rows).sort_values("name")
+
         citations = get_citations(analytics)
-        dataframes = {
-            "analytics": pd.DataFrame(analytic_rows).sort_values("name"),
-        }
         if not citations.empty:
             dataframes["citations"] = citations.sort_values("reference")
 
@@ -398,20 +449,36 @@ def detectionstrategiesToDf(src):
     dataframes = {}
     if detection_strategies:
         detection_strategy_rows = []
+        rel_rows = []
         for detection_strategy in tqdm(detection_strategies, desc="parsing detection strategies"):
-            detection_strategy_rows.append(parseBaseStix(detection_strategy))
+            row = parseBaseStix(detection_strategy)
+            row["analytic_refs"] = "; ".join(detection_strategy.get("x_mitre_analytic_refs", []))
+            detection_strategy_rows.append(row)
+
+            # analytics relationship table rows
+            for analytic_id in detection_strategy.get("x_mitre_analytic_refs", []):
+                analytic_obj = src.get(analytic_id)
+
+                rel_rows.append(
+                    {
+                        "detection_strategy_attack_id": detection_strategy["external_references"][0]["external_id"],
+                        "detection_strategy_id": detection_strategy["id"],
+                        "detection_strategy_name": detection_strategy.get("name", ""),
+                        "analytic_id": analytic_id,
+                        "analytic_name": analytic_obj["external_references"][0]["external_id"],
+                        "platforms": ", ".join(sorted(analytic_obj.get("x_mitre_platforms", []))),
+                    }
+                )
+
+        # Build main dataframes
+        dataframes["detectionstrategies"] = pd.DataFrame(detection_strategy_rows).sort_values("name")
 
         citations = get_citations(detection_strategies)
-        dataframes = {
-            "detectionstrategies": pd.DataFrame(detection_strategy_rows).sort_values("name"),
-        }
         if not citations.empty:
-            if "citations" in dataframes:  # append to existing citations from references
-                dataframes["citations"] = citations.sort_values("reference")
+            dataframes["citations"] = citations.sort_values("reference")
 
     else:
         logger.warning("No detection strategies found - nothing to parse")
-
     return dataframes
 
 
@@ -461,6 +528,50 @@ def softwareToDf(src):
     return dataframes
 
 
+def detectionStrategiesAnalyticsLogSourcesDf(src):
+    """Build a single DS -> LogSource -> Analytic dataframe directly from STIX."""
+    detection_strategies = src.query([Filter("type", "=", "x-mitre-detection-strategy")])
+    detection_strategies = remove_revoked_deprecated(detection_strategies)
+
+    analytics = src.query([Filter("type", "=", "x-mitre-analytic")])
+    analytics = remove_revoked_deprecated(analytics)
+    analytics_by_id = {a["id"]: a for a in analytics}
+
+    rows = []
+    for ds in detection_strategies:
+        ds_attack_id = ds.get("external_references", [{}])[0].get("external_id", "")
+        ds_id = ds.get("id", "")
+        ds_name = ds.get("name", "")
+
+        for analytic_id in ds.get("x_mitre_analytic_refs", []):
+            analytic = analytics_by_id.get(analytic_id)
+            analytic_attack_id = analytic["external_references"][0]["external_id"]
+            platforms = ", ".join(sorted(analytic.get("x_mitre_platforms", [])))
+
+            logsrc_refs = analytic.get("x_mitre_log_source_references", [])
+            for logsrc in logsrc_refs:
+                data_comp_id = logsrc.get("x_mitre_data_component_ref", "")
+                data_comp = src.get(data_comp_id)
+
+                rows.append(
+                    {
+                        "detection_strategy_attack_id": ds_attack_id,
+                        "detection_strategy_id": ds_id,
+                        "detection_strategy_name": ds_name,
+                        "analytic_id": analytic_id,
+                        "analytic_name": analytic_attack_id,
+                        "platforms": platforms,
+                        "log_source_name": logsrc.get("name", ""),
+                        "channel": logsrc.get("channel", ""),
+                        "data_component_id": data_comp_id,
+                        "data_component_name": (data_comp.get("name", "") if data_comp else ""),
+                        "data_component_attack_id": data_comp["external_references"][0]["external_id"],
+                    }
+                )
+
+    return pd.DataFrame(rows)
+
+
 def groupsToDf(src):
     """Parse STIX groups from the given data and return corresponding pandas dataframes.
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "mitreattack-python"
 description = "MITRE ATT&CK python library"
-version = "5.3.0"
+version = "5.4.1"
 authors = [{ name = "MITRE ATT&CK", email = "attack@mitre.org" }]
 license = { text = "Apache-2.0" }
 readme = "README.md"
@@ -30,6 +30,7 @@ dependencies = [
     "tabulate>=0.9.0",
     "tqdm>=4.66.1",
     "typer>=0.9.0",
+    "typing-extensions>=4.0.0",
     "wheel>=0.41.2",
     "xlsxwriter>=3.1.8",
 ]
@@ -126,4 +127,4 @@ version_files = [
     "docs/conf.py:^version = ['\"](.*)['\"]",
     "docs/conf.py:^release = ['\"](.*)['\"]",
     "mitreattack/__init__.py:^__version__ = ['\"](.*)['\"]",
-]
+]
