contentctl 4.3.3__py3-none-any.whl → 4.3.5__py3-none-any.whl

contentctl/objects/atomic.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from contentctl.objects.config import validate
+
 from contentctl.input.yml_reader import YmlReader
 from pydantic import BaseModel, model_validator, ConfigDict, FilePath, UUID4
+import dataclasses
 from typing import List, Optional, Dict, Union, Self
 import pathlib
-
-
 from enum import StrEnum, auto
-
+import uuid
 
 class SupportedPlatform(StrEnum):        
     windows = auto()
@@ -84,15 +87,6 @@ class AtomicTest(BaseModel):
     dependencies: Optional[List[AtomicDependency]] = None
     dependency_executor_name: Optional[DependencyExecutorType] = None
 
-    @staticmethod
-    def AtomicTestWhenEnrichmentIsDisabled(auto_generated_guid: UUID4) -> AtomicTest:
-        return AtomicTest(name="Placeholder Atomic Test (enrichment disabled)",
-                          auto_generated_guid=auto_generated_guid,
-                          description="This is a placeholder AtomicTest. Because enrichments were not enabled, it has not been validated against the real Atomic Red Team Repo.",
-                          supported_platforms=[],
-                          executor=AtomicExecutor(name="Placeholder Executor (enrichment disabled)", 
-                                                  command="Placeholder command (enrichment disabled)"))
-    
     @staticmethod
     def AtomicTestWhenTestIsMissing(auto_generated_guid: UUID4) -> AtomicTest:
         return AtomicTest(name="Missing Atomic",
@@ -100,31 +94,16 @@ class AtomicTest(BaseModel):
                           description="This is a placeholder AtomicTest. Either the auto_generated_guid is incorrect or it there was an exception while parsing its AtomicFile.",
                           supported_platforms=[],
                           executor=AtomicExecutor(name="Placeholder Executor (failed to find auto_generated_guid)", 
-                                                  command="Placeholder command (failed to find auto_generated_guid)"))
-
-
-    @classmethod
-    def getAtomicByAtomicGuid(cls, guid: UUID4, all_atomics:list[AtomicTest] | None)->AtomicTest:
-        if all_atomics is None:
-            return AtomicTest.AtomicTestWhenEnrichmentIsDisabled(guid)
-        matching_atomics = [atomic for atomic in all_atomics if atomic.auto_generated_guid == guid]
-        if len(matching_atomics) == 0:
-            raise ValueError(f"Unable to find atomic_guid {guid} in {len(all_atomics)} atomic_tests from ART Repo")
-        elif len(matching_atomics) > 1:
-            raise ValueError(f"Found {len(matching_atomics)} matching tests for atomic_guid {guid} in {len(all_atomics)} atomic_tests from ART Repo")
-        
-        return matching_atomics[0]
+                                                  command="Placeholder command (failed to find auto_generated_guid)"))    
     
     @classmethod
-    def parseArtRepo(cls, repo_path:pathlib.Path)->List[AtomicFile]:
-        if not repo_path.is_dir():
-            print(f"WARNING: Atomic Red Team repo does NOT exist at {repo_path.absolute()}. You can check it out with:\n * git clone --single-branch https://github.com/redcanaryco/atomic-red-team. This will ONLY throw a validation error if you reference atomid_guids in your detection(s).")
-            return []
+    def parseArtRepo(cls, repo_path:pathlib.Path)->dict[uuid.UUID, AtomicTest]:
+        test_mapping: dict[uuid.UUID, AtomicTest] = {}
         atomics_path = repo_path/"atomics"
         if not atomics_path.is_dir():
-            print(f"WARNING: Atomic Red Team repo exists at {repo_path.absolute}, but atomics directory does NOT exist at {atomics_path.absolute()}. Was it deleted or renamed? This will ONLY throw a validation error if you reference atomid_guids in your detection(s).")
-            return []
-        
+            raise FileNotFoundError(f"WARNING: Atomic Red Team repo exists at {repo_path}, "
+                                    f"but atomics directory does NOT exist at {atomics_path}. "
+                                    "Was it deleted or renamed?")
 
         atomic_files:List[AtomicFile] = []
         error_messages:List[str] = []
@@ -133,6 +112,7 @@ class AtomicTest(BaseModel):
                 atomic_files.append(cls.constructAtomicFile(obj_path))
             except Exception as e:
                 error_messages.append(f"File [{obj_path}]\n{str(e)}")
+
         if len(error_messages) > 0:
             exceptions_string = '\n\n'.join(error_messages)
             print(f"WARNING: The following [{len(error_messages)}] ERRORS were generated when parsing the Atomic Red Team Repo.\n"
@@ -140,38 +120,28 @@ class AtomicTest(BaseModel):
                    "Note that this is only a warning and contentctl will ignore Atomics contained in these files.\n"
                   f"However, if you have written a detection that references them, 'contentctl build --enrichments' will fail:\n\n{exceptions_string}")
         
-        return atomic_files
+        # Now iterate over all the files, collect all the tests, and return the dict mapping
+        redefined_guids:set[uuid.UUID] = set()
+        for atomic_file in atomic_files:
+            for atomic_test in atomic_file.atomic_tests:
+                if atomic_test.auto_generated_guid in test_mapping:
+                    redefined_guids.add(atomic_test.auto_generated_guid)
+                else:
+                    test_mapping[atomic_test.auto_generated_guid] = atomic_test
+        if len(redefined_guids) > 0:
+            guids_string = '\n\t'.join([str(guid) for guid in redefined_guids])
+            raise Exception(f"The following [{len(redefined_guids)}] Atomic Test"
+                            " auto_generated_guid(s) were defined more than once. "
+                            f"auto_generated_guids MUST be unique:\n\t{guids_string}")
+
+        print(f"Successfully parsed [{len(test_mapping)}] Atomic Red Team Tests!")
+        return test_mapping
     
     @classmethod
     def constructAtomicFile(cls, file_path:pathlib.Path)->AtomicFile:
         yml_dict = YmlReader.load_file(file_path) 
         atomic_file = AtomicFile.model_validate(yml_dict)
         return atomic_file
-    
-    @classmethod
-    def getAtomicTestsFromArtRepo(cls, repo_path:pathlib.Path, enabled:bool=True)->list[AtomicTest] | None:
-        # Get all the atomic files.  Note that if the ART repo is not found, we will not throw an error,
-        # but will not have any atomics. This means that if atomic_guids are referenced during validation,
-        # validation for those detections will fail
-        if not enabled:
-            return None
-        
-        atomic_files = cls.getAtomicFilesFromArtRepo(repo_path)
-            
-        atomic_tests:List[AtomicTest] = []
-        for atomic_file in atomic_files:
-            atomic_tests.extend(atomic_file.atomic_tests)
-        print(f"Found [{len(atomic_tests)}] Atomic Simulations in the Atomic Red Team Repo!")
-        return atomic_tests
-
-    
-    @classmethod
-    def getAtomicFilesFromArtRepo(cls, repo_path:pathlib.Path)->List[AtomicFile]:
-        return cls.parseArtRepo(repo_path)
-
-    
-    
-
 
 
 class AtomicFile(BaseModel):
@@ -182,27 +152,31 @@ class AtomicFile(BaseModel):
     atomic_tests: List[AtomicTest]
 
 
+class AtomicEnrichment(BaseModel):
+    data: dict[uuid.UUID,AtomicTest] = dataclasses.field(default_factory = dict)
+    use_enrichment: bool = False
 
+    @classmethod
+    def getAtomicEnrichment(cls, config:validate)->AtomicEnrichment:
+        enrichment = AtomicEnrichment(use_enrichment=config.enrichments)
+        if config.enrichments:
+            enrichment.data = AtomicTest.parseArtRepo(config.atomic_red_team_repo_path)
+
+        return enrichment
+
+    def getAtomic(self, atomic_guid: uuid.UUID)->AtomicTest:
+        if self.use_enrichment:
+            if atomic_guid in self.data:
+                return self.data[atomic_guid]
+            else:
+                raise Exception(f"Atomic with GUID {atomic_guid} not found.")
+        else:
+            # If enrichment is not enabled, for the sake of compatability
+            # return a stub test with no useful or meaningful information.
+            return AtomicTest.AtomicTestWhenTestIsMissing(atomic_guid)
 
-# ATOMICS_PATH = pathlib.Path("./atomics")
-# atomic_objects = []
-# atomic_simulations = []
-# for obj_path in ATOMICS_PATH.glob("**/T*.yaml"):
-#     try:
-#         with open(obj_path, 'r', encoding="utf-8") as obj_handle:
-#             obj_data = yaml.load(obj_handle, Loader=yaml.CSafeLoader)
-#             atomic_obj = AtomicFile.model_validate(obj_data)
-#     except Exception as e:
-#         print(f"Error parsing object at path {obj_path}: {str(e)}")
-#         print(f"We have successfully parsed {len(atomic_objects)}, however!")
-#         sys.exit(1)
-
-#     print(f"Successfully parsed {obj_path}!")
-#     atomic_objects.append(atomic_obj)
-#     atomic_simulations += atomic_obj.atomic_tests
+    
 
-# print(f"Successfully parsed all {len(atomic_objects)} files!")
-# print(f"Successfully parsed all {len(atomic_simulations)} simulations!")
     
 
         

contentctl/objects/config.py

@@ -1,26 +1,31 @@
 from __future__ import annotations
+
+from os import environ
+from datetime import datetime, UTC
+from typing import Optional, Any, List, Union, Self
+import random
+from enum import StrEnum, auto
+import pathlib
+from urllib.parse import urlparse
+from abc import ABC, abstractmethod
+from functools import partialmethod
+
+import tqdm
+import semantic_version
 from pydantic import (
     BaseModel, Field, field_validator, 
     field_serializer, ConfigDict, DirectoryPath,
     PositiveInt, FilePath, HttpUrl, AnyUrl, model_validator,
     ValidationInfo
 )
+
+from contentctl.objects.constants import DOWNLOADS_DIRECTORY
 from contentctl.output.yml_writer import YmlWriter
-from os import environ
-from datetime import datetime, UTC
-from typing import Optional,Any,Annotated,List,Union, Self
-import semantic_version
-import random
-from enum import StrEnum, auto
-import pathlib
 from contentctl.helper.utils import Utils
-from urllib.parse import urlparse
-from abc import ABC, abstractmethod
 from contentctl.objects.enums import PostTestBehavior, DetectionTestingMode
 from contentctl.objects.detection import Detection
-
-import tqdm
-from functools import partialmethod
+from contentctl.objects.annotated_types import APPID_TYPE
+from contentctl.helper.splunk_app import SplunkApp
 
 ENTERPRISE_SECURITY_UID = 263
 COMMON_INFORMATION_MODEL_UID = 1621
@@ -33,7 +38,7 @@ class App_Base(BaseModel,ABC):
     model_config = ConfigDict(use_enum_values=True,validate_default=True, arbitrary_types_allowed=True)
     uid: Optional[int] = Field(default=None)
     title: str = Field(description="Human-readable name used by the app. This can have special characters.")
-    appid: Optional[Annotated[str, Field(pattern="^[a-zA-Z0-9_-]+$")]]= Field(default=None,description="Internal name used by your app. "
+    appid: Optional[APPID_TYPE]= Field(default=None,description="Internal name used by your app. "
                                                                     "It may ONLY have characters, numbers, and underscores. No other characters are allowed.")
     version: str = Field(description="The version of your Content Pack.  This must follow semantic versioning guidelines.")
     description: Optional[str] = Field(default="description of app",description="Free text description of the Content Pack.")
@@ -101,7 +106,7 @@ class CustomApp(App_Base):
     # https://docs.splunk.com/Documentation/Splunk/9.0.4/Admin/Appconf
     uid: int = Field(ge=2, lt=100000, default_factory=lambda:random.randint(20000,100000))
     title: str = Field(default="Content Pack",description="Human-readable name used by the app. This can have special characters.")
-    appid: Annotated[str, Field(pattern="^[a-zA-Z0-9_-]+$")]= Field(default="ContentPack",description="Internal name used by your app. "
+    appid: APPID_TYPE = Field(default="ContentPack",description="Internal name used by your app. "
                                                                     "It may ONLY have characters, numbers, and underscores. No other characters are allowed.")
     version: str = Field(default="0.0.1",description="The version of your Content Pack.  This must follow semantic versioning guidelines.", validate_default=True)
 
@@ -171,7 +176,13 @@ class Config_Base(BaseModel):
         return str(path)
 
 class init(Config_Base):
-    pass
+    model_config = ConfigDict(use_enum_values=True,validate_default=True, arbitrary_types_allowed=True)
+    bare: bool = Field(default=False, description="contentctl normally provides some some example content "
+                       "(macros, stories, data_sources, and/or analytic stories).  This option disables "
+                       "initialization with that additional contnet.  Note that even if --bare is used, it "
+                       "init will still create the directory structure of the app, "
+                       "include the app_template directory with default content, and content in "
+                       "the deployment/ directory (since it is not yet easily customizable).")
 
 
 # TODO (#266): disable the use_enum_values configuration
@@ -185,8 +196,45 @@ class validate(Config_Base):
     build_api: bool = Field(default=False, description="Should api objects be built and output in the build_path?")
     data_source_TA_validation: bool = Field(default=False, description="Validate latest TA information from Splunkbase")
 
-    def getAtomicRedTeamRepoPath(self, atomic_red_team_repo_name:str = "atomic-red-team"):
-        return self.path/atomic_red_team_repo_name
+    @property
+    def external_repos_path(self)->pathlib.Path:
+        return self.path/"external_repos"
+
+    @property    
+    def mitre_cti_repo_path(self)->pathlib.Path:
+        return self.external_repos_path/"cti"
+
+    @property
+    def atomic_red_team_repo_path(self):
+        return self.external_repos_path/"atomic-red-team"
+
+    @model_validator(mode="after")
+    def ensureEnrichmentReposPresent(self)->Self:
+        '''
+        Ensures that the enrichments repos, the atomic red team repo and the 
+        mitre attack enrichment repo, are present at the inded path.
+        Raises a detailed exception if either of these are not present
+        when enrichments are enabled.
+        '''
+        if not self.enrichments:
+            return self
+        # If enrichments are enabled, ensure that all of the
+        # enrichment directories exist
+        missing_repos:list[str] = []
+        if not self.atomic_red_team_repo_path.is_dir():
+            missing_repos.append(f"https://github.com/redcanaryco/atomic-red-team {self.atomic_red_team_repo_path}")
+
+        if not self.mitre_cti_repo_path.is_dir():
+            missing_repos.append(f"https://github.com/mitre/cti {self.mitre_cti_repo_path}")
+
+        if len(missing_repos) > 0: 
+            msg_list = ["The following repositories, which are required for enrichment, have not "
+                        f"been checked out to the {self.external_repos_path} directory. "
+                        "Please check them out using the following commands:"]
+            msg_list.extend([f"git clone --single-branch {repo_string}" for repo_string in missing_repos])
+            msg = '\n\t'.join(msg_list)
+            raise FileNotFoundError(msg)
+        return self
 
 class report(validate):
     #reporting takes no extra args, but we define it here so that it can be a mode on the command line    
@@ -233,9 +281,6 @@ class build(validate):
             return self.getBuildDir() / f"{self.app.appid}-{self.app.version}.tar.gz"
         else:
             return self.getBuildDir() / f"{self.app.appid}-latest.tar.gz"
-    
-    def getSSAPath(self)->pathlib.Path:
-        return self.getBuildDir() / "ssa"
 
     def getAPIPath(self)->pathlib.Path:
         return self.getBuildDir() / "api"
@@ -249,11 +294,89 @@ class StackType(StrEnum):
     classic = auto()
     victoria = auto()
 
+
 class inspect(build):
-    splunk_api_username: str = Field(description="Splunk API username used for running appinspect.")
-    splunk_api_password: str = Field(exclude=True, description="Splunk API password used for running appinspect.")
+    splunk_api_username: str = Field(
+        description="Splunk API username used for appinspect and Splunkbase downloads."
+    )
+    splunk_api_password: str = Field(
+        exclude=True,
+        description="Splunk API password used for appinspect and Splunkbase downloads."
+    )
+    enable_metadata_validation: bool = Field(
+        default=False,
+        description=(
+            "Flag indicating whether detection metadata validation and versioning enforcement "
+            "should be enabled."
+        )
+    )
+    enrichments: bool = Field(
+        default=True,
+        description=(
+            "[NOTE: enrichments must be ENABLED for inspect to run. Please adjust your config "
+            f"or CLI invocation appropriately] {validate.model_fields['enrichments'].description}"
+            )
+        )
+    # TODO (cmcginley): wording should change here if we want to be able to download any app from
+    #   Splunkbase
+    previous_build: str | None = Field(
+        default=None,
+        description=(
+            "Local path to the previous app build for metatdata validation and versioning "
+            "enforcement (defaults to the latest release of the app published on Splunkbase)."
+        )
+    )
     stack_type: StackType = Field(description="The type of your Splunk Cloud Stack")
 
+    @field_validator("enrichments", mode="after")
+    @classmethod
+    def validate_needed_flags_metadata_validation(cls, v: bool, info: ValidationInfo) -> bool:
+        """
+        Validates that `enrichments` is True for the inspect action
+
+        :param v: the field's value
+        :type v: bool
+        :param info: the ValidationInfo to be used
+        :type info: :class:`pydantic.ValidationInfo`
+
+        :returns: bool, for v
+        :rtype: bool
+        """
+        # Enforce that `enrichments` is True for the inspect action
+        if v is False:
+            raise ValueError("Field `enrichments` must be True for the `inspect` action")
+
+        return v
+
+    def get_previous_package_file_path(self) -> pathlib.Path:
+        """
+        Returns a Path object for the path to the prior package build. If no path was provided, the
+        latest version is downloaded from Splunkbase and it's filepath is returned, and saved to the
+        in-memory config (so download doesn't happen twice in the same run).
+
+        :returns: Path object to previous app build
+        :rtype: :class:`pathlib.Path`
+        """
+        previous_build_path = self.previous_build
+        # Download the previous build as the latest release on Splunkbase if no path was provided
+        if previous_build_path is None:
+            print(
+                f"Downloading latest {self.app.label} build from Splunkbase to serve as previous "
+                "build during validation..."
+            )
+            app = SplunkApp(app_uid=self.app.uid)
+            previous_build_path = app.download(
+                out=pathlib.Path(DOWNLOADS_DIRECTORY),
+                username=self.splunk_api_username,
+                password=self.splunk_api_password,
+                is_dir=True,
+                overwrite=True
+            )
+            print(f"Latest release downloaded from Splunkbase to: {previous_build_path}")
+            self.previous_build = str(previous_build_path)
+        return pathlib.Path(previous_build_path)
+
+
 class NewContentType(StrEnum):
     detection = auto()
     story = auto()

contentctl/objects/constants.py

@@ -136,4 +136,7 @@ SES_ATTACK_TACTICS_ID_MAPPING = {
 RBA_OBSERVABLE_ROLE_MAPPING = {
     "Attacker": 0,
     "Victim": 1
-}
+}
+
+# The relative path to the directory where any apps/packages will be downloaded
+DOWNLOADS_DIRECTORY = "downloads"

contentctl/objects/correlation_search.py

@@ -575,10 +575,11 @@ class CorrelationSearch(BaseModel):
             self.logger.debug(f"Using cached risk events ({len(self._risk_events)} total).")
             return self._risk_events
 
+        # TODO (#248): Refactor risk/notable querying to pin to a single savedsearch ID
         # Search for all risk events from a single scheduled search (indicated by orig_sid)
         query = (
             f'search index=risk search_name="{self.name}" [search index=risk search '
-            f'search_name="{self.name}" | head 1 | fields orig_sid] | tojson'
+            f'search_name="{self.name}" | tail 1 | fields orig_sid] | tojson'
         )
         result_iterator = self._search(query)
 
@@ -643,7 +644,7 @@ class CorrelationSearch(BaseModel):
         # Search for all notable events from a single scheduled search (indicated by orig_sid)
         query = (
             f'search index=notable search_name="{self.name}" [search index=notable search '
-            f'search_name="{self.name}" | head 1 | fields orig_sid] | tojson'
+            f'search_name="{self.name}" | tail 1 | fields orig_sid] | tojson'
         )
         result_iterator = self._search(query)
 
@@ -686,15 +687,17 @@ class CorrelationSearch(BaseModel):
             check the risks/notables
         :returns: an IntegrationTestResult on failure; None on success
         """
-        # TODO (PEX-433): Re-enable this check once we have refined the logic and reduced the false
-        #   positive rate in risk/obseravble matching
         # Create a mapping of the relevant observables to counters
-        # observables = CorrelationSearch._get_relevant_observables(self.detection.tags.observable)
-        # observable_counts: dict[str, int] = {str(x): 0 for x in observables}
-        # if len(observables) != len(observable_counts):
-        #     raise ClientError(
-        #         f"At least two observables in '{self.detection.name}' have the same name."
-        #     )
+        observables = CorrelationSearch._get_relevant_observables(self.detection.tags.observable)
+        observable_counts: dict[str, int] = {str(x): 0 for x in observables}
+
+        # NOTE: we intentionally want this to be an error state and not a failure state, as
+        #   ultimately this validation should be handled during the build process
+        if len(observables) != len(observable_counts):
+            raise ClientError(
+                f"At least two observables in '{self.detection.name}' have the same name; "
+                "each observable for a detection should be unique."
+            )
 
         # Get the risk events; note that we use the cached risk events, expecting they were
         # saved by a prior call to risk_event_exists
@@ -710,25 +713,29 @@ class CorrelationSearch(BaseModel):
             )
             event.validate_against_detection(self.detection)
 
-            # TODO (PEX-433): Re-enable this check once we have refined the logic and reduced the
-            #   false positive rate in risk/obseravble matching
             # Update observable count based on match
-            # matched_observable = event.get_matched_observable(self.detection.tags.observable)
-            # self.logger.debug(
-            #     f"Matched risk event ({event.risk_object}, {event.risk_object_type}) to observable "
-            #     f"({matched_observable.name}, {matched_observable.type}, {matched_observable.role})"
-            # )
-            # observable_counts[str(matched_observable)] += 1
-
-        # TODO (PEX-433): test my new contentctl logic against an old ESCU build; my logic should
-        #   detect the faulty attacker events -> this was the issue from the 4.28/4.27 release;
-        #   recreate by testing against one of those old builds w/ the bad config
-        # TODO (PEX-433): Re-enable this check once we have refined the logic and reduced the false
-        #   positive
-        #   rate in risk/obseravble matching
-        # TODO (PEX-433): I foresee issues here if for example a parent and child process share a
-        #   name (matched observable could be either) -> these issues are confirmed to exist, e.g.
-        #   `Windows Steal Authentication Certificates Export Certificate`
+            matched_observable = event.get_matched_observable(self.detection.tags.observable)
+            self.logger.debug(
+                f"Matched risk event (object={event.risk_object}, type={event.risk_object_type}) "
+                f"to observable (name={matched_observable.name}, type={matched_observable.type}, "
+                f"role={matched_observable.role}) using the source field "
+                f"'{event.source_field_name}'"
+            )
+            observable_counts[str(matched_observable)] += 1
+
+        # Report any observables which did not have at least one match to a risk event
+        for observable in observables:
+            self.logger.debug(
+                f"Matched observable (name={observable.name}, type={observable.type}, "
+                f"role={observable.role}) to {observable_counts[str(observable)]} risk events."
+            )
+            if observable_counts[str(observable)] == 0:
+                raise ValidationFailed(
+                    f"Observable (name={observable.name}, type={observable.type}, "
+                    f"role={observable.role}) was not matched to any risk events."
+                )
+
+        # TODO (#250): Re-enable and refactor code that validates the specific risk counts
         # Validate risk events in aggregate; we should have an equal amount of risk events for each
         # relevant observable, and the total count should match the total number of events
         # individual_count: Optional[int] = None

contentctl/objects/detection_metadata.py

@@ -0,0 +1,71 @@
+import uuid
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class DetectionMetadata(BaseModel):
+    """
+    A model of the metadata line in a detection stanza in savedsearches.conf
+    """
+    # A bool indicating whether the detection is deprecated (serialized as an int, 1 or 0)
+    deprecated: bool = Field(...)
+
+    # A UUID identifying the detection
+    detection_id: uuid.UUID = Field(...)
+
+    # The version of the detection
+    detection_version: int = Field(...)
+
+    # The time the detection was published. **NOTE** This field was added to the metadata in ESCU
+    # as of v4.39.0
+    publish_time: float = Field(...)
+
+    class Config:
+        # Allowing for future fields that may be added to the metadata JSON
+        extra = "allow"
+
+    @field_validator("deprecated", mode="before")
+    @classmethod
+    def validate_deprecated(cls, v: Any) -> Any:
+        """
+        Convert str to int, and then ints to bools for deprecated; raise if not 0 or 1 in the case
+        of an int, or if str cannot be converted to int.
+
+        :param v: the value passed
+        :type v: :class:`typing.Any`
+
+        :returns: the value
+        :rtype: :class:`typing.Any`
+        """
+        if isinstance(v, str):
+            try:
+                v = int(v)
+            except ValueError as e:
+                raise ValueError(f"Cannot convert str value ({v}) to int: {e}") from e
+        if isinstance(v, int):
+            if not (0 <= v <= 1):
+                raise ValueError(
+                    f"Value for field 'deprecated' ({v}) must be 0 or 1, if not a bool."
+                )
+            v = bool(v)
+        return v
+
+    @field_validator("detection_version", mode="before")
+    @classmethod
+    def validate_detection_version(cls, v: Any) -> Any:
+        """
+        Convert str to int; raise if str cannot be converted to int.
+
+        :param v: the value passed
+        :type v: :class:`typing.Any`
+
+        :returns: the value
+        :rtype: :class:`typing.Any`
+        """
+        if isinstance(v, str):
+            try:
+                v = int(v)
+            except ValueError as e:
+                raise ValueError(f"Cannot convert str value ({v}) to int: {e}") from e
+        return v

contentctl/objects/detection_stanza.py

@@ -0,0 +1,79 @@
+from typing import ClassVar
+import hashlib
+from functools import cached_property
+
+from pydantic import BaseModel, Field, computed_field
+
+from contentctl.objects.detection_metadata import DetectionMetadata
+
+
+class DetectionStanza(BaseModel):
+    """
+    A model representing a stanza for a detection in savedsearches.conf
+    """
+    # The lines that comprise this stanza, in the order they appear in the conf
+    lines: list[str] = Field(...)
+
+    # The full name of the detection (e.g. "ESCU - My Detection - Rule")
+    name: str = Field(...)
+
+    # The key prefix indicating the metadata attribute
+    METADATA_LINE_PREFIX: ClassVar[str] = "action.correlationsearch.metadata = "
+
+    @computed_field
+    @cached_property
+    def metadata(self) -> DetectionMetadata:
+        """
+        The metadata extracted from the stanza. Using the provided lines, parse out the metadata
+
+        :returns: the detection stanza's metadata
+        :rtype: :class:`contentctl.objects.detection_metadata.DetectionMetadata`
+        """
+        # Set a variable to store the metadata line in
+        meta_line: str | None = None
+
+        # Iterate over the lines to look for the metadata line
+        for line in self.lines:
+            if line.startswith(DetectionStanza.METADATA_LINE_PREFIX):
+                # If we find a matching line more than once, we've hit an error
+                if meta_line is not None:
+                    raise Exception(
+                        f"Metadata for detection '{self.name}' found twice in stanza."
+                    )
+                meta_line = line
+
+        # Report if we could not find the metadata line
+        if meta_line is None:
+            raise Exception(f"No metadata for detection '{self.name}' found in stanza.")
+
+        # Parse the metadata JSON into a model
+        return DetectionMetadata.model_validate_json(meta_line[len(DetectionStanza.METADATA_LINE_PREFIX):])
+
+    @computed_field
+    @cached_property
+    def hash(self) -> str:
+        """
+        The SHA256 hash of the lines of the stanza, excluding the metadata line
+
+        :returns: hexdigest
+        :rtype: str
+        """
+        hash = hashlib.sha256()
+        for line in self.lines:
+            if not line.startswith(DetectionStanza.METADATA_LINE_PREFIX):
+                hash.update(line.encode("utf-8"))
+        return hash.hexdigest()
+
+    def version_should_be_bumped(self, previous: "DetectionStanza") -> bool:
+        """
+        A helper method that compares this stanza against the same stanza from a previous build;
+        returns True if the version still needs to be bumped (e.g. the detection was changed but
+        the version was not), False otherwise.
+
+        :param previous: the previous build's DetectionStanza for comparison
+        :type previous: :class:`contentctl.objects.detection_stanza.DetectionStanza`
+
+        :returns: True if the version still needs to be bumped
+        :rtype: bool
+        """
+        return (self.hash != previous.hash) and (self.metadata.detection_version <= previous.metadata.detection_version)