contentctl 4.3.4__py3-none-any.whl → 4.4.0__py3-none-any.whl

contentctl/actions/inspect.py

@@ -1,78 +1,86 @@
 import sys
-
-
 from dataclasses import dataclass
-
 import pathlib
 import json
 import datetime
+import timeit
+import time
 
-
-from contentctl.objects.config import inspect
 from requests import Session, post, get
 from requests.auth import HTTPBasicAuth
-import timeit
-import time
+
+from contentctl.objects.config import inspect
+from contentctl.objects.savedsearches_conf import SavedsearchesConf
+from contentctl.objects.errors import (
+    MetadataValidationError,
+    DetectionIDError,
+    DetectionMissingError,
+    VersionDecrementedError,
+    VersionBumpingError
+)
+
+
 @dataclass(frozen=True)
 class InspectInputDto:
-    config:inspect
+    config: inspect
 
 
 class Inspect:
 
     def execute(self, config: inspect) -> str:
-        if config.build_app or config.build_api:    
-         
+        if config.build_app or config.build_api:
+
             self.inspectAppCLI(config)
             appinspect_token = self.inspectAppAPI(config)
-            
-            
+
+            if config.enable_metadata_validation:
+                self.check_detection_metadata(config)
+            else:
+                print("🟡 Detection metadata validation disabled, skipping.")
+
             return appinspect_token
 
         else:
-            raise Exception("Inspect only supported for app and api build targets")    
-    
-    def getElapsedTime(self, startTime:float)->datetime.timedelta:
-        return datetime.timedelta(seconds=round(timeit.default_timer() - startTime))
+            raise Exception("Inspect only supported for app and api build targets")
 
+    def getElapsedTime(self, startTime: float) -> datetime.timedelta:
+        return datetime.timedelta(seconds=round(timeit.default_timer() - startTime))
 
-    def inspectAppAPI(self, config: inspect)->str:
+    def inspectAppAPI(self, config: inspect) -> str:
         session = Session()
         session.auth = HTTPBasicAuth(config.splunk_api_username, config.splunk_api_password)
         if config.stack_type not in ['victoria', 'classic']:
             raise Exception(f"stack_type MUST be either 'classic' or 'victoria', NOT '{config.stack_type}'")
-        
+
         APPINSPECT_API_LOGIN = "https://api.splunk.com/2.0/rest/login/splunk"
-        
-            
-        
+
         res = session.get(APPINSPECT_API_LOGIN)
-        #If login failed or other failure, raise an exception
+        # If login failed or other failure, raise an exception
         res.raise_for_status()
-        
-        authorization_bearer = res.json().get("data",{}).get("token",None)
+
+        authorization_bearer = res.json().get("data", {}).get("token", None)
         APPINSPECT_API_VALIDATION_REQUEST = "https://appinspect.splunk.com/v1/app/validate"
         headers = {
             "Authorization": f"bearer {authorization_bearer}",
             "Cache-Control": "no-cache"
         }
-        
+
         package_path = config.getPackageFilePath(include_version=False)
         if not package_path.is_file():
             raise Exception(f"Cannot run Appinspect API on App '{config.app.title}' - "
                             f"no package exists as expected path '{package_path}'.\nAre you "
                             "trying to 'contentctl deploy_acs' the package BEFORE running 'contentctl build'?")
-        
+
         files = {
-            "app_package": open(package_path,"rb"),
-            "included_tags":(None,"cloud")
-        } 
-        
+            "app_package": open(package_path, "rb"),
+            "included_tags": (None, "cloud")
+        }
+
         res = post(APPINSPECT_API_VALIDATION_REQUEST, headers=headers, files=files)
 
         res.raise_for_status()
 
-        request_id = res.json().get("request_id",None)
+        request_id = res.json().get("request_id", None)
         APPINSPECT_API_VALIDATION_STATUS = f"https://appinspect.splunk.com/v1/app/validate/status/{request_id}?included_tags=private_{config.stack_type}"
         headers = headers = {
             "Authorization": f"bearer {authorization_bearer}"
@@ -83,10 +91,10 @@ class Inspect:
         # checking many times when we know it will take at least 40 seconds to run.
         iteration_wait_time = 40
         while True:
-            
+
             res = get(APPINSPECT_API_VALIDATION_STATUS, headers=headers)
             res.raise_for_status()
-            status = res.json().get("status",None)
+            status = res.json().get("status", None)
             if status in ["PROCESSING", "PREPARING"]:
                 print(f"[{self.getElapsedTime(startTime)}] Appinspect API is {status}...")
                 time.sleep(iteration_wait_time)
@@ -97,12 +105,10 @@ class Inspect:
                 break
             else:
                 raise Exception(f"Error - Unknown Appinspect API status '{status}'")
-        
-        
 
-        #We have finished running appinspect, so get the report
+        # We have finished running appinspect, so get the report
         APPINSPECT_API_REPORT = f"https://appinspect.splunk.com/v1/app/report/{request_id}?included_tags=private_{config.stack_type}"
-        #Get human-readable HTML report
+        # Get human-readable HTML report
         headers = headers = {
             "Authorization": f"bearer {authorization_bearer}",
             "Content-Type": "text/html"
@@ -110,8 +116,8 @@ class Inspect:
         res = get(APPINSPECT_API_REPORT, headers=headers)
         res.raise_for_status()
         report_html = res.content
-        
-        #Get JSON report for processing
+
+        # Get JSON report for processing
         headers = headers = {
             "Authorization": f"bearer {authorization_bearer}",
             "Content-Type": "application/json"
@@ -119,33 +125,31 @@ class Inspect:
         res = get(APPINSPECT_API_REPORT, headers=headers)
         res.raise_for_status()
         report_json = res.json()
-        
+
         # Just get app path here to avoid long function calls in the open() calls below
         appPath = config.getPackageFilePath(include_version=True)
         appinpect_html_path = appPath.with_suffix(appPath.suffix+".appinspect_api_results.html")
         appinspect_json_path = appPath.with_suffix(appPath.suffix+".appinspect_api_results.json")
-        #Use the full path of the app, but update the suffix to include info about appinspect
+        # Use the full path of the app, but update the suffix to include info about appinspect
         with open(appinpect_html_path, "wb") as report:
             report.write(report_html)
         with open(appinspect_json_path, "w") as report:
             json.dump(report_json, report)
-        
-        
+
         self.parseAppinspectJsonLogFile(appinspect_json_path)
-      
 
         return authorization_bearer
-    
-    
-    def inspectAppCLI(self, config:inspect)-> None:
-        
+
+    def inspectAppCLI(self, config: inspect) -> None:
         try:
-            raise Exception("Local spunk-appinspect Not Supported at this time (you may use the appinspect api). If you would like to locally inspect your app with"
-                  "Python 3.7, 3.8, or 3.9 (with limited support), please refer to:\n"
-                  "\t - https://dev.splunk.com/enterprise/docs/developapps/testvalidate/appinspect/useappinspectclitool/")
+            raise Exception(
+                "Local spunk-appinspect Not Supported at this time (you may use the appinspect api). If you would like to locally inspect your app with"
+                "Python 3.7, 3.8, or 3.9 (with limited support), please refer to:\n"
+                "\t - https://dev.splunk.com/enterprise/docs/developapps/testvalidate/appinspect/useappinspectclitool/"
+            )
             from splunk_appinspect.main import (
-                validate, MODE_OPTION, APP_PACKAGE_ARGUMENT, OUTPUT_FILE_OPTION, 
-                LOG_FILE_OPTION, INCLUDED_TAGS_OPTION, EXCLUDED_TAGS_OPTION, 
+                validate, MODE_OPTION, APP_PACKAGE_ARGUMENT, OUTPUT_FILE_OPTION,
+                LOG_FILE_OPTION, INCLUDED_TAGS_OPTION, EXCLUDED_TAGS_OPTION,
                 PRECERT_MODE, TEST_MODE)
         except Exception as e:
             print(e)
@@ -153,19 +157,19 @@ class Inspect:
             # if sys.version_info.major == 3 and sys.version_info.minor > 9:
             #     print("The package splunk-appinspect was not installed due to a current issue with the library on Python3.10+.  "
             #           "Please use the following commands to set up a virtualenvironment in a different folder so you may run appinspect manually (if desired):"
-            #           "\n\tpython3.9 -m venv .venv" 
+            #           "\n\tpython3.9 -m venv .venv"
             #           "\n\tsource .venv/bin/activate"
             #           "\n\tpython3 -m pip install splunk-appinspect"
-            #           f"\n\tsplunk-appinspect inspect {self.getPackagePath(include_version=False).relative_to(pathlib.Path('.').absolute())} --mode precert")    
-                
+            #           f"\n\tsplunk-appinspect inspect {self.getPackagePath(include_version=False).relative_to(pathlib.Path('.').absolute())} --mode precert")
+
             # else:
             #     print("splunk-appinspect is only compatable with Python3.9 at this time.  Please see the following open issue here: https://github.com/splunk/contentctl/issues/28")
             # print("******WARNING******")
             return
 
         # Note that all tags are available and described here:
-        # https://dev.splunk.com/enterprise/reference/appinspect/appinspecttagreference/ 
-        # By default, precert mode will run ALL checks.  Explicitly included or excluding tags will 
+        # https://dev.splunk.com/enterprise/reference/appinspect/appinspecttagreference/
+        # By default, precert mode will run ALL checks.  Explicitly included or excluding tags will
         # change this behavior. To give the most thorough inspection, we leave these empty so that
         # ALL checks are run
         included_tags = []
@@ -179,82 +183,178 @@ class Inspect:
             options_list += [MODE_OPTION, TEST_MODE]
             options_list += [OUTPUT_FILE_OPTION, str(appinspect_output)]
             options_list += [LOG_FILE_OPTION, str(appinspect_logging)]
-            
-            #If there are any tags defined, then include them here
+
+            # If there are any tags defined, then include them here
             for opt in included_tags:
                 options_list += [INCLUDED_TAGS_OPTION, opt]
             for opt in excluded_tags:
                 options_list += [EXCLUDED_TAGS_OPTION, opt]
 
-            cmdline = options_list + [arg[1] for arg in arguments_list]        
+            cmdline = options_list + [arg[1] for arg in arguments_list]
             validate(cmdline)
-    
+
         except SystemExit as e:
             if e.code == 0:
                 # The sys.exit called inside of appinspect validate closes stdin.  We need to
                 # reopen it.
-                sys.stdin = open("/dev/stdin","r")
+                sys.stdin = open("/dev/stdin", "r")
                 print(f"AppInspect passed! Please check [ {appinspect_output} , {appinspect_logging} ] for verbose information.")
             else:
                 if sys.version.startswith('3.11') or sys.version.startswith('3.12'):
-                    raise Exception("At this time, AppInspect may fail on valid apps under Python>=3.11 with " 
-                                    "the error 'global flags not at the start of the expression at position 1'. "  
+                    raise Exception("At this time, AppInspect may fail on valid apps under Python>=3.11 with "
+                                    "the error 'global flags not at the start of the expression at position 1'. "
                                     "If you encounter this error, please run AppInspect on a version of Python "
                                     "<3.11.  This issue is currently tracked. Please review the appinspect "
                                     "report output above for errors.")
-                else: 
-                    raise Exception("AppInspect Failure - Please review the appinspect report output above for errors.")        
+                else:
+                    raise Exception("AppInspect Failure - Please review the appinspect report output above for errors.")
         finally:
-                # appinspect outputs the log in json format, but does not format it to be easier
-                # to read (it is all in one line). Read back that file and write it so it
-                # is easier to understand
-                
-                #Note that this may raise an exception itself!
-                self.parseAppinspectJsonLogFile(appinspect_output)
-
-    def parseAppinspectJsonLogFile(self, logfile_path:pathlib.Path, 
-                                   status_types:list[str] = ["error", "failure", "manual_check", "warning"], 
-                                   exception_types = ["error","failure","manual_check"] )->None:
+            # appinspect outputs the log in json format, but does not format it to be easier
+            # to read (it is all in one line). Read back that file and write it so it
+            # is easier to understand
+
+            # Note that this may raise an exception itself!
+            self.parseAppinspectJsonLogFile(appinspect_output)
+
+    def parseAppinspectJsonLogFile(
+            self,
+            logfile_path: pathlib.Path,
+            status_types: list[str] = ["error", "failure", "manual_check", "warning"],
+            exception_types: list[str] = ["error", "failure", "manual_check"]
+    ) -> None:
         if not set(exception_types).issubset(set(status_types)):
-                raise Exception(f"Error - exception_types {exception_types} MUST be a subset of status_types {status_types}, but it is not")
+            raise Exception(f"Error - exception_types {exception_types} MUST be a subset of status_types {status_types}, but it is not")
         with open(logfile_path, "r+") as logfile:
             j = json.load(logfile)
-            #Seek back to the beginning of the file. We don't need to clear
-            #it sice we will always write AT LEAST the same number of characters
-            #back as we read (due to the addition of whitespace)
+            # Seek back to the beginning of the file. We don't need to clear
+            # it sice we will always write AT LEAST the same number of characters
+            # back as we read (due to the addition of whitespace)
             logfile.seek(0)
             json.dump(j, logfile, indent=3, )
-            
+
         reports = j.get("reports", [])
         if len(reports) != 1:
             raise Exception("Expected to find one appinspect report but found 0")
         verbose_errors = []
-        
+
         for group in reports[0].get("groups", []):
-            for check in group.get("checks",[]):
-                if check.get("result","") in status_types:                                    
+            for check in group.get("checks", []):
+                if check.get("result", "") in status_types:
                     verbose_errors.append(f" - {check.get('result','')} [{group.get('name','NONAME')}: {check.get('name', 'NONAME')}]")
         verbose_errors.sort()
-        
+
         summary = j.get("summary", None)
         if summary is None:
             raise Exception("Missing summary from appinspect report")
         msgs = []
         generated_exception = False
         for key in status_types:
-            if summary.get(key,0)>0:
+            if summary.get(key, 0) > 0:
                 msgs.append(f" - {summary.get(key,0)} {key}s")
                 if key in exception_types:
                     generated_exception = True
-        if len(msgs)>0 or len(verbose_errors):
+        if len(msgs) > 0 or len(verbose_errors):
             summary = '\n'.join(msgs)
             details = '\n'.join(verbose_errors)
             summary = f"{summary}\nDetails:\n{details}"
             if generated_exception:
-                raise Exception(f"AppInspect found [{','.join(exception_types)}] that MUST be addressed to pass AppInspect API:\n{summary}")        
+                raise Exception(f"AppInspect found [{','.join(exception_types)}] that MUST be addressed to pass AppInspect API:\n{summary}")
             else:
-                print(f"AppInspect found [{','.join(status_types)}] that MAY cause a failure during AppInspect API:\n{summary}")            
+                print(f"AppInspect found [{','.join(status_types)}] that MAY cause a failure during AppInspect API:\n{summary}")
         else:
             print("AppInspect was successful!")
-                
+
         return
+
+    def check_detection_metadata(self, config: inspect) -> None:
+        """
+        Using a previous build, compare the savedsearches.conf files to detect any issues w/
+        detection metadata. **NOTE**: Detection metadata validation can only be performed between
+        two builds with theappropriate metadata structure. In ESCU, this was added as of release
+        v4.39.0, so all current and previous builds for use with this feature must be this version
+        or greater.
+
+        :param config: an inspect config
+        :type config: :class:`contentctl.objects.config.inspect`
+        """
+        # TODO (#282): We should be inspect the same artifact we're passing around from the
+        #   build stage ideally
+        # Unpack the savedsearch.conf of each app package
+        current_build_conf = SavedsearchesConf.init_from_package(
+            package_path=config.getPackageFilePath(include_version=False),
+            app_name=config.app.label,
+            appid=config.app.appid
+        )
+        previous_build_conf = SavedsearchesConf.init_from_package(
+            package_path=config.get_previous_package_file_path(),
+            app_name=config.app.label,
+            appid=config.app.appid
+        )
+
+        # Compare the conf files
+        validation_errors: dict[str, list[MetadataValidationError]] = {}
+        for rule_name in previous_build_conf.detection_stanzas:
+            validation_errors[rule_name] = []
+            # No detections should be removed from build to build
+            if rule_name not in current_build_conf.detection_stanzas:
+                if config.suppress_missing_content_exceptions:
+                    print(f"[SUPPRESSED] {DetectionMissingError(rule_name=rule_name).long_message}")
+                else:
+                    validation_errors[rule_name].append(DetectionMissingError(rule_name=rule_name))
+                continue
+            # Pull out the individual stanza for readability
+            previous_stanza = previous_build_conf.detection_stanzas[rule_name]
+            current_stanza = current_build_conf.detection_stanzas[rule_name]
+
+            # Detection IDs should not change
+            if current_stanza.metadata.detection_id != previous_stanza.metadata.detection_id:
+                validation_errors[rule_name].append(
+                    DetectionIDError(
+                        rule_name=rule_name,
+                        current_id=current_stanza.metadata.detection_id,
+                        previous_id=previous_stanza.metadata.detection_id
+                    )
+                )
+
+            # Versions should never decrement in successive builds
+            if current_stanza.metadata.detection_version < previous_stanza.metadata.detection_version:
+                validation_errors[rule_name].append(
+                    VersionDecrementedError(
+                        rule_name=rule_name,
+                        current_version=current_stanza.metadata.detection_version,
+                        previous_version=previous_stanza.metadata.detection_version
+                    )
+                )
+
+            # Versions need to be bumped if the stanza changes at all
+            if current_stanza.version_should_be_bumped(previous_stanza):
+                validation_errors[rule_name].append(
+                    VersionBumpingError(
+                        rule_name=rule_name,
+                        current_version=current_stanza.metadata.detection_version,
+                        previous_version=previous_stanza.metadata.detection_version
+                    )
+                )
+
+        # Convert our dict mapping to a flat list of errors for use in reporting
+        validation_error_list = [x for inner_list in validation_errors.values() for x in inner_list]    
+
+        # Report failure/success
+        print("\nDetection Metadata Validation:")
+        if len(validation_error_list) > 0:
+            # Iterate over each rule and report the failures
+            for rule_name in validation_errors:
+                if len(validation_errors[rule_name]) > 0:
+                    print(f"\t❌ {rule_name}")
+                    for error in validation_errors[rule_name]:
+                        print(f"\t\t🔸 {error.short_message}")
+        else:
+            # If no errors in the list, report success
+            print("\t✅ Detection metadata looks good and all versions were bumped appropriately :)")
+
+        # Raise an ExceptionGroup for all validation issues
+        if len(validation_error_list) > 0:
+            raise ExceptionGroup(
+                "Validation errors when comparing detection stanzas in current and previous build:",
+                validation_error_list
+            )

contentctl/actions/new_content.py

@@ -16,7 +16,11 @@ class NewContent:
 
     def buildDetection(self)->dict[str,Any]:
         questions = NewContentQuestions.get_questions_detection()
-        answers = questionary.prompt(questions)
+        answers: dict[str,str] = questionary.prompt(
+            questions, 
+            kbi_msg="User did not answer all of the prompt questions. Exiting...")
+        if not answers:
+            raise ValueError("User didn't answer one or more questions!")
         answers.update(answers)
         answers['name'] = answers['detection_name']
         del answers['detection_name']
@@ -70,7 +74,11 @@ class NewContent:
 
     def buildStory(self)->dict[str,Any]:
         questions = NewContentQuestions.get_questions_story()
-        answers = questionary.prompt(questions)
+        answers = questionary.prompt(
+            questions, 
+            kbi_msg="User did not answer all of the prompt questions. Exiting...")
+        if not answers:
+            raise ValueError("User didn't answer one or more questions!")
         answers['name'] = answers['story_name']
         del answers['story_name']
         answers['id'] = str(uuid.uuid4())

contentctl/actions/validate.py

@@ -5,7 +5,7 @@ from contentctl.input.director import Director, DirectorOutputDto
 from contentctl.objects.config import validate
 from contentctl.enrichments.attack_enrichment import AttackEnrichment
 from contentctl.enrichments.cve_enrichment import CveEnrichment
-from contentctl.objects.atomic import AtomicTest
+from contentctl.objects.atomic import AtomicEnrichment
 from contentctl.helper.utils import Utils
 from contentctl.objects.data_source import DataSource
 from contentctl.helper.splunk_app import SplunkApp
@@ -13,12 +13,8 @@ from contentctl.helper.splunk_app import SplunkApp
 
 class Validate:
     def execute(self, input_dto: validate) -> DirectorOutputDto:
-
         director_output_dto = DirectorOutputDto(
-            AtomicTest.getAtomicTestsFromArtRepo(
-                repo_path=input_dto.getAtomicRedTeamRepoPath(),
-                enabled=input_dto.enrichments,
-            ),
+            AtomicEnrichment.getAtomicEnrichment(input_dto),
             AttackEnrichment.getAttackEnrichment(input_dto),
             CveEnrichment.getCveEnrichment(input_dto),
             [],
@@ -30,6 +26,7 @@ class Validate:
             [],
             [],
             [],
+            []
         )
 
         director = Director(director_output_dto)

contentctl/api.py

@@ -126,7 +126,7 @@ def update_config(config:Union[test,test_servers], **key_value_updates:dict[str,
 def content_to_dict(director:DirectorOutputDto)->dict[str,list[dict[str,Any]]]:
     output_dict:dict[str,list[dict[str,Any]]] = {}
     for contentType in ['detections','stories','baselines','investigations',
-                        'playbooks','macros','lookups','deployments','ssa_detections']:
+                        'playbooks','macros','lookups','deployments',]:
         
         output_dict[contentType] = []
         t:list[SecurityContentObject] = getattr(director,contentType)

contentctl/contentctl.py

@@ -211,6 +211,9 @@ def main():
             test_common_func(config)
         else:
             raise Exception(f"Unknown command line type '{type(config).__name__}'")
+    except FileNotFoundError as e:
+        print(e)
+        sys.exit(1)
     except Exception as e:
         if config is None:
             print("There was a serious issue where the config file could not be created.\n"