Adds private auxiliary module configuration option (#2345)

This adds a new `configure_from_data` method to analyzer.windows.lib.common.abstracts.Auxiliary.

This optional method provides the ability to run private auxiliary-specific configuration code from `data.packages.<module_name>`.

If an auxiliary module doesn't provide a `configure_from_data` method, it's logged but ignored.

Author: josh-feather

analyzer/windows/analyzer.py

@@ -509,6 +509,21 @@ def run(self):
             except ImportError as e:
                 log.warning('Unable to import the auxiliary module "%s": %s', name, e)
 
+        def configure_aux_from_data(instance):
+        # Do auxiliary module configuration stored in 'data/auxiliary/<package_name>'
+            _class = type(instance)
+            try:
+                log.debug("attempting to configure '%s' from data", _class.__name__)
+                instance.configure_from_data()
+            except ModuleNotFoundError:
+                # let it go, not every module is configurable from data
+                log.debug("module %s does not support data configuration, ignoring", _class.__name__)
+            except ImportError as iexc:
+                # let it go but emit a warning; assume a dependency is missing
+                log.warning("configuration error for module %s: %s", _class.__name__, iexc)
+            except Exception as exc:
+                log.error("error configuring module %s: %s", _class.__name__, exc)
+
         # Walk through the available auxiliary modules.
         aux_modules = []
 
@@ -517,6 +532,7 @@ def run(self):
                 aux = module(self.options, self.config)
                 log.debug('Initialized auxiliary module "%s"', module.__name__)
                 aux_modules.append(aux)
+                configure_aux_from_data(aux)
                 log.debug('Trying to start auxiliary module "%s"...', module.__module__)
                 aux.start()
             except (NotImplementedError, AttributeError) as e:

analyzer/windows/lib/common/abstracts.py

@@ -322,3 +322,29 @@ def add_pid(self, pid):
 
     def del_pid(self, pid):
         pass
+
+    def configure_from_data(self):
+        """Do private auxiliary module-specific configuration.
+
+        Auxiliary modules can implement this method to perform pre-analysis
+        configuration based on runtime data contained in "data/auxiliary/<package_name>".
+
+        This method raises:
+         - ImportError when any exception occurs during import
+         - AttributeError if the module configure function is invalid
+         - ModuleNotFoundError if the module does not support configuration from data
+        """
+        package_module_name = self.__class__.__module__.split(".")[-1]
+        module_name = f"data.auxiliary.{package_module_name}"
+        try:
+            mod = importlib.import_module(module_name)
+        except ModuleNotFoundError as exc:
+            raise exc
+        except Exception as exc:
+            raise ImportError(f"error importing {module_name}: {exc}") from exc
+
+        spec = inspect.getfullargspec(mod.configure)
+        if len(spec.args) != 1:
+            err_msg = f"{module_name}.configure: expected 1 arguments, got {len(spec.args)}"
+            raise AttributeError(err_msg)
+        mod.configure(self)

docs/book/src/customization/auxiliary.rst

@@ -27,3 +27,52 @@ very end of the analysis process, before launching the processing and reporting
 
 For example, an auxiliary module provided by default in CAPE is called *sniffer.py* and
 takes care of executing **tcpdump** in order to dump the generated network traffic.
+
+Auxiliary Module Configuration
+==============================
+
+Auxiliary modules can be "configured" before being started. This allows data to be added
+at runtime, whilst also allowing for the configuration to be stored separately from the
+CAPE python code.
+
+Private Auxiliary Module Configuration
+--------------------------------------
+
+Private auxiliary module configuration is stored outside the auxiliary class, in a module
+under the same name as the auxiliary module. This is useful when managing configuration
+of auxiliary modules separately if desired, for privacy reasons or otherwise.
+
+Here is a configuration module example that installs some software prior to the auxiliary
+module starting:
+
+    .. code-block:: python
+        :linenos:
+
+        # data/auxiliary/example.py
+        import subprocess
+        import logging
+        from pathlib import Path
+
+        log = logging.getLogger(__name__)
+        BIN_PATH = Path.cwd() / "bin"
+
+
+        def configure(aux_instance):
+            # here "example" refers to modules.auxiliary.example.Example
+            if not aux_instance.enabled:
+                return
+            msi = aux_instance.options.get("example_msi")
+            if not msi:
+                return
+            msi_path = BIN_PATH / msi
+            if not msi_path.exists():
+                log.warning("missing MSI %s", msi_path)
+                return
+            cmd = ["msiexec", "/i", msi_path, "/quiet"]
+            try:
+                log.info("Executing msi package...")
+                subprocess.check_output(cmd)
+                log.info("Installation succesful")
+            except subprocess.CalledProcessError as exc:
+                log.error("Installation failed: %s", exc)
+                return