splunk-soar-sdk 3.1.0__tar.gz → 3.2.1__tar.gz

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/PKG-INFO

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

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

splunk_soar_sdk-3.2.1/release_notes.txt

@@ -0,0 +1,21 @@
+## [3.2.1](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.2.0...3.2.1) (2025-11-06)
+
+
+### Bug Fixes
+
+* fix abi3 wheel matching ([719028d](https://github.com/phantomcyber/splunk-soar-sdk/commit/719028dfe3e76f78e4a60b9c3487dba8ca0015d7))
+
+
+
+
+
+## [3.2.1](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.2.0...3.2.1) (2025-11-06)
+
+
+### Bug Fixes
+
+* fix abi3 wheel matching ([719028d](https://github.com/phantomcyber/splunk-soar-sdk/commit/719028dfe3e76f78e4a60b9c3487dba8ca0015d7))
+
+
+
+

splunk_soar_sdk-3.2.1/release_version.txt

@@ -0,0 +1 @@
+3.2.1

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/actions_manager.py

@@ -154,6 +154,13 @@ class ActionsManager(BaseConnector):
         # For non-broker just proceed as we did before
         return super().get_app_dir()
 
+    def send_finding_to_es(self, finding: dict[str, Any]) -> str:
+        """Send finding to ES.
+
+        Returns finding_id: ID for the finding in ES.
+        """
+        return ""
+
     @classmethod
     def get_soar_base_url(cls) -> str:
         """Get the base URL of the Splunk SOAR instance this app is running on."""

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/app.py

@@ -38,6 +38,7 @@ from soar_sdk.decorators import (
     ActionDecorator,
     ViewHandlerDecorator,
     OnPollDecorator,
+    OnESPollDecorator,
     WebhookDecorator,
     MakeRequestDecorator,
 )
@@ -495,6 +496,31 @@ class App:
         """
         return OnPollDecorator(self)
 
+    def on_es_poll(self) -> OnESPollDecorator:
+        """Decorator for the on_es_poll action.
+
+        The decorated function must be a generator (using yield) or return an Iterator that yields tuples of (Finding, list[AttachmentInput]). Only one on_es_poll action is allowed per app.
+
+        Example:
+            >>> @app.on_es_poll()
+            ... def on_es_poll(
+            ...     params: OnESPollParams, soar: SOARClient, asset: Asset
+            ... ) -> Iterator[tuple[Finding, list[AttachmentInput]]]:
+            ...     yield (
+            ...         Finding(
+            ...             rule_title="Risk threshold exceeded for user",
+            ...             rule_description="Risk Threshold Exceeded for an object over a 24 hour period",
+            ...             security_domain="threat",
+            ...             risk_object="bad_user@splunk.com",
+            ...             risk_object_type="user",
+            ...             risk_score=100.0,
+            ...             status="New",
+            ...         ),
+            ...         [],
+            ...     )
+        """
+        return OnESPollDecorator(self)
+
     def view_handler(
         self,
         *,

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/code_renderers/action_renderer.py

@@ -103,6 +103,62 @@ class ActionRenderer(AstRenderer[ActionMeta]):
                 ctx=ast.Load(),
             ),
         ),
+        "on es poll": ast.FunctionDef(
+            name="on_es_poll",
+            args=ast.arguments(
+                posonlyargs=[],
+                args=[
+                    ast.arg(
+                        arg="soar", annotation=ast.Name(id="SOARClient", ctx=ast.Load())
+                    ),
+                    ast.arg(
+                        arg="asset", annotation=ast.Name(id="Asset", ctx=ast.Load())
+                    ),
+                    ast.arg(
+                        arg="params",
+                        annotation=ast.Name(id="OnESPollParams", ctx=ast.Load()),
+                    ),
+                ],
+                vararg=None,
+                kwonlyargs=[],
+                kw_defaults=[],
+                kwarg=None,
+                defaults=[],
+            ),
+            body=[
+                ast.Raise(
+                    ast.Call(
+                        func=ast.Name(id="NotImplementedError"), args=[], keywords=[]
+                    )
+                )
+            ],
+            decorator_list=[
+                ast.Call(
+                    func=ast.Name(id="app.on_es_poll", ctx=ast.Load()),
+                    args=[],
+                    keywords=[],
+                )
+            ],
+            returns=ast.Subscript(
+                value=ast.Name(id="Iterator", ctx=ast.Load()),
+                slice=ast.Subscript(
+                    value=ast.Name(id="tuple", ctx=ast.Load()),
+                    slice=ast.Tuple(
+                        elts=[
+                            ast.Name(id="Finding", ctx=ast.Load()),
+                            ast.Subscript(
+                                value=ast.Name(id="list", ctx=ast.Load()),
+                                slice=ast.Name(id="AttachmentInput", ctx=ast.Load()),
+                                ctx=ast.Load(),
+                            ),
+                        ],
+                        ctx=ast.Load(),
+                    ),
+                    ctx=ast.Load(),
+                ),
+                ctx=ast.Load(),
+            ),
+        ),
     }
 
     @property

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/code_renderers/app_renderer.py

@@ -80,6 +80,7 @@ class AppRenderer:
                 ast.alias(name="Param", asname=None),
                 ast.alias(name="Params", asname=None),
                 ast.alias(name="OnPollParams", asname=None),
+                ast.alias(name="OnESPollParams", asname=None),
             ],
             level=0,
         )
@@ -114,6 +115,16 @@ class AppRenderer:
             names=[ast.alias(name="Artifact", asname=None)],
             level=0,
         )
+        yield ast.ImportFrom(
+            module="soar_sdk.models.finding",
+            names=[ast.alias(name="Finding", asname=None)],
+            level=0,
+        )
+        yield ast.ImportFrom(
+            module="soar_sdk.models.attachment_input",
+            names=[ast.alias(name="AttachmentInput", asname=None)],
+            level=0,
+        )
 
     def create_app_constructor(self) -> ast.Assign:
         """Create the App class constructor.

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/decorators/__init__.py

@@ -4,6 +4,7 @@ from .action import ActionDecorator
 from .test_connectivity import ConnectivityTestDecorator
 from .view_handler import ViewHandlerDecorator
 from .on_poll import OnPollDecorator
+from .on_es_poll import OnESPollDecorator
 from .webhook import WebhookDecorator
 from .make_request import MakeRequestDecorator
 
@@ -11,6 +12,7 @@ __all__ = [
     "ActionDecorator",
     "ConnectivityTestDecorator",
     "MakeRequestDecorator",
+    "OnESPollDecorator",
     "OnPollDecorator",
     "ViewHandlerDecorator",
     "WebhookDecorator",

splunk_soar_sdk-3.2.1/src/soar_sdk/decorators/on_es_poll.py

@@ -0,0 +1,218 @@
+import inspect
+from functools import wraps
+from typing import Any
+from collections.abc import Callable
+from collections.abc import Iterator
+
+from soar_sdk.abstract import SOARClient
+from soar_sdk.action_results import ActionResult
+from soar_sdk.params import OnESPollParams
+from soar_sdk.meta.actions import ActionMeta
+from soar_sdk.types import Action, action_protocol
+from soar_sdk.exceptions import ActionFailure
+from soar_sdk.async_utils import run_async_if_needed
+from soar_sdk.logging import getLogger
+from soar_sdk.models.finding import Finding
+from soar_sdk.models.attachment_input import AttachmentInput
+from soar_sdk.models.container import Container
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soar_sdk.app import App
+
+
+class OnESPollDecorator:
+    """Class-based decorator for tagging a function as the special 'on es poll' action."""
+
+    def __init__(self, app: "App") -> None:
+        self.app = app
+
+    def __call__(self, function: Callable) -> Action:
+        """Decorator for the 'on es poll' action.
+
+        The decorated function must be a generator (using yield) or return an Iterator that yields tuples of (Finding, list[AttachmentInput]). Only one on_es_poll action is allowed per app.
+
+        Usage:
+        Each yielded tuple creates a Container from the Finding metadata. All AttachmentInput items in the list are added as vault attachments to that container.
+        """
+        if self.app.actions_manager.get_action("on_es_poll"):
+            raise TypeError(
+                "The 'on_es_poll' decorator can only be used once per App instance."
+            )
+
+        is_generator = inspect.isgeneratorfunction(function)
+        is_async_generator = inspect.isasyncgenfunction(function)
+        signature = inspect.signature(function)
+
+        has_iterator_return = (
+            signature.return_annotation != inspect.Signature.empty
+            and getattr(signature.return_annotation, "__origin__", None) is Iterator
+        )
+
+        if not (is_generator or is_async_generator or has_iterator_return):
+            raise TypeError(
+                "The on_es_poll function must be a generator (use 'yield') or return an Iterator."
+            )
+
+        action_identifier = "on_es_poll"
+        action_name = "on es poll"
+
+        validated_params_class = OnESPollParams
+        logger = getLogger()
+
+        @action_protocol
+        @wraps(function)
+        def inner(
+            params: OnESPollParams,
+            soar: SOARClient = self.app.soar_client,
+            *args: Any,  # noqa: ANN401
+            **kwargs: Any,  # noqa: ANN401
+        ) -> bool:
+            try:
+                try:
+                    action_params = validated_params_class.parse_obj(params)
+                except Exception as e:
+                    logger.info(f"Parameter validation error: {e!s}")
+                    return self.app._adapt_action_result(
+                        ActionResult(
+                            status=False, message=f"Invalid parameters: {e!s}"
+                        ),
+                        self.app.actions_manager,
+                    )
+
+                kwargs = self.app._build_magic_args(function, soar=soar, **kwargs)
+
+                result = function(action_params, *args, **kwargs)
+                result = run_async_if_needed(result)
+
+                for item in result:
+                    if not isinstance(item, tuple) or len(item) != 2:
+                        logger.info(
+                            f"Warning: Expected tuple of (Finding, list[AttachmentInput]), got: {type(item)}"
+                        )
+                        continue
+
+                    finding, attachments = item
+
+                    if not isinstance(finding, Finding):
+                        logger.info(
+                            f"Warning: First element must be Finding, got: {type(finding)}"
+                        )
+                        continue
+
+                    if not isinstance(attachments, list):
+                        logger.info(
+                            f"Warning: Second element must be list[AttachmentInput], got: {type(attachments)}"
+                        )
+                        continue
+
+                    for attachment in attachments:
+                        if not isinstance(attachment, AttachmentInput):
+                            logger.info(
+                                f"Warning: Attachment must be AttachmentInput, got: {type(attachment)}"
+                            )
+                            break
+                    else:
+                        finding_dict = finding.to_dict()
+                        logger.info(
+                            f"Processing finding: {finding_dict.get('rule_title', 'Unnamed finding')}"
+                        )
+
+                        # Send finding to ES and get finding_id back
+                        finding_id = self.app.actions_manager.send_finding_to_es(
+                            finding_dict
+                        )
+
+                        container = Container(
+                            name=finding.rule_title,
+                            description=finding.rule_description,
+                            severity=finding.urgency or "medium",
+                            status=finding.status,
+                            owner_id=finding.owner,
+                            sensitivity=finding.disposition,
+                            tags=finding.source,
+                            external_id=finding_id,
+                            data={
+                                "security_domain": finding.security_domain,
+                                "risk_score": finding.risk_score,
+                                "risk_object": finding.risk_object,
+                                "risk_object_type": finding.risk_object_type,
+                            },
+                        )
+
+                        ret_val, message, container_id = (
+                            self.app.actions_manager.save_container(container.to_dict())
+                        )
+                        logger.info(
+                            f"Creating container for finding: {finding.rule_title}"
+                        )
+
+                        if not ret_val:
+                            logger.info(f"Failed to create container: {message}")
+                            continue
+
+                        for attachment in attachments:
+                            try:
+                                if attachment.file_content is not None:
+                                    vault_id = soar.vault.create_attachment(
+                                        container_id=container_id,
+                                        file_content=attachment.file_content,
+                                        file_name=attachment.file_name,
+                                        metadata=attachment.metadata,
+                                    )
+                                else:
+                                    vault_id = soar.vault.add_attachment(
+                                        container_id=container_id,
+                                        file_location=attachment.file_location,
+                                        file_name=attachment.file_name,
+                                        metadata=attachment.metadata,
+                                    )
+                                logger.info(
+                                    f"Added attachment {attachment.file_name} with vault_id: {vault_id}"
+                                )
+                            except Exception as e:
+                                logger.info(
+                                    f"Failed to add attachment {attachment.file_name}: {e!s}"
+                                )
+
+                return self.app._adapt_action_result(
+                    ActionResult(status=True, message="Finding processing complete"),
+                    self.app.actions_manager,
+                )
+            except ActionFailure as e:
+                e.set_action_name(action_name)
+                return self.app._adapt_action_result(
+                    ActionResult(status=False, message=str(e)),
+                    self.app.actions_manager,
+                )
+            except Exception as e:
+                self.app.actions_manager.add_exception(e)
+                logger.info(f"Error during finding processing: {e!s}")
+                return self.app._adapt_action_result(
+                    ActionResult(status=False, message=str(e)),
+                    self.app.actions_manager,
+                )
+
+        inner.params_class = validated_params_class
+
+        class OnESPollActionMeta(ActionMeta):
+            def model_dump(self, *args: object, **kwargs: object) -> dict[str, Any]:
+                data = super().model_dump(*args, **kwargs)
+                data["output"] = []
+                return data
+
+        inner.meta = OnESPollActionMeta(
+            action=action_name,
+            identifier=action_identifier,
+            description=inspect.getdoc(function) or action_name,
+            verbose="Callback action for the on_es_poll ingest functionality",
+            type="ingest",
+            read_only=True,
+            parameters=validated_params_class,
+            versions="EQ(*)",
+        )
+
+        self.app.actions_manager.set_action(action_identifier, inner)
+        self.app._dev_skip_in_pytest(function, inner)
+        return inner

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/meta/dependencies.py

@@ -277,9 +277,7 @@ class UvPackage(BaseModel):
         for abi in abi_precedence:
             abi_wheels = [wheel for wheel in self.wheels if abi in wheel.abi_tags]
             for python in python_precedence:
-                python_wheels = [
-                    wheel for wheel in abi_wheels if python in wheel.python_tags
-                ]
+                python_wheels = self._filter_python_wheels(abi_wheels, python, abi)
                 for platform in platform_precedence:
                     platform_wheels = [
                         wheel
@@ -293,6 +291,54 @@ class UvPackage(BaseModel):
             f"Could not find a suitable wheel for {self.name=}, {self.version=}, {abi_precedence=}, {python_precedence=}, {platform_precedence=}"
         )
 
+    def _filter_python_wheels(
+        self, wheels: list[UvWheel], target_python: str, abi: str
+    ) -> list[UvWheel]:
+        """Filter and sort wheels by Python version compatibility.
+
+        For abi3 wheels, prefers the highest compatible minimum version
+        (e.g., cp311-abi3 over cp38-abi3 for Python 3.13).
+        """
+        compatible = [
+            wheel
+            for wheel in wheels
+            if self._is_python_compatible(wheel, target_python, abi)
+        ]
+
+        # For abi3 wheels, prefer highest minimum version (closest to target)
+        if abi == "abi3" and compatible:
+            compatible = sorted(
+                compatible,
+                key=lambda w: max(
+                    (int(tag[2:]) for tag in w.python_tags if tag.startswith("cp")),
+                    default=0,
+                ),
+                reverse=True,
+            )
+
+        return compatible
+
+    def _is_python_compatible(
+        self, wheel: UvWheel, target_python: str, abi: str
+    ) -> bool:
+        """Check if a wheel is compatible with the target Python version.
+
+        For abi3 wheels, the Python tag indicates minimum version (e.g., cp311-abi3 works with Python ≥3.11).
+        For non-abi3 wheels, exact tag matching is required.
+        """
+        if target_python in wheel.python_tags:
+            return True
+
+        # For abi3 wheels, check if target >= minimum version (e.g., cp313 >= cp311)
+        if abi == "abi3":
+            return any(
+                int(tag[2:]) <= int(target_python[2:])
+                for tag in wheel.python_tags
+                if tag.startswith("cp") and target_python.startswith("cp")
+            )
+
+        return False
+
     _manylinux_precedence: ClassVar[list[str]] = [
         "_2_28",  # glibc 2.28, latest stable version, supports Ubuntu 18.10+ and RHEL/Oracle 8+
         "_2_17",  # glibc 2.17, LTS-ish, supports Ubuntu 13.10+ and RHEL/Oracle 7+

splunk_soar_sdk-3.2.1/src/soar_sdk/models/__init__.py

@@ -0,0 +1,15 @@
+from .artifact import Artifact
+from .attachment_input import AttachmentInput
+from .container import Container
+from .finding import Finding, DrilldownSearch, DrilldownDashboard
+from .vault_attachment import VaultAttachment
+
+__all__ = [
+    "Artifact",
+    "AttachmentInput",
+    "Container",
+    "DrilldownDashboard",
+    "DrilldownSearch",
+    "Finding",
+    "VaultAttachment",
+]

splunk_soar_sdk-3.2.1/src/soar_sdk/models/attachment_input.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel, field_validator, ConfigDict
+from pydantic_core.core_schema import ValidationInfo
+
+
+class AttachmentInput(BaseModel):
+    """Represents a vault attachment to be created during on_es_poll.
+
+    Specify either file_content OR file_location, not both.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    file_content: str | bytes | None = None
+    file_location: str | None = None
+    file_name: str
+    metadata: dict[str, str] | None = None
+
+    @field_validator("file_location")
+    @classmethod
+    def validate_one_source(cls, v: str | None, info: ValidationInfo) -> str | None:
+        """Validate that exactly one of file_content or file_location is provided."""
+        file_content = info.data.get("file_content")
+        if v is None and file_content is None:
+            raise ValueError("Must provide either file_content or file_location")
+        if v is not None and file_content is not None:
+            raise ValueError("Cannot provide both file_content and file_location")
+        return v

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/models/container.py

@@ -14,6 +14,7 @@ class Container(BaseModel):
     label: str | None = None
     description: str | None = None
     source_data_identifier: str | None = None
+    external_id: str | None = None
     severity: str | None = None
     status: str | None = None
     tags: list[str] | str | None = None

{splunk_soar_sdk-3.1.0 → splunk_soar_sdk-3.2.1}/src/soar_sdk/params.py

@@ -193,6 +193,25 @@ class OnPollParams(Params):
     )
 
 
+class OnESPollParams(Params):
+    """Canonical parameters for the special 'on es poll' action."""
+
+    start_time: int = Param(
+        description="Start of time range, in epoch time (milliseconds).",
+        required=False,
+    )
+
+    end_time: int = Param(
+        description="End of time range, in epoch time (milliseconds).",
+        required=False,
+    )
+
+    container_count: int = Param(
+        description="Maximum number of container records to query for.",
+        required=False,
+    )
+
+
 class MakeRequestParams(Params):
     """Canonical parameters for the special make request action."""