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

contentctl/objects/detection_tags.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 import uuid
-from typing import TYPE_CHECKING, List, Optional, Annotated, Union
+from typing import TYPE_CHECKING, List, Optional, Union
 from pydantic import (
     BaseModel,
     Field,
@@ -32,8 +32,8 @@ from contentctl.objects.enums import (
     RiskLevel,
     SecurityContentProductName
 )
-from contentctl.objects.atomic import AtomicTest
-
+from contentctl.objects.atomic import AtomicEnrichment, AtomicTest
+from contentctl.objects.annotated_types import MITRE_ATTACK_ID_TYPE, CVE_TYPE
 
 # TODO (#266): disable the use_enum_values configuration
 class DetectionTags(BaseModel):
@@ -50,8 +50,10 @@ class DetectionTags(BaseModel):
     def risk_score(self) -> int:
         return round((self.confidence * self.impact)/100)
 
-    mitre_attack_id: List[Annotated[str, Field(pattern=r"^T\d{4}(.\d{3})?$")]] = []
+    mitre_attack_id: List[MITRE_ATTACK_ID_TYPE] = []
     nist: list[NistCategory] = []
+
+    # TODO (#249): Add pydantic validator to ensure observables are unique within a detection
     observable: List[Observable] = []
     message: str = Field(...)
     product: list[SecurityContentProductName] = Field(..., min_length=1)
@@ -69,7 +71,7 @@ class DetectionTags(BaseModel):
         else:
             return RiskSeverity('low')
 
-    cve: List[Annotated[str, r"^CVE-[1|2]\d{3}-\d+$"]] = []
+    cve: List[CVE_TYPE] = []
     atomic_guid: List[AtomicTest] = []
     drilldown_search: Optional[str] = None
 
@@ -238,7 +240,7 @@ class DetectionTags(BaseModel):
         if output_dto is None:
             raise ValueError("Context not provided to detection.detection_tags.atomic_guid validator")
 
-        all_tests: None | List[AtomicTest] = output_dto.atomic_tests
+        atomic_enrichment: AtomicEnrichment = output_dto.atomic_enrichment
 
         matched_tests: List[AtomicTest] = []
         missing_tests: List[UUID4] = []
@@ -252,7 +254,7 @@ class DetectionTags(BaseModel):
                 badly_formatted_guids.append(str(atomic_guid_str))
                 continue
             try:
-                matched_tests.append(AtomicTest.getAtomicByAtomicGuid(atomic_guid, all_tests))
+                matched_tests.append(atomic_enrichment.getAtomic(atomic_guid))
             except Exception:
                 missing_tests.append(atomic_guid)
 
@@ -263,7 +265,7 @@ class DetectionTags(BaseModel):
                 f"\n\tPlease review the output above for potential exception(s) when parsing the "
                 "Atomic Red Team Repo."
                 "\n\tVerify that these auto_generated_guid exist and try updating/pulling the "
-                f"repo again.: {[str(guid) for guid in missing_tests]}"
+                f"repo again: {[str(guid) for guid in missing_tests]}"
             )
         else:
             missing_tests_string = ""
@@ -276,6 +278,6 @@ class DetectionTags(BaseModel):
             raise ValueError(f"{bad_guids_string}{missing_tests_string}")
 
         elif len(missing_tests) > 0:
-            print(missing_tests_string)
+            raise ValueError(missing_tests_string)
 
         return matched_tests + [AtomicTest.AtomicTestWhenTestIsMissing(test) for test in missing_tests]

contentctl/objects/enums.py

@@ -54,7 +54,6 @@ class SecurityContentType(enum.Enum):
     deployments = 7
     investigations = 8
     unit_tests = 9
-    ssa_detections = 10
     data_sources = 11
 
 # Bringing these changes back in line will take some time after
@@ -69,7 +68,6 @@ class SecurityContentType(enum.Enum):
 
 class SecurityContentProduct(enum.Enum):
     SPLUNK_APP = 1
-    SSA = 2
     API = 3
     CUSTOM = 4
 

contentctl/objects/errors.py

@@ -1,3 +1,7 @@
+from abc import ABC, abstractmethod
+from uuid import UUID
+
+
 class ValidationFailed(Exception):
     """Indicates not an error in execution, but a validation failure"""
     pass
@@ -16,3 +20,186 @@ class ServerError(IntegrationTestingError):
 class ClientError(IntegrationTestingError):
     """An error encounterd during integration testing, on the client's side (locally)"""
     pass
+
+
+class MetadataValidationError(Exception, ABC):
+    """
+    Base class for any errors arising from savedsearches.conf detection metadata validation
+    """
+    # The name of the rule the error relates to
+    rule_name: str
+
+    @property
+    @abstractmethod
+    def long_message(self) -> str:
+        """
+        A long-form error message
+        :returns: a str, the message
+        """
+        raise NotImplementedError()
+
+    @property
+    @abstractmethod
+    def short_message(self) -> str:
+        """
+        A short-form error message
+        :returns: a str, the message
+        """
+        raise NotImplementedError()
+
+
+class DetectionMissingError(MetadataValidationError):
+    """
+    An error indicating a detection in the prior build could not be found in the current build
+    """
+    def __init__(
+            self,
+            rule_name: str,
+            *args: object
+    ) -> None:
+        self.rule_name = rule_name
+        super().__init__(self.long_message, *args)
+
+    @property
+    def long_message(self) -> str:
+        """
+        A long-form error message
+        :returns: a str, the message
+        """
+        return (
+            f"Rule '{self.rule_name}' in previous build not found in current build; "
+            "detection may have been removed or renamed."
+        )
+
+    @property
+    def short_message(self) -> str:
+        """
+        A short-form error message
+        :returns: a str, the message
+        """
+        return (
+            "Detection from previous build not found in current build."
+        )
+
+
+class DetectionIDError(MetadataValidationError):
+    """
+    An error indicating the detection ID may have changed between builds
+    """
+    # The ID from the current build
+    current_id: UUID
+
+    # The ID from the previous build
+    previous_id: UUID
+
+    def __init__(
+            self,
+            rule_name: str,
+            current_id: UUID,
+            previous_id: UUID,
+            *args: object
+    ) -> None:
+        self.rule_name = rule_name
+        self.current_id = current_id
+        self.previous_id = previous_id
+        super().__init__(self.long_message, *args)
+
+    @property
+    def long_message(self) -> str:
+        """
+        A long-form error message
+        :returns: a str, the message
+        """
+        return (
+            f"Rule '{self.rule_name}' has ID {self.current_id} in current build "
+            f"and {self.previous_id} in previous build; detection IDs and "
+            "names should not change for the same detection between releases."
+        )
+
+    @property
+    def short_message(self) -> str:
+        """
+        A short-form error message
+        :returns: a str, the message
+        """
+        return (
+            f"Detection ID {self.current_id} in current build does not match ID {self.previous_id} in previous build."
+        )
+
+
+class VersioningError(MetadataValidationError, ABC):
+    """
+    A base class for any metadata validation errors relating to detection versioning
+    """
+    # The version in the current build
+    current_version: int
+
+    # The version in the previous build
+    previous_version: int
+
+    def __init__(
+            self,
+            rule_name: str,
+            current_version: int,
+            previous_version: int,
+            *args: object
+    ) -> None:
+        self.rule_name = rule_name
+        self.current_version = current_version
+        self.previous_version = previous_version
+        super().__init__(self.long_message, *args)
+
+
+class VersionDecrementedError(VersioningError):
+    """
+    An error indicating the version number went down between builds
+    """
+    @property
+    def long_message(self) -> str:
+        """
+        A long-form error message
+        :returns: a str, the message
+        """
+        return (
+            f"Rule '{self.rule_name}' has version {self.current_version} in "
+            f"current build and {self.previous_version} in previous build; "
+            "detection versions cannot decrease in successive builds."
+        )
+
+    @property
+    def short_message(self) -> str:
+        """
+        A short-form error message
+        :returns: a str, the message
+        """
+        return (
+            f"Detection version ({self.current_version}) in current build is less than version "
+            f"({self.previous_version}) in previous build."
+        )
+
+
+class VersionBumpingError(VersioningError):
+    """
+    An error indicating the detection changed but its version wasn't bumped appropriately
+    """
+    @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); the detection version should be bumped "
+            f"to at least {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 bumped to at least {self.previous_version + 1}."
+        )

contentctl/objects/mitre_attack_enrichment.py

@@ -3,6 +3,7 @@ from pydantic import BaseModel, Field, ConfigDict, HttpUrl, field_validator
 from typing import List, Annotated
 from enum import StrEnum
 import datetime
+from contentctl.objects.annotated_types import MITRE_ATTACK_ID_TYPE
 
 class MitreTactics(StrEnum):
     RECONNAISSANCE = "Reconnaissance"
@@ -85,7 +86,7 @@ class MitreAttackGroup(BaseModel):
 # TODO (#266): disable the use_enum_values configuration
 class MitreAttackEnrichment(BaseModel):
     ConfigDict(use_enum_values=True)
-    mitre_attack_id: Annotated[str, Field(pattern=r"^T\d{4}(.\d{3})?$")] = Field(...)
+    mitre_attack_id: MITRE_ATTACK_ID_TYPE = Field(...)
     mitre_attack_technique: str = Field(...)
     mitre_attack_tactics: List[MitreTactics] = Field(...)
     mitre_attack_groups: List[str] = Field(...)

contentctl/objects/risk_event.py

@@ -1,32 +1,51 @@
 import re
-from typing import Union, Optional
 
-from pydantic import BaseModel, Field, PrivateAttr, field_validator
+from pydantic import BaseModel, Field, PrivateAttr, field_validator, computed_field
 
 from contentctl.objects.errors import ValidationFailed
 from contentctl.objects.detection import Detection
 from contentctl.objects.observable import Observable
 
-# TODO (PEX-433): use SES_OBSERVABLE_TYPE_MAPPING
+# TODO (#259): Map our observable types to more than user/system
+# TODO (#247): centralize this mapping w/ usage of SES_OBSERVABLE_TYPE_MAPPING (see
+#   observable.py) and the ad hoc mapping made in detection_abstract.py (see the risk property func)
 TYPE_MAP: dict[str, list[str]] = {
-    "user": ["User"],
-    "system": ["Hostname", "IP Address", "Endpoint"],
-    "other": ["Process", "URL String", "Unknown", "Process Name"],
+    "system": [
+        "Hostname",
+        "IP Address",
+        "Endpoint"
+    ],
+    "user": [
+        "User",
+        "User Name",
+        "Email Address",
+        "Email"
+    ],
+    "hash_values": [],
+    "network_artifacts": [],
+    "host_artifacts": [],
+    "tools": [],
+    "other": [
+        "Process",
+        "URL String",
+        "Unknown",
+        "Process Name",
+        "MAC Address",
+        "File Name",
+        "File Hash",
+        "Resource UID",
+        "Uniform Resource Locator",
+        "File",
+        "Geo Location",
+        "Container",
+        "Registry Key",
+        "Registry Value",
+        "Other"
+    ]
 }
-# TODO (PEX-433): 'Email Address', 'File Name', 'File Hash', 'Other', 'User Name', 'File',
-#   'Process Name'
 
-# TODO (PEX-433): use SES_OBSERVABLE_ROLE_MAPPING
+# Roles that should not generate risks
 IGNORE_ROLES: list[str] = ["Attacker"]
-# Known valid roles: Victim, Parent Process, Child Process
-# TODO (PEX-433): 'Other', 'Target', 'Unknown'
-# TODO (PEX-433): is Other a valid role
-
-# TODO (PEX-433): do we need User Name in conjunction w/ User? User Name doesn't get mapped to
-#   "user" in risk events
-# TODO (PEX-433): similarly, do we need Process and Process Name?
-
-RESERVED_FIELDS = ["host"]
 
 
 class RiskEvent(BaseModel):
@@ -36,7 +55,7 @@ class RiskEvent(BaseModel):
     search_name: str
 
     # The subject of the risk event (e.g. a username, process name, system name, account ID, etc.)
-    risk_object: Union[int, str]
+    risk_object: int | str
 
     # The type of the risk object (e.g. user, system, or other)
     risk_object_type: str
@@ -59,8 +78,12 @@ class RiskEvent(BaseModel):
         default=[]
     )
 
+    # Contributing events search query (we use this to derive the corresponding field from the
+    # observables)
+    contributing_events_search: str
+
     # Private attribute caching the observable this RiskEvent is mapped to
-    _matched_observable: Optional[Observable] = PrivateAttr(default=None)
+    _matched_observable: Observable | None = PrivateAttr(default=None)
 
     class Config:
         # Allowing fields that aren't explicitly defined to be passed since some of the risk event's
@@ -69,7 +92,7 @@ class RiskEvent(BaseModel):
 
     @field_validator("annotations_mitre_attack", "analyticstories", mode="before")
     @classmethod
-    def _convert_str_value_to_singleton(cls, v: Union[str, list[str]]) -> list[str]:
+    def _convert_str_value_to_singleton(cls, v: str | list[str]) -> list[str]:
         """
         Given a value, determine if its a list or a single str value; if a single value, return as a
         singleton. Do nothing if anything else.
@@ -79,6 +102,25 @@ class RiskEvent(BaseModel):
         else:
             return [v]
 
+    @computed_field
+    @property
+    def source_field_name(self) -> str:
+        """
+        A cached derivation of the source field name the risk event corresponds to in the relevant
+        event(s). Useful for mapping back to an observable in the detection.
+        """
+        pattern = re.compile(
+            r"\| savedsearch \"" + self.search_name + r"\" \| search (?P<field>[^=]+)=.+"
+        )
+        match = pattern.search(self.contributing_events_search)
+        if match is None:
+            raise ValueError(
+                "Unable to parse source field name from risk event using "
+                f"'contributing_events_search' ('{self.contributing_events_search}') using "
+                f"pattern: {pattern}"
+            )
+        return match.group("field")
+
     def validate_against_detection(self, detection: Detection) -> None:
         """
         Given the associated detection, validate the risk event against its fields
@@ -108,10 +150,8 @@ class RiskEvent(BaseModel):
         # Check risk_message
         self.validate_risk_message(detection)
 
-        # TODO (PEX-433): Re-enable this check once we have refined the logic and reduced the false
-        #   positive rate in risk/obseravble matching
         # Check several conditions against the observables
-        # self.validate_risk_against_observables(detection.tags.observable)
+        self.validate_risk_against_observables(detection.tags.observable)
 
     def validate_mitre_ids(self, detection: Detection) -> None:
         """
@@ -199,7 +239,11 @@ class RiskEvent(BaseModel):
         if self.risk_object_type != expected_type:
             raise ValidationFailed(
                 f"The risk object type ({self.risk_object_type}) does not match the expected type "
-                f"based on the matched observable ({matched_observable.type}=={expected_type})."
+                f"based on the matched observable ({matched_observable.type}->{expected_type}): "
+                f"risk=(object={self.risk_object}, type={self.risk_object_type}, "
+                f"source_field_name={self.source_field_name}), "
+                f"observable=(name={matched_observable.name}, type={matched_observable.type}, "
+                f"role={matched_observable.role})"
             )
 
     @staticmethod
@@ -220,8 +264,6 @@ class RiskEvent(BaseModel):
             f"Observable type {observable_type} does not have a mapping to a risk type in TYPE_MAP"
         )
 
-    # TODO (PEX-433): should this be an observable instance method? It feels less relevant to
-    #   observables themselves, as it's really only relevant to the handling of risk events
     @staticmethod
     def ignore_observable(observable: Observable) -> bool:
         """
@@ -230,8 +272,6 @@ class RiskEvent(BaseModel):
         :param observable: the Observable object we are checking the roles of
         :returns: a bool indicating whether this observable should be ignored or not
         """
-        # TODO (PEX-433): could there be a case where an observable has both an Attacker and Victim
-        #   (or equivalent) role? If so, how should we handle ignoring it?
         ignore = False
         for role in observable.role:
             if role in IGNORE_ROLES:
@@ -239,29 +279,6 @@ class RiskEvent(BaseModel):
                 break
         return ignore
 
-    # TODO (PEX-433): two possibilities: alway check for the field itself and the field prefixed
-    #   w/ "orig_" OR more explicitly maintain a list of known "reserved fields", like "host". I
-    #   think I like option 2 better as it can have fewer unknown side effects
-    def matches_observable(self, observable: Observable) -> bool:
-        """
-        Given an observable, check if the risk event matches is
-        :param observable: the Observable object we are comparing the risk event against
-        :returns: bool indicating a match or not
-        """
-        # When field names collide w/ reserved fields in Splunk events (e.g. sourcetype or host)
-        # they get prefixed w/ "orig_"
-        attribute_name = observable.name
-        if attribute_name in RESERVED_FIELDS:
-            attribute_name = f"orig_{attribute_name}"
-
-        # Retrieve the value of this attribute and see if it matches the risk_object
-        value: Union[str, list[str]] = getattr(self, attribute_name)
-        if isinstance(value, str):
-            value = [value]
-
-        # The value of the attribute may be a list of values, so check for any matches
-        return self.risk_object in value
-
     def get_matched_observable(self, observables: list[Observable]) -> Observable:
         """
         Given a list of observables, return the one this risk event matches
@@ -274,40 +291,41 @@ class RiskEvent(BaseModel):
         if self._matched_observable is not None:
             return self._matched_observable
 
-        matched_observable: Optional[Observable] = None
+        matched_observable: Observable | None = None
 
         # Iterate over the obervables and check for a match
         for observable in observables:
+            # TODO (#252): Refactor and re-enable per-field validation of risk events
             # Each the field name used in each observable shoud be present in the risk event
-            # TODO (PEX-433): this check is redundant I think; earlier in the unit test, observable
-            #   field
-            #   names are compared against the search result set, ensuring all are present; if all
-            #   are present in the result set, all are present in the risk event
-            if not hasattr(self, observable.name):
-                raise ValidationFailed(
-                    f"Observable field \"{observable.name}\" not found in risk event."
-                )
+            # if not hasattr(self, observable.name):
+            #     raise ValidationFailed(
+            #         f"Observable field \"{observable.name}\" not found in risk event."
+            #     )
 
             # Try to match the risk_object against a specific observable for the obervables with
-            # a valid role (some, like Attacker, don't get converted to risk events)
-            if not RiskEvent.ignore_observable(observable):
-                if self.matches_observable(observable):
-                    # TODO (PEX-433): This check fails as there are some instances where this is
-                    #   true (e.g. we have an observable for process and parent_process and both
-                    #   have the same name like "cmd.exe")
-                    if matched_observable is not None:
-                        raise ValueError(
-                            "Unexpected conditon: we don't expect the value corresponding to an "
-                            "observables field name to be repeated"
-                        )
-                    # NOTE: we explicitly do not break early as we want to check each observable
-                    matched_observable = observable
+            # a valid role (some, like Attacker, shouldn't get converted to risk events)
+            if self.source_field_name == observable.name:
+                if matched_observable is not None:
+                    raise ValueError(
+                        "Unexpected conditon: we don't expect the source event field "
+                        "corresponding to an observables field name to be repeated."
+                    )
+
+                # Report any risk events we find that shouldn't be there
+                if RiskEvent.ignore_observable(observable):
+                    raise ValidationFailed(
+                        "Risk event matched an observable with an invalid role: "
+                        f"(name={observable.name}, type={observable.type}, role={observable.role})")
+                # NOTE: we explicitly do not break early as we want to check each observable
+                matched_observable = observable
 
         # Ensure we were able to match the risk event to a specific observable
         if matched_observable is None:
             raise ValidationFailed(
-                f"Unable to match risk event ({self.risk_object}, {self.risk_object_type}) to an "
-                "appropriate observable"
+                f"Unable to match risk event (object={self.risk_object}, type="
+                f"{self.risk_object_type}, source_field_name={self.source_field_name}) to an "
+                "observable; please check for errors in the observable roles/types for this "
+                "detection, as well as the risk event build process in contentctl."
             )
 
         # Cache and return the matched observable