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

contentctl/objects/enums.py

@@ -9,6 +9,7 @@ class AnalyticsType(StrEnum):
     Hunting = "Hunting"
     Correlation = "Correlation"
 
+
 class DeploymentType(StrEnum):
     TTP = "TTP"
     Anomaly = "Anomaly"
@@ -20,7 +21,7 @@ class DeploymentType(StrEnum):
 
 class DataModel(StrEnum):
     ENDPOINT = "Endpoint"
-    NETWORK_TRAFFIC  = "Network_Traffic"
+    NETWORK_TRAFFIC = "Network_Traffic"
     AUTHENTICATION = "Authentication"
     CHANGE = "Change"
     CHANGE_ANALYSIS = "Change_Analysis"
@@ -31,11 +32,11 @@ class DataModel(StrEnum):
     UPDATES = "Updates"
     VULNERABILITIES = "Vulnerabilities"
     WEB = "Web"
-    #Should the following more specific DMs be added? 
-    #Or should they just fall under endpoint?
-    #ENDPOINT_PROCESSES = "Endpoint_Processes"
-    #ENDPOINT_FILESYSTEM = "Endpoint_Filesystem"
-    #ENDPOINT_REGISTRY = "Endpoint_Registry"
+    # Should the following more specific DMs be added?
+    # Or should they just fall under endpoint?
+    # ENDPOINT_PROCESSES = "Endpoint_Processes"
+    # ENDPOINT_FILESYSTEM = "Endpoint_Filesystem"
+    # ENDPOINT_REGISTRY = "Endpoint_Registry"
     RISK = "Risk"
     SPLUNK_AUDIT = "Splunk_Audit"
 
@@ -44,6 +45,7 @@ class PlaybookType(StrEnum):
     INVESTIGATION = "Investigation"
     RESPONSE = "Response"
 
+
 class SecurityContentType(IntEnum):
     detections = 1
     baselines = 2
@@ -68,7 +70,6 @@ class SecurityContentType(IntEnum):
 #     json_objects = "json_objects"
 
 
-
 class SecurityContentProductName(StrEnum):
     SPLUNK_ENTERPRISE = "Splunk Enterprise"
     SPLUNK_ENTERPRISE_SECURITY = "Splunk Enterprise Security"
@@ -76,6 +77,7 @@ class SecurityContentProductName(StrEnum):
     SPLUNK_SECURITY_ANALYTICS_FOR_AWS = "Splunk Security Analytics for AWS"
     SPLUNK_BEHAVIORAL_ANALYTICS = "Splunk Behavioral Analytics"
 
+
 class SecurityContentInvestigationProductName(StrEnum):
     SPLUNK_ENTERPRISE = "Splunk Enterprise"
     SPLUNK_ENTERPRISE_SECURITY = "Splunk Enterprise Security"
@@ -83,7 +85,7 @@ class SecurityContentInvestigationProductName(StrEnum):
     SPLUNK_SECURITY_ANALYTICS_FOR_AWS = "Splunk Security Analytics for AWS"
     SPLUNK_BEHAVIORAL_ANALYTICS = "Splunk Behavioral Analytics"
     SPLUNK_PHANTOM = "Splunk Phantom"
-    
+
 
 class DetectionStatus(StrEnum):
     production = "production"
@@ -147,7 +149,7 @@ class DetectionTestingMode(StrEnum):
 #     "Actions on Objectives": 7
 # }
 class KillChainPhase(StrEnum):
-    UNKNOWN ="Unknown"
+    UNKNOWN = "Unknown"
     RECONNAISSANCE = "Reconnaissance"
     WEAPONIZATION = "Weaponization"
     DELIVERY = "Delivery"
@@ -197,6 +199,7 @@ class DataSource(StrEnum):
     WINDOWS_SECURITY_5145 = "Windows Security 5145"
     WINDOWS_SYSTEM_7045 = "Windows System 7045"
 
+
 class ProvidingTechnology(StrEnum):
     AMAZON_SECURITY_LAKE = "Amazon Security Lake"
     AMAZON_WEB_SERVICES_CLOUDTRAIL = "Amazon Web Services - Cloudtrail"
@@ -216,9 +219,9 @@ class ProvidingTechnology(StrEnum):
     SPLUNK_INTERNAL_LOGS = "Splunk Internal Logs"
     SYMANTEC_ENDPOINT_PROTECTION = "Symantec Endpoint Protection"
     ZEEK = "Zeek"
-    
+
     @staticmethod
-    def getProvidingTechFromSearch(search_string:str)->List[ProvidingTechnology]:
+    def getProvidingTechFromSearch(search_string: str) -> List[ProvidingTechnology]:
         """_summary_
 
         Args:
@@ -230,34 +233,45 @@ class ProvidingTechnology(StrEnum):
         Returns:
             List[ProvidingTechnology]: List of providing technologies (with no duplicates because
             it is derived from a set) calculated from the search string.
-        """        
-        matched_technologies:set[ProvidingTechnology] = set()
-        #As there are many different sources that use google logs, we define the set once
-        google_logs = set([ProvidingTechnology.GOOGLE_WORKSPACE, ProvidingTechnology.GOOGLE_CLOUD_PLATFORM])
+        """
+        matched_technologies: set[ProvidingTechnology] = set()
+        # As there are many different sources that use google logs, we define the set once
+        google_logs = set(
+            [
+                ProvidingTechnology.GOOGLE_WORKSPACE,
+                ProvidingTechnology.GOOGLE_CLOUD_PLATFORM,
+            ]
+        )
         providing_technologies_mapping = {
-            '`amazon_security_lake`': set([ProvidingTechnology.AMAZON_SECURITY_LAKE]),
-            'audit_searches': set([ProvidingTechnology.SPLUNK_INTERNAL_LOGS]),
-            '`azure_monitor_aad`': set([ProvidingTechnology.AZURE_AD, ProvidingTechnology.ENTRA_ID]),
-            '`cloudtrail`': set([ProvidingTechnology.AMAZON_WEB_SERVICES_CLOUDTRAIL]),
-            #Endpoint is NOT a Macro (and this is intentional since it is to capture Endpoint Datamodel usage)
-            'Endpoint': set([ProvidingTechnology.MICROSOFT_SYSMON, 
-                             ProvidingTechnology.MICROSOFT_WINDOWS,
-                             ProvidingTechnology.CARBON_BLACK_RESPONSE,
-                             ProvidingTechnology.CROWDSTRIKE_FALCON, 
-                             ProvidingTechnology.SYMANTEC_ENDPOINT_PROTECTION]),
-            '`google_': google_logs,
-            '`gsuite': google_logs,
-            '`gws_': google_logs,
-            '`kube': set([ProvidingTechnology.KUBERNETES]),
-            '`ms_defender`': set([ProvidingTechnology.MICROSOFT_DEFENDER]),
-            '`o365_': set([ProvidingTechnology.MICROSOFT_OFFICE_365]),
-            '`okta': set([ProvidingTechnology.OKTA]),
-            '`pingid`': set([ProvidingTechnology.PING_ID]),
-            '`powershell`': set(set([ProvidingTechnology.MICROSOFT_WINDOWS])),
-            '`splunkd_': set([ProvidingTechnology.SPLUNK_INTERNAL_LOGS]),
-            '`sysmon`': set([ProvidingTechnology.MICROSOFT_SYSMON]),
-            '`wineventlog_security`': set([ProvidingTechnology.MICROSOFT_WINDOWS]),
-            '`zeek_': set([ProvidingTechnology.ZEEK]),
+            "`amazon_security_lake`": set([ProvidingTechnology.AMAZON_SECURITY_LAKE]),
+            "audit_searches": set([ProvidingTechnology.SPLUNK_INTERNAL_LOGS]),
+            "`azure_monitor_aad`": set(
+                [ProvidingTechnology.AZURE_AD, ProvidingTechnology.ENTRA_ID]
+            ),
+            "`cloudtrail`": set([ProvidingTechnology.AMAZON_WEB_SERVICES_CLOUDTRAIL]),
+            # Endpoint is NOT a Macro (and this is intentional since it is to capture Endpoint Datamodel usage)
+            "Endpoint": set(
+                [
+                    ProvidingTechnology.MICROSOFT_SYSMON,
+                    ProvidingTechnology.MICROSOFT_WINDOWS,
+                    ProvidingTechnology.CARBON_BLACK_RESPONSE,
+                    ProvidingTechnology.CROWDSTRIKE_FALCON,
+                    ProvidingTechnology.SYMANTEC_ENDPOINT_PROTECTION,
+                ]
+            ),
+            "`google_": google_logs,
+            "`gsuite": google_logs,
+            "`gws_": google_logs,
+            "`kube": set([ProvidingTechnology.KUBERNETES]),
+            "`ms_defender`": set([ProvidingTechnology.MICROSOFT_DEFENDER]),
+            "`o365_": set([ProvidingTechnology.MICROSOFT_OFFICE_365]),
+            "`okta": set([ProvidingTechnology.OKTA]),
+            "`pingid`": set([ProvidingTechnology.PING_ID]),
+            "`powershell`": set(set([ProvidingTechnology.MICROSOFT_WINDOWS])),
+            "`splunkd_": set([ProvidingTechnology.SPLUNK_INTERNAL_LOGS]),
+            "`sysmon`": set([ProvidingTechnology.MICROSOFT_SYSMON]),
+            "`wineventlog_security`": set([ProvidingTechnology.MICROSOFT_WINDOWS]),
+            "`zeek_": set([ProvidingTechnology.ZEEK]),
         }
         for key in providing_technologies_mapping:
             if key in search_string:
@@ -286,6 +300,7 @@ class Cis18Value(StrEnum):
     CIS_17 = "CIS 17"
     CIS_18 = "CIS 18"
 
+
 class SecurityDomain(StrEnum):
     ENDPOINT = "endpoint"
     NETWORK = "network"
@@ -294,6 +309,7 @@ class SecurityDomain(StrEnum):
     ACCESS = "access"
     AUDIT = "audit"
 
+
 class AssetType(StrEnum):
     AWS_ACCOUNT = "AWS Account"
     AWS_EKS_KUBERNETES_CLUSTER = "AWS EKS Kubernetes cluster"
@@ -303,9 +319,9 @@ class AssetType(StrEnum):
     AMAZON_EKS_KUBERNETES_CLUSTER = "Amazon EKS Kubernetes cluster"
     AMAZON_EKS_KUBERNETES_CLUSTER_POD = "Amazon EKS Kubernetes cluster Pod"
     AMAZON_ELASTIC_CONTAINER_REGISTRY = "Amazon Elastic Container Registry"
-    #AZURE = "Azure"
-    #AZURE_AD = "Azure AD"
-    #AZURE_AD_TENANT = "Azure AD Tenant"
+    # AZURE = "Azure"
+    # AZURE_AD = "Azure AD"
+    # AZURE_AD_TENANT = "Azure AD Tenant"
     AZURE_TENANT = "Azure Tenant"
     AZURE_AKS_KUBERNETES_CLUSTER = "Azure AKS Kubernetes cluster"
     AZURE_ACTIVE_DIRECTORY = "Azure Active Directory"
@@ -332,8 +348,8 @@ class AssetType(StrEnum):
     INSTANCE = "Instance"
     KUBERNETES = "Kubernetes"
     NETWORK = "Network"
-    #OFFICE_365 = "Office 365"
-    #OFFICE_365_Tenant = "Office 365 Tenant"
+    # OFFICE_365 = "Office 365"
+    # OFFICE_365_Tenant = "Office 365 Tenant"
     O365_TENANT = "O365 Tenant"
     OKTA_TENANT = "Okta Tenant"
     PROXY = "Proxy"
@@ -345,6 +361,7 @@ class AssetType(StrEnum):
     WEB_APPLICATION = "Web Application"
     WINDOWS = "Windows"
 
+
 class NistCategory(StrEnum):
     ID_AM = "ID.AM"
     ID_BE = "ID.BE"
@@ -369,6 +386,7 @@ class NistCategory(StrEnum):
     RC_IM = "RC.IM"
     RC_CO = "RC.CO"
 
+
 class RiskSeverity(StrEnum):
     # Levels taken from the following documentation link
     # https://docs.splunk.com/Documentation/ES/7.3.2/User/RiskScoring

contentctl/objects/errors.py

@@ -4,21 +4,25 @@ from uuid import UUID
 
 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
 
 
@@ -26,6 +30,7 @@ class MetadataValidationError(Exception, ABC):
     """
     Base class for any errors arising from savedsearches.conf detection metadata validation
     """
+
     # The name of the rule the error relates to
     rule_name: str
 
@@ -52,11 +57,8 @@ class DetectionMissingError(MetadataValidationError):
     """
     An error indicating a detection in the prior build could not be found in the current build
     """
-    def __init__(
-            self,
-            rule_name: str,
-            *args: object
-    ) -> None:
+
+    def __init__(self, rule_name: str, *args: object) -> None:
         self.rule_name = rule_name
         super().__init__(self.long_message, *args)
 
@@ -77,15 +79,14 @@ class DetectionMissingError(MetadataValidationError):
         A short-form error message
         :returns: a str, the message
         """
-        return (
-            "Detection from previous build not found in current build."
-        )
+        return "Detection from previous build not found in current build."
 
 
 class DetectionIDError(MetadataValidationError):
     """
     An error indicating the detection ID may have changed between builds
     """
+
     # The ID from the current build
     current_id: UUID
 
@@ -93,11 +94,7 @@ class DetectionIDError(MetadataValidationError):
     previous_id: UUID
 
     def __init__(
-            self,
-            rule_name: str,
-            current_id: UUID,
-            previous_id: UUID,
-            *args: object
+        self, rule_name: str, current_id: UUID, previous_id: UUID, *args: object
     ) -> None:
         self.rule_name = rule_name
         self.current_id = current_id
@@ -122,15 +119,14 @@ class DetectionIDError(MetadataValidationError):
         A short-form error message
         :returns: a str, the message
         """
-        return (
-            f"Detection ID {self.current_id} in current build does not match ID {self.previous_id} in previous build."
-        )
+        return f"Detection ID {self.current_id} in current build does not match ID {self.previous_id} in previous build."
 
 
 class VersioningError(MetadataValidationError, ABC):
     """
     A base class for any metadata validation errors relating to detection versioning
     """
+
     # The version in the current build
     current_version: int
 
@@ -138,11 +134,7 @@ class VersioningError(MetadataValidationError, ABC):
     previous_version: int
 
     def __init__(
-            self,
-            rule_name: str,
-            current_version: int,
-            previous_version: int,
-            *args: object
+        self, rule_name: str, current_version: int, previous_version: int, *args: object
     ) -> None:
         self.rule_name = rule_name
         self.current_version = current_version
@@ -154,6 +146,7 @@ class VersionDecrementedError(VersioningError):
     """
     An error indicating the version number went down between builds
     """
+
     @property
     def long_message(self) -> str:
         """
@@ -182,6 +175,7 @@ class VersionBumpingError(VersioningError):
     """
     An error indicating the detection changed but its version wasn't bumped appropriately
     """
+
     @property
     def long_message(self) -> str:
         """
@@ -200,6 +194,4 @@ class VersionBumpingError(VersioningError):
         A short-form error message
         :returns: a str, the message
         """
-        return (
-            f"Detection version in current build should be bumped to at least {self.previous_version + 1}."
-        )
+        return f"Detection version in current build should be bumped to at least {self.previous_version + 1}."

contentctl/objects/integration_test.py

@@ -10,6 +10,7 @@ class IntegrationTest(BaseTest):
     """
     An integration test for a detection against ES
     """
+
     # The test type (integration)
     test_type: TestType = Field(default=TestType.INTEGRATION)
 
@@ -34,7 +35,6 @@ class IntegrationTest(BaseTest):
         Skip the test by setting its result status
         :param message: the reason for skipping
         """
-        self.result = IntegrationTestResult(                                                        # type: ignore
-            message=message,
-            status=TestResultStatus.SKIP
+        self.result = IntegrationTestResult(  # type: ignore
+            message=message, status=TestResultStatus.SKIP
         )

contentctl/objects/integration_test_result.py

@@ -5,5 +5,6 @@ class IntegrationTestResult(BaseTestResult):
     """
     An integration test result
     """
+
     # the total time we slept waiting for the detection to fire after activating it
     wait_duration: int | None = None

contentctl/objects/investigation.py

@@ -1,32 +1,37 @@
 from __future__ import annotations
+
 import re
-from typing import List, Any
-from pydantic import computed_field, Field, ConfigDict,model_serializer
-from contentctl.objects.security_content_object import SecurityContentObject
-from contentctl.objects.enums import DataModel
-from contentctl.objects.investigation_tags import InvestigationTags
+from typing import Any, List, Literal
+
+from pydantic import ConfigDict, Field, computed_field, model_serializer
+
+from contentctl.objects.config import CustomApp
 from contentctl.objects.constants import (
     CONTENTCTL_MAX_SEARCH_NAME_LENGTH,
+    CONTENTCTL_MAX_STANZA_LENGTH,
     CONTENTCTL_RESPONSE_TASK_NAME_FORMAT_TEMPLATE,
-    CONTENTCTL_MAX_STANZA_LENGTH
 )
-from contentctl.objects.config import CustomApp
+from contentctl.objects.enums import DataModel, DetectionStatus
+from contentctl.objects.investigation_tags import InvestigationTags
+from contentctl.objects.security_content_object import SecurityContentObject
+
 
 class Investigation(SecurityContentObject):
     model_config = ConfigDict(validate_default=False)
-    type: str = Field(...,pattern="^Investigation$")
-    name:str = Field(...,max_length=CONTENTCTL_MAX_SEARCH_NAME_LENGTH)
+    type: str = Field(..., pattern="^Investigation$")
+    name: str = Field(..., max_length=CONTENTCTL_MAX_SEARCH_NAME_LENGTH)
     search: str = Field(...)
     how_to_implement: str = Field(...)
     known_false_positives: str = Field(...)
     tags: InvestigationTags
+    status: Literal[DetectionStatus.production, DetectionStatus.deprecated]
 
     # enrichment
     @computed_field
     @property
-    def inputs(self)->List[str]:
-        #Parse out and return all inputs from the searchj
-        inputs:List[str] = []
+    def inputs(self) -> List[str]:
+        # Parse out and return all inputs from the searchj
+        inputs: List[str] = []
         pattern = r"\$([^\s.]*)\$"
 
         for input in re.findall(pattern, self.search):
@@ -41,27 +46,42 @@ class Investigation(SecurityContentObject):
 
     @computed_field
     @property
-    def lowercase_name(self)->str:
-        return self.name.replace(' ', '_').replace('-','_').replace('.','_').replace('/','_').lower().replace(' ', '_').replace('-','_').replace('.','_').replace('/','_').lower()
+    def lowercase_name(self) -> str:
+        return (
+            self.name.replace(" ", "_")
+            .replace("-", "_")
+            .replace(".", "_")
+            .replace("/", "_")
+            .lower()
+            .replace(" ", "_")
+            .replace("-", "_")
+            .replace(".", "_")
+            .replace("/", "_")
+            .lower()
+        )
 
-    
     # This is a slightly modified version of the get_conf_stanza_name function from
     # SecurityContentObject_Abstract
-    def get_response_task_name(self, app:CustomApp, max_stanza_length:int=CONTENTCTL_MAX_STANZA_LENGTH)->str:
-        stanza_name = CONTENTCTL_RESPONSE_TASK_NAME_FORMAT_TEMPLATE.format(app_label=app.label, detection_name=self.name)
+    def get_response_task_name(
+        self, app: CustomApp, max_stanza_length: int = CONTENTCTL_MAX_STANZA_LENGTH
+    ) -> str:
+        stanza_name = CONTENTCTL_RESPONSE_TASK_NAME_FORMAT_TEMPLATE.format(
+            app_label=app.label, detection_name=self.name
+        )
         if len(stanza_name) > max_stanza_length:
-            raise ValueError(f"conf stanza may only be {max_stanza_length} characters, "
-                             f"but stanza was actually {len(stanza_name)} characters: '{stanza_name}' ")
+            raise ValueError(
+                f"conf stanza may only be {max_stanza_length} characters, "
+                f"but stanza was actually {len(stanza_name)} characters: '{stanza_name}' "
+            )
         return stanza_name
-    
 
     @model_serializer
     def serialize_model(self):
-        #Call serializer for parent
+        # Call serializer for parent
         super_fields = super().serialize_model()
-        
-        #All fields custom to this model
-        model= {
+
+        # All fields custom to this model
+        model = {
             "type": self.type,
             "datamodel": self.datamodel,
             "search": self.search,
@@ -69,18 +89,20 @@ class Investigation(SecurityContentObject):
             "known_false_positives": self.known_false_positives,
             "inputs": self.inputs,
             "tags": self.tags.model_dump(),
-            "lowercase_name":self.lowercase_name
+            "lowercase_name": self.lowercase_name,
         }
-        
-        #Combine fields from this model with fields from parent
+
+        # Combine fields from this model with fields from parent
         super_fields.update(model)
-        
-        #return the model
-        return super_fields
 
+        # return the model
+        return super_fields
 
-    def model_post_init(self, ctx:dict[str,Any]):
+    def model_post_init(self, ctx: dict[str, Any]):
         # Ensure we link all stories this investigation references
         # back to itself
         for story in self.tags.analytic_story:
             story.investigations.append(self)
+        # back to itself
+        for story in self.tags.analytic_story:
+            story.investigations.append(self)

contentctl/objects/investigation_tags.py

@@ -1,33 +1,45 @@
 from __future__ import annotations
 from typing import List
-from pydantic import BaseModel, Field, field_validator, ValidationInfo, model_serializer,ConfigDict
+from pydantic import (
+    BaseModel,
+    Field,
+    field_validator,
+    ValidationInfo,
+    model_serializer,
+    ConfigDict,
+)
 from contentctl.objects.story import Story
-from contentctl.objects.enums import SecurityContentInvestigationProductName, SecurityDomain
+from contentctl.objects.enums import (
+    SecurityContentInvestigationProductName,
+    SecurityDomain,
+)
+
 
 class InvestigationTags(BaseModel):
     model_config = ConfigDict(extra="forbid")
-    analytic_story: List[Story] = Field([],min_length=1)
-    product: List[SecurityContentInvestigationProductName] = Field(...,min_length=1)
+    analytic_story: List[Story] = Field([], min_length=1)
+    product: List[SecurityContentInvestigationProductName] = Field(..., min_length=1)
     security_domain: SecurityDomain = Field(...)
 
-
-    @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 mapStoryNamesToStoryObjects(
+        cls, v: list[str], info: ValidationInfo
+    ) -> list[Story]:
+        return Story.mapNamesToSecurityContentObjects(
+            v, info.context.get("output_dto", None)
+        )
 
     @model_serializer
     def serialize_model(self):
-        #All fields custom to this model
-        model= {
+        # All fields custom to this model
+        model = {
             "analytic_story": [story.name for story in self.analytic_story],
             "product": self.product,
             "security_domain": self.security_domain,
         }
-        
-        #Combine fields from this model with fields from parent
-        
-        
-        #return the model
-        return model
+
+        # Combine fields from this model with fields from parent
+
+        # return the model
+        return model