contentctl 4.2.1__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

@@ -8,19 +8,21 @@ if TYPE_CHECKING:
     from contentctl.objects.config import validate
 from contentctl.objects.security_content_object import SecurityContentObject
 
-
+# This section is used to ignore lookups that are NOT  shipped with ESCU app but are used in the detections. Adding exclusions here will so that contentctl builds will not fail.
 LOOKUPS_TO_IGNORE = set(["outputlookup"])
 LOOKUPS_TO_IGNORE.add("ut_shannon_lookup") #In the URL toolbox app which is recommended for ESCU
 LOOKUPS_TO_IGNORE.add("identity_lookup_expanded") #Shipped with the Asset and Identity Framework
 LOOKUPS_TO_IGNORE.add("cim_corporate_web_domain_lookup") #Shipped with the Asset and Identity Framework
 LOOKUPS_TO_IGNORE.add("alexa_lookup_by_str") #Shipped with the Asset and Identity Framework
 LOOKUPS_TO_IGNORE.add("interesting_ports_lookup") #Shipped with the Asset and Identity Framework
+LOOKUPS_TO_IGNORE.add("admon_groups_def") #Shipped with the SA-admon addon
 
 #Special case for the Detection "Exploit Public Facing Application via Apache Commons Text"
 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(