contentctl 3.6.0__py3-none-any.whl → 4.0.2__py3-none-any.whl

contentctl/objects/constants.py

@@ -12,7 +12,6 @@ ATTACK_TACTICS_KILLCHAIN_MAPPING = {
     "Lateral Movement": "Exploitation",
     "Collection": "Exploitation",
     "Command And Control": "Command and Control",
-    "Command And Control": "Command and Control",
     "Exfiltration": "Actions on Objectives",
     "Impact": "Actions on Objectives"
 }

contentctl/objects/correlation_search.py

@@ -220,7 +220,7 @@ class CorrelationSearch(BaseModel):
 
     # The logger to use (logs all go to a null pipe unless ENABLE_LOGGING is set to True, so as not
     # to conflict w/ tqdm)
-    logger: logging.Logger = Field(default_factory=get_logger, const=True)
+    logger: logging.Logger = Field(default_factory=get_logger)
 
     # The search name (e.g. "ESCU - Windows Modify Registry EnableLinkedConnections - Rule")
     name: Optional[str] = None

contentctl/objects/data_source.py

@@ -1,10 +1,8 @@
+from __future__ import annotations
+from pydantic import BaseModel
 
 
 
-from pydantic import BaseModel, validator, ValidationError
-from dataclasses import dataclass
-
-
 class DataSource(BaseModel):
     name: str
     id: str

contentctl/objects/deployment.py

@@ -1,30 +1,70 @@
-
-import uuid
-import string
-
-from pydantic import BaseModel, validator, ValidationError
-from datetime import datetime
+from __future__ import annotations
+from pydantic import Field, computed_field, model_validator,ValidationInfo, model_serializer
+from typing import Optional,Any
 
 from contentctl.objects.security_content_object import SecurityContentObject
 from contentctl.objects.deployment_scheduling import DeploymentScheduling
-from contentctl.objects.deployment_email import DeploymentEmail
-from contentctl.objects.deployment_notable import DeploymentNotable
-from contentctl.objects.deployment_rba import DeploymentRBA
-from contentctl.objects.deployment_slack import DeploymentSlack
-from contentctl.objects.deployment_phantom import DeploymentPhantom
-from contentctl.objects.enums import SecurityContentType
+from contentctl.objects.alert_action import AlertAction
+
+from contentctl.objects.enums import DeploymentType
+
+
 class Deployment(SecurityContentObject):
-    name: str = "PLACEHOLDER_NAME"
     #id: str = None
     #date: str = None
     #author: str = None
     #description: str = None
     #contentType: SecurityContentType = SecurityContentType.deployments
-    scheduling: DeploymentScheduling = None
-    email: DeploymentEmail = None
-    notable: DeploymentNotable = None
-    rba: DeploymentRBA = None
-    slack: DeploymentSlack = None
-    phantom: DeploymentPhantom = None
-    tags: dict = None
-    
+    scheduling: DeploymentScheduling = Field(...)
+    alert_action: AlertAction = AlertAction()
+    type: DeploymentType = Field(...)
+
+    #Type was the only tag exposed and should likely be removed/refactored.
+    #For transitional reasons, provide this as a computed_field in prep for removal
+    @computed_field
+    @property
+    def tags(self)->dict[str,DeploymentType]:
+        return {"type": self.type}
+    
+    @staticmethod
+    def getDeployment(v:dict[str,Any], info:ValidationInfo)->Deployment:
+        if v != {}:
+            # If the user has defined a deployment, then allow it to be validated
+            # and override the default deployment info defined in type:Baseline
+            v['type'] = DeploymentType.Embedded
+            
+            detection_name = info.data.get("name", None)
+            if detection_name is None:
+                raise ValueError("Could not create inline deployment - Baseline or Detection lacking 'name' field,")
+            
+            v['name'] = f"{detection_name} - Inline Deployment"
+            # This constructs a temporary in-memory deployment,
+            # allowing the deployment to be easily defined in the 
+            # detection on a per detection basis.
+            return Deployment.model_validate(v)
+                        
+        else:
+            return SecurityContentObject.getDeploymentFromType(info.data.get("type",None), info)
+    
+    @model_serializer
+    def serialize_model(self):
+        #Call serializer for parent
+        super_fields = super().serialize_model()
+        
+        #All fields custom to this model
+        model= {
+            "scheduling": self.scheduling.model_dump(),
+            "tags": self.tags
+        }
+
+        
+        #Combine fields from this model with fields from parent
+        model.update(super_fields)
+        
+        alert_action_fields = self.alert_action.model_dump()
+        model.update(alert_action_fields)
+
+        del(model['references'])
+        
+        #return the model
+        return model

contentctl/objects/deployment_email.py

@@ -1,5 +1,5 @@
-
-from pydantic import BaseModel, validator, ValidationError
+from __future__ import annotations
+from pydantic import BaseModel
 
 
 class DeploymentEmail(BaseModel):

contentctl/objects/deployment_notable.py

@@ -1,8 +1,8 @@
-
-from pydantic import BaseModel, validator, ValidationError
-
+from __future__ import annotations
+from pydantic import BaseModel
+from typing import List
 
 class DeploymentNotable(BaseModel):
     rule_description: str
     rule_title: str
-    nes_fields: list
+    nes_fields: List[str]

contentctl/objects/deployment_phantom.py

@@ -1,5 +1,5 @@
-
-from pydantic import BaseModel, validator, ValidationError
+from __future__ import annotations
+from pydantic import BaseModel
 
 
 class DeploymentPhantom(BaseModel):

contentctl/objects/deployment_rba.py

@@ -1,7 +1,6 @@
-
-
-from pydantic import BaseModel, validator, ValidationError
+from __future__ import annotations
+from pydantic import BaseModel
 
 
 class DeploymentRBA(BaseModel):
-    enabled: str
+    enabled: bool = False

contentctl/objects/deployment_scheduling.py

@@ -1,6 +1,5 @@
-
-
-from pydantic import BaseModel, validator, ValidationError
+from __future__ import annotations
+from pydantic import BaseModel
 
 
 class DeploymentScheduling(BaseModel):

contentctl/objects/deployment_slack.py

@@ -1,5 +1,5 @@
-
-from pydantic import BaseModel, validator, ValidationError
+from __future__ import annotations
+from pydantic import BaseModel
 
 
 class DeploymentSlack(BaseModel):

contentctl/objects/detection.py

@@ -1,10 +1,6 @@
-from typing import Union
-from pydantic import validator
-
+from __future__ import annotations
 from contentctl.objects.abstract_security_content_objects.detection_abstract import Detection_Abstract
 
-
-
 class Detection(Detection_Abstract):
     # Customization to the Detection Class go here.
     # You may add fields and/or validations

contentctl/objects/detection_tags.py

@@ -1,134 +1,100 @@
-import re
+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 contentctl.objects.story import Story
+if TYPE_CHECKING:
+    from contentctl.input.director import DirectorOutputDto
+
+
 
-from pydantic import BaseModel, validator, ValidationError, root_validator
 from contentctl.objects.mitre_attack_enrichment import MitreAttackEnrichment
 from contentctl.objects.constants import *
 from contentctl.objects.observable import Observable
+from contentctl.objects.enums import Cis18Value, AssetType, SecurityDomain, RiskSeverity, KillChainPhase, NistCategory, RiskLevel, SecurityContentProductName
+from contentctl.objects.atomic import AtomicTest
+
+
 
 class DetectionTags(BaseModel):
     # detection spec
-    name: str
-    analytic_story: list
-    asset_type: str
-    automated_detection_testing: str = None
-    cis20: list = None
-    confidence: str
-    impact: int
-    kill_chain_phases: list = None
-    mitre_attack_id: list = None
-    nist: list = None
-    observable: list[Observable] = []
-    message: str
-    product: list
-    required_fields: list
-    risk_score: int
-    security_domain: str
-    risk_severity: str = None
-    cve: list = None
-    supported_tas: list = None
-    atomic_guid: list = None
-    drilldown_search: str = None
-    manual_test: str = None
+    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)
+    @computed_field
+    @property
+    def risk_score(self)->int:
+        return round((self.confidence * self.impact)/100)
+    
+    
+    mitre_attack_id: List[Annotated[str, Field(pattern="^T\d{4}(.\d{3})?$")]] = []
+    nist: list[NistCategory] = []
+    observable: List[Observable] = []
+    message: Optional[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:
+        if self.risk_score >= 80:
+            return RiskSeverity('high')
+        elif (self.risk_score >= 50 and self.risk_score <= 79):
+            return RiskSeverity('medium')
+        else:
+            return RiskSeverity('low')
+
+
+    
+    cve: List[Annotated[str, "^CVE-[1|2][0-9]{3}-[0-9]+$"]] = []
+    atomic_guid: List[AtomicTest] = []
+    drilldown_search: Optional[str] = None
 
 
     # enrichment
-    mitre_attack_enrichments: list[MitreAttackEnrichment] = []
-    confidence_id: int = None
-    impact_id: int = None
-    context_ids: list = None
-    risk_level_id: int = None
-    risk_level: str = None
-    observable_str: str = None
-    evidence_str: str = None
-    kill_chain_phases_id: list = None
-    research_site_url: str = None
-    event_schema: str = None
-    mappings: list = None
-    annotations: dict = None
-
-
-    @validator('cis20')
-    def tags_cis20(cls, v, values):
-        pattern = '^CIS ([0-9]|1[0-9]|20)$' #DO NOT match leading zeroes and ensure no extra characters before or after the string
-        for value in v:
-            if not re.match(pattern, value):
-                raise ValueError(f"CIS control '{value}' is not a valid Control ('CIS 1' -> 'CIS 20'):  {values['name']}")
-        return v
+    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: Optional[RiskLevel] = 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()
+        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))
     
-    @validator('nist')
-    def tags_nist(cls, v, values):
-        # Sourced Courtest of NIST: https://www.nist.gov/system/files/documents/cyberframework/cybersecurity-framework-021214.pdf (Page 19)
-        IDENTIFY = [f'ID.{category}' for category in ["AM", "BE", "GV", "RA", "RM"]      ]
-        PROTECT  = [f'PR.{category}' for category in ["AC", "AT", "DS", "IP", "MA", "PT"]]
-        DETECT   = [f'DE.{category}' for category in ["AE", "CM", "DP"]                  ]
-        RESPOND  = [f'RS.{category}' for category in ["RP", "CO", "AN", "MI", "IM"]      ]
-        RECOVER  = [f'RC.{category}' for category in ["RP", "IM", "CO"]                  ]
-        ALL_NIST_CATEGORIES = IDENTIFY + PROTECT + DETECT + RESPOND + RECOVER
-
-        
-        for value in v:
-            if not value in ALL_NIST_CATEGORIES:
-                raise ValueError(f"NIST Category '{value}' is not a valid category")
-        return v
-
-    @validator('confidence')
-    def tags_confidence(cls, v, values):
-        v = int(v)
-        if not (v > 0 and v <= 100):
-             raise ValueError('confidence score is out of range 1-100: ' + values["name"])
-        else:
-            return v
-
-    @validator('context_ids')
-    def tags_context(cls, v, values):
-        context_list = SES_CONTEXT_MAPPING.keys()
-        for value in v:
-            if value not in context_list:
-                raise ValueError('context value not valid for ' + values["name"] + '. valid options are ' + str(context_list) )
-        return v
-
-    @validator('impact')
-    def tags_impact(cls, v, values):
-        if not (v > 0 and v <= 100):
-             raise ValueError('impact score is out of range 1-100: ' + values["name"])
+    #enum is intentionally Cis18 even though field is named cis20 for legacy reasons
+    @computed_field
+    @property
+    def cis20(self)->list[Cis18Value]:
+        if self.security_domain == SecurityDomain.NETWORK:
+            return [Cis18Value.CIS_13]
         else:
-            return v
-
-    @validator('kill_chain_phases')
-    def tags_kill_chain_phases(cls, v, values):
-        valid_kill_chain_phases = SES_KILL_CHAIN_MAPPINGS.keys()
-        for value in v:
-            if value not in valid_kill_chain_phases:
-                raise ValueError('kill chain phase not valid for ' + values["name"] + '. valid options are ' + str(valid_kill_chain_phases))
-        return v
-
-    @validator('mitre_attack_id')
-    def tags_mitre_attack_id(cls, v, values):
-        pattern = 'T[0-9]{4}'
-        for value in v:
-            if not re.match(pattern, value):
-                raise ValueError('Mitre Attack ID are not following the pattern Txxxx: ' + values["name"])
-        return v
-
-    @validator('product')
-    def tags_product(cls, v, values):
-        valid_products = [
-            "Splunk Enterprise", "Splunk Enterprise Security", "Splunk Cloud",
-            "Splunk Security Analytics for AWS", "Splunk Behavioral Analytics"
-        ]
-
-        for value in v:
-            if value not in valid_products:
-                raise ValueError('product is not valid for ' + values['name'] + '. valid products are ' + str(valid_products))
-        return v
-
-    @validator('risk_score')
-    def tags_calculate_risk_score(cls, v, values):
-        calculated_risk_score = round(values['impact'] * values['confidence'] / 100)
-        if calculated_risk_score != int(v):
-            raise ValueError(f"Risk Score must be calculated as round(confidence * impact / 100)"
-                             f"\n  Expected risk_score={calculated_risk_score}, found risk_score={int(v)}: {values['name']}")
-        return v
+            return [Cis18Value.CIS_10]
+
+    
+    research_site_url: Optional[HttpUrl] = None
+    event_schema: str = "ocsf"
+    mappings: Optional[List] = None
+    #annotations: Optional[dict] = None
+    manual_test: Optional[str] = None
+    
     
     # The following validator is temporarily disabled pending further discussions
     # @validator('message')
@@ -157,4 +123,129 @@ class DetectionTags(BaseModel):
     #         raise ValueError(f"The following observables were declared, but are not referenced in the message: {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
+        return {
+            "analytic_story": [story.name for story in self.analytic_story],
+            "asset_type": self.asset_type.value,
+            "cis20": self.cis20,
+            "kill_chain_phases": self.kill_chain_phases,
+            "nist": self.nist,
+            "observable": self.observable,
+            "message": self.message,
+            "risk_score": self.risk_score,
+            "security_domain": self.security_domain,
+            "risk_severity": self.risk_severity,
+            "mitre_attack_enrichments": self.mitre_attack_enrichments
+        }
+    
+        
+    @model_validator(mode="after")
+    def addAttackEnrichment(self, info:ValidationInfo):
+        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: {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 model post validator")
+        
+        if output_dto.attack_enrichment.use_enrichment is False:
+            return self
+        
+
+        mitre_enrichments = []
+        missing_tactics = []
+        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)            
+        
+        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
+
+    '''
+    @field_validator('mitre_attack_enrichments', mode="before")
+    @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)}")
+        
+        
+        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 = []
+
+
+
+        
+        return enrichments
+    '''
+
+    @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]:
+        return [str(atomic_guid.auto_generated_guid) for atomic_guid in self.atomic_guid]
+            
+
+    @field_validator('atomic_guid',mode="before")
+    @classmethod
+    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 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] = []
+        for atomic_guid_str in v:
+            try:
+                #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
+                badly_formatted_guids.append(str(atomic_guid_str))
+                continue
+            try:
+                matched_tests.append(AtomicTest.getAtomicByAtomicGuid(atomic_guid,all_tests))
+            except Exception as _:
+                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]}"
+        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}")
+        
+        elif len(missing_tests) > 0:
+            print(missing_tests_string)
+
+        return matched_tests + [AtomicTest.AtomicTestWhenTestIsMissing(test) for test in missing_tests]