contentctl 4.4.7__py3-none-any.whl → 5.0.0__py3-none-any.whl

contentctl/objects/manual_test.py

@@ -12,6 +12,7 @@ class ManualTest(BaseTest):
     """
     A manual test for a detection
     """
+
     # The test type (manual)
     test_type: TestType = Field(default=TestType.MANUAL)
 
@@ -26,7 +27,6 @@ class ManualTest(BaseTest):
         Skip the test by setting its result status
         :param message: the reason for skipping
         """
-        self.result = ManualTestResult(                                                             # type: ignore
-            message=message,
-            status=TestResultStatus.SKIP
+        self.result = ManualTestResult(  # type: ignore
+            message=message, status=TestResultStatus.SKIP
         )

contentctl/objects/manual_test_result.py

@@ -5,4 +5,5 @@ class ManualTestResult(BaseTestResult):
     """
     A manual test result
     """
+
     pass

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
 
-# TODO (#266): disable the use_enum_values configuration
+
 class MitreAttackEnrichment(BaseModel):
-    ConfigDict(use_enum_values=True)
+    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
+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,16 +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] = []
+
     detection_objects: list[Detection] = []
-    

contentctl/objects/rba.py

@@ -0,0 +1,96 @@
+from enum import Enum
+from pydantic import BaseModel, computed_field, Field
+from abc import ABC
+from typing import Set, Annotated
+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"
+    CERTIFICATE_SERIAL = "certificate_serial"
+    CERTIFICATE_UNIT = "certificate_unit"
+    COMMAND = "command"
+    DOMAIN = "domain"
+    EMAIL_ADDRESS = "email_address"
+    EMAIL_SUBJECT = "email_subject"
+    FILE_HASH = "file_hash"
+    FILE_NAME = "file_name"
+    FILE_PATH = "file_path"
+    HTTP_USER_AGENT = "http_user_agent"
+    IP_ADDRESS = "ip_address"
+    PROCESS = "process"
+    PROCESS_NAME = "process_name"
+    PARENT_PROCESS = "parent_process"
+    PARENT_PROCESS_NAME = "parent_process_name"
+    PROCESS_HASH = "process_hash"
+    REGISTRY_PATH = "registry_path"
+    REGISTRY_VALUE_NAME = "registry_value_name"
+    REGISTRY_VALUE_TEXT = "registry_value_text"
+    SERVICE = "service"
+    SIGNATURE = "signature"
+    SYSTEM = "system"
+    TLS_HASH = "tls_hash"
+    URL = "url"
+
+
+class RiskObject(BaseModel):
+    field: str
+    type: RiskObjectType
+    score: RiskScoreValue_Type
+
+    def __hash__(self):
+        return hash((self.field, self.type, self.score))
+
+
+class ThreatObject(BaseModel):
+    field: str
+    type: ThreatObjectType
+
+    def __hash__(self):
+        return hash((self.field, 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:
+        # 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."
+            )
+        return max([risk_object.score for risk_object in self.risk_objects])
+
+    @computed_field
+    @property
+    def severity(self) -> RiskSeverity:
+        if 0 <= self.risk_score <= 20:
+            return RiskSeverity.INFORMATIONAL
+        elif 20 < self.risk_score <= 40:
+            return RiskSeverity.LOW
+        elif 40 < self.risk_score <= 60:
+            return RiskSeverity.MEDIUM
+        elif 60 < self.risk_score <= 80:
+            return RiskSeverity.HIGH
+        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}"
+            )

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"]
         )