contentctl 5.3.1__py3-none-any.whl → 5.4.0__py3-none-any.whl

contentctl/actions/inspect.py

@@ -16,6 +16,7 @@ from contentctl.objects.errors import (
     DetectionMissingError,
     MetadataValidationError,
     VersionBumpingError,
+    VersionBumpingTooFarError,
     VersionDecrementedError,
 )
 from contentctl.objects.savedsearches_conf import SavedsearchesConf
@@ -101,7 +102,7 @@ class Inspect:
             -F "app_package=@<PATH/APP-PACKAGE>" \
             -F "included_tags=cloud" \
             --url "https://appinspect.splunk.com/v1/app/validate"
-        
+
         This is confirmed by the great resource:
         https://curlconverter.com/
         """
@@ -429,6 +430,19 @@ class Inspect:
                     )
                 )
 
+            # Versions should never increase more than one version between releases
+            if (
+                current_stanza.metadata.detection_version
+                > previous_stanza.metadata.detection_version + 1
+            ):
+                validation_errors[rule_name].append(
+                    VersionBumpingTooFarError(
+                        rule_name=rule_name,
+                        current_version=current_stanza.metadata.detection_version,
+                        previous_version=previous_stanza.metadata.detection_version,
+                    )
+                )
+
         # Convert our dict mapping to a flat list of errors for use in reporting
         validation_error_list = [
             x for inner_list in validation_errors.values() for x in inner_list

contentctl/actions/validate.py

@@ -4,7 +4,7 @@ from contentctl.enrichments.attack_enrichment import AttackEnrichment
 from contentctl.enrichments.cve_enrichment import CveEnrichment
 from contentctl.helper.splunk_app import SplunkApp
 from contentctl.helper.utils import Utils
-from contentctl.input.director import Director, DirectorOutputDto
+from contentctl.input.director import Director, DirectorOutputDto, ValidationFailedError
 from contentctl.objects.atomic import AtomicEnrichment
 from contentctl.objects.config import validate
 from contentctl.objects.data_source import DataSource
@@ -13,19 +13,26 @@ from contentctl.objects.lookup import FileBackedLookup, RuntimeCSV
 
 class Validate:
     def execute(self, input_dto: validate) -> DirectorOutputDto:
-        director_output_dto = DirectorOutputDto(
-            AtomicEnrichment.getAtomicEnrichment(input_dto),
-            AttackEnrichment.getAttackEnrichment(input_dto),
-            CveEnrichment.getCveEnrichment(input_dto),
-        )
+        try:
+            director_output_dto = DirectorOutputDto(
+                AtomicEnrichment.getAtomicEnrichment(input_dto),
+                AttackEnrichment.getAttackEnrichment(input_dto),
+                CveEnrichment.getCveEnrichment(input_dto),
+            )
+
+            director = Director(director_output_dto)
+            director.execute(input_dto)
+            self.ensure_no_orphaned_files_in_lookups(
+                input_dto.path, director_output_dto
+            )
+            if input_dto.data_source_TA_validation:
+                self.validate_latest_TA_information(director_output_dto.data_sources)
 
-        director = Director(director_output_dto)
-        director.execute(input_dto)
-        self.ensure_no_orphaned_files_in_lookups(input_dto.path, director_output_dto)
-        if input_dto.data_source_TA_validation:
-            self.validate_latest_TA_information(director_output_dto.data_sources)
+            return director_output_dto
 
-        return director_output_dto
+        except ValidationFailedError:
+            # Just re-raise without additional output since we already formatted everything
+            raise SystemExit(1)
 
     def ensure_no_orphaned_files_in_lookups(
         self, repo_path: pathlib.Path, director_output_dto: DirectorOutputDto

contentctl/input/director.py

@@ -109,6 +109,40 @@ class DirectorOutputDto:
         self.uuid_to_content_map[content.id] = content
 
 
+class Colors:
+    HEADER = "\033[95m"
+    BLUE = "\033[94m"
+    CYAN = "\033[96m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    RED = "\033[91m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+    END = "\033[0m"
+    MAGENTA = "\033[35m"
+    BRIGHT_MAGENTA = "\033[95m"
+
+    # Add fallback symbols for Windows
+    CHECK_MARK = "✓" if sys.platform != "win32" else "*"
+    WARNING = "⚠️" if sys.platform != "win32" else "!"
+    ERROR = "❌" if sys.platform != "win32" else "X"
+    ARROW = "🎯" if sys.platform != "win32" else ">"
+    TOOLS = "🛠️" if sys.platform != "win32" else "#"
+    DOCS = "📚" if sys.platform != "win32" else "?"
+    BULB = "💡" if sys.platform != "win32" else "i"
+    SEARCH = "🔍" if sys.platform != "win32" else "@"
+    SPARKLE = "✨" if sys.platform != "win32" else "*"
+    ZAP = "⚡" if sys.platform != "win32" else "!"
+
+
+class ValidationFailedError(Exception):
+    """Custom exception for validation failures that already have formatted output."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+
 class Director:
     input_dto: validate
     output_dto: DirectorOutputDto
@@ -268,18 +302,96 @@ class Director:
             end="",
             flush=True,
         )
-        print("Done!")
 
         if len(validation_errors) > 0:
-            errors_string = "\n\n".join(
-                [
-                    f"File: {e_tuple[0]}\nError: {str(e_tuple[1])}"
-                    for e_tuple in validation_errors
-                ]
+            if sys.platform == "win32":
+                sys.stdout.reconfigure(encoding="utf-8")
+
+            print("\n")  # Clean separation
+            print(f"{Colors.BOLD}{Colors.BRIGHT_MAGENTA}╔{'═' * 60}╗{Colors.END}")
+            print(
+                f"{Colors.BOLD}{Colors.BRIGHT_MAGENTA}║{Colors.BLUE}{f'{Colors.SEARCH} Content Validation Summary':^59}{Colors.BRIGHT_MAGENTA}║{Colors.END}"
             )
-            # print(f"The following {len(validation_errors)} error(s) were found during validation:\n\n{errors_string}\n\nVALIDATION FAILED")
-            # We quit after validation a single type/group of content because it can cause significant cascading errors in subsequent
-            # types of content (since they may import or otherwise use it)
-            raise Exception(
-                f"The following {len(validation_errors)} error(s) were found during validation:\n\n{errors_string}\n\nVALIDATION FAILED"
+            print(f"{Colors.BOLD}{Colors.BRIGHT_MAGENTA}╚{'═' * 60}╝{Colors.END}\n")
+
+            print(
+                f"{Colors.BOLD}{Colors.GREEN}{Colors.SPARKLE} Validation Completed{Colors.END} – Issues detected in {Colors.RED}{Colors.BOLD}{len(validation_errors)}{Colors.END} files.\n"
             )
+
+            for index, entry in enumerate(validation_errors, 1):
+                file_path, error = entry
+                width = max(70, len(str(file_path)) + 15)
+
+                # File header with numbered emoji
+                number_emoji = f"{index}️⃣"
+                print(f"{Colors.YELLOW}┏{'━' * width}┓{Colors.END}")
+                print(
+                    f"{Colors.YELLOW}┃{Colors.BOLD} {number_emoji} File: {Colors.CYAN}{file_path}{Colors.END}{' ' * (width - len(str(file_path)) - 9)}{Colors.YELLOW}┃{Colors.END}"
+                )
+                print(f"{Colors.YELLOW}┗{'━' * width}┛{Colors.END}")
+
+                print(
+                    f"   {Colors.RED}{Colors.BOLD}{Colors.ZAP} Validation Issues:{Colors.END}"
+                )
+
+                if isinstance(error, ValidationError):
+                    for err in error.errors():
+                        error_msg = err.get("msg", "")
+                        if "https://errors.pydantic.dev" in error_msg:
+                            continue
+
+                        # Clean error categorization
+                        if "Field required" in error_msg:
+                            print(
+                                f"      {Colors.YELLOW}{Colors.WARNING} Field Required: {err.get('loc', [''])[0]}{Colors.END}"
+                            )
+                        elif "Input should be" in error_msg:
+                            print(
+                                f"      {Colors.MAGENTA}{Colors.ARROW} Invalid Value for {err.get('loc', [''])[0]}{Colors.END}"
+                            )
+                            if err.get("ctx", {}).get("expected", None) is not None:
+                                print(
+                                    f"        Valid options: {err.get('ctx', {}).get('expected', None)}"
+                                )
+                        elif "Extra inputs" in error_msg:
+                            print(
+                                f"      {Colors.BLUE}{Colors.ERROR} Unexpected Field: {err.get('loc', [''])[0]}{Colors.END}"
+                            )
+                        elif "Failed to find" in error_msg:
+                            print(
+                                f"      {Colors.RED}{Colors.SEARCH} Missing Reference: {error_msg}{Colors.END}"
+                            )
+                        else:
+                            print(
+                                f"      {Colors.RED}{Colors.ERROR} {error_msg}{Colors.END}"
+                            )
+                else:
+                    print(f"      {Colors.RED}{Colors.ERROR} {str(error)}{Colors.END}")
+                print("")
+
+            # Clean footer with next steps
+            max_width = max(60, max(len(str(e[0])) + 15 for e in validation_errors))
+            print(f"{Colors.BOLD}{Colors.CYAN}╔{'═' * max_width}╗{Colors.END}")
+            print(
+                f"{Colors.BOLD}{Colors.CYAN}║{Colors.BLUE}{Colors.ARROW + ' Next Steps':^{max_width - 1}}{Colors.CYAN}║{Colors.END}"
+            )
+            print(f"{Colors.BOLD}{Colors.CYAN}╚{'═' * max_width}╝{Colors.END}\n")
+
+            print(
+                f"{Colors.GREEN}{Colors.TOOLS} Fix the validation issues in the listed files{Colors.END}"
+            )
+            print(
+                f"{Colors.YELLOW}{Colors.DOCS} Check the documentation: {Colors.UNDERLINE}https://github.com/splunk/contentctl{Colors.END}"
+            )
+            print(
+                f"{Colors.BLUE}{Colors.BULB} Use --verbose for detailed error information{Colors.END}\n"
+            )
+
+            raise ValidationFailedError(
+                f"Validation failed with {len(validation_errors)} error(s)"
+            )
+
+        # Success case
+        print(
+            f"\r{f'{contentCartegoryName} Progress'.rjust(23)}: [{progress_percent:3.0f}%]... {Colors.GREEN}{Colors.CHECK_MARK} Done!{Colors.END}"
+        )

contentctl/objects/abstract_security_content_objects/security_content_object_abstract.py

@@ -12,6 +12,7 @@ import pathlib
 import pprint
 import uuid
 from abc import abstractmethod
+from difflib import get_close_matches
 from functools import cached_property
 from typing import List, Optional, Tuple, Union
 
@@ -700,16 +701,18 @@ class SecurityContentObject_Abstract(BaseModel, abc.ABC):
     def mapNamesToSecurityContentObjects(
         cls, v: list[str], director: Union[DirectorOutputDto, None]
     ) -> list[Self]:
-        if director is not None:
-            name_map = director.name_to_content_map
-        else:
-            name_map = {}
+        if director is None:
+            raise Exception(
+                "Direction was 'None' when passed to "
+                "'mapNamesToSecurityContentObjects'. This is "
+                "an error in the contentctl codebase which must be resolved."
+            )
 
         mappedObjects: list[Self] = []
         mistyped_objects: list[SecurityContentObject_Abstract] = []
         missing_objects: list[str] = []
         for object_name in v:
-            found_object = name_map.get(object_name, None)
+            found_object = director.name_to_content_map.get(object_name, None)
             if not found_object:
                 missing_objects.append(object_name)
             elif not isinstance(found_object, cls):
@@ -718,22 +721,40 @@ class SecurityContentObject_Abstract(BaseModel, abc.ABC):
                 mappedObjects.append(found_object)
 
         errors: list[str] = []
-        if len(missing_objects) > 0:
+        for missing_object in missing_objects:
+            if missing_object.endswith("_filter"):
+                # Most filter macros are defined as empty at runtime, so we do not
+                # want to make any suggestions.  It is time consuming and not helpful
+                # to make these suggestions, so we just skip them in this check.
+                continue
+            matches = get_close_matches(
+                missing_object,
+                director.name_to_content_map.keys(),
+                n=3,
+            )
+            if matches == []:
+                matches = ["NO SUGGESTIONS"]
+
+            matches_string = ", ".join(matches)
             errors.append(
-                f"Failed to find the following '{cls.__name__}': {missing_objects}"
+                f"Unable to find: {missing_object}\n       Suggestions: {matches_string}"
+            )
+
+        for mistyped_object in mistyped_objects:
+            matches = get_close_matches(
+                mistyped_object.name, director.name_to_content_map.keys(), n=3
+            )
+
+            errors.append(
+                f"'{mistyped_object.name}' expected to have type '{cls.__name__}', but actually "
+                f"had type '{type(mistyped_object).__name__}'"
             )
-        if len(mistyped_objects) > 0:
-            for mistyped_object in mistyped_objects:
-                errors.append(
-                    f"'{mistyped_object.name}' expected to have type '{cls}', but actually "
-                    f"had type '{type(mistyped_object)}'"
-                )
 
         if len(errors) > 0:
-            error_string = "\n  - ".join(errors)
+            error_string = "\n\n  - ".join(errors)
             raise ValueError(
-                f"Found {len(errors)} issues when resolving references Security Content Object "
-                f"names:\n  - {error_string}"
+                f"Found {len(errors)} issues when resolving references to '{cls.__name__}' objects:\n"
+                f"  - {error_string}"
             )
 
         # Sort all objects sorted by name

contentctl/objects/base_security_event.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel, ConfigDict
+
+from contentctl.objects.detection import Detection
+
+
+class BaseSecurityEvent(BaseModel, ABC):
+    """
+    Base event class for a Splunk security event (e.g. risks and notables)
+    """
+
+    # The search name (e.g. "ESCU - Windows Modify Registry EnableLinkedConnections - Rule")
+    search_name: str
+
+    # The search ID that found that generated this event
+    orig_sid: str
+
+    # Allowing fields that aren't explicitly defined to be passed since some of the risk/notable
+    # event's fields vary depending on the SPL which generated them
+    model_config = ConfigDict(extra="allow")
+
+    @abstractmethod
+    def validate_against_detection(self, detection: Detection) -> None:
+        """
+        Validate this risk/notable event against the given detection
+        """
+        raise NotImplementedError()

contentctl/objects/correlation_search.py

@@ -18,6 +18,7 @@ from contentctl.actions.detection_testing.progress_bar import (
     format_pbar_string,  # type: ignore
 )
 from contentctl.helper.utils import Utils
+from contentctl.objects.base_security_event import BaseSecurityEvent
 from contentctl.objects.base_test_result import TestResultStatus
 from contentctl.objects.detection import Detection
 from contentctl.objects.errors import (
@@ -222,6 +223,9 @@ class CorrelationSearch(BaseModel):
     # The list of risk events found
     _risk_events: list[RiskEvent] | None = PrivateAttr(default=None)
 
+    # The list of risk data model events found
+    _risk_dm_events: list[BaseSecurityEvent] | None = PrivateAttr(default=None)
+
     # The list of notable events found
     _notable_events: list[NotableEvent] | None = PrivateAttr(default=None)
 
@@ -554,6 +558,13 @@ class CorrelationSearch(BaseModel):
                         raise
                     events.append(event)
                     self.logger.debug(f"Found risk event for '{self.name}': {event}")
+                else:
+                    msg = (
+                        f"Found event for unexpected index ({result['index']}) in our query "
+                        f"results (expected {Indexes.RISK_INDEX})"
+                    )
+                    self.logger.error(msg)
+                    raise ValueError(msg)
         except ServerError as e:
             self.logger.error(f"Error returned from Splunk instance: {e}")
             raise e
@@ -623,6 +634,13 @@ class CorrelationSearch(BaseModel):
                         raise
                     events.append(event)
                     self.logger.debug(f"Found notable event for '{self.name}': {event}")
+                else:
+                    msg = (
+                        f"Found event for unexpected index ({result['index']}) in our query "
+                        f"results (expected {Indexes.NOTABLE_INDEX})"
+                    )
+                    self.logger.error(msg)
+                    raise ValueError(msg)
         except ServerError as e:
             self.logger.error(f"Error returned from Splunk instance: {e}")
             raise e
@@ -637,15 +655,119 @@ class CorrelationSearch(BaseModel):
 
         return events
 
+    def risk_dm_event_exists(self) -> bool:
+        """Whether at least one matching risk data model event exists
+
+        Queries the `risk` data model and returns True if at least one matching event (could come
+        from risk or notable index) exists for this search
+        :return: a bool indicating whether a risk data model event for this search exists in the
+            risk data model
+        """
+        # We always force an update on the cache when checking if events exist
+        events = self.get_risk_dm_events(force_update=True)
+        return len(events) > 0
+
+    def get_risk_dm_events(self, force_update: bool = False) -> list[BaseSecurityEvent]:
+        """Get risk data model events from the Splunk instance
+
+        Queries the `risk` data model and returns any matching events (could come from risk or
+        notable index)
+        :param force_update: whether the cached _risk_events should be forcibly updated if already
+            set
+        :return: a list of risk events
+        """
+        # Reset the list of risk data model events if we're forcing an update
+        if force_update:
+            self.logger.debug("Resetting risk data model event cache.")
+            self._risk_dm_events = None
+
+        # Use the cached risk_dm_events unless we're forcing an update
+        if self._risk_dm_events is not None:
+            self.logger.debug(
+                f"Using cached risk data model events ({len(self._risk_dm_events)} total)."
+            )
+            return self._risk_dm_events
+
+        # TODO (#248): Refactor risk/notable querying to pin to a single savedsearch ID
+        # Search for all risk data model events from a single scheduled search (indicated by
+        # orig_sid)
+        query = (
+            f'datamodel Risk All_Risk flat | search search_name="{self.name}" [datamodel Risk '
+            f'All_Risk flat | search search_name="{self.name}" | tail 1 | fields orig_sid] '
+            "| tojson"
+        )
+        result_iterator = self._search(query)
+
+        # Iterate over the events, storing them in a list and checking for any errors
+        events: list[BaseSecurityEvent] = []
+        risk_count = 0
+        notable_count = 0
+        try:
+            for result in result_iterator:
+                # sanity check that this result from the iterator is a risk event and not some
+                # other metadata
+                if result["index"] == Indexes.RISK_INDEX:
+                    try:
+                        parsed_raw = json.loads(result["_raw"])
+                        event = RiskEvent.model_validate(parsed_raw)
+                    except Exception:
+                        self.logger.error(
+                            f"Failed to parse RiskEvent from search result: {result}"
+                        )
+                        raise
+                    events.append(event)
+                    risk_count += 1
+                    self.logger.debug(
+                        f"Found risk event in risk data model for '{self.name}': {event}"
+                    )
+                elif result["index"] == Indexes.NOTABLE_INDEX:
+                    try:
+                        parsed_raw = json.loads(result["_raw"])
+                        event = NotableEvent.model_validate(parsed_raw)
+                    except Exception:
+                        self.logger.error(
+                            f"Failed to parse NotableEvent from search result: {result}"
+                        )
+                        raise
+                    events.append(event)
+                    notable_count += 1
+                    self.logger.debug(
+                        f"Found notable event in risk data model for '{self.name}': {event}"
+                    )
+                else:
+                    msg = (
+                        f"Found event for unexpected index ({result['index']}) in our query "
+                        f"results (expected {Indexes.NOTABLE_INDEX} or {Indexes.RISK_INDEX})"
+                    )
+                    self.logger.error(msg)
+                    raise ValueError(msg)
+        except ServerError as e:
+            self.logger.error(f"Error returned from Splunk instance: {e}")
+            raise e
+
+        # Log if no events were found
+        if len(events) < 1:
+            self.logger.debug(f"No events found in risk data model for '{self.name}'")
+        else:
+            # Set the cache if we found events
+            self._risk_dm_events = events
+            self.logger.debug(
+                f"Caching {len(self._risk_dm_events)} risk data model events."
+            )
+
+        # Log counts of risk and notable events found
+        self.logger.debug(
+            f"Found {risk_count} risk events and {notable_count} notable events in the risk data "
+            "model"
+        )
+
+        return events
+
     def validate_risk_events(self) -> None:
         """Validates the existence of any expected risk events
 
         First ensure the risk event exists, and if it does validate its risk message and make sure
-        any events align with the specified risk object. Also adds the risk index to the purge list
-        if risk events existed
-        :param elapsed_sleep_time: an int representing the amount of time slept thus far waiting to
-            check the risks/notables
-        :returns: an IntegrationTestResult on failure; None on success
+        any events align with the specified risk object.
         """
         # Ensure the rba object is defined
         if self.detection.rba is None:
@@ -735,13 +857,29 @@ class CorrelationSearch(BaseModel):
     def validate_notable_events(self) -> None:
         """Validates the existence of any expected notables
 
-        Ensures the notable exists. Also adds the notable index to the purge list if notables
-        existed
-        :param elapsed_sleep_time: an int representing the amount of time slept thus far waiting to
-            check the risks/notables
-        :returns: an IntegrationTestResult on failure; None on success
+        Check various fields within the notable to ensure alignment with the detection definition.
+        Additionally, ensure that the notable does not appear in the risk data model, as this is
+        currently undesired behavior for ESCU detections.
+        """
+        if self.notable_in_risk_dm():
+            raise ValidationFailed(
+                "One or more notables appeared in the risk data model. This could lead to risk "
+                "score doubling, and/or notable multiplexing, depending on the detection type "
+                "(e.g. TTP), or the number of risk modifiers."
+            )
+
+    def notable_in_risk_dm(self) -> bool:
+        """Check if notables are in the risk data model
+
+        Returns a bool indicating whether notables are in the risk data model or not.
+
+        :returns: a bool, True if notables are in the risk data model results; False if not
         """
-        raise NotImplementedError()
+        if self.risk_dm_event_exists():
+            for event in self.get_risk_dm_events():
+                if isinstance(event, NotableEvent):
+                    return True
+        return False
 
     # NOTE: it would be more ideal to switch this to a system which gets the handle of the saved search job and polls
     #   it for completion, but that seems more tricky
@@ -828,8 +966,8 @@ class CorrelationSearch(BaseModel):
 
                     try:
                         # Validate risk events
-                        self.logger.debug("Checking for matching risk events")
                         if self.has_risk_analysis_action:
+                            self.logger.debug("Checking for matching risk events")
                             if self.risk_event_exists():
                                 # TODO (PEX-435): should this in the retry loop? or outside it?
                                 #   -> I've observed there being a missing risk event (15/16) on
@@ -846,22 +984,28 @@ class CorrelationSearch(BaseModel):
                                 raise ValidationFailed(
                                     f"TEST FAILED: No matching risk event created for: {self.name}"
                                 )
+                        else:
+                            self.logger.debug(
+                                f"No risk action defined for '{self.name}'"
+                            )
 
                         # Validate notable events
-                        self.logger.debug("Checking for matching notable events")
                         if self.has_notable_action:
+                            self.logger.debug("Checking for matching notable events")
                             # NOTE: because we check this last, if both fail, the error message about notables will
                             # always be the last to be added and thus the one surfaced to the user
                             if self.notable_event_exists():
                                 # TODO (PEX-435): should this in the retry loop? or outside it?
-                                # TODO (PEX-434): implement deeper notable validation (the method
-                                #   commented out below is unimplemented)
-                                # self.validate_notable_events(elapsed_sleep_time)
+                                self.validate_notable_events()
                                 pass
                             else:
                                 raise ValidationFailed(
                                     f"TEST FAILED: No matching notable event created for: {self.name}"
                                 )
+                        else:
+                            self.logger.debug(
+                                f"No notable action defined for '{self.name}'"
+                            )
                     except ValidationFailed as e:
                         self.logger.error(f"Risk/notable validation failed: {e}")
                         result = IntegrationTestResult(
@@ -1015,6 +1159,7 @@ class CorrelationSearch(BaseModel):
         # reset caches
         self._risk_events = None
         self._notable_events = None
+        self._risk_dm_events = None
 
     def update_pbar(self, state: str) -> str:
         """

contentctl/objects/errors.py

@@ -185,7 +185,7 @@ class VersionBumpingError(VersioningError):
         return (
             f"Rule '{self.rule_name}' has changed in current build compared to previous "
             "build (stanza hashes differ); the detection version should be bumped "
-            f"to at least {self.previous_version + 1}."
+            f"to {self.previous_version + 1}."
         )
 
     @property
@@ -194,4 +194,30 @@ class VersionBumpingError(VersioningError):
         A short-form error message
         :returns: a str, the message
         """
-        return f"Detection version in current build should be bumped to at least {self.previous_version + 1}."
+        return f"Detection version in current build should be bumped to {self.previous_version + 1}."
+
+
+class VersionBumpingTooFarError(VersioningError):
+    """
+    An error indicating the detection changed but its version was bumped too far
+    """
+
+    @property
+    def long_message(self) -> str:
+        """
+        A long-form error message
+        :returns: a str, the message
+        """
+        return (
+            f"Rule '{self.rule_name}' has changed in current build compared to previous "
+            "build (stanza hashes differ); however the detection version increased too much"
+            f"The version should be reduced to {self.previous_version + 1}."
+        )
+
+    @property
+    def short_message(self) -> str:
+        """
+        A short-form error message
+        :returns: a str, the message
+        """
+        return f"Detection version in current build should be reduced to {self.previous_version + 1}."

contentctl/objects/notable_event.py

@@ -1,19 +1,12 @@
-from pydantic import ConfigDict, BaseModel
-
+from contentctl.objects.base_security_event import BaseSecurityEvent
 from contentctl.objects.detection import Detection
 
 
-# TODO (PEX-434): implement deeper notable validation
-class NotableEvent(BaseModel):
-    # The search name (e.g. "ESCU - Windows Modify Registry EnableLinkedConnections - Rule")
-    search_name: str
-
-    # The search ID that found that generated this risk event
-    orig_sid: str
-
-    # Allowing fields that aren't explicitly defined to be passed since some of the risk event's
-    # fields vary depending on the SPL which generated them
-    model_config = ConfigDict(extra="allow")
+class NotableEvent(BaseSecurityEvent):
+    # TODO (PEX-434): implement deeper notable validation
 
     def validate_against_detection(self, detection: Detection) -> None:
+        """
+        Validate this risk/notable event against the given detection
+        """
         raise NotImplementedError()

contentctl/objects/risk_event.py

@@ -1,26 +1,17 @@
 import re
 from functools import cached_property
 
-from pydantic import (
-    BaseModel,
-    ConfigDict,
-    Field,
-    PrivateAttr,
-    computed_field,
-    field_validator,
-)
+from pydantic import Field, PrivateAttr, computed_field, field_validator
 
+from contentctl.objects.base_security_event import BaseSecurityEvent
 from contentctl.objects.detection import Detection
 from contentctl.objects.errors import ValidationFailed
 from contentctl.objects.rba import RiskObject
 
 
-class RiskEvent(BaseModel):
+class RiskEvent(BaseSecurityEvent):
     """Model for risk event in ES"""
 
-    # The search name (e.g. "ESCU - Windows Modify Registry EnableLinkedConnections - Rule")
-    search_name: str
-
     # The subject of the risk event (e.g. a username, process name, system name, account ID, etc.)
     # (not to be confused w/ the risk object from the detection)
     es_risk_object: int | str = Field(alias="risk_object")
@@ -32,9 +23,6 @@ class RiskEvent(BaseModel):
     # The level of risk associated w/ the risk event
     risk_score: int
 
-    # The search ID that found that generated this risk event
-    orig_sid: str
-
     # The message for the risk event
     risk_message: str
 
@@ -53,10 +41,6 @@ class RiskEvent(BaseModel):
     # Private attribute caching the risk object this RiskEvent is mapped to
     _matched_risk_object: RiskObject | None = PrivateAttr(default=None)
 
-    # Allowing fields that aren't explicitly defined to be passed since some of the risk event's
-    # fields vary depending on the SPL which generated them
-    model_config = ConfigDict(extra="allow")
-
     @field_validator("annotations_mitre_attack", "analyticstories", mode="before")
     @classmethod
     def _convert_str_value_to_singleton(cls, v: str | list[str]) -> list[str]:

{contentctl-5.3.1.dist-info → contentctl-5.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: contentctl
-Version: 5.3.1
+Version: 5.4.0
 Summary: Splunk Content Control Tool
 License: Apache 2.0
 Author: STRT

{contentctl-5.3.1.dist-info → contentctl-5.4.0.dist-info}/RECORD

@@ -14,12 +14,12 @@ contentctl/actions/detection_testing/views/DetectionTestingViewFile.py,sha256=G-
 contentctl/actions/detection_testing/views/DetectionTestingViewWeb.py,sha256=CXV1fByf3J-Jc4D9U6jgWSaUhNzjcMpvEgRMuusF2vU,4740
 contentctl/actions/doc_gen.py,sha256=P2-RYsJoW-QuhAkSpOQespDLJBC-4Cq3-XGTmadK8Ys,936
 contentctl/actions/initialize.py,sha256=KXVUyjLMS7yE34wd2odyj5pVXyc_eOlvH_d7LzgR_Bc,4238
-contentctl/actions/inspect.py,sha256=zFNbDXY7Bi1xTBHirNyHpH1-2A1n3rsOsRvu8E0xUao,19375
+contentctl/actions/inspect.py,sha256=ER1CJZk5ls4bithhDimXmBJepQ6ha1Ns-D2z-AZUdcQ,19991
 contentctl/actions/new_content.py,sha256=xs0QvHzlrf0g-EgdUJTkdDdFaA-uEGmzMTixDt6NcTY,8212
 contentctl/actions/release_notes.py,sha256=rrloomsLBfl53xpjqDez6RgHU5AE4Gb9ASrivGbYYVs,17122
 contentctl/actions/reporting.py,sha256=GF32i7sHdc47bw-VWSW-nZ1QBaUl6Ni1JjV5_SOyiAU,1660
 contentctl/actions/test.py,sha256=ftZazqoqv7bLNhyW23aRnDpetG9zltS8wr4Xq9Hls0k,6268
-contentctl/actions/validate.py,sha256=hgcczMFA8xOo4T--RviBPJdZ7INfkq5kCZkWFB7rnDs,5879
+contentctl/actions/validate.py,sha256=teqRVxNlUgzDvKQm-sXb05TST05duA2-NhJOzNxlBTw,6152
 contentctl/api.py,sha256=6s17vNOW1E1EzQqOCXAa5uWuhwwShu-JkGSgrsOFEMs,6329
 contentctl/contentctl.py,sha256=nR8nHxXY0elvQogVHFqsyid7Ch5sMnIiNAOFbCa0yzI,11755
 contentctl/enrichments/attack_enrichment.py,sha256=68C9xQ8Q3YX-luRdK2hLnwWtRFpheFA2kE4v5GOLGEo,6358
@@ -29,14 +29,15 @@ contentctl/helper/link_validator.py,sha256=kzEi2GdncPWSi-UKNerXm2jtTJfFQ5goS9pqy
 contentctl/helper/logger.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 contentctl/helper/splunk_app.py,sha256=Zq_C9rjNVqCjBNgm-5CWdBpXyeX5jSpbE-QTGptEZlk,14571
 contentctl/helper/utils.py,sha256=1_6cbvvbPXWxym3ZhRhL18ttmXLXiHbavpXAkROtGcg,21154
-contentctl/input/director.py,sha256=rThzfssOG4v52ClhVwUx-sU0MKWb_UaMy3MSANCrwmo,11999
+contentctl/input/director.py,sha256=h2F7vfP56RyBhrUmI9_9Wn_gDIH2d1NKepc8Yt5cHf4,17002
 contentctl/input/new_content_questions.py,sha256=z2C4Mg7-EyxtiF2z9m4SnSbi6QO4CUPB3wg__JeMXIQ,4067
 contentctl/input/yml_reader.py,sha256=L27b14_xXQYypUV1eAzZrfMtwtkzAZx--6nRo3RNZnE,2729
 contentctl/objects/abstract_security_content_objects/detection_abstract.py,sha256=Gsb6v44VpWeGnMi79viJ0zO81pZ9GuiaqQJyHM-ba5I,46861
-contentctl/objects/abstract_security_content_objects/security_content_object_abstract.py,sha256=VzAkq-oJ05Y7Y2BzoUG8De8tVANV5X9ZvHbrDe65iRA,33282
+contentctl/objects/abstract_security_content_objects/security_content_object_abstract.py,sha256=un1tjoZdxKi07dSddPD5MXRN3tea3dj0poKmFrbCu-k,34206
 contentctl/objects/alert_action.py,sha256=iEvdEOT4TrTXT0z4rQ_W5v79hPJpPhFPSzo7TuHDxwA,1376
 contentctl/objects/annotated_types.py,sha256=xR4EKvdOpNDEt0doGs8XjxCzKK99J2NHZgHFAmt7p2c,424
 contentctl/objects/atomic.py,sha256=5nl-JhZnymadi8B8ZEJ8l80DnpvjG-OlRxUjVKR6ffY,7341
+contentctl/objects/base_security_event.py,sha256=VxfsMuu1IV0uKutEkqowEZRbXORmu51VKCjHC-KUbeo,890
 contentctl/objects/base_test.py,sha256=JG6qlr7xe9P71n3CzKOro8_bsmDQGYDfTG9YooHQSIE,1105
 contentctl/objects/base_test_result.py,sha256=TYYzTPKWqp9rHTebWoid50uxAp_iALZouril4sFwIcA,5197
 contentctl/objects/baseline.py,sha256=EMcuz_9sVgOFh3YCj871GSAA6v3FIkRTf90-LAHq-J0,3700
@@ -44,7 +45,7 @@ contentctl/objects/baseline_tags.py,sha256=Eomy8y3HV-E6Lym5B5ZZTtsmQJYi6Jd4y8GZp
 contentctl/objects/config.py,sha256=8F_zpcnFyE_rSdGomm2qeVDG6tTpjhrVyK6BsNHM8js,49357
 contentctl/objects/constants.py,sha256=VwwQtJBGC_zb3ukjb3A7P0CwAlyhacWiXczwAW5Jiog,5466
 contentctl/objects/content_versioning_service.py,sha256=BDk_TV1PTVoXpPcUxqTLa5_bjkfOs9PFYgqTuzOS9UI,20566
-contentctl/objects/correlation_search.py,sha256=Zui6GAtYSUnMUzJkKOQ5sSYDTYoAxODUICpHXwxNMwo,45147
+contentctl/objects/correlation_search.py,sha256=tvcFeHGFRyZso50KHsEVCjTmHh3rHDegcfqaD-TjCFg,51473
 contentctl/objects/dashboard.py,sha256=owp-bYVagmSHUpVyOHgGtAEaKFSHAXN7kDhYqs09H_g,4998
 contentctl/objects/data_source.py,sha256=O58GArXVlflz3dCtVOn96Ubyi5_ekSC1N9LuveQNws4,2019
 contentctl/objects/deployment.py,sha256=OctNayxFPRvrQtTklAKgfjCXFKOspD19swLj0hi6dWE,3323
@@ -60,7 +61,7 @@ contentctl/objects/detection_stanza.py,sha256=-BRQNib5NNhY7Z2fILS5xkpjNkGSLF7qBc
 contentctl/objects/detection_tags.py,sha256=j92t4TWlNNVdFi4_DoHvEyvJuURlBp5_o1xv2w2pAVk,10699
 contentctl/objects/drilldown.py,sha256=Vinw6UYlOl0YzoRA_0oBCfHA5Gvgu5p-rEsfBIgMCdI,4186
 contentctl/objects/enums.py,sha256=nWufu5YgzllBfDQBneIe_Hf_erNXouERciqU_di5DNo,13754
-contentctl/objects/errors.py,sha256=xX_FDUaJbJiOWgjgrzjtYW5QsD41UZ2KWqH-yGkHaCU,5554
+contentctl/objects/errors.py,sha256=7ebvjAR9W2Wj0a4ihdOakGPZRNr7rDDZe0X3rvhh_dE,6367
 contentctl/objects/integration_test.py,sha256=TYjKyH4YinUnYXOse5BQGCa4-ez_5mtoMwvh1JJcb0o,1254
 contentctl/objects/integration_test_result.py,sha256=_uUSgqgjFhEZM8UwOJI6Q9K-ekIrbKU6OPdqHZycl-s,279
 contentctl/objects/investigation.py,sha256=GZsvhSZO7ZSmhg2ZeT-kPMqDG-GYpTXIvGBgV1H2lwQ,4030
@@ -71,13 +72,13 @@ contentctl/objects/manual_test.py,sha256=cx_XAtQ8VG8Ui_F553Xnut75vFEOtRwm1dDIIWN
 contentctl/objects/manual_test_result.py,sha256=FyCVVf-f1DKs-qBkM4tbKfY6mkrW25NcIEBqyaDC2rE,156
 contentctl/objects/mitre_attack_enrichment.py,sha256=PCakRksW5qrTENIZ7JirEZplE9xpmvSvX2GKv7N8j_k,3683
 contentctl/objects/notable_action.py,sha256=sW5XlpGznMHqyBmGXtXrl22hWLiCoKkfGCasGtK3rGo,1607
-contentctl/objects/notable_event.py,sha256=2aOtmfnsdInTtN_fHAGIKmBTBritjHbS_Nc-pqL-GbY,689
+contentctl/objects/notable_event.py,sha256=jMmD1sGtTvOFNfjAfienWD2-sVL67axzdLrLZSGQ8Sw,421
 contentctl/objects/playbook.py,sha256=veG2luPfFrOMdzl99D8gsO85HYSJ8kZMYWj3GG64HKk,2879
 contentctl/objects/playbook_tags.py,sha256=O5obkQyb82YdJEii8ZJEQtrHtLOSnAvAkT1qIgpCK2s,1547
 contentctl/objects/rba.py,sha256=2xE_DXhQvG6tVLJTXYaFEBm9owePE4QG0NVgdcVgoiY,3547
 contentctl/objects/removed_security_content_object.py,sha256=bx-gVCqzT81E5jKncMD3-yKawTnl3tWsuzRBmsAqeqQ,1852
 contentctl/objects/risk_analysis_action.py,sha256=v-TQktXEEzbGzmTtqwEykXoSKdGnIlK_JojnqvvAE1s,4370
-contentctl/objects/risk_event.py,sha256=JQUmXriiwi5FetqVnhM0hf5cUp6LzLSNPuoecC2JKK0,12593
+contentctl/objects/risk_event.py,sha256=p3WJQrDNuhoXBMOxCX5x8P7xKr2XwROcog_pPpb653A,12219
 contentctl/objects/risk_object.py,sha256=5iUKW_UwQLjjLWiD_vlE78uwH9bkaMNCHRNmKM25W1Q,905
 contentctl/objects/savedsearches_conf.py,sha256=Dn_Pxd9i3RT6DwNh6JrgmfxjsO3q15xzMksYr3wIGwQ,8624
 contentctl/objects/security_content_object.py,sha256=2mEf-wt3hMsLEyo4yatyK66jKjgUOVjJHIN9fgQB5nA,246
@@ -163,8 +164,8 @@ contentctl/templates/detections/web/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRk
 contentctl/templates/macros/security_content_ctime.yml,sha256=Gg1YNllHVsX_YB716H1SJLWzxXZEfuJlnsgB2fuyoHU,159
 contentctl/templates/macros/security_content_summariesonly.yml,sha256=9BYUxAl2E4Nwh8K19F3AJS8Ka7ceO6ZDBjFiO3l3LY0,162
 contentctl/templates/stories/cobalt_strike.yml,sha256=uj8idtDNOAIqpZ9p8usQg6mop1CQkJ5TlB4Q7CJdTIE,3082
-contentctl-5.3.1.dist-info/LICENSE.md,sha256=hQWUayRk-pAiOZbZnuy8djmoZkjKBx8MrCFpW-JiOgo,11344
-contentctl-5.3.1.dist-info/METADATA,sha256=1nKu_O4jpY0Vtv0lNteAbgJR_Fx8Wc5UhTal5frFyTg,5134
-contentctl-5.3.1.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-contentctl-5.3.1.dist-info/entry_points.txt,sha256=5bjZ2NkbQfSwK47uOnA77yCtjgXhvgxnmCQiynRF_-U,57
-contentctl-5.3.1.dist-info/RECORD,,
+contentctl-5.4.0.dist-info/LICENSE.md,sha256=hQWUayRk-pAiOZbZnuy8djmoZkjKBx8MrCFpW-JiOgo,11344
+contentctl-5.4.0.dist-info/METADATA,sha256=0Ym0O-VJlAqZbBBwe5BWrymkdZgj-SW1pncPksgZ9jM,5134
+contentctl-5.4.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+contentctl-5.4.0.dist-info/entry_points.txt,sha256=5bjZ2NkbQfSwK47uOnA77yCtjgXhvgxnmCQiynRF_-U,57
+contentctl-5.4.0.dist-info/RECORD,,