Initial MITRE v19 Support

CLI.md

@@ -647,6 +647,28 @@ rules. This is based on the hash of the rule in the following format:
 
 As a result, all cases where rules are shown or converted to JSON are not just simple conversions from TOML.
 
+
+## Multi-version threat mappings (MITRE ATT&CK v18 / v19)
+
+Rules can carry more than one ATT&CK mapping at once. The `threat` field holds the baseline mapping
+(MITRE ATT&CK v18) that ships to Kibana, while an optional `threat_mappings` field holds additional
+version-tagged mappings (e.g. v19). At build time exactly one mapping is emitted as the API `threat`,
+selected automatically by stack version (≤ 9.4 → v18, ≥ 9.5 → v19) or overridden explicitly via
+the `threat_mapping_framework` / `threat_mapping_version` config keys or the
+`DR_THREAT_MAPPING_FRAMEWORK` / `DR_THREAT_MAPPING_VERSION` environment variables;
+`threat_mappings` is always stripped from the shipped artifact.
+
+Generate a target-version mapping from a rule's existing mapping with
+`dev attack convert-threat-mappings` (accuracy-first: anything not present in the mapping config is
+dropped, never guessed), and scaffold a mapping config with `dev attack scaffold-version-map`. The
+feature is DaC-aware. See [docs-dev/multi-version-threat-mappings.md](docs-dev/multi-version-threat-mappings.md)
+for the full guide.
+
+```bash
+# preview v18 -> v19 conversion without writing
+python -m detection_rules dev attack convert-threat-mappings -t 19 --dry-run
+```
+
 ## Debugging
 
 Most of the CLI errors will print a concise, user friendly error. To enable debug mode and see full error stacktraces,

detection_rules/cli_utils.py

@@ -215,17 +215,21 @@ def get_collection(*args: Any, **kwargs: Any) -> Any:
 
         # Warn that if the path does not match the expected path, it will be saved to the expected path
         for rule in rules:
-            threat = rule.contents.data.get("threat")
-            first_tactic = threat[0].tactic.name if threat else ""
             # Check if flag or config is set to not include tactic in the filename
             no_tactic_filename = no_tactic_filename or RULES_CONFIG.no_tactic_filename
-            tactic_name = None if no_tactic_filename else first_tactic
-            rule_name = rulename_to_filename(rule.contents.data.name, tactic_name=tactic_name)
+            # Accept a filename built from the baseline tactic or any versioned (e.g. v19) threat_mappings
+            # tactic, since a rule may still use its older tactic name in the filename until it's renamed.
+            tactic_names = [] if no_tactic_filename else rule.contents.data.get_primary_tactic_names()
+            candidate_names = [rulename_to_filename(rule.contents.data.name, tactic_name=t) for t in tactic_names]
+            if not candidate_names:
+                candidate_names = [rulename_to_filename(rule.contents.data.name, tactic_name=None)]
+            rule_name = candidate_names[0]
             if not rule.path:
                 click.secho(f"WARNING: Rule path for rule not found: {rule_name}", fg="yellow")
-            elif rule.path.name != rule_name:
+            elif rule.path.name not in candidate_names:
+                expected = rule_name if len(candidate_names) == 1 else f"one of {candidate_names}"
                 click.secho(
-                    f"WARNING: Rule path does not match required path: {rule.path.name} != {rule_name}", fg="yellow"
+                    f"WARNING: Rule path does not match required path: {rule.path.name} != {expected}", fg="yellow"
                 )
 
         kwargs["rules"] = rules

detection_rules/config.py

@@ -27,6 +27,16 @@
 ROOT_DIR = Path(__file__).parent.parent
 CUSTOM_RULES_DIR = os.getenv("CUSTOM_RULES_DIR", None)
 
+# Output threat-mapping selection (which framework/version is emitted as the API `threat`).
+# Defaults to MITRE ATT&CK v18 for stacks <= 9.4; auto-promotes to v19 for stacks >= 9.5.
+# Either may be overridden via _config.yaml (`threat_mapping_framework` /
+# `threat_mapping_version`) or the environment variables below, with the environment taking
+# precedence (an explicit env var suppresses auto-promotion).
+DEFAULT_THREAT_MAPPING_FRAMEWORK = "MITRE ATT&CK"
+DEFAULT_THREAT_MAPPING_VERSION = "18"
+THREAT_MAPPING_FRAMEWORK_ENV = "DR_THREAT_MAPPING_FRAMEWORK"
+THREAT_MAPPING_VERSION_ENV = "DR_THREAT_MAPPING_VERSION"
+
 
 @dataclass
 class UnitTest:
@@ -208,7 +218,12 @@ class RulesConfig:
 
     action_dir: Path | None = None
     action_connector_dir: Path | None = None
+    attack_version_maps_dir: Path | None = None
     auto_gen_schema_file: Path | None = None
+    threat_mapping_framework: str = DEFAULT_THREAT_MAPPING_FRAMEWORK
+    threat_mapping_version: str = DEFAULT_THREAT_MAPPING_VERSION
+    # True when the version came from an explicit config key or env var (suppresses auto-promotion)
+    threat_mapping_version_pinned: bool = False
     bbr_rules_dirs: list[Path] = field(default_factory=list)  # type: ignore[reportUnknownVariableType]
     bypass_version_lock: bool = False
     exception_dir: Path | None = None
@@ -355,6 +370,33 @@ def parse_rules_config(path: Path | None = None) -> RulesConfig:  # noqa: PLR091
     # no_tactic_filename
     contents["no_tactic_filename"] = loaded.get("no_tactic_filename", False)
 
+    # attack version mapping configs directory (used by `dev attack convert-threat-mappings`).
+    # Defaults to the stock etc/attack-version-maps directory; custom rules repos may point this at
+    # their own directory of per-pair mapping configs.
+    attack_maps_dir = loaded.get("attack_version_maps_dir")
+    if attack_maps_dir:
+        contents["attack_version_maps_dir"] = base_dir.joinpath(attack_maps_dir).resolve()
+    else:
+        default_maps_dir = Path(get_etc_path(["attack-version-maps"]))
+        contents["attack_version_maps_dir"] = default_maps_dir if default_maps_dir.exists() else None
+
+    # threat-mapping output selection (which framework/version is emitted as the API `threat`).
+    # Environment variables take precedence over the config file values. A version set explicitly
+    # by either source is recorded as pinned, which suppresses stack-based auto-promotion.
+    contents["threat_mapping_framework"] = os.getenv(
+        THREAT_MAPPING_FRAMEWORK_ENV,
+        loaded.get("threat_mapping_framework", DEFAULT_THREAT_MAPPING_FRAMEWORK),
+    )
+    contents["threat_mapping_version"] = str(
+        os.getenv(
+            THREAT_MAPPING_VERSION_ENV,
+            loaded.get("threat_mapping_version", DEFAULT_THREAT_MAPPING_VERSION),
+        )
+    )
+    contents["threat_mapping_version_pinned"] = (
+        os.getenv(THREAT_MAPPING_VERSION_ENV) is not None or "threat_mapping_version" in loaded
+    )
+
     # return the config
     try:
         rules_config = RulesConfig(test_config=test_config, **contents)  # type: ignore[reportArgumentType]