contentctl 4.2.2__py3-none-any.whl → 4.2.4__py3-none-any.whl

contentctl/objects/detection_tags.py

@@ -1,48 +1,66 @@
 from __future__ import annotations
 import uuid
 from typing import TYPE_CHECKING, List, Optional, Annotated, Union
-from pydantic import BaseModel,Field, NonNegativeInt, PositiveInt, computed_field, UUID4, HttpUrl, ConfigDict, field_validator, ValidationInfo, model_serializer, model_validator
+from pydantic import (
+    BaseModel,
+    Field,
+    NonNegativeInt,
+    PositiveInt,
+    computed_field,
+    UUID4,
+    HttpUrl,
+    ConfigDict,
+    field_validator,
+    ValidationInfo,
+    model_serializer,
+    model_validator
+)
 from contentctl.objects.story import Story
 if TYPE_CHECKING:
     from contentctl.input.director import DirectorOutputDto
 
-
-
 from contentctl.objects.mitre_attack_enrichment import MitreAttackEnrichment
-from contentctl.objects.constants import *
+from contentctl.objects.constants import ATTACK_TACTICS_KILLCHAIN_MAPPING
 from contentctl.objects.observable import Observable
-from contentctl.objects.enums import Cis18Value, AssetType, SecurityDomain, RiskSeverity, KillChainPhase, NistCategory, RiskLevel, SecurityContentProductName
+from contentctl.objects.enums import (
+    Cis18Value,
+    AssetType,
+    SecurityDomain,
+    RiskSeverity,
+    KillChainPhase,
+    NistCategory,
+    RiskLevel,
+    SecurityContentProductName
+)
 from contentctl.objects.atomic import AtomicTest
 
 
-
 class DetectionTags(BaseModel):
     # detection spec
-    model_config = ConfigDict(use_enum_values=True,validate_default=False)
+    model_config = ConfigDict(use_enum_values=True, validate_default=False)
     analytic_story: list[Story] = Field(...)
     asset_type: AssetType = Field(...)
-    
-    
-    confidence: NonNegativeInt = Field(...,le=100)
-    impact: NonNegativeInt = Field(...,le=100)
+
+    confidence: NonNegativeInt = Field(..., le=100)
+    impact: NonNegativeInt = Field(..., le=100)
+
     @computed_field
     @property
-    def risk_score(self)->int:
+    def risk_score(self) -> int:
         return round((self.confidence * self.impact)/100)
-    
-    
-    mitre_attack_id: List[Annotated[str, Field(pattern="^T[0-9]{4}(.[0-9]{3})?$")]] = []
+
+    mitre_attack_id: List[Annotated[str, Field(pattern=r"^T\d{4}(.\d{3})?$")]] = []
     nist: list[NistCategory] = []
     observable: List[Observable] = []
-    message: Optional[str] = Field(...)
-    product: list[SecurityContentProductName] = Field(...,min_length=1)
+    message: str = Field(...)
+    product: list[SecurityContentProductName] = Field(..., min_length=1)
     required_fields: list[str] = Field(min_length=1)
-    
+
     security_domain: SecurityDomain = Field(...)
 
     @computed_field
     @property
-    def risk_severity(self)->RiskSeverity:
+    def risk_severity(self) -> RiskSeverity:
         if self.risk_score >= 80:
             return RiskSeverity('high')
         elif (self.risk_score >= 50 and self.risk_score <= 79):
@@ -50,83 +68,81 @@ class DetectionTags(BaseModel):
         else:
             return RiskSeverity('low')
 
-
-    
-    cve: List[Annotated[str, "^CVE-[1|2][0-9]{3}-[0-9]+$"]] = []
+    cve: List[Annotated[str, r"^CVE-[1|2]\d{3}-\d+$"]] = []
     atomic_guid: List[AtomicTest] = []
     drilldown_search: Optional[str] = None
 
-
     # enrichment
-    mitre_attack_enrichments: List[MitreAttackEnrichment] = Field([],validate_default=True)
-    confidence_id: Optional[PositiveInt] = Field(None,ge=1,le=3)
-    impact_id: Optional[PositiveInt] = Field(None,ge=1,le=5)
+    mitre_attack_enrichments: List[MitreAttackEnrichment] = Field([], validate_default=True)
+    confidence_id: Optional[PositiveInt] = Field(None, ge=1, le=3)
+    impact_id: Optional[PositiveInt] = Field(None, ge=1, le=5)
     # context_ids: list = None
-    risk_level_id: Optional[NonNegativeInt] = Field(None,le=4)
+    risk_level_id: Optional[NonNegativeInt] = Field(None, le=4)
     risk_level: Optional[RiskLevel] = None
-    #observable_str: str = None
+    # observable_str: str = None
     evidence_str: Optional[str] = None
 
     @computed_field
     @property
-    def kill_chain_phases(self)->list[KillChainPhase]:
-        if self.mitre_attack_enrichments is None:
-            return []
-        phases:set[KillChainPhase] = set()
+    def kill_chain_phases(self) -> list[KillChainPhase]:
+        phases: set[KillChainPhase] = set()
         for enrichment in self.mitre_attack_enrichments:
             for tactic in enrichment.mitre_attack_tactics:
                 phase = KillChainPhase(ATTACK_TACTICS_KILLCHAIN_MAPPING[tactic])
                 phases.add(phase)
         return sorted(list(phases))
-    
-    #enum is intentionally Cis18 even though field is named cis20 for legacy reasons
+
+    # enum is intentionally Cis18 even though field is named cis20 for legacy reasons
     @computed_field
     @property
-    def cis20(self)->list[Cis18Value]:
+    def cis20(self) -> list[Cis18Value]:
         if self.security_domain == SecurityDomain.NETWORK:
             return [Cis18Value.CIS_13]
         else:
             return [Cis18Value.CIS_10]
 
-    
     research_site_url: Optional[HttpUrl] = None
     event_schema: str = "ocsf"
+    # TODO (#221): mappings should be fleshed out into a proper class
     mappings: Optional[List] = None
-    #annotations: Optional[dict] = None
+    # annotations: Optional[dict] = None
     manual_test: Optional[str] = None
-    
-    
+
     # The following validator is temporarily disabled pending further discussions
     # @validator('message')
     # def validate_message(cls,v,values):
-        
+
     #     observables:list[Observable] = values.get("observable",[])
     #     observable_names = set([o.name for o in observables])
     #     #find all of the observables used in the message by name
     #     name_match_regex = r"\$([^\s.]*)\$"
-        
+
     #     message_observables = set()
 
-    #     #Make sure that all observable names in 
+    #     #Make sure that all observable names in
     #     for match in re.findall(name_match_regex, v):
     #         #Remove
     #         match_without_dollars = match.replace("$", "")
     #         message_observables.add(match_without_dollars)
-        
 
     #     missing_observables = message_observables - observable_names
     #     unused_observables = observable_names - message_observables
     #     if len(missing_observables) > 0:
-    #         raise ValueError(f"The following observables are referenced in the message, but were not declared as observables: {missing_observables}")
-        
+    #         raise ValueError(
+    #             "The following observables are referenced in the message, but were not declared as"
+    #             f" observables: {missing_observables}"
+    #         )
+
     #     if len(unused_observables) > 0:
-    #         raise ValueError(f"The following observables were declared, but are not referenced in the message: {unused_observables}")        
+    #         raise ValueError(
+    #             "The following observables were declared, but are not referenced in the message:"
+    #             f" {unused_observables}"
+    #         )
     #     return v
 
-    
     @model_serializer
     def serialize_model(self):
-        #Since this field has no parent, there is no need to call super() serialization function
+        # Since this field has no parent, there is no need to call super() serialization function
         return {
             "analytic_story": [story.name for story in self.analytic_story],
             "asset_type": self.asset_type.value,
@@ -141,34 +157,38 @@ class DetectionTags(BaseModel):
             "mitre_attack_id": self.mitre_attack_id,
             "mitre_attack_enrichments": self.mitre_attack_enrichments
         }
-    
-        
+
     @model_validator(mode="after")
-    def addAttackEnrichment(self, info:ValidationInfo):
+    def addAttackEnrichment(self, info: ValidationInfo):
+        if info.context is None:
+            raise ValueError("ValidationInfo.context unexpectedly null")
+
         if len(self.mitre_attack_enrichments) > 0:
-            raise ValueError(f"Error, field 'mitre_attack_enrichment' should be empty and dynamically populated at runtime. Instead, this field contained: {self.mitre_attack_enrichments}")
-        
-        output_dto:Union[DirectorOutputDto,None]= info.context.get("output_dto",None)
+            raise ValueError(
+                "Error, field 'mitre_attack_enrichment' should be empty and dynamically populated"
+                f" at runtime. Instead, this field contained: {self.mitre_attack_enrichments}"
+            )
+
+        output_dto: Union[DirectorOutputDto, None] = info.context.get("output_dto", None)
         if output_dto is None:
             raise ValueError("Context not provided to detection.detection_tags model post validator")
-        
+
         if output_dto.attack_enrichment.use_enrichment is False:
             return self
-        
 
-        mitre_enrichments = []
-        missing_tactics = []
+        mitre_enrichments: list[MitreAttackEnrichment] = []
+        missing_tactics: list[str] = []
         for mitre_attack_id in self.mitre_attack_id:
             try:
                 mitre_enrichments.append(output_dto.attack_enrichment.getEnrichmentByMitreID(mitre_attack_id))
-            except Exception as e:
-                missing_tactics.append(mitre_attack_id)            
-        
+            except Exception:
+                missing_tactics.append(mitre_attack_id)
+
         if len(missing_tactics) > 0:
             raise ValueError(f"Missing Mitre Attack IDs. {missing_tactics} not found.")
         else:
             self.mitre_attack_enrichments = mitre_enrichments
-        
+
         return self
 
     '''
@@ -176,77 +196,83 @@ class DetectionTags(BaseModel):
     @classmethod
     def addAttackEnrichments(cls, v:list[MitreAttackEnrichment], info:ValidationInfo)->list[MitreAttackEnrichment]:
         if len(v) > 0:
-            raise ValueError(f"Error, field 'mitre_attack_enrichment' should be empty and dynamically populated at runtime. Instead, this field contained: {str(v)}")
-        
-        
+            raise ValueError(
+                f"Error, field 'mitre_attack_enrichment' should be empty and dynamically populated"
+                f" at runtime. Instead, this field contained: {str(v)}"
+            )
+
+
         output_dto:Union[DirectorOutputDto,None]= info.context.get("output_dto",None)
         if output_dto is None:
             raise ValueError("Context not provided to detection.detection_tags.mitre_attack_enrichments")
-        
-        enrichments = []
-
 
+        enrichments = []
 
-        
         return enrichments
     '''
 
-    @field_validator('analytic_story',mode="before")
+    @field_validator('analytic_story', mode="before")
     @classmethod
-    def mapStoryNamesToStoryObjects(cls, v:list[str], info:ValidationInfo)->list[Story]:
-        return Story.mapNamesToSecurityContentObjects(v, info.context.get("output_dto",None))
-    
-    def getAtomicGuidStringArray(self)->List[str]:
+    def mapStoryNamesToStoryObjects(cls, v: list[str], info: ValidationInfo) -> list[Story]:
+        if info.context is None:
+            raise ValueError("ValidationInfo.context unexpectedly null")
+
+        return Story.mapNamesToSecurityContentObjects(v, info.context.get("output_dto", None))
+
+    def getAtomicGuidStringArray(self) -> List[str]:
         return [str(atomic_guid.auto_generated_guid) for atomic_guid in self.atomic_guid]
-            
 
-    @field_validator('atomic_guid',mode="before")
+    @field_validator('atomic_guid', mode="before")
     @classmethod
-    def mapAtomicGuidsToAtomicTests(cls, v:List[UUID4], info:ValidationInfo)->List[AtomicTest]:
+    def mapAtomicGuidsToAtomicTests(cls, v: List[UUID4], info: ValidationInfo) -> List[AtomicTest]:
         if len(v) == 0:
             return []
-        
-        output_dto:Union[DirectorOutputDto,None]= info.context.get("output_dto",None)
+
+        if info.context is None:
+            raise ValueError("ValidationInfo.context unexpectedly null")
+
+        output_dto: Union[DirectorOutputDto, None] = info.context.get("output_dto", None)
         if output_dto is None:
             raise ValueError("Context not provided to detection.detection_tags.atomic_guid validator")
 
-        
-        all_tests:List[AtomicTest]= output_dto.atomic_tests
-        
-        matched_tests:List[AtomicTest] = []
-        missing_tests:List[UUID4] = []
-        badly_formatted_guids:List[str] = []
+        all_tests: None | List[AtomicTest] = output_dto.atomic_tests
+
+        matched_tests: List[AtomicTest] = []
+        missing_tests: List[UUID4] = []
+        badly_formatted_guids: List[str] = []
         for atomic_guid_str in v:
             try:
-                #Ensure that this is a valid UUID
+                # Ensure that this is a valid UUID
                 atomic_guid = uuid.UUID(str(atomic_guid_str))
-            except Exception as e:
-                #We will not try to load a test for this since it was invalid
+            except Exception:
+                # We will not try to load a test for this since it was invalid
                 badly_formatted_guids.append(str(atomic_guid_str))
                 continue
             try:
-                matched_tests.append(AtomicTest.getAtomicByAtomicGuid(atomic_guid,all_tests))
-            except Exception as _:
+                matched_tests.append(AtomicTest.getAtomicByAtomicGuid(atomic_guid, all_tests))
+            except Exception:
                 missing_tests.append(atomic_guid)
 
-        
-        
-        
         if len(missing_tests) > 0:
-            missing_tests_string = f"\n\tWARNING: Failed to find [{len(missing_tests)}] Atomic Test(s) with the following atomic_guids (called auto_generated_guid in the ART Repo)."\
-                                   f"\n\tPlease review the output above for potential exception(s) when parsing the Atomic Red Team Repo."\
-                                   f"\n\tVerify that these auto_generated_guid exist and try updating/pulling the repo again.: {[str(guid) for guid in missing_tests]}"
+            missing_tests_string = (
+                f"\n\tWARNING: Failed to find [{len(missing_tests)}] Atomic Test(s) with the "
+                "following atomic_guids (called auto_generated_guid in the ART Repo)."
+                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]}"
+            )
         else:
             missing_tests_string = ""
-            
 
         if len(badly_formatted_guids) > 0:
-            if len(badly_formatted_guids) > 0:
-                bad_guids_string = f"The following [{len(badly_formatted_guids)}] value(s) are not properly formatted UUIDs: {badly_formatted_guids}\n"
-                raise ValueError(f"{bad_guids_string}{missing_tests_string}")
-        
+            bad_guids_string = (
+                f"The following [{len(badly_formatted_guids)}] value(s) are not properly "
+                f"formatted UUIDs: {badly_formatted_guids}\n"
+            )
+            raise ValueError(f"{bad_guids_string}{missing_tests_string}")
+
         elif len(missing_tests) > 0:
             print(missing_tests_string)
 
         return matched_tests + [AtomicTest.AtomicTestWhenTestIsMissing(test) for test in missing_tests]
-    

contentctl/objects/errors.py

@@ -0,0 +1,18 @@
+class ValidationFailed(Exception):
+    """Indicates not an error in execution, but a validation failure"""
+    pass
+
+
+class IntegrationTestingError(Exception):
+    """Base exception class for integration testing"""
+    pass
+
+
+class ServerError(IntegrationTestingError):
+    """An error encounterd during integration testing, as provided by the server (Splunk instance)"""
+    pass
+
+
+class ClientError(IntegrationTestingError):
+    """An error encounterd during integration testing, on the client's side (locally)"""
+    pass

contentctl/objects/lookup.py

@@ -22,6 +22,7 @@ LOOKUPS_TO_IGNORE.add("=")
 LOOKUPS_TO_IGNORE.add("other_lookups") 
 
 
+# TODO (#220): Split Lookup into 2 classes
 class Lookup(SecurityContentObject):
     
     collection: Optional[str] = None

contentctl/objects/mitre_attack_enrichment.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 from pydantic import BaseModel, Field, ConfigDict
-from typing import Set,List,Annotated
+from typing import List, Annotated
 from enum import StrEnum
 
 
@@ -23,10 +23,10 @@ class MitreTactics(StrEnum):
 
 class MitreAttackEnrichment(BaseModel):
     ConfigDict(use_enum_values=True)
-    mitre_attack_id: Annotated[str, Field(pattern="^T\d{4}(.\d{3})?$")] = Field(...)
+    mitre_attack_id: Annotated[str, Field(pattern=r"^T\d{4}(.\d{3})?$")] = Field(...)
     mitre_attack_technique: str = Field(...)
     mitre_attack_tactics: List[MitreTactics] = Field(...)
     mitre_attack_groups: List[str] = Field(...)
 
     def __hash__(self) -> int:
-        return id(self)
+        return id(self)

contentctl/objects/notable_event.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+
+from contentctl.objects.detection import Detection
+
+
+# TODO (PEX-434): implement deeper notable validation
+class NotableEvent(BaseModel):
+    # The search name (e.g. "ESCU - Windows Modify Registry EnableLinkedConnections - Rule")
+    search_name: str
+
+    # The search ID that found that generated this risk event
+    orig_sid: str
+
+    class Config:
+        # 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
+        extra = 'allow'
+
+    def validate_against_detection(self, detection: Detection) -> None:
+        raise NotImplementedError()

contentctl/objects/observable.py

@@ -1,8 +1,5 @@
-from __future__ import annotations
-from pydantic import BaseModel, validator
-
-from contentctl.objects.constants import *
-
+from pydantic import BaseModel, field_validator
+from contentctl.objects.constants import SES_OBSERVABLE_TYPE_MAPPING, SES_OBSERVABLE_ROLE_MAPPING
 
 
 class Observable(BaseModel):
@@ -10,32 +7,29 @@ class Observable(BaseModel):
     type: str
     role: list[str]
 
-
-
-    @validator('name')
-    def check_name(cls, v, values):
+    @field_validator('name')
+    def check_name(cls, v: str):
         if v == "":
             raise ValueError("No name provided for observable")
         return v
-    
-    @validator('type')
-    def check_type(cls, v, values):
+
+    @field_validator('type')
+    def check_type(cls, v: str):
         if v not in SES_OBSERVABLE_TYPE_MAPPING.keys():
-            raise ValueError(f"Invalid type '{v}' provided for observable.  Valid observable types are {SES_OBSERVABLE_TYPE_MAPPING.keys()}")
+            raise ValueError(
+                f"Invalid type '{v}' provided for observable.  Valid observable types are "
+                f"{SES_OBSERVABLE_TYPE_MAPPING.keys()}"
+            )
         return v
 
-    
-    @validator('role', each_item=False)
-    def check_roles_not_empty(cls, v, values):
+    @field_validator('role')
+    def check_roles(cls, v: list[str]):
         if len(v) == 0:
-            raise ValueError("At least one role must be defined for observable")
+            raise ValueError("Error, at least 1 role must be listed for Observable.")
+        for role in v:
+            if role not in SES_OBSERVABLE_ROLE_MAPPING.keys():
+                raise ValueError(
+                    f"Invalid role '{role}' provided for observable.  Valid observable types are "
+                    f"{SES_OBSERVABLE_ROLE_MAPPING.keys()}"
+                )
         return v
-
-    @validator('role', each_item=True)
-    def check_roles(cls, v, values):
-        if v not in SES_OBSERVABLE_ROLE_MAPPING.keys():
-            raise ValueError(f"Invalid role '{v}' provided for observable.  Valid observable types are {SES_OBSERVABLE_ROLE_MAPPING.keys()}")
-        return v
-
-
-    

contentctl/objects/risk_analysis_action.py

@@ -7,7 +7,7 @@ from contentctl.objects.risk_object import RiskObject
 from contentctl.objects.threat_object import ThreatObject
 
 
-# TODO (cmcginley): add logic which reports concretely that integration testing failed (or would fail)
+# TODO (#231): add logic which reports concretely that integration testing failed (or would fail)
 #   as a result of a missing victim observable
 class RiskAnalysisAction(BaseModel):
     """Representation of a risk analysis action
@@ -77,7 +77,7 @@ class RiskAnalysisAction(BaseModel):
         risk_objects: list[RiskObject] = []
         threat_objects: list[ThreatObject] = []
 
-        # TODO (cmcginley): add validation ensuring at least 1 risk objects
+        # 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(