Merge branch 'main' into conf_file_updates

Author: pyth0n1c

contentctl/actions/inspect.py

@@ -16,6 +16,7 @@
     DetectionMissingError,
     MetadataValidationError,
     VersionBumpingError,
+    VersionBumpingTooFarError,
     VersionDecrementedError,
 )
 from contentctl.objects.savedsearches_conf import SavedsearchesConf
@@ -101,7 +102,7 @@ def inspectAppAPI(self, config: inspect) -> str:
             -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 @@ def check_detection_metadata(self, config: inspect) -> None:
                     )
                 )
 
+            # 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.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 @@
 
 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 @@ def addContentToDictMappings(self, content: SecurityContentObject):
         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,101 @@ def createSecurityContent(
             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:
+                            # Unfortunately, this is a catch-all for untyped errors. We will still need to emit this
+                            # This is harder to read, but the other option is suppressing it which we cannot do as
+                            # it makes troubleshooting extremelt difficult
+                            print(
+                                f"      {Colors.RED}{Colors.ERROR} {error_msg}{Colors.END}"
+                            )
+
+                        # Clean error categorization
+                        elif "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 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 @@ def getReferencesListForJson(self) -> List[str]:
     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 @@ def mapNamesToSecurityContentObjects(
                 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()