splunk-soar-sdk 1.3.3__tar.gz → 1.4.0__tar.gz

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/.github/workflows/generate_docs.yml

@@ -32,6 +32,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           ref: ${{ inputs.ref || github.ref }}
+          fetch-depth: 0
       - name: Install uv
         uses: astral-sh/setup-uv@v5
         with:

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/.pre-commit-config.yaml

@@ -26,7 +26,6 @@ repos:
     rev: 6.3.0
     hooks:
       - id: pydocstyle
-        name: pydocstyle (warning only)
         args:
           - --convention=google
           - --add-ignore=D100,D104,D105,D107
@@ -34,8 +33,6 @@ repos:
         exclude: ^(src/soar_sdk/shims/)
         additional_dependencies: [tomli]
         verbose: true
-        # Override the command to make it non-blocking
-        entry: bash -c 'pydocstyle "$@" || true' --
 
   - repo: local
     hooks:

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunk-soar-sdk
-Version: 1.3.3
+Version: 1.4.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.3.3 → splunk_soar_sdk-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "splunk-soar-sdk"
-version = "1.3.3"
+version = "1.4.0"
 description = "The official framework for developing and testing Splunk SOAR Apps"
 readme = "README.md"
 requires-python = ">=3.9, <3.14"

splunk_soar_sdk-1.4.0/release_notes.txt

@@ -0,0 +1,21 @@
+# [1.4.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/1.3.4...1.4.0) (2025-09-10)
+
+
+### Features
+
+* function to get container id on soar client ([2329956](https://github.com/phantomcyber/splunk-soar-sdk/commit/232995679cc5c568fc9ebd895c96aaf8f3f6448e))
+
+
+
+
+
+# [1.4.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/1.3.4...1.4.0) (2025-09-10)
+
+
+### Features
+
+* function to get container id on soar client ([2329956](https://github.com/phantomcyber/splunk-soar-sdk/commit/232995679cc5c568fc9ebd895c96aaf8f3f6448e))
+
+
+
+

splunk_soar_sdk-1.4.0/release_version.txt

@@ -0,0 +1 @@
+1.4.0

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/abstract.py

@@ -63,6 +63,11 @@ class SOARClient(Generic[SummaryType]):
         """Object governing interaction with the SOAR container API. Subclasses must define."""
         pass
 
+    @abstractmethod
+    def get_executing_container_id(self) -> int:
+        """Return the current Container ID passed in the Connector Run Action JSON."""
+        pass
+
     def get(
         self,
         endpoint: str,
@@ -202,7 +207,9 @@ class SOARClient(Generic[SummaryType]):
         return "https://localhost:9999/"
 
     @abstractmethod
-    def update_client(self, soar_auth: SOARClientAuth, asset_id: str) -> None:
+    def update_client(
+        self, soar_auth: SOARClientAuth, asset_id: str, container_id: int = 0
+    ) -> None:
         """Hook to update the SOAR API client before any actions run with the input data.
 
         An example of what this function might do is authenticate the API client.

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/action_results.py

@@ -151,9 +151,7 @@ class ActionOutput(BaseModel):
     """
 
     def generate_action_summary_message(self) -> str:
-        """.. deprecated:: 1.3.0
-
-        Generate a summary message for the action output.
+        """Generate a summary message for the action output.
 
         This method provides a human-readable summary of the action results,
         which appears when running the action in a SOAR playbook or container.
@@ -161,6 +159,7 @@ class ActionOutput(BaseModel):
         Returns:
             A string summarizing the action output.
 
+        .. deprecated:: 1.3.0
         """
         return "Action completed successfully."
 

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/actions_manager.py

@@ -97,8 +97,12 @@ class ActionsManager(BaseConnector):
             raise RuntimeError(f"Action {action_id} not found.")
 
     def initialize(self) -> bool:
-        # Load the state in initialize, use it to store data
-        # that needs to be accessed across actions
+        """Load asset state into memory at initialization, splitting it into 3 categories.
+
+        Asset state is used to store data that needs to be accessed across actions.
+        Chiefly, it is used to store ingestion state, authentication state, and/or
+        used as an asset cache. Returns True only to conform with the BaseConnector interface.
+        """
         state = self.load_state() or {}
         self.ingestion_state = state.get(_INGEST_STATE_KEY, {})
         self.auth_state = state.get(_AUTH_STATE_KEY, {})
@@ -107,6 +111,12 @@ class ActionsManager(BaseConnector):
         return True
 
     def finalize(self) -> bool:
+        """Save asset state from memory into persistent storage at finalization.
+
+        Joins the SDK's 3 categories of asset state into a single dictionary, conforming
+        to the platform's expectations, and saves it.
+        Returns True only to conform with the BaseConnector interface.
+        """
         state = {
             _INGEST_STATE_KEY: self.ingestion_state,
             _AUTH_STATE_KEY: self.auth_state,
@@ -116,12 +126,15 @@ class ActionsManager(BaseConnector):
         return True
 
     def add_result(self, action_result: PhantomActionResult) -> PhantomActionResult:
+        """Wrapper for BaseConnector's add_action_result method."""
         return self.add_action_result(action_result)
 
     def get_results(self) -> list[PhantomActionResult]:
+        """Wrapper for BaseConnector's get_action_results method."""
         return self.get_action_results()
 
     def add_exception(self, exception: Exception) -> None:
+        """Public method for adding an exception to an app run result set."""
         self._BaseConnector__conn_result.add_exception(exception)
 
     def set_csrf_info(self, token: str, referer: str) -> None:
@@ -130,4 +143,5 @@ class ActionsManager(BaseConnector):
 
     @classmethod
     def get_soar_base_url(cls) -> str:
+        """Get the base URL of the Splunk SOAR instance this app is running on."""
         return cls._get_phantom_base_url()

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/app.py

@@ -187,7 +187,9 @@ class App:
 
         self.__logger.handler.set_handle(handle)
         soar_auth = App.create_soar_client_auth_object(input_data)
-        self.soar_client.update_client(soar_auth, input_data.asset_id)
+        self.soar_client.update_client(
+            soar_auth, input_data.asset_id, input_data.container_id
+        )
         return self.actions_manager.handle(input_data, handle=handle)
 
     @staticmethod

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/app_client.py

@@ -45,6 +45,7 @@ class AppClient(SOARClient[SummaryType]):
 
         self._summary: Optional[SummaryType] = None
         self._message: Optional[str] = None
+        self.__container_id: int = 0
 
     @property
     def client(self) -> httpx.Client:
@@ -66,10 +67,17 @@ class AppClient(SOARClient[SummaryType]):
         """The SOAR Vault API."""
         return self._vault_api
 
-    def update_client(self, soar_auth: SOARClientAuth, asset_id: str) -> None:
+    def get_executing_container_id(self) -> int:
+        """Return the current Container ID passed in the Connector Run Action JSON."""
+        return self.__container_id
+
+    def update_client(
+        self, soar_auth: SOARClientAuth, asset_id: str, container_id: int = 0
+    ) -> None:
         """Update the SOAR client with the given authentication and asset ID."""
         self.authenticate_soar_client(soar_auth)
         self._containers_api.set_executing_asset(asset_id)
+        self.__container_id = container_id
 
     def authenticate_soar_client(self, soar_auth: SOARClientAuth) -> None:
         """Authenticate the SOAR client with the given authentication credentials."""

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/cli/manifests/cli.py

@@ -10,6 +10,7 @@ manifests = typer.Typer()
 
 @manifests.command()
 def display(filename: str) -> None:
+    """Parse and print the contents of a manifest JSON file."""
     with open(filename) as f:
         meta = json.load(f)
 
@@ -18,4 +19,5 @@ def display(filename: str) -> None:
 
 @manifests.command()
 def create(filename: str, project_context: str) -> None:
+    """Create a manifest file from the given project context."""
     ManifestProcessor(filename, project_context).create()

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/cli/manifests/deserializers.py

@@ -14,6 +14,11 @@ from soar_sdk.meta.datatypes import to_python_type
 
 
 class DeserializedAppMeta(NamedTuple):
+    """Named tuple containing a deserialized app metadata and related info.
+
+    Used to return multiple values from AppMetaDeserializer.from_app_json.
+    """
+
     app_meta: AppMeta
     actions_with_custom_views: list[str]
     has_rest_handlers: bool
@@ -21,8 +26,19 @@ class DeserializedAppMeta(NamedTuple):
 
 
 class AppMetaDeserializer:
+    """Namespace class responsible for deserializing an AppMeta from a JSON manifest file."""
+
     @staticmethod
     def from_app_json(json_path: Path) -> DeserializedAppMeta:
+        """Deserialize an AppMeta from a JSON manifest file.
+
+        Args:
+            json_path: The path to the JSON manifest file.
+
+        Returns:
+            A DeserializedAppMeta named tuple containing the AppMeta and info
+            about actions with custom views, REST handlers, and webhooks.
+        """
         manifest: dict[str, Any] = json.loads(json_path.read_text())
 
         # Massage the python_version field, which may be a comma-separated string
@@ -60,12 +76,16 @@ class AppMetaDeserializer:
 
 
 class FieldSpec(NamedTuple):
+    """Named tuple representing the metadata required to create a pydantic field specification."""
+
     type_: type
     default: Any
 
 
 @dataclasses.dataclass
 class OutputFieldModel:
+    """Canonical representation of an output field specification in an app manifest."""
+
     data_path: str
     data_type: str
     contains: Optional[list[str]] = None
@@ -75,13 +95,29 @@ class OutputFieldModel:
 
 
 class DeserializedActionMeta(NamedTuple):
+    """Named tuple containing a deserialized action metadata and related info.
+
+    Used to return multiple values from ActionDeserializer.from_app_json.
+    """
+
     action_meta: ActionMeta
     has_custom_view: bool
 
 
 class ActionDeserializer:
+    """Namespace class responsible for deserializing an ActionMeta from a JSON action definition."""
+
     @classmethod
     def from_action_json(cls, action: dict[str, Any]) -> DeserializedActionMeta:
+        """Deserialize an ActionMeta from a JSON action definition.
+
+        Args:
+            action: The JSON dictionary representing the action.
+
+        Returns:
+            A DeserializedActionMeta named tuple containing the ActionMeta and
+            info about whether the action has a custom view.
+        """
         action["parameters"] = cls.parse_parameters(
             action["action"], action.get("parameters", {})
         )
@@ -95,9 +131,7 @@ class ActionDeserializer:
     def parse_parameters(
         cls, action_name: str, parameters: dict[str, Any]
     ) -> type[Params]:
-        """
-        Parses the parameters from a dictionary to generate a Params model class
-        """
+        """Parses the parameters from a dictionary to generate a Params model class."""
         # If no parameters, return base Params class
         if not parameters:
             return Params
@@ -122,9 +156,7 @@ class ActionDeserializer:
 
     @staticmethod
     def _create_param_field(param_spec: dict[str, Any]) -> FieldSpec:
-        """
-        Create a parameter field from a parameter specification.
-        """
+        """Create a parameter field from a parameter specification."""
         # Get the Python type from data_type
         data_type = param_spec.get("data_type", "string")
         python_type = to_python_type(data_type)
@@ -147,9 +179,7 @@ class ActionDeserializer:
     def parse_output(
         cls, action_name: str, output: list[OutputFieldSpecification]
     ) -> type[ActionOutput]:
-        """
-        Parses the output from a list of OutputFieldSpecification to generate an ActionOutput model class
-        """
+        """Parses a list of OutputFieldSpecification to generate an ActionOutput model class."""
         # Filter out automatic fields and extract the action's real output fields
         output_fields = cls._filter_output_fields(output)
 
@@ -173,8 +203,7 @@ class ActionDeserializer:
     def _build_output_structure(
         datapath_specs: dict[str, OutputFieldModel],
     ) -> dict[str, Union[list, dict, OutputFieldModel]]:
-        """
-        Parse a datapath string into a dictionary.
+        """Parse a datapath string into a dictionary.
 
         Args:
             datapath_specs: The set of datapaths and their types to parse.
@@ -261,9 +290,10 @@ class ActionDeserializer:
         action_name: str,
         output_structure: dict[str, Union[dict, list, OutputFieldModel]],
     ) -> type[ActionOutput]:
-        """
-        Recursively (depth-first) build dynamic pydantic models for the action output,
-        from the output data paths definitions.
+        """Build dynamic pydantic models for an action output, from the output data paths.
+
+        This function is part of a depth-first recursive approach to build nested
+        models, in tandem with _build_output_field.
 
         Returns:
             A dynamically created ActionOutput class with nested structure based on the output fields.
@@ -285,6 +315,14 @@ class ActionDeserializer:
     def _build_output_field(
         cls, field_name: str, output_structure: Union[list, dict, OutputFieldModel]
     ) -> tuple[str, FieldSpec]:
+        """Build dynamic specs for an action output field, from an output data path.
+
+        This function is part of a depth-first recursive approach to build nested
+        models, in tandem with _build_output_class.
+
+        Returns:
+            A tuple containing the normalized field name and its FieldSpec.
+        """
         normalized_name = normalize_field_name(field_name)
 
         # Base case: primitive (leaf node) output field
@@ -331,9 +369,7 @@ class ActionDeserializer:
     def _filter_output_fields(
         output: list[OutputFieldSpecification],
     ) -> list[OutputFieldSpecification]:
-        """
-        Filter out automatic fields and extract the action's real output fields.
-        """
+        """Filter out automatic fields and extract the action's real output fields."""
         output_fields: list[OutputFieldSpecification] = []
         for output_spec in output:
             data_path = output_spec["data_path"].removeprefix("action_result.")

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/decorators/on_poll.py

@@ -20,16 +20,13 @@ if TYPE_CHECKING:
 
 
 class OnPollDecorator:
-    """
-    Class-based decorator for on_poll functionality.
-    """
+    """Class-based decorator for tagging a function as the special 'on poll' action."""
 
     def __init__(self, app: "App") -> None:
         self.app = app
 
     def __call__(self, function: Callable) -> Action:
-        """
-        Decorator for the on_poll action.
+        """Decorator for the 'on poll' action.
 
         The decorated function must be a generator (using yield) or return an Iterator that yields Container and/or Artifact objects. Only one on_poll action is allowed per app.
 

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/params.py

@@ -22,11 +22,10 @@ def Param(
     allow_list: bool = False,
     sensitive: bool = False,
 ) -> Any:  # noqa: ANN401
-    """
-    Representation of the param passed into the action. The param needs extra meta
-    information that is later used for the configuration of the app and use in
-    playbooks. This function takes care of the required information for the manifest
-    JSON file and fills in defaults.
+    """Representation of a single complex action parameter.
+
+    Use this function to define the default value for an action parameter that requires
+    extra metadata for the manifest. This function is a thin wrapper around pydantic.Field.
 
     :param order: The order key, starting at 0, allows the app
       author to control the display order of the controls in the UI.
@@ -69,6 +68,8 @@ def Param(
 
 
 class InputFieldSpecification(TypedDict):
+    """Canonical data format for the JSON dictionary given to action runs by the SOAR platform."""
+
     order: int
     name: str
     description: str
@@ -82,9 +83,9 @@ class InputFieldSpecification(TypedDict):
 
 
 class Params(BaseModel):
-    """
-    Params defines the inputs for an action. It can contain strings, booleans, or numbers -- no lists or dictionaries.
+    """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.
     """
 
@@ -140,11 +141,7 @@ class Params(BaseModel):
 
 
 class OnPollParams(Params):
-    """
-    Parameters for on_poll.
-
-    Used to define the specific parameters for the on_poll action.
-    """
+    """Canonical parameters for the special 'on poll' action."""
 
     start_time: int = Param(
         description="Start of time range, in epoch time (milliseconds).",
@@ -174,11 +171,7 @@ class OnPollParams(Params):
 
 
 class GenericActionParams(Params):
-    """
-    Parameters for generic actions.
-
-    Used to define the specific parameters for the generic action.
-    """
+    """Canonical parameters for the special generic HTTP actions."""
 
     http_method: str = Param(
         description="The HTTP method to use for the request.",

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/src/soar_sdk/views/template_renderer.py

@@ -60,6 +60,15 @@ class JinjaTemplateRenderer(TemplateRenderer):
         setup_jinja_env(self.env)
 
     def render_template(self, template_name: str, context: dict[str, Any]) -> str:
+        """Render a template with its name and the given context.
+
+        Args:
+            template_name: The name of the template to render.
+            context: The context dictionary to pass to the Jinja rendering engine.
+
+        Returns:
+            The rendered template as a string.
+        """
         template = self.env.get_template(template_name)
         return template.render(**context)
 
@@ -70,6 +79,17 @@ class JinjaTemplateRenderer(TemplateRenderer):
         function_name: str,
         template_name: str,
     ) -> str:
+        """Render the standard error template with error information.
+
+        Args:
+            error_type: The type or category of the error.
+            error_message: A descriptive error message.
+            function_name: The name of the function where the error occurred.
+            template_name: The name of the template being rendered.
+
+        Returns:
+            The rendered error template as a string.
+        """
         try:
             template = self.env.get_template(ERROR_TEMPLATE_PATH)
 
@@ -89,6 +109,21 @@ class JinjaTemplateRenderer(TemplateRenderer):
 def get_template_renderer(
     engine: Optional[str] = None, templates_dir: Optional[str] = None
 ) -> TemplateRenderer:
+    """Factory function to get the appropriate template renderer.
+
+    Args:
+        engine: The template engine to use (default is "jinja").
+        templates_dir: The directory where templates are located (default is "./templates").
+
+    Returns:
+        An instance of the appropriate TemplateRenderer subclass.
+
+    Raises:
+        ValueError: If an unsupported template engine is specified.
+
+    .. note::
+        Currently, only the Jinja2 template engine is supported.
+    """
     if engine is None:
         engine = DEFAULT_TEMPLATE_ENGINE
 
@@ -102,6 +137,14 @@ def get_template_renderer(
 
 
 def get_templates_dir(function_globals: dict[str, Any]) -> str:
+    """Determine an app's templates directory based on a view handler's file location.
+
+    Args:
+        function_globals: The ``.__globals`` dictionary from a view handler function.
+
+    Returns:
+        The path to the templates directory as a string.
+    """
     caller_file = function_globals.get("__file__")
     if caller_file:
         app_dir = Path(caller_file).parent

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/tests/example_app/src/app.py

@@ -43,6 +43,8 @@ app = App(
 @app.test_connectivity()
 def test_connectivity(soar: SOARClient, asset: Asset) -> None:
     soar.get("rest/version")
+    container_id = soar.get_executing_container_id()
+    logger.info(f"current executing container's container_id is: {container_id}")
     logger.info(f"testing connectivity against {asset.base_url}")
     logger.debug("hello")
     logger.warning("this is a warning")

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/tests/test_app_action.py

@@ -198,7 +198,8 @@ def test_action_decoration_uses_meta_identifier_for_action_name(simple_app):
 def test_action_with_mocked_client(simple_app, sample_params):
     @simple_app.action()
     def action_function(params: SampleParams, soar: SOARClient) -> ActionOutput:
-        soar.save_progress("Progress was made")
+        container_id = str(soar.get_executing_container_id())
+        soar.save_progress(f"Container ID is: {container_id}")
 
     client_mock = mock.Mock()
     client_mock.save_progress = mock.Mock()

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/tests/test_app_client.py

@@ -31,3 +31,7 @@ def test_authenticate_soar_client_on_platform(
 ):
     simple_connector.authenticate_soar_client(soar_client_auth_token)
     assert mock_get_any_soar_call.call_count == 1
+
+
+def test_get_executing_container_id(simple_connector: AppClient):
+    assert simple_connector.get_executing_container_id() == 0

{splunk_soar_sdk-1.3.3 → splunk_soar_sdk-1.4.0}/uv.lock

@@ -1291,7 +1291,7 @@ wheels = [
 
 [[package]]
 name = "splunk-soar-sdk"
-version = "1.3.3"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4", marker = "(python_full_version < '3.10' and platform_machine == 'arm64' and sys_platform == 'darwin') or (python_full_version >= '3.13' and platform_machine == 'arm64' and sys_platform == 'darwin') or (python_full_version < '3.10' and platform_machine == 'x86_64' and sys_platform == 'darwin') or (python_full_version >= '3.13' and platform_machine == 'x86_64' and sys_platform == 'darwin') or (python_full_version < '3.10' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.13' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version < '3.10' and platform_machine == 'x86_64' and sys_platform == 'linux') or (python_full_version >= '3.13' and platform_machine == 'x86_64' and sys_platform == 'linux')" },

splunk_soar_sdk-1.3.3/release_notes.txt

@@ -1,23 +0,0 @@
-## [1.3.3](https://github.com/phantomcyber/splunk-soar-sdk/compare/1.3.2...1.3.3) (2025-09-08)
-
-
-### Bug Fixes
-
-* **docs:** resolve a lot of pydocstyle warnings ([0e4fce6](https://github.com/phantomcyber/splunk-soar-sdk/commit/0e4fce648ae3a76fa64e319a34c2ad14a33783a4))
-* **docs:** use 'Splunk SOAR' everywhere ([adaa616](https://github.com/phantomcyber/splunk-soar-sdk/commit/adaa6168159a7a9f50be3d024fb9af33a3ebd817))
-
-
-
-
-
-## [1.3.3](https://github.com/phantomcyber/splunk-soar-sdk/compare/1.3.2...1.3.3) (2025-09-08)
-
-
-### Bug Fixes
-
-* **docs:** resolve a lot of pydocstyle warnings ([0e4fce6](https://github.com/phantomcyber/splunk-soar-sdk/commit/0e4fce648ae3a76fa64e319a34c2ad14a33783a4))
-* **docs:** use 'Splunk SOAR' everywhere ([adaa616](https://github.com/phantomcyber/splunk-soar-sdk/commit/adaa6168159a7a9f50be3d024fb9af33a3ebd817))
-
-
-
-

splunk_soar_sdk-1.3.3/release_version.txt

@@ -1 +0,0 @@
-1.3.3