contentctl 5.0.0a2__py3-none-any.whl → 5.0.1__py3-none-any.whl

contentctl/objects/mitre_attack_enrichment.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 from pydantic import BaseModel, Field, ConfigDict, HttpUrl, field_validator
-from typing import List, Annotated
+from typing import List
 from enum import StrEnum
 import datetime
 from contentctl.objects.annotated_types import MITRE_ATTACK_ID_TYPE
 
+
 class MitreTactics(StrEnum):
     RECONNAISSANCE = "Reconnaissance"
     RESOURCE_DEVELOPMENT = "Resource Development"
@@ -31,16 +32,17 @@ class AttackGroupMatrix(StrEnum):
 class AttackGroupType(StrEnum):
     intrusion_set = "intrusion-set"
 
+
 class MitreExternalReference(BaseModel):
-    model_config = ConfigDict(extra='forbid')
+    model_config = ConfigDict(extra="forbid")
     source_name: str
-    external_id: None | str = None 
+    external_id: None | str = None
     url: None | HttpUrl = None
     description: None | str = None
 
 
 class MitreAttackGroup(BaseModel):
-    model_config = ConfigDict(extra='forbid')
+    model_config = ConfigDict(extra="forbid")
     contributors: list[str] = []
     created: datetime.datetime
     created_by_ref: str
@@ -53,45 +55,44 @@ class MitreAttackGroup(BaseModel):
     matrix: list[AttackGroupMatrix]
     mitre_attack_spec_version: None | str
     mitre_version: str
-    #assume that if the deprecated field is not present, then the group is not deprecated
+    # assume that if the deprecated field is not present, then the group is not deprecated
     mitre_deprecated: bool
     modified: datetime.datetime
     modified_by_ref: str
     object_marking_refs: list[str]
     type: AttackGroupType
     url: HttpUrl
-    
 
     @field_validator("mitre_deprecated", mode="before")
-    def standardize_mitre_deprecated(cls, mitre_deprecated:bool | None) -> bool:
-        '''
+    def standardize_mitre_deprecated(cls, mitre_deprecated: bool | None) -> bool:
+        """
         For some reason, the API will return either a bool for mitre_deprecated OR
         None. We simplify our typing by converting None to False, and assuming that
         if deprecated is None, then the group is not deprecated.
-        '''
+        """
         if mitre_deprecated is None:
             return False
         return mitre_deprecated
 
     @field_validator("contributors", mode="before")
-    def standardize_contributors(cls, contributors:list[str] | None) -> list[str]:
-        '''
+    def standardize_contributors(cls, contributors: list[str] | None) -> list[str]:
+        """
         For some reason, the API will return either a list of strings for contributors OR
         None. We simplify our typing by converting None to an empty list.
-        '''
+        """
         if contributors is None:
             return []
         return contributors
 
-class MitreAttackEnrichment(BaseModel):
 
-    ConfigDict(extra='forbid')
+class MitreAttackEnrichment(BaseModel):
+    ConfigDict(extra="forbid")
     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(...)
-    #Exclude this field from serialization - it is very large and not useful in JSON objects
+    # Exclude this field from serialization - it is very large and not useful in JSON objects
     mitre_attack_group_objects: list[MitreAttackGroup] = Field(..., exclude=True)
+
     def __hash__(self) -> int:
         return id(self)
-

contentctl/objects/notable_action.py

@@ -14,6 +14,7 @@ class NotableAction(BaseModel):
     :param security_domain: the domain associated with the notable action and related rule (detection/search)
     :param severity: severity (e.g. "high") associated with the notable action and related rule (detection/search)
     """
+
     rule_name: str
     rule_description: str
     security_domain: str
@@ -32,5 +33,5 @@ class NotableAction(BaseModel):
             rule_name=dict_["action.notable.param.rule_title"],
             rule_description=dict_["action.notable.param.rule_description"],
             security_domain=dict_["action.notable.param.security_domain"],
-            severity=dict_["action.notable.param.severity"]
+            severity=dict_["action.notable.param.severity"],
         )

contentctl/objects/notable_event.py

@@ -13,9 +13,7 @@ class NotableEvent(BaseModel):
 
     # Allowing fields that aren't explicitly defined to be passed since some of the risk event's
     # fields vary depending on the SPL which generated them
-    model_config = ConfigDict(
-        extra='allow'
-    )
+    model_config = ConfigDict(extra="allow")
 
     def validate_against_detection(self, detection: Detection) -> None:
         raise NotImplementedError()

contentctl/objects/playbook.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING,Self
+from typing import Self
 from pydantic import model_validator, Field, FilePath
 
 
@@ -10,57 +10,59 @@ from contentctl.objects.enums import PlaybookType
 
 class Playbook(SecurityContentObject):
     type: PlaybookType = Field(...)
-    
+
     # Override the type definition for filePath.
     # This MUST be backed by a file and cannot be None
     file_path: FilePath
-    
+
     how_to_implement: str = Field(min_length=4)
     playbook: str = Field(min_length=4)
-    app_list: list[str] = Field(...,min_length=0) 
+    app_list: list[str] = Field(..., min_length=0)
     tags: PlaybookTag = Field(...)
-    
 
-    
     @model_validator(mode="after")
-    def ensureJsonAndPyFilesExist(self)->Self:
+    def ensureJsonAndPyFilesExist(self) -> Self:
         json_file_path = self.file_path.with_suffix(".json")
         python_file_path = self.file_path.with_suffix(".py")
-        missing:list[str] = []
+        missing: list[str] = []
         if not json_file_path.is_file():
-            missing.append(f"Playbook file named '{self.file_path.name}' MUST "\
-                           f"have a .json file named '{json_file_path.name}', "\
-                            "but it does not exist")
-            
+            missing.append(
+                f"Playbook file named '{self.file_path.name}' MUST "
+                f"have a .json file named '{json_file_path.name}', "
+                "but it does not exist"
+            )
+
         if not python_file_path.is_file():
-            missing.append(f"Playbook file named '{self.file_path.name}' MUST "\
-                           f"have a .py file named '{python_file_path.name}', "\
-                            "but it does not exist")
-            
-        
+            missing.append(
+                f"Playbook file named '{self.file_path.name}' MUST "
+                f"have a .py file named '{python_file_path.name}', "
+                "but it does not exist"
+            )
+
         if len(missing) == 0:
             return self
         else:
-            missing_files_string = '\n - '.join(missing)
+            missing_files_string = "\n - ".join(missing)
             raise ValueError(f"Playbook files missing:\n -{missing_files_string}")
 
-
-    #Override playbook file name checking FOR NOW
+    # Override playbook file name checking FOR NOW
     @model_validator(mode="after")
-    def ensureFileNameMatchesSearchName(self)->Self:
-        file_name = self.name \
-            .replace(' ', '_') \
-            .replace('-','_') \
-            .replace('.','_') \
-            .replace('/','_') \
-            .lower() + ".yml"
-        
-        #allow different capitalization FOR NOW in playbook file names
-        if (self.file_path is not None and file_name != self.file_path.name.lower()):
-            raise ValueError(f"The file name MUST be based off the content 'name' field:\n"\
-                            f"\t- Expected File Name: {file_name}\n"\
-                            f"\t- Actual File Name  : {self.file_path.name}")
+    def ensureFileNameMatchesSearchName(self) -> Self:
+        file_name = (
+            self.name.replace(" ", "_")
+            .replace("-", "_")
+            .replace(".", "_")
+            .replace("/", "_")
+            .lower()
+            + ".yml"
+        )
 
-        return self
+        # allow different capitalization FOR NOW in playbook file names
+        if self.file_path is not None and file_name != self.file_path.name.lower():
+            raise ValueError(
+                f"The file name MUST be based off the content 'name' field:\n"
+                f"\t- Expected File Name: {file_name}\n"
+                f"\t- Actual File Name  : {self.file_path.name}"
+            )
 
-    
+        return self

contentctl/objects/playbook_tags.py

@@ -1,26 +1,31 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Optional, List
-from pydantic import BaseModel, Field,ConfigDict
+from typing import Optional, List
+from pydantic import BaseModel, Field, ConfigDict
 import enum
 from contentctl.objects.detection import Detection
 
 
-class PlaybookProduct(str,enum.Enum):
+class PlaybookProduct(str, enum.Enum):
     SPLUNK_SOAR = "Splunk SOAR"
 
-class PlaybookUseCase(str,enum.Enum):
+
+class PlaybookUseCase(str, enum.Enum):
     PHISHING = "Phishing"
     ENDPOINT = "Endpoint"
     ENRICHMENT = "Enrichment"
-    
-class PlaybookType(str,enum.Enum):
+
+
+class PlaybookType(str, enum.Enum):
     INPUT = "Input"
     AUTOMATION = "Automation"
 
-class VpeType(str,enum.Enum):
+
+class VpeType(str, enum.Enum):
     MODERN = "Modern"
     CLASSIC = "Classic"
-class DefendTechnique(str,enum.Enum):
+
+
+class DefendTechnique(str, enum.Enum):
     D3_AL = "D3-AL"
     D3_DNSDL = "D3-DNSDL"
     D3_DA = "D3-DA"
@@ -35,20 +40,21 @@ class DefendTechnique(str,enum.Enum):
     D3_FHRA = "D3-FHRA"
     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)
+    platform_tags: list[str] = Field(..., min_length=0)
     playbook_type: PlaybookType = Field(...)
     vpe_type: VpeType = Field(...)
     playbook_fields: list[str] = Field([], min_length=0)
-    product: list[PlaybookProduct] = Field([],min_length=0)
-    use_cases: list[PlaybookUseCase] = Field([],min_length=0)
+    product: list[PlaybookProduct] = Field([], min_length=0)
+    use_cases: list[PlaybookUseCase] = Field([], min_length=0)
     defend_technique_id: Optional[List[DefendTechnique]] = None
-    
-    labels:list[str] = []
-    playbook_outputs:list[str] = []
-    
+
+    labels: list[str] = []
+    playbook_outputs: list[str] = []
+
     detection_objects: list[Detection] = []
-    

contentctl/objects/rba.py

@@ -1,17 +1,22 @@
-from enum import Enum
-from pydantic import BaseModel, computed_field, Field
+from __future__ import annotations
+
 from abc import ABC
-from typing import Set, Annotated
-from contentctl.objects.enums import RiskSeverity
+from enum import Enum
+from typing import Annotated, Set
 
+from pydantic import BaseModel, Field, computed_field, model_serializer
+
+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"
@@ -40,6 +45,7 @@ class ThreatObjectType(str, Enum):
     TLS_HASH = "tls_hash"
     URL = "url"
 
+
 class RiskObject(BaseModel):
     field: str
     type: RiskObjectType
@@ -48,6 +54,29 @@ class RiskObject(BaseModel):
     def __hash__(self):
         return hash((self.field, self.type, self.score))
 
+    def __lt__(self, other: RiskObject) -> bool:
+        if (
+            f"{self.field}{self.type}{self.score}"
+            < f"{other.field}{other.type}{other.score}"
+        ):
+            return True
+        return False
+
+    @model_serializer
+    def serialize_risk_object(self) -> dict[str, str | int]:
+        """
+        We define this explicitly for two reasons, even though the automatic
+        serialization works correctly.  First we want to enforce a specific
+        field order for reasons of readability. Second, some of the fields
+        actually have different names than they do in the object.
+        """
+        return {
+            "risk_object_field": self.field,
+            "risk_object_type": self.type,
+            "risk_score": self.score,
+        }
+
+
 class ThreatObject(BaseModel):
     field: str
     type: ThreatObjectType
@@ -55,26 +84,45 @@ class ThreatObject(BaseModel):
     def __hash__(self):
         return hash((self.field, self.type))
 
+    def __lt__(self, other: ThreatObject) -> bool:
+        if f"{self.field}{self.type}" < f"{other.field}{other.type}":
+            return True
+        return False
+
+    @model_serializer
+    def serialize_threat_object(self) -> dict[str, str]:
+        """
+        We define this explicitly for two reasons, even though the automatic
+        serialization works correctly.  First we want to enforce a specific
+        field order for reasons of readability. Second, some of the fields
+        actually have different names than they do in the object.
+        """
+        return {
+            "threat_object_field": self.field,
+            "threat_object_type": 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:
+    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.")
+            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:
+    def severity(self) -> RiskSeverity:
         if 0 <= self.risk_score <= 20:
             return RiskSeverity.INFORMATIONAL
         elif 20 < self.risk_score <= 40:
@@ -86,5 +134,14 @@ class RBAObject(BaseModel, ABC):
         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}")
+            raise Exception(
+                f"Error getting severity - risk_score must be between 0-100, but was actually {self.risk_score}"
+            )
 
+    @model_serializer
+    def serialize_rba(self) -> dict[str, str | list[dict[str, str | int]]]:
+        return {
+            "message": self.message,
+            "risk_objects": [obj.model_dump() for obj in sorted(self.risk_objects)],
+            "threat_objects": [obj.model_dump() for obj in sorted(self.threat_objects)],
+        }

contentctl/objects/risk_analysis_action.py

@@ -18,6 +18,7 @@ class RiskAnalysisAction(BaseModel):
     :param message: the message associated w/ the risk event (NOTE: may contain macros of the form
         $...$ which should be replaced with real values in the resulting risk events)
     """
+
     risk_objects: list[RiskObject]
     message: str
 
@@ -80,21 +81,24 @@ class RiskAnalysisAction(BaseModel):
         # TODO (#231): add validation ensuring at least 1 risk objects
         for entry in object_dicts:
             if "risk_object_field" in entry:
-                risk_objects.append(RiskObject(
-                    field=entry["risk_object_field"],
-                    type=entry["risk_object_type"],
-                    score=int(entry["risk_score"])
-                ))
+                risk_objects.append(
+                    RiskObject(
+                        field=entry["risk_object_field"],
+                        type=entry["risk_object_type"],
+                        score=int(entry["risk_score"]),
+                    )
+                )
             elif "threat_object_field" in entry:
-                threat_objects.append(ThreatObject(
-                    field=entry["threat_object_field"],
-                    type=entry["threat_object_type"]
-                ))
+                threat_objects.append(
+                    ThreatObject(
+                        field=entry["threat_object_field"],
+                        type=entry["threat_object_type"],
+                    )
+                )
             else:
                 raise ValueError(
                     f"Unexpected object within 'action.risk.param._risk': {entry}"
                 )
         return cls(
-            risk_objects=risk_objects,
-            message=dict_["action.risk.param._risk_message"]
+            risk_objects=risk_objects, message=dict_["action.risk.param._risk_message"]
         )

contentctl/objects/risk_event.py

@@ -1,9 +1,17 @@
 import re
 from functools import cached_property
 
-from pydantic import ConfigDict, BaseModel, Field, PrivateAttr, field_validator, computed_field
-from contentctl.objects.errors import ValidationFailed
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    computed_field,
+    field_validator,
+)
+
 from contentctl.objects.detection import Detection
+from contentctl.objects.errors import ValidationFailed
 from contentctl.objects.rba import RiskObject
 
 
@@ -15,11 +23,11 @@ class RiskEvent(BaseModel):
 
     # The subject of the risk event (e.g. a username, process name, system name, account ID, etc.)
     # (not to be confused w/ the risk object from the detection)
-    es_risk_object: int | str
+    es_risk_object: int | str = Field(alias="risk_object")
 
     # 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
+    es_risk_object_type: str = Field(alias="risk_object_type")
 
     # The level of risk associated w/ the risk event
     risk_score: int
@@ -35,8 +43,7 @@ class RiskEvent(BaseModel):
 
     # The MITRE ATT&CK IDs
     annotations_mitre_attack: list[str] = Field(
-        alias="annotations.mitre_attack",
-        default=[]
+        alias="annotations.mitre_attack", default=[]
     )
 
     # Contributing events search query (we use this to derive the corresponding field from the
@@ -48,9 +55,7 @@ class RiskEvent(BaseModel):
 
     # Allowing fields that aren't explicitly defined to be passed since some of the risk event's
     # fields vary depending on the SPL which generated them
-    model_config = ConfigDict(
-        extra="allow"
-    )
+    model_config = ConfigDict(extra="allow")
 
     @field_validator("annotations_mitre_attack", "analyticstories", mode="before")
     @classmethod
@@ -72,7 +77,9 @@ class RiskEvent(BaseModel):
         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>[^=]+)=.+"
+            r"\| savedsearch \""
+            + self.search_name
+            + r"\" \| search (?P<field>[^=]+)=.+"
         )
         match = pattern.search(self.contributing_events_search)
         if match is None:
@@ -121,7 +128,9 @@ class RiskEvent(BaseModel):
         :param detection: the detection associated w/ this risk event
         :raises: ValidationFailed
         """
-        if sorted(self.annotations_mitre_attack) != sorted(detection.tags.mitre_attack_id):
+        if sorted(self.annotations_mitre_attack) != sorted(
+            detection.tags.mitre_attack_id
+        ):
             raise ValidationFailed(
                 f"MITRE ATT&CK IDs in risk event ({self.annotations_mitre_attack}) do not match those"
                 f" in detection ({detection.tags.mitre_attack_id})."
@@ -134,7 +143,9 @@ class RiskEvent(BaseModel):
         :raises: ValidationFailed
         """
         # Render the detection analytic_story to a list of strings before comparing
-        detection_analytic_story = [story.name for story in detection.tags.analytic_story]
+        detection_analytic_story = [
+            story.name for story in detection.tags.analytic_story
+        ]
         if sorted(self.analyticstories) != sorted(detection_analytic_story):
             raise ValidationFailed(
                 f"Analytic stories in risk event ({self.analyticstories}) do not match those"
@@ -174,16 +185,12 @@ class RiskEvent(BaseModel):
         # placeholder
         tmp_placeholder = "PLACEHOLDERPATTERNFORESCAPING"
         escaped_source_message_with_placeholder: str = re.escape(
-            field_replacement_pattern.sub(
-                tmp_placeholder,
-                detection.rba.message
-            )
+            field_replacement_pattern.sub(tmp_placeholder, detection.rba.message)
         )
         placeholder_replacement_pattern = re.compile(tmp_placeholder)
         final_risk_message_pattern = re.compile(
             placeholder_replacement_pattern.sub(
-                r"[\\s\\S]*\\S[\\s\\S]*",
-                escaped_source_message_with_placeholder
+                r"[\\s\\S]*\\S[\\s\\S]*", escaped_source_message_with_placeholder
             )
         )
 
@@ -191,8 +198,8 @@ class RiskEvent(BaseModel):
         if final_risk_message_pattern.match(self.risk_message) is None:
             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.rba.message}\"."
+                f'risk event: "{self.risk_message}". Message in detection: '
+                f'"{detection.rba.message}".'
             )
 
     def validate_risk_against_risk_objects(self, risk_objects: set[RiskObject]) -> None:

contentctl/objects/risk_object.py

@@ -13,6 +13,7 @@ class RiskObject(BaseModel):
     :param type_: the type of the risk object (e.g. "system")
     :param score: the risk score associated with the obersevable (e.g. 64)
     """
+
     field: str
     type: str
     score: int

contentctl/objects/savedsearches_conf.py

@@ -1,4 +1,3 @@
-
 from pathlib import Path
 from typing import Any, ClassVar
 import re
@@ -17,6 +16,7 @@ class SavedsearchesConf(BaseModel):
     NOTE: At present, this model only parses the detections themselves from the .conf; thing like
     baselines or response tasks are left alone currently
     """
+
     # The path to the conf file
     path: Path = Field(...)
 
@@ -112,8 +112,7 @@ class SavedsearchesConf(BaseModel):
 
         # Build the stanza model from the accumulated lines and adjust the state to end this section
         self.detection_stanzas[self._current_section_name] = DetectionStanza(
-            name=self._current_section_name,
-            lines=self._current_section_lines
+            name=self._current_section_name, lines=self._current_section_lines
         )
         self._in_section = False
 
@@ -170,7 +169,9 @@ class SavedsearchesConf(BaseModel):
                     self._in_detections = True
 
     @staticmethod
-    def init_from_package(package_path: Path, app_name: str, appid: str) -> "SavedsearchesConf":
+    def init_from_package(
+        package_path: Path, app_name: str, appid: str
+    ) -> "SavedsearchesConf":
         """
         Alternate constructor which can take an app package, and extract the savedsearches.conf from
         a temporary file.
@@ -188,9 +189,10 @@ class SavedsearchesConf(BaseModel):
             # Open the tar/gzip archive
             with tarfile.open(package_path) as package:
                 # Extract the savedsearches.conf and use it to init the model
-                package_conf_path = SavedsearchesConf.PACKAGE_CONF_PATH_FMT_STR.format(appid=appid)
+                package_conf_path = SavedsearchesConf.PACKAGE_CONF_PATH_FMT_STR.format(
+                    appid=appid
+                )
                 package.extract(package_conf_path, path=tmpdir)
                 return SavedsearchesConf(
-                    path=Path(tmpdir, package_conf_path),
-                    app_label=app_name
+                    path=Path(tmpdir, package_conf_path), app_label=app_name
                 )

contentctl/objects/security_content_object.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
-from contentctl.objects.abstract_security_content_objects.security_content_object_abstract import SecurityContentObject_Abstract
+from contentctl.objects.abstract_security_content_objects.security_content_object_abstract import (
+    SecurityContentObject_Abstract,
+)
+
 
 class SecurityContentObject(SecurityContentObject_Abstract):
-    pass
+    pass