contentctl 4.2.5__py3-none-any.whl → 4.3.1__py3-none-any.whl

contentctl/actions/build.py

@@ -8,7 +8,6 @@ from contentctl.objects.enums import SecurityContentProduct, SecurityContentType
 from contentctl.input.director import Director, DirectorOutputDto
 from contentctl.output.conf_output import ConfOutput
 from contentctl.output.conf_writer import ConfWriter
-from contentctl.output.ba_yml_output import BAYmlOutput
 from contentctl.output.api_json_output import ApiJsonOutput
 from contentctl.output.data_source_writer import DataSourceWriter
 from contentctl.objects.lookup import Lookup
@@ -86,17 +85,4 @@ class Build:
             
             print(f"Build of '{input_dto.config.app.title}' API successful to {input_dto.config.getAPIPath()}")
 
-        if input_dto.config.build_ssa:
-            
-            srs_path = input_dto.config.getSSAPath() / 'srs'
-            complex_path = input_dto.config.getSSAPath() / 'complex'
-            shutil.rmtree(srs_path, ignore_errors=True)
-            shutil.rmtree(complex_path, ignore_errors=True)
-            srs_path.mkdir(parents=True)
-            complex_path.mkdir(parents=True)
-            ba_yml_output = BAYmlOutput()
-            ba_yml_output.writeObjects(input_dto.director_output_dto.ssa_detections, str(input_dto.config.getSSAPath()))
-
-            print(f"Build of 'SSA' successful to {input_dto.config.getSSAPath()}")
-                
         return input_dto.director_output_dto

contentctl/actions/detection_testing/infrastructures/DetectionTestingInfrastructure.py

@@ -1060,7 +1060,9 @@ class DetectionTestingInfrastructure(BaseModel, abc.ABC):
             results = JSONResultsReader(job.results(output_mode="json"))
 
             # Consolidate a set of the distinct observable field names
-            observable_fields_set = set([o.name for o in detection.tags.observable])
+            observable_fields_set = set([o.name for o in detection.tags.observable]) # keeping this around for later
+            risk_object_fields_set = set([o.name for o in detection.tags.observable if "Victim" in o.role ]) # just the "Risk Objects"
+            threat_object_fields_set = set([o.name for o in detection.tags.observable if "Attacker" in o.role]) # just the "threat objects"
 
             # Ensure the search had at least one result
             if int(job.content.get("resultCount", "0")) > 0:
@@ -1068,7 +1070,10 @@ class DetectionTestingInfrastructure(BaseModel, abc.ABC):
                 test.result = UnitTestResult()
 
                 # Initialize the collection of fields that are empty that shouldn't be
+                present_threat_objects: set[str] = set()
                 empty_fields: set[str] = set()
+                
+                
 
                 # Filter out any messages in the results
                 for result in results:
@@ -1077,30 +1082,50 @@ class DetectionTestingInfrastructure(BaseModel, abc.ABC):
 
                     # If not a message, it is a dict and we will process it
                     results_fields_set = set(result.keys())
+                    # Guard against first events (relevant later)
 
-                    # Identify any observable fields that are not available in the results
-                    missing_fields = observable_fields_set - results_fields_set
-                    if len(missing_fields) > 0:
+                    # Identify any risk object fields that are not available in the results
+                    missing_risk_objects = risk_object_fields_set - results_fields_set
+                    if len(missing_risk_objects) > 0:
                         # Report a failure in such cases
-                        e = Exception(f"The observable field(s) {missing_fields} are missing in the detection results")
+                        e = Exception(f"The observable field(s) {missing_risk_objects} are missing in the detection results")
                         test.result.set_job_content(
                             job.content,
                             self.infrastructure,
-                            TestResultStatus.ERROR,
+                            TestResultStatus.FAIL,
                             exception=e,
                             duration=time.time() - search_start_time,
                         )
 
-                        return
+                        return                    
 
-                    # If we find one or more fields that contain the string "null" then they were
+                    # If we find one or more risk object fields that contain the string "null" then they were
                     # not populated and we should throw an error.  This can happen if there is a typo
                     # on a field.  In this case, the field will appear but will not contain any values
-                    current_empty_fields = set()
+                    current_empty_fields: set[str] = set()
+                    
                     for field in observable_fields_set:
                         if result.get(field, 'null') == 'null':
-                            current_empty_fields.add(field)
-
+                            if field in risk_object_fields_set:
+                                e = Exception(f"The risk object field {field} is missing in at least one result.")
+                                test.result.set_job_content(
+                                    job.content,
+                                    self.infrastructure,
+                                    TestResultStatus.FAIL,
+                                    exception=e,
+                                    duration=time.time() - search_start_time,
+                                )
+                                return
+                            else:
+                                if field in threat_object_fields_set:
+                                    current_empty_fields.add(field)
+                        else:
+                            if field in threat_object_fields_set:
+                                present_threat_objects.add(field)
+                                continue
+                                
+
+                    
                     # If everything succeeded up until now, and no empty fields are found in the
                     # current result, then the search was a success
                     if len(current_empty_fields) == 0:
@@ -1114,21 +1139,32 @@ class DetectionTestingInfrastructure(BaseModel, abc.ABC):
 
                     else:
                         empty_fields = empty_fields.union(current_empty_fields)
-
-                # Report a failure if there were empty fields in all results
-                e = Exception(
-                    f"One or more required observable fields {empty_fields} contained 'null' values.  Is the "
-                    "data being parsed correctly or is there an error in the naming of a field?"
+                        
+                        
+                missing_threat_objects = threat_object_fields_set - present_threat_objects
+                # Report a failure if there were empty fields in a threat object in all results
+                if len(missing_threat_objects) > 0:
+                    e = Exception(
+                        f"One or more required threat object fields {missing_threat_objects} contained 'null' values in all events. "
+                        "Is the data being parsed correctly or is there an error in the naming of a field?"
                     )
-                test.result.set_job_content(
-                    job.content,
-                    self.infrastructure,
-                    TestResultStatus.ERROR,
-                    exception=e,
-                    duration=time.time() - search_start_time,
-                )
+                    test.result.set_job_content(
+                        job.content,
+                        self.infrastructure,
+                        TestResultStatus.FAIL,
+                        exception=e,
+                        duration=time.time() - search_start_time,
+                    )
+                    return
+                
 
-                return
+                test.result.set_job_content(
+                            job.content,
+                            self.infrastructure,
+                            TestResultStatus.PASS,
+                            duration=time.time() - search_start_time,
+                        )
+                return               
 
             else:
                 # Report a failure if there were no results at all

contentctl/actions/validate.py

@@ -30,7 +30,6 @@ class Validate:
             [],
             [],
             [],
-            [],
         )
 
         director = Director(director_output_dto)

contentctl/input/director.py

@@ -28,13 +28,11 @@ from contentctl.enrichments.attack_enrichment import AttackEnrichment
 from contentctl.enrichments.cve_enrichment import CveEnrichment
 
 from contentctl.objects.config import validate
-from contentctl.input.ssa_detection_builder import SSADetectionBuilder
 from contentctl.objects.enums import SecurityContentType
 
 from contentctl.objects.enums import DetectionStatus
 from contentctl.helper.utils import Utils
 
-from contentctl.input.ssa_detection_builder import SSADetectionBuilder
 from contentctl.objects.enums import SecurityContentType
 
 from contentctl.objects.enums import DetectionStatus 
@@ -56,7 +54,6 @@ class DirectorOutputDto:
     macros: list[Macro]
     lookups: list[Lookup]
     deployments: list[Deployment]
-    ssa_detections: list[SSADetection]
     data_sources: list[DataSource]
     name_to_content_map: dict[str, SecurityContentObject] = field(default_factory=dict)
     uuid_to_content_map: dict[UUID, SecurityContentObject] = field(default_factory=dict)
@@ -98,8 +95,6 @@ class DirectorOutputDto:
             self.stories.append(content)
         elif isinstance(content, Detection):
             self.detections.append(content)
-        elif isinstance(content, SSADetection):
-            self.ssa_detections.append(content)
         elif isinstance(content, DataSource):
             self.data_sources.append(content)
         else:
@@ -112,11 +107,9 @@ class DirectorOutputDto:
 class Director():
     input_dto: validate
     output_dto: DirectorOutputDto
-    ssa_detection_builder: SSADetectionBuilder
 
     def __init__(self, output_dto: DirectorOutputDto) -> None:
         self.output_dto = output_dto
-        self.ssa_detection_builder = SSADetectionBuilder()
 
     def execute(self, input_dto: validate) -> None:
         self.input_dto = input_dto
@@ -129,7 +122,6 @@ class Director():
         self.createSecurityContent(SecurityContentType.data_sources)
         self.createSecurityContent(SecurityContentType.playbooks)
         self.createSecurityContent(SecurityContentType.detections)
-        self.createSecurityContent(SecurityContentType.ssa_detections)
 
         
         from contentctl.objects.abstract_security_content_objects.detection_abstract import MISSING_SOURCES
@@ -142,12 +134,7 @@ class Director():
             print("No missing data_sources!")
 
     def createSecurityContent(self, contentType: SecurityContentType) -> None:
-        if contentType == SecurityContentType.ssa_detections:
-            files = Utils.get_all_yml_files_from_directory(
-                os.path.join(self.input_dto.path, "ssa_detections")
-            )
-            security_content_files = [f for f in files if f.name.startswith("ssa___")]
-        elif contentType in [
+        if contentType in [
             SecurityContentType.deployments,
             SecurityContentType.lookups,
             SecurityContentType.macros,
@@ -179,43 +166,37 @@ class Director():
                 modelDict = YmlReader.load_file(file)
 
                 if contentType == SecurityContentType.lookups:
-                    lookup = Lookup.model_validate(modelDict,context={"output_dto":self.output_dto, "config":self.input_dto})
+                    lookup = Lookup.model_validate(modelDict, context={"output_dto":self.output_dto, "config":self.input_dto})
                     self.output_dto.addContentToDictMappings(lookup)
                 
                 elif contentType == SecurityContentType.macros:
-                    macro = Macro.model_validate(modelDict,context={"output_dto":self.output_dto})
+                    macro = Macro.model_validate(modelDict, context={"output_dto":self.output_dto})
                     self.output_dto.addContentToDictMappings(macro)
                 
                 elif contentType == SecurityContentType.deployments:
-                    deployment = Deployment.model_validate(modelDict,context={"output_dto":self.output_dto})
+                    deployment = Deployment.model_validate(modelDict, context={"output_dto":self.output_dto})
                     self.output_dto.addContentToDictMappings(deployment)
 
                 elif contentType == SecurityContentType.playbooks:
-                    playbook = Playbook.model_validate(modelDict,context={"output_dto":self.output_dto})
+                    playbook = Playbook.model_validate(modelDict, context={"output_dto":self.output_dto})
                     self.output_dto.addContentToDictMappings(playbook)                  
                 
                 elif contentType == SecurityContentType.baselines:
-                    baseline = Baseline.model_validate(modelDict,context={"output_dto":self.output_dto})
+                    baseline = Baseline.model_validate(modelDict, context={"output_dto":self.output_dto})
                     self.output_dto.addContentToDictMappings(baseline)
                 
                 elif contentType == SecurityContentType.investigations:
-                    investigation = Investigation.model_validate(modelDict,context={"output_dto":self.output_dto})
+                    investigation = Investigation.model_validate(modelDict, context={"output_dto":self.output_dto})
                     self.output_dto.addContentToDictMappings(investigation)
 
                 elif contentType == SecurityContentType.stories:
-                    story = Story.model_validate(modelDict,context={"output_dto":self.output_dto})
+                    story = Story.model_validate(modelDict, context={"output_dto":self.output_dto})
                     self.output_dto.addContentToDictMappings(story)
             
                 elif contentType == SecurityContentType.detections:
-                    detection = Detection.model_validate(modelDict,context={"output_dto":self.output_dto, "app":self.input_dto.app})
+                    detection = Detection.model_validate(modelDict, context={"output_dto":self.output_dto, "app":self.input_dto.app})
                     self.output_dto.addContentToDictMappings(detection)
 
-                elif contentType == SecurityContentType.ssa_detections:
-                    self.constructSSADetection(self.ssa_detection_builder, self.output_dto,str(file))
-                    ssa_detection = self.ssa_detection_builder.getObject()
-                    if ssa_detection.status in [DetectionStatus.production.value, DetectionStatus.validation.value]:
-                        self.output_dto.addContentToDictMappings(ssa_detection)
-                
                 elif contentType == SecurityContentType.data_sources:
                     data_source = DataSource.model_validate(
                         modelDict, context={"output_dto": self.output_dto}
@@ -262,19 +243,3 @@ class Director():
                 f"The following {len(validation_errors)} error(s) were found during validation:\n\n{errors_string}\n\nVALIDATION FAILED"
             )
 
-    def constructSSADetection(
-        self,
-        builder: SSADetectionBuilder,
-        directorOutput: DirectorOutputDto,
-        file_path: str,
-    ) -> None:
-        builder.reset()
-        builder.setObject(file_path)
-        builder.addMitreAttackEnrichmentNew(directorOutput.attack_enrichment)
-        builder.addKillChainPhase()
-        builder.addCIS()
-        builder.addNist()
-        builder.addAnnotations()
-        builder.addMappings()
-        builder.addUnitTest()
-        builder.addRBA()

contentctl/objects/abstract_security_content_objects/detection_abstract.py

@@ -46,7 +46,7 @@ class Detection_Abstract(SecurityContentObject):
     status: DetectionStatus = Field(...)
     data_source: list[str] = []
     tags: DetectionTags = Field(...)
-    search: Union[str, dict[str, Any]] = Field(...)
+    search: str = Field(...)
     how_to_implement: str = Field(..., min_length=4)
     known_false_positives: str = Field(..., min_length=4)
 
@@ -65,11 +65,7 @@ class Detection_Abstract(SecurityContentObject):
 
     @field_validator("search", mode="before")
     @classmethod
-    def validate_presence_of_filter_macro(
-        cls,
-        value: Union[str, dict[str, Any]],
-        info: ValidationInfo
-    ) -> Union[str, dict[str, Any]]:
+    def validate_presence_of_filter_macro(cls, value:str, info:ValidationInfo)->str:
         """
         Validates that, if required to be present, the filter macro is present with the proper name.
         The filter macro MUST be derived from the name of the detection
@@ -83,12 +79,9 @@ class Detection_Abstract(SecurityContentObject):
 
         Returns:
             Union[str, dict[str,Any]]: The search, either in sigma or SPL format.
-        """
-
-        if isinstance(value, dict):
-            # If the search is a dict, then it is in Sigma format so return it
-            return value
-
+        """        
+        
+        
         # Otherwise, the search is SPL.
 
         # In the future, we will may add support that makes the inclusion of the
@@ -155,15 +148,16 @@ class Detection_Abstract(SecurityContentObject):
     @computed_field
     @property
     def datamodel(self) -> List[DataModel]:
-        if isinstance(self.search, str):
-            return [dm for dm in DataModel if dm.value in self.search]
-        else:
-            return []
+        return [dm for dm in DataModel if dm.value in self.search]
+        
+            
+    
 
     @computed_field
     @property
     def source(self) -> str:
         return self.file_path.absolute().parent.name
+        
 
     deployment: Deployment = Field({})
 
@@ -249,12 +243,9 @@ class Detection_Abstract(SecurityContentObject):
     @computed_field
     @property
     def providing_technologies(self) -> List[ProvidingTechnology]:
-        if isinstance(self.search, str):
-            return ProvidingTechnology.getProvidingTechFromSearch(self.search)
-        else:
-            # Dict-formatted searches (sigma) will not have providing technologies
-            return []
-
+        return ProvidingTechnology.getProvidingTechFromSearch(self.search)
+        
+    
     @computed_field
     @property
     def risk(self) -> list[dict[str, Any]]:
@@ -299,6 +290,11 @@ class Detection_Abstract(SecurityContentObject):
                 risk_object['threat_object_field'] = entity.name
                 risk_object['threat_object_type'] = "url"
                 risk_objects.append(risk_object)
+            
+            elif 'Attacker' in entity.role:
+                risk_object['threat_object_field'] = entity.name
+                risk_object['threat_object_type'] = entity.type.lower()
+                risk_objects.append(risk_object)
 
             else:
                 risk_object['risk_object_type'] = 'other'
@@ -445,18 +441,13 @@ class Detection_Abstract(SecurityContentObject):
 
     @field_validator('lookups', mode="before")
     @classmethod
-    def getDetectionLookups(cls, v: list[str], info: ValidationInfo) -> list[Lookup]:
-        if info.context is None:
-            raise ValueError("ValidationInfo.context unexpectedly null")
-
-        director: DirectorOutputDto = info.context.get("output_dto", None)
-
-        search: Union[str, dict[str, Any], None] = info.data.get("search", None)
-        if not isinstance(search, str):
-            # The search was sigma formatted (or failed other validation and was None), so we will
-            # not validate macros in it
-            return []
-
+    def getDetectionLookups(cls, v:list[str], info:ValidationInfo) -> list[Lookup]:
+        director:DirectorOutputDto = info.context.get("output_dto",None)
+        
+        search:Union[str,None] = info.data.get("search",None)
+        if search is None:
+            raise ValueError("Search was None - is this file missing the search field?")
+        
         lookups = Lookup.get_lookups(search, director)
         return lookups
 
@@ -496,11 +487,9 @@ class Detection_Abstract(SecurityContentObject):
 
         director: DirectorOutputDto = info.context.get("output_dto", None)
 
-        search: str | dict[str, Any] | None = info.data.get("search", None)
-        if not isinstance(search, str):
-            # The search was sigma formatted (or failed other validation and was None), so we will
-            # not validate macros in it
-            return []
+        search: str | None = info.data.get("search", None)
+        if search is None:
+            raise ValueError("Search was None - is this file missing the search field?")
 
         search_name: Union[str, Any] = info.data.get("name", None)
         message = f"Expected 'search_name' to be a string, instead it was [{type(search_name)}]"
@@ -614,45 +603,43 @@ class Detection_Abstract(SecurityContentObject):
 
     @model_validator(mode="after")
     def search_observables_exist_validate(self):
-        if isinstance(self.search, str):
+        observable_fields = [ob.name.lower() for ob in self.tags.observable]
 
-            observable_fields = [ob.name.lower() for ob in self.tags.observable]
+        # All $field$ fields from the message must appear in the search
+        field_match_regex = r"\$([^\s.]*)\$"
 
-            # All $field$ fields from the message must appear in the search
-            field_match_regex = r"\$([^\s.]*)\$"
-
-            missing_fields: set[str]
-            if self.tags.message:
-                matches = re.findall(field_match_regex, self.tags.message.lower())
-                message_fields = [match.replace("$", "").lower() for match in matches]
-                missing_fields = set([field for field in observable_fields if field not in self.search.lower()])
-            else:
-                message_fields = []
-                missing_fields = set()
-
-            error_messages: list[str] = []
-            if len(missing_fields) > 0:
-                error_messages.append(
-                    "The following fields are declared as observables, but do not exist in the "
-                    f"search: {missing_fields}"
-                )
+        missing_fields: set[str]
+        if self.tags.message:
+            matches = re.findall(field_match_regex, self.tags.message.lower())
+            message_fields = [match.replace("$", "").lower() for match in matches]
+            missing_fields = set([field for field in observable_fields if field not in self.search.lower()])
+        else:
+            message_fields = []
+            missing_fields = set()
+
+        error_messages: list[str] = []
+        if len(missing_fields) > 0:
+            error_messages.append(
+                "The following fields are declared as observables, but do not exist in the "
+                f"search: {missing_fields}"
+            )
 
-            missing_fields = set([field for field in message_fields if field not in self.search.lower()])
-            if len(missing_fields) > 0:
-                error_messages.append(
-                    "The following fields are used as fields in the message, but do not exist in "
-                    f"the search: {missing_fields}"
-                )
+        missing_fields = set([field for field in message_fields if field not in self.search.lower()])
+        if len(missing_fields) > 0:
+            error_messages.append(
+                "The following fields are used as fields in the message, but do not exist in "
+                f"the search: {missing_fields}"
+            )
 
-            # NOTE: we ignore the type error around self.status because we are using Pydantic's
-            # use_enum_values configuration
-            # https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.populate_by_name
-            if len(error_messages) > 0 and self.status == DetectionStatus.production.value:         # type: ignore
-                msg = (
-                    "Use of fields in observables/messages that do not appear in search:\n\t- "
-                    "\n\t- ".join(error_messages)
-                )
-                raise ValueError(msg)
+        # NOTE: we ignore the type error around self.status because we are using Pydantic's
+        # use_enum_values configuration
+        # https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.populate_by_name
+        if len(error_messages) > 0 and self.status == DetectionStatus.production.value:         # type: ignore
+            msg = (
+                "Use of fields in observables/messages that do not appear in search:\n\t- "
+                "\n\t- ".join(error_messages)
+            )
+            raise ValueError(msg)
 
         # Found everything
         return self

contentctl/objects/config.py

@@ -175,7 +175,6 @@ class validate(Config_Base):
                                                          "be avoided for performance reasons.")
     build_app: bool = Field(default=True, description="Should an app be built and output in the build_path?")
     build_api: bool = Field(default=False, description="Should api objects be built and output in the build_path?")
-    build_ssa: bool = Field(default=False, description="Should ssa objects be built and output in the build_path?")
     data_source_TA_validation: bool = Field(default=False, description="Validate latest TA information from Splunkbase")
 
     def getAtomicRedTeamRepoPath(self, atomic_red_team_repo_name:str = "atomic-red-team"):
@@ -577,7 +576,6 @@ class test_common(build):
         # output to dist. We have already built it!
         self.build_app = False
         self.build_api = False
-        self.build_ssa = False
         self.enrichments = False
         
         self.enable_integration_testing = True

contentctl/objects/constants.py

@@ -132,3 +132,8 @@ SES_ATTACK_TACTICS_ID_MAPPING = {
     "Exfiltration": "TA0010",
     "Impact": "TA0040"
 }
+
+RBA_OBSERVABLE_ROLE_MAPPING = {
+    "Attacker": 0,
+    "Victim": 1
+}

contentctl/objects/observable.py

@@ -1,5 +1,5 @@
 from pydantic import BaseModel, field_validator
-from contentctl.objects.constants import SES_OBSERVABLE_TYPE_MAPPING, SES_OBSERVABLE_ROLE_MAPPING
+from contentctl.objects.constants import SES_OBSERVABLE_TYPE_MAPPING, RBA_OBSERVABLE_ROLE_MAPPING
 
 
 class Observable(BaseModel):
@@ -26,10 +26,12 @@ class Observable(BaseModel):
     def check_roles(cls, v: list[str]):
         if len(v) == 0:
             raise ValueError("Error, at least 1 role must be listed for Observable.")
+        if len(v) > 1:
+            raise ValueError("Error, each Observable can only have one role.")
         for role in v:
-            if role not in SES_OBSERVABLE_ROLE_MAPPING.keys():
+            if role not in RBA_OBSERVABLE_ROLE_MAPPING.keys():
                 raise ValueError(
                     f"Invalid role '{role}' provided for observable.  Valid observable types are "
-                    f"{SES_OBSERVABLE_ROLE_MAPPING.keys()}"
+                    f"{RBA_OBSERVABLE_ROLE_MAPPING.keys()}"
                 )
         return v

contentctl/templates/detections/endpoint/anomalous_usage_of_7zip.yml

@@ -53,11 +53,11 @@ tags:
   - name: parent_process_name
     type: Process
     role:
-    - Parent Process
+    - Attacker
   - name: process_name
     type: Process
     role:
-    - Child Process
+    - Attacker
   product:
   - Splunk Enterprise
   - Splunk Enterprise Security

{contentctl-4.2.5.dist-info → contentctl-4.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: contentctl
-Version: 4.2.5
+Version: 4.3.1
 Summary: Splunk Content Control Tool
 License: Apache 2.0
 Author: STRT
@@ -19,12 +19,10 @@ Requires-Dist: gitpython (>=3.1.43,<4.0.0)
 Requires-Dist: pycvesearch (>=1.2,<2.0)
 Requires-Dist: pydantic (>=2.7.1,<3.0.0)
 Requires-Dist: pygit2 (>=1.14.1,<2.0.0)
-Requires-Dist: pysigma (>=0.11.5,<0.12.0)
-Requires-Dist: pysigma-backend-splunk (>=1.1.0,<2.0.0)
 Requires-Dist: questionary (>=2.0.1,<3.0.0)
 Requires-Dist: requests (>=2.32.2,<2.33.0)
 Requires-Dist: semantic-version (>=2.10.0,<3.0.0)
-Requires-Dist: setuptools (>=69.5.1,<73.0.0)
+Requires-Dist: setuptools (>=69.5.1,<74.0.0)
 Requires-Dist: splunk-sdk (>=2.0.1,<3.0.0)
 Requires-Dist: tqdm (>=4.66.4,<5.0.0)
 Requires-Dist: tyro (>=0.8.3,<0.9.0)
@@ -36,8 +34,20 @@ Description-Content-Type: text/markdown
 <p align="center">
 <img src="docs/contentctl_logo_white.png" title="In case you're wondering, it's a capybara" alt="contentctl logo" width="250" height="250"></p>
 
-
-
+# contentctl Quick Start Guide
+If you are already familiar with contentctl, the following common commands may be very useful for basic operations
+
+| Operation | Command |
+|-----------|---------|
+| Create a repository | `contentctl init` |
+| Validate Your Content | `contentctl validate` |
+| Validate Your Content, performing MITRE Enrichments | `contentctl validate –-enrichments`|
+| Build Your App | `contentctl build` |
+| Test All the content in your app, pausing so that you can debug a search if it fails | `contentctl test –-post-test-behavior pause_on_failure mode:all` |
+| Test All the content in your app, pausing after every detection to allow debugging | `contentctl test –-post-test-behavior always_pause mode:all` |
+| Test 1 or more specified detections. If you are testing more than one detection, the paths are space-separated. You may also use shell-expanded regexes | `contentctl test –-post-test-behavior always_pause mode:selected --mode.files detections/endpoint/7zip_commandline_to_smb_share_path.yml detections/cloud/aws_multi_factor_authentication_disabled.yml detections/application/okta*` |
+| Diff your current branch with a target_branch and test detections that have been updated. Your current branch **must be DIFFERENT** than the target_branch | `contentctl test –-post-test-behavior always_pause mode:changes –-mode.target_branch develop` |
+| Perform Integration Testing of all content. Note that Enterprise Security MUST be listed as an app in your contentctl.yml folder, otherwise all tests will subsequently fail | `contentctl test –-enable-integration-testing --post-test-behavior never_pause mode:all` |
 
 # Introduction
 #### Security Is Hard