contentctl 4.4.7__py3-none-any.whl → 5.0.0a0__py3-none-any.whl

contentctl/objects/mitre_attack_enrichment.py

@@ -83,9 +83,9 @@ class MitreAttackGroup(BaseModel):
             return []
         return contributors
 
-# TODO (#266): disable the use_enum_values configuration
 class MitreAttackEnrichment(BaseModel):
-    ConfigDict(use_enum_values=True)
+
+    ConfigDict(extra='forbid')
     mitre_attack_id: MITRE_ATTACK_ID_TYPE = Field(...)
     mitre_attack_technique: str = Field(...)
     mitre_attack_tactics: List[MitreTactics] = Field(...)

contentctl/objects/observable.py

@@ -1,8 +1,10 @@
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel, field_validator, ConfigDict
 from contentctl.objects.constants import SES_OBSERVABLE_TYPE_MAPPING, RBA_OBSERVABLE_ROLE_MAPPING
 
+# TODO (cmcginley): should this class be removed?
 
 class Observable(BaseModel):
+    model_config = ConfigDict(extra="forbid")
     name: str
     type: str
     role: list[str]

contentctl/objects/playbook_tags.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, List
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field,ConfigDict
 import enum
 from contentctl.objects.detection import Detection
 
@@ -36,6 +36,7 @@ class DefendTechnique(str,enum.Enum):
     D3_SRA = "D3-SRA"
     D3_RUAA = "D3-RUAA"
 class PlaybookTag(BaseModel):
+    model_config = ConfigDict(extra="forbid")
     analytic_story: Optional[list] = None
     detections: Optional[list] = None
     platform_tags: list[str] = Field(...,min_length=0)
@@ -46,5 +47,8 @@ class PlaybookTag(BaseModel):
     use_cases: list[PlaybookUseCase] = Field([],min_length=0)
     defend_technique_id: Optional[List[DefendTechnique]] = None
     
+    labels:list[str] = []
+    playbook_outputs:list[str] = []
+    
     detection_objects: list[Detection] = []
     

contentctl/objects/rba.py

@@ -0,0 +1,90 @@
+from enum import Enum
+from pydantic import BaseModel, computed_field, Field
+from abc import ABC
+from typing import Set, Annotated
+from contentctl.objects.enums import RiskSeverity
+
+
+RiskScoreValue_Type = Annotated[int, Field(ge=1, le=100)]
+
+class RiskObjectType(str, Enum):
+    SYSTEM = "system"
+    USER = "user"
+    OTHER = "other"
+
+class ThreatObjectType(str, Enum):
+    CERTIFICATE_COMMON_NAME = "certificate_common_name"
+    CERTIFICATE_ORGANIZATION = "certificate_organization"
+    CERTIFICATE_SERIAL = "certificate_serial"
+    CERTIFICATE_UNIT = "certificate_unit"
+    COMMAND = "command"
+    DOMAIN = "domain"
+    EMAIL_ADDRESS = "email_address"
+    EMAIL_SUBJECT = "email_subject"
+    FILE_HASH = "file_hash"
+    FILE_NAME = "file_name"
+    FILE_PATH = "file_path"
+    HTTP_USER_AGENT = "http_user_agent"
+    IP_ADDRESS = "ip_address"
+    PROCESS = "process"
+    PROCESS_NAME = "process_name"
+    PARENT_PROCESS = "parent_process"
+    PARENT_PROCESS_NAME = "parent_process_name"
+    PROCESS_HASH = "process_hash"
+    REGISTRY_PATH = "registry_path"
+    REGISTRY_VALUE_NAME = "registry_value_name"
+    REGISTRY_VALUE_TEXT = "registry_value_text"
+    SERVICE = "service"
+    SIGNATURE = "signature"
+    SYSTEM = "system"
+    TLS_HASH = "tls_hash"
+    URL = "url"
+
+class RiskObject(BaseModel):
+    field: str
+    type: RiskObjectType
+    score: RiskScoreValue_Type
+
+    def __hash__(self):
+        return hash((self.field, self.type, self.score))
+
+class ThreatObject(BaseModel):
+    field: str
+    type: ThreatObjectType
+
+    def __hash__(self):
+        return hash((self.field, self.type))
+
+class RBAObject(BaseModel, ABC):
+    message: str
+    risk_objects: Annotated[Set[RiskObject], Field(min_length=1)]
+    threat_objects: Set[ThreatObject]
+
+    
+    
+    @computed_field
+    @property
+    def risk_score(self)->RiskScoreValue_Type:
+        # First get the maximum score associated with
+        # a risk object. If there are no objects, then
+        # we should throw an exception.
+        if len(self.risk_objects) == 0:
+            raise Exception("There must be at least one Risk Object present to get Severity.")
+        return max([risk_object.score for risk_object in self.risk_objects])
+    
+    @computed_field
+    @property
+    def severity(self)->RiskSeverity:
+        if 0 <= self.risk_score <= 20:
+            return RiskSeverity.INFORMATIONAL
+        elif 20 < self.risk_score <= 40:
+            return RiskSeverity.LOW
+        elif 40 < self.risk_score <= 60:
+            return RiskSeverity.MEDIUM
+        elif 60 < self.risk_score <= 80:
+            return RiskSeverity.HIGH
+        elif 80 < self.risk_score <= 100:
+            return RiskSeverity.CRITICAL
+        else:
+            raise Exception(f"Error getting severity - risk_score must be between 0-100, but was actually {self.risk_score}")
+

contentctl/objects/risk_event.py

@@ -4,48 +4,7 @@ from functools import cached_property
 from pydantic import ConfigDict, 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 (#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]] = {
-    "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"
-    ]
-}
-
-# Roles that should not generate risks
-IGNORE_ROLES: list[str] = ["Attacker"]
+from contentctl.objects.rba import RiskObject
 
 
 class RiskEvent(BaseModel):
@@ -55,10 +14,12 @@ 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: int | str
+    # (not to be confused w/ the risk object from the detection)
+    es_risk_object: int | str
 
-    # The type of the risk object (e.g. user, system, or other)
-    risk_object_type: str
+    # The type of the risk object from ES (e.g. user, system, or other) (not to be confused w/
+    # the risk object from the detection)
+    es_risk_object_type: str
 
     # The level of risk associated w/ the risk event
     risk_score: int
@@ -79,11 +40,11 @@ class RiskEvent(BaseModel):
     )
 
     # Contributing events search query (we use this to derive the corresponding field from the
-    # observables)
+    # detection's risk object definition)
     contributing_events_search: str
 
-    # Private attribute caching the observable this RiskEvent is mapped to
-    _matched_observable: Observable | None = PrivateAttr(default=None)
+    # 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
@@ -108,7 +69,7 @@ class RiskEvent(BaseModel):
     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.
+        event(s). Useful for mapping back to a risk object in the detection.
         """
         pattern = re.compile(
             r"\| savedsearch \"" + self.search_name + r"\" \| search (?P<field>[^=]+)=.+"
@@ -128,13 +89,6 @@ class RiskEvent(BaseModel):
         :param detection: the detection associated w/ this risk event
         :raises: ValidationFailed
         """
-        # Check risk_score
-        if self.risk_score != detection.tags.risk_score:
-            raise ValidationFailed(
-                f"Risk score observed in risk event ({self.risk_score}) does not match risk score in "
-                f"detection ({detection.tags.risk_score})."
-            )
-
         # Check analyticstories
         self.validate_analyticstories(detection)
 
@@ -151,8 +105,15 @@ class RiskEvent(BaseModel):
         # Check risk_message
         self.validate_risk_message(detection)
 
-        # Check several conditions against the observables
-        self.validate_risk_against_observables(detection.tags.observable)
+        # Ensure the rba object is defined
+        if detection.rba is None:
+            raise ValidationFailed(
+                f"Unexpected error: Detection '{detection.name}' has no RBA objects associated "
+                "with it; cannot validate."
+            )
+
+        # Check several conditions against the detection's risk objects
+        self.validate_risk_against_risk_objects(detection.rba.risk_objects)
 
     def validate_mitre_ids(self, detection: Detection) -> None:
         """
@@ -177,7 +138,7 @@ class RiskEvent(BaseModel):
         if sorted(self.analyticstories) != sorted(detection_analytic_story):
             raise ValidationFailed(
                 f"Analytic stories in risk event ({self.analyticstories}) do not match those"
-                f" in detection ({detection.tags.analytic_story})."
+                f" in detection ({[x.name for x in detection.tags.analytic_story]})."
             )
 
     def validate_risk_message(self, detection: Detection) -> None:
@@ -186,10 +147,20 @@ class RiskEvent(BaseModel):
         :param detection: the detection associated w/ this risk event
         :raises: ValidationFailed
         """
+        # Ensure the rba object is defined
+        if detection.rba is None:
+            raise ValidationFailed(
+                f"Unexpected error: Detection '{detection.name}' has no RBA objects associated "
+                "with it; cannot validate."
+            )
+
         # Extract the field replacement tokens ("$...$")
         field_replacement_pattern = re.compile(r"\$\S+\$")
-        tokens = field_replacement_pattern.findall(detection.tags.message)
+        tokens = field_replacement_pattern.findall(detection.rba.message)
 
+        # TODO (#346): could expand this to get the field values from the raw events and check
+        #   to see that allexpected strings ARE in the risk message (as opposed to checking only
+        #   that unexpected strings aren't)
         # Check for the presence of each token in the message from the risk event
         for token in tokens:
             if token in self.risk_message:
@@ -205,7 +176,7 @@ class RiskEvent(BaseModel):
         escaped_source_message_with_placeholder: str = re.escape(
             field_replacement_pattern.sub(
                 tmp_placeholder,
-                detection.tags.message
+                detection.rba.message
             )
         )
         placeholder_replacement_pattern = re.compile(tmp_placeholder)
@@ -221,114 +192,86 @@ class RiskEvent(BaseModel):
             raise ValidationFailed(
                 "Risk message in event does not match the pattern set by the detection. Message in "
                 f"risk event: \"{self.risk_message}\". Message in detection: "
-                f"\"{detection.tags.message}\"."
+                f"\"{detection.rba.message}\"."
             )
 
-    def validate_risk_against_observables(self, observables: list[Observable]) -> None:
+    def validate_risk_against_risk_objects(self, risk_objects: set[RiskObject]) -> None:
         """
-        Given the observables from the associated detection, validate the risk event against those
-        observables
-        :param observables: the Observable objects from the detection
+        Given the risk objects from the associated detection, validate the risk event against those
+        risk objects
+        :param risk_objects: the risk objects from the detection
         :raises: ValidationFailed
         """
-        # Get the matched observable; will raise validation errors if no match can be made or if
-        # risk is missing values associated w/ observables
-        matched_observable = self.get_matched_observable(observables)
+        # Get the matched risk object; will raise validation errors if no match can be made or if
+        # risk is missing values associated w/ risk objects
+        matched_risk_object = self.get_matched_risk_object(risk_objects)
 
-        # The risk object type should match our mapping of observable types to risk types
-        expected_type = RiskEvent.observable_type_to_risk_type(matched_observable.type)
-        if self.risk_object_type != expected_type:
+        # The risk object type from the risk event should match our mapping of internal risk object
+        # types
+        if self.es_risk_object_type != matched_risk_object.type.value:
             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"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})"
+                f"The risk object type from the risk event ({self.es_risk_object_type}) does not match"
+                " the expected type based on the matched risk object "
+                f"({matched_risk_object.type.value}): risk event=(object={self.es_risk_object}, "
+                f"type={self.es_risk_object_type}, source_field_name={self.source_field_name}), "
+                f"risk object=(name={matched_risk_object.field}, "
+                f"type={matched_risk_object.type.value})"
             )
 
-    @staticmethod
-    def observable_type_to_risk_type(observable_type: str) -> str:
-        """
-        Given a string representing the observable type, use our mapping to convert it to the
-        expected type in the risk event
-        :param observable_type: the type of the observable
-        :returns: a string (the risk object type)
-        :raises ValueError: if the observable type has not yet been mapped to a risk object type
-        """
-        # Iterate over the map and search the lists for a match
-        for risk_type in TYPE_MAP:
-            if observable_type in TYPE_MAP[risk_type]:
-                return risk_type
-
-        raise ValueError(
-            f"Observable type {observable_type} does not have a mapping to a risk type in TYPE_MAP"
-        )
+        # Check risk_score
+        if self.risk_score != matched_risk_object.score:
+            raise ValidationFailed(
+                f"Risk score observed in risk event ({self.risk_score}) does not match risk score in "
+                f"matched risk object from detection ({matched_risk_object.score})."
+            )
 
-    @staticmethod
-    def ignore_observable(observable: Observable) -> bool:
-        """
-        Given an observable, determine based on its roles if it should be ignored in risk/observable
-        matching (e.g. Attacker role observables should not generate risk events)
-        :param observable: the Observable object we are checking the roles of
-        :returns: a bool indicating whether this observable should be ignored or not
-        """
-        ignore = False
-        for role in observable.role:
-            if role in IGNORE_ROLES:
-                ignore = True
-                break
-        return ignore
-
-    def get_matched_observable(self, observables: list[Observable]) -> Observable:
+    def get_matched_risk_object(self, risk_objects: set[RiskObject]) -> RiskObject:
         """
-        Given a list of observables, return the one this risk event matches
-        :param observables: the list of Observable objects we are checking against
-        :returns: the matched Observable object
+        Given a set of risk objects, return the one this risk event matches
+        :param risk_objects: the list of risk objects we are checking against
+        :returns: the matched risk object
         :raises ValidationFailed: if a match could not be made or if an expected field (based on
-            one of the observables) could not be found in the risk event
+            one of the risk objects) could not be found in the risk event
         """
         # Return the cached match if already found
-        if self._matched_observable is not None:
-            return self._matched_observable
+        if self._matched_risk_object is not None:
+            return self._matched_risk_object
 
-        matched_observable: Observable | None = None
+        matched_risk_object: RiskObject | None = None
 
         # Iterate over the obervables and check for a match
-        for observable in observables:
+        for risk_object in risk_objects:
             # 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
-            # if not hasattr(self, observable.name):
+            # Each the field name used in each risk object shoud be present in the risk event
+            # if not hasattr(self, risk_object.field):
             #     raise ValidationFailed(
-            #         f"Observable field \"{observable.name}\" not found in risk event."
+            #         f"Risk object field \"{risk_object.field}\" 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, shouldn't get converted to risk events)
-            if self.source_field_name == observable.name:
-                if matched_observable is not None:
+            # Try to match the risk_object against a specific risk object
+            if self.source_field_name == risk_object.field:
+                # TODO (#347): enforce that field names are not repeated across risk objects as
+                #   part of build/validate
+                if matched_risk_object is not None:
                     raise ValueError(
-                        "Unexpected conditon: we don't expect the source event field "
-                        "corresponding to an observables field name to be repeated."
+                        "Unexpected conditon: we don't expect multiple risk objects to use the "
+                        "same field name, so we should not be able match the risk event to "
+                        "multiple risk objects."
                     )
 
-                # 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
+                # NOTE: we explicitly do not break early as we want to check each risk object
+                matched_risk_object = risk_object
 
-        # Ensure we were able to match the risk event to a specific observable
-        if matched_observable is None:
+        # Ensure we were able to match the risk event to a specific risk object
+        if matched_risk_object is None:
             raise ValidationFailed(
-                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."
+                f"Unable to match risk event (object={self.es_risk_object}, type="
+                f"{self.es_risk_object_type}, source_field_name={self.source_field_name}) to a "
+                "risk object in the detection; please check for errors in the risk object types for this "
+                "detection, as well as the risk event build process in contentctl (e.g. threat "
+                "objects aren't being converted to risk objects somehow)."
             )
 
-        # Cache and return the matched observable
-        self._matched_observable = matched_observable
-        return self._matched_observable
+        # Cache and return the matched risk object
+        self._matched_risk_object = matched_risk_object
+        return self._matched_risk_object

contentctl/objects/story_tags.py

@@ -18,9 +18,8 @@ class StoryUseCase(str,Enum):
    OTHER = "Other"
 
 
-# TODO (#266): disable the use_enum_values configuration
 class StoryTags(BaseModel):
-   model_config = ConfigDict(extra='forbid', use_enum_values=True)
+   model_config = ConfigDict(extra='forbid')
    category: List[StoryCategory] = Field(...,min_length=1)
    product: List[SecurityContentProductName] = Field(...,min_length=1)
    usecase: StoryUseCase = Field(...)

contentctl/objects/test_attack_data.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
-from pydantic import BaseModel, HttpUrl, FilePath, Field
+from pydantic import BaseModel, HttpUrl, FilePath, Field, ConfigDict
 
 
 class TestAttackData(BaseModel):
+    model_config = ConfigDict(extra="forbid")
     data: HttpUrl | FilePath = Field(...)
     # TODO - should source and sourcetype should be mapped to a list
     # of supported source and sourcetypes in a given environment?

contentctl/objects/unit_test_baseline.py

@@ -1,9 +1,10 @@
 
 
-from pydantic import BaseModel
+from pydantic import BaseModel,ConfigDict
 from typing import Union
 
 class UnitTestBaseline(BaseModel):
+    model_config = ConfigDict(extra="forbid")
     name: str
     file: str
     pass_condition: str