splunk-soar-sdk 1.4.1__py3-none-any.whl → 1.5.0__py3-none-any.whl

soar_sdk/abstract.py

@@ -34,10 +34,7 @@ class SOARClientAuth:
 
 
 class SOARClient(Generic[SummaryType]):
-    """A unified API interface for performing actions on SOAR Platform.
-
-    Replaces previously used BaseConnector API interface.
-    """
+    """An API interface for interacting with the Splunk SOAR Platform."""
 
     @property
     @abstractmethod

soar_sdk/actions_manager.py

@@ -71,7 +71,7 @@ class ActionsManager(BaseConnector):
             )  # TODO: replace with a valid lack of action handling
 
     def handle_action(self, param: dict[str, Any]) -> None:
-        """The central action execution function BaseConnector expects to be overriden.
+        """The central action execution function BaseConnector expects to be overridden.
 
         Given the input parameter dictionary from Splunk SOAR, find the Action function
         referred to by the input, parse the parameters into the appropriate Pydantic model,

soar_sdk/app.py

@@ -1,5 +1,7 @@
+import importlib.util
 import inspect
 import json
+from pathlib import Path
 import sys
 from typing import Any, Optional, Union, Callable
 from collections.abc import Iterator
@@ -226,7 +228,7 @@ class App:
     def register_action(
         self,
         /,
-        action: Callable,
+        action: Union[str, Callable],
         *,
         name: Optional[str] = None,
         identifier: Optional[str] = None,
@@ -236,7 +238,7 @@ class App:
         read_only: bool = True,
         params_class: Optional[type[Params]] = None,
         output_class: Optional[type[ActionOutput]] = None,
-        view_handler: Optional[Callable] = None,
+        view_handler: Union[str, Callable, None] = None,
         view_template: Optional[str] = None,
         versions: str = "EQ(*)",
         summary_type: Optional[type[ActionOutput]] = None,
@@ -248,8 +250,30 @@ class App:
         actions without using decorators directly on the action function.
 
         Args:
-            action: Function import for the action. Must be a callable function that
-                follows SOAR action function conventions and is imported from another module.
+            action: Either an import string to find the function that implements an action, or the imported function itself.
+
+                .. warning::
+                    If you import the function directly, and provide the callable to this function, this sometimes messes with the app's CLI invocation. For example, if you import your function with a relative import, like::
+
+                        from .actions.my_action import my_action_function
+
+                    then executing your app directly, like::
+
+                        python src/app.py action my_action_function
+
+                    will fail, but running as a module, like::
+
+                        python -m src.app action my_action_function
+
+                    will work. By contrast, if you use an absolute import, like::
+
+                        from actions.my_action import my_action_function
+
+                    then the `direct CLI invocation` will work, while the `module invocation` will fail. This is a limitation with Python itself.
+
+                    To avoid this confusion, it is recommended to provide the action as an import string, like ``"actions.my_action:my_action_function"``. This way, both invocation methods will work consistently.
+
+
             name: Human-readable name for the action. If not provided, defaults
                 to the function name with underscores replaced by spaces.
             identifier: Unique identifier for the action. If not provided, defaults
@@ -265,12 +289,19 @@ class App:
                 If not provided, uses generic parameter validation.
             output_class: Pydantic model class for structuring action output.
                 If not provided, uses generic output format.
-            view_handler: Optional raw view handler function to associate with this action.
+            view_handler: Optional import string to a view handler function,
+                or the imported function itself, to associate with this action.
                 Will be automatically decorated with the view_handler decorator.
+
+                .. warning::
+
+                    See the warning above about importing action functions as opposed to using import strings. The same issues apply to view handler functions as well.
+
             view_template: Template name to use with the view handler. Only
                 relevant if view_handler is provided.
             versions: Version constraint string for when this action is available.
                 Defaults to "EQ(*)" (all versions).
+            summary_type: Pydantic model class for structuring action summary output.
 
         Returns:
             The registered Action instance with all metadata and handlers configured.
@@ -280,17 +311,20 @@ class App:
                 found in its original module for replacement.
 
         Example:
-            >>> from my_actions_module import my_action_function
-            >>> from my_views_module import my_view_handler
-            >>>
             >>> action = app.register_action(
-            ...     my_action_function,
+            ...     "action.my_action:my_action_function",
             ...     name="Dynamic Action",
             ...     description="Action imported from another module",
-            ...     view_handler=my_view_handler,
+            ...     view_handler="my_views_module:my_view_handler",
             ...     view_template="custom_template.html",
             ... )
         """
+        if isinstance(action, str):
+            action = self._resolve_function_import(action)
+
+        if isinstance(view_handler, str):
+            view_handler = self._resolve_function_import(view_handler)
+
         if view_handler:
             decorated_view_handler = self.view_handler(template=view_template)(
                 view_handler
@@ -298,8 +332,6 @@ class App:
 
             # Replace the function in its original module with the decorated version
             if hasattr(view_handler, "__module__") and view_handler.__module__:
-                import sys
-
                 if (
                     original_module := sys.modules.get(view_handler.__module__)
                 ) and hasattr(original_module, view_handler.__name__):
@@ -327,6 +359,55 @@ class App:
             summary_type=summary_type,
         )(action)
 
+    def _resolve_function_import(self, action_path: str) -> Callable:
+        """Resolves a callable action function from a dot-separated import string.
+
+        This method takes a string representing the full import path of a function,
+        imports the necessary module, and retrieves the function object.
+
+        Args:
+            action_path: Dot-separated string representing the import path of the function.
+                Example: "my_module.my_submodule:my_function"
+
+        Returns:
+            The callable function object.
+
+        Raises:
+            ValueError: If the action_path is not properly formatted or if the
+                module/function cannot be imported.
+        """
+        # Split the action_path into module and function parts,
+        # handling both dot notation and file paths
+        module_root = Path(inspect.stack()[2].filename).parent
+        func_delim = ":" if ":" in action_path else "."
+        module_name, action_func_name = action_path.rsplit(func_delim, 1)
+        module_name = module_name.removesuffix(".py").replace(".", "/") + ".py"
+        module_path = module_root / module_name
+
+        module_name = (
+            # Jump up from module -> src -> package root
+            module_path.relative_to(module_root.parent.parent)
+            # Remove .py suffix, convert to dot notation
+            .with_suffix("")
+            .as_posix()
+            .replace("/", ".")
+        )
+        spec = importlib.util.spec_from_file_location(module_name, module_path)
+        # Not sure how to actually make spec None,
+        # but the type hint says it's technically possible
+        if spec is None or spec.loader is None:  # pragma: no cover
+            raise ActionRegistrationError(action_func_name)
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        try:
+            spec.loader.exec_module(module)
+            action_func = getattr(module, action_func_name)
+        except Exception as e:
+            raise ActionRegistrationError(action_func_name) from e
+
+        return action_func
+
     def action(
         self,
         *,
@@ -415,7 +496,9 @@ class App:
         The decorated function receives parsed ActionOutput objects and can return either a dict for template rendering, HTML string, or component data model.
         If a template is provided, dict results will be rendered using the template. Component type is automatically inferred from the return type annotation.
 
-        For more information on custom views, see the following :doc:`custom views documentation </custom_views/index>`:
+        .. seealso::
+
+            For more information on custom views, see the following :doc:`custom views documentation </custom_views/index>`:
 
         Example:
             >>> @app.view_handler(template="my_template.html")

soar_sdk/cli/manifests/processors.py

@@ -7,7 +7,7 @@ from pprint import pprint
 
 from soar_sdk.app import App
 from soar_sdk.cli.path_utils import context_directory
-from soar_sdk.compat import remove_when_soar_newer_than
+from soar_sdk.compat import remove_when_soar_newer_than, UPDATE_TIME_FORMAT
 from soar_sdk.meta.adapters import TOMLDataAdapter
 from soar_sdk.meta.app import AppMeta
 from soar_sdk.meta.dependencies import UvLock
@@ -31,7 +31,7 @@ class ManifestProcessor:
         app_meta.configuration = app.asset_cls.to_json_schema()
         app_meta.actions = app.actions_manager.get_actions_meta_list()
         app_meta.utctime_updated = datetime.now(timezone.utc).strftime(
-            "%Y-%m-%dT%H:%M:%S.%fZ"
+            UPDATE_TIME_FORMAT
         )
         for field, value in app.app_meta_info.items():
             setattr(app_meta, field, value)

soar_sdk/compat.py

@@ -4,6 +4,8 @@ from packaging.version import Version
 
 MIN_PHANTOM_VERSION = "6.4.0"
 
+UPDATE_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ"
+
 
 @functools.lru_cache(maxsize=32)
 def remove_when_soar_newer_than(

soar_sdk/meta/app.py

@@ -20,7 +20,7 @@ class AppMeta(BaseModel):
 
     name: str = ""
     description: str
-    appid: str = "1e1618e7-2f70-4fc0-916a-f96facc2d2e4"  # placeholder value to pass inital validation
+    appid: str = "1e1618e7-2f70-4fc0-916a-f96facc2d2e4"  # placeholder value to pass initial validation
     type: str = ""
     product_vendor: str = ""
     app_version: str

soar_sdk/params.py

@@ -88,7 +88,7 @@ class Params(BaseModel):
     """Params defines the full set of inputs for an action.
 
     It can contain strings, booleans, or numbers -- no lists or dictionaries.
-    Params fields can be optional if desired, or optionally have a default value, CEF type, and other metadata defined in soar_sdk.params.Param.
+    Params fields can be optional if desired, or optionally have a default value, CEF type, and other metadata defined in :func:`soar_sdk.params.Param`.
     """
 
     @staticmethod

{splunk_soar_sdk-1.4.1.dist-info → splunk_soar_sdk-1.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunk-soar-sdk
-Version: 1.4.1
+Version: 1.5.0
 Summary: The official framework for developing and testing Splunk SOAR Apps
 Project-URL: Homepage, https://github.com/phantomcyber/splunk-soar-sdk
 Project-URL: Documentation, https://github.com/phantomcyber/splunk-soar-sdk

{splunk_soar_sdk-1.4.1.dist-info → splunk_soar_sdk-1.5.0.dist-info}/RECORD

@@ -1,19 +1,19 @@
 soar_sdk/__init__.py,sha256=RzAng-ARqpK01SY82lNy4uYJFVG0yW6Q3CccEqbToJ4,726
-soar_sdk/abstract.py,sha256=2fYEc_xdhz635RnUn5Fn7odTuNkzqQ_YjKF25A-KjNM,7863
+soar_sdk/abstract.py,sha256=ExsLCY99aoPRFHsUfw7yIVdWJeZjq1ahQCVwQmZyYh8,7798
 soar_sdk/action_results.py,sha256=gAQwHjXbkkzOJTmQnLwBjKjwbuz8mSPyqIVcirVS598,10114
-soar_sdk/actions_manager.py,sha256=vYglKejmPX1MldTzafCVE2K60UiSLhNGfYcVOxD4YwU,5884
-soar_sdk/app.py,sha256=lCCOLKfpUxE9WgLYn_S83riHe4vL2Kzcgda2ra4xNs4,29207
+soar_sdk/actions_manager.py,sha256=U8OZmNCjuwtLKlC19BsVIvDyeJDS_ZiTyZIHA4SS1go,5885
+soar_sdk/app.py,sha256=9zI8RM6uo4V0Bj4cgCvJzSOjIBPrvt2meXVAMaPhVrE,32882
 soar_sdk/app_cli_runner.py,sha256=uk9V-cbAHx1tzK_1gCYpfdF7IJ_ZwuWV2Ak4NMOvKGA,11873
 soar_sdk/app_client.py,sha256=UVCMFYweaYcFk7WrtoVsCoprYZ7JlzMBR108ZQRV8SE,6051
 soar_sdk/asset.py,sha256=deS8_B5hr7W2fED8_6wUpVriRgiQ5r8TkGVHiasIaro,10666
 soar_sdk/async_utils.py,sha256=gND8ZiVTqDYLQ88Ua6SN1mInJaEcfa168eOaRoURt3E,1441
 soar_sdk/colors.py,sha256=--i_iXqfyITUz4O95HMjfZQGbwFZ34bLmBhtfpXXqlQ,1095
-soar_sdk/compat.py,sha256=jW3l9vJ7jLUicZ9SvfFrL4l3H84DQHUYSBy0-51VE3s,2620
+soar_sdk/compat.py,sha256=H7At6OSsZQMtlarjyWNcPfsa4_8FC5k0JLdGrmU-O1M,2666
 soar_sdk/crypto.py,sha256=qiBMHUQqgn5lPI1DbujSj700s89FuLJrkQgCO9_eBn4,392
 soar_sdk/exceptions.py,sha256=CxJ_Q6N1jlknO_3ItDQNhHEw2pNWZr3sMLqutYmr5HA,1863
 soar_sdk/input_spec.py,sha256=BAa36l8IKDvM8SVMjgZ1XcnWZ2F7O052n2415tLeKK8,4690
 soar_sdk/logging.py,sha256=lSz8PA6hOCw2MHGE0ZSKbw-FzSr1WdbfQ7BHnXBUUY0,11440
-soar_sdk/params.py,sha256=K16_umW_dAfvqa2QcHR2XHc93py-k7SVOHdz3GUGFGk,7615
+soar_sdk/params.py,sha256=JKhlyBlYDdgUpQv1G6QEnJiY5G1XkiQ364_iNmyjxks,7623
 soar_sdk/paths.py,sha256=XhpanQCAiTXaulRx440oKu36mnll7P05TethHXgMpgQ,239
 soar_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soar_sdk/types.py,sha256=uMFnNOHpmCLrbAhQOgmXjScXiGE67sM8ySN04MhkC3U,602
@@ -37,7 +37,7 @@ soar_sdk/cli/init/cli.py,sha256=bVp8t28FYCS_wP2FhLWqmIvCkFbqmO1-7Dw8PpTFNq0,1449
 soar_sdk/cli/manifests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soar_sdk/cli/manifests/cli.py,sha256=cly5xVdj4bBIdZVMQPIWTXRgUfd1ON3qKO-76Fwql18,524
 soar_sdk/cli/manifests/deserializers.py,sha256=FtXv-OywYGb_O5TptS2Hg6niWcfihRPF_RaS5zDBXRk,17045
-soar_sdk/cli/manifests/processors.py,sha256=anR_7TledkYvPWtcMakzO4JWO1iNWlj6lQBx7cD5hmE,4140
+soar_sdk/cli/manifests/processors.py,sha256=6B1fQC2WGVaUP-7E9Y5g7BipaVwEomJCkUQ_7gRfSn8,4155
 soar_sdk/cli/manifests/serializers.py,sha256=HA7a3DSzB3P-v2yomAMZW0M1__wY2yCNLU_v0QZv7Vo,3245
 soar_sdk/cli/package/cli.py,sha256=oCpP9E3PtXq-zCdzQD8Z-4dowKF1YT-uKjTpbt_YT-A,9516
 soar_sdk/cli/package/utils.py,sha256=JmVf_PwoXiuypE1DZ1-k4sFjZszD0c_BYTiLtwy9jDk,1448
@@ -58,7 +58,7 @@ soar_sdk/decorators/webhook.py,sha256=Pde0MjxC2kckpxoKb3m4WVfLWtiFAAzAwZe5AF5VIb
 soar_sdk/meta/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soar_sdk/meta/actions.py,sha256=-Py_AbQ9BOr3P-J9OrKTTdKAQvNZ5g6xvgYLCjJktlg,2215
 soar_sdk/meta/adapters.py,sha256=KjSYIUtkCz2eesA_vhsNCjfi5C-Uz71tbSuDIjhuB8U,1112
-soar_sdk/meta/app.py,sha256=cmbfACoFiBNvZ3IWT_f3C-Yz8hyZgqa1KURCYQV5N6k,1764
+soar_sdk/meta/app.py,sha256=rwgoFfIFnLutLB9PF1kR7X1neKs175VA0Xx4KpJ6c7I,1765
 soar_sdk/meta/datatypes.py,sha256=piR-oBVAATiRciXSdVE7XaqjUZTgSaOvTEqcOcNvCS0,795
 soar_sdk/meta/dependencies.py,sha256=AQlkdm6A7JEfLI0IAXKU6WzPkUX7oPfxgDkGZ3AofHk,17927
 soar_sdk/meta/webhooks.py,sha256=1sh4-3I3_UiXFNzVEyoz2Tp6NhgTEZWpERYIzV8OYNY,1188
@@ -96,8 +96,8 @@ soar_sdk/views/components/pie_chart.py,sha256=LVTeHVJN6nf2vjUs9y7PDBhS0U1fKW750l
 soar_sdk/webhooks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soar_sdk/webhooks/models.py,sha256=-rjuFA9cRX5zTLp7cHSHVTkt5eVJD6BdESGbj_qkyHI,4540
 soar_sdk/webhooks/routing.py,sha256=BKbURSrBPdOTS5UFL-mHzFEr-Fj04mJMx9KeiPrZ2VQ,6872
-splunk_soar_sdk-1.4.1.dist-info/METADATA,sha256=mAYVSNDk067JSRxMrKll00jaNgNZWH5tF5syV5fZxoQ,7355
-splunk_soar_sdk-1.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-splunk_soar_sdk-1.4.1.dist-info/entry_points.txt,sha256=CgBjo2ZWpYNkt9TgvToL26h2Tg1yt8FbvYTb5NVgNuc,51
-splunk_soar_sdk-1.4.1.dist-info/licenses/LICENSE,sha256=gNCGrGhrSQb1PUzBOByVUN1tvaliwLZfna-QU2r2hQ8,11345
-splunk_soar_sdk-1.4.1.dist-info/RECORD,,
+splunk_soar_sdk-1.5.0.dist-info/METADATA,sha256=l89BBxU2lNASu9LoIr9GU9iEBItjPj3Z-RY1zhN3kX0,7355
+splunk_soar_sdk-1.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+splunk_soar_sdk-1.5.0.dist-info/entry_points.txt,sha256=CgBjo2ZWpYNkt9TgvToL26h2Tg1yt8FbvYTb5NVgNuc,51
+splunk_soar_sdk-1.5.0.dist-info/licenses/LICENSE,sha256=gNCGrGhrSQb1PUzBOByVUN1tvaliwLZfna-QU2r2hQ8,11345
+splunk_soar_sdk-1.5.0.dist-info/RECORD,,