splunk-soar-sdk 3.5.0__tar.gz → 3.6.0__tar.gz

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunk-soar-sdk
-Version: 3.5.0
+Version: 3.6.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
@@ -22,6 +22,8 @@ Requires-Dist: bleach>=6.2.0
 Requires-Dist: build>=1.3.0
 Requires-Dist: click<8.2.0,>=8.0.0
 Requires-Dist: distro>=1.8.0
+Requires-Dist: hatchling>=1.28.0
+Requires-Dist: httpx-retries>=0.4.5
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: humanize>=4.12.2
 Requires-Dist: jinja2>=3.1.0

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "splunk-soar-sdk"
-version = "3.5.0"
+version = "3.6.0"
 description = "The official framework for developing and testing Splunk SOAR Apps"
 readme = "README.md"
 requires-python = ">=3.13, <3.15"
@@ -44,6 +44,8 @@ dependencies = [
     "packaging>=25.0",
     "build>=1.3.0",
     "setuptools>=80.9.0",
+    "httpx-retries>=0.4.5",
+    "hatchling>=1.28.0",
 ]
 
 [project.urls]
@@ -243,4 +245,4 @@ match = "(?!test_).*\\.py"
 match-dir = "(?!tests|__pycache__|build|dist).*"
 
 [tool.codespell]
-ignore-words-list = "MergeT"
+ignore-words-list = "MergeT,asend"

splunk_soar_sdk-3.6.0/release_notes.txt

@@ -0,0 +1,37 @@
+# [3.6.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.5.0...3.6.0) (2025-12-12)
+
+
+### Bug Fixes
+
+* remove the useless test files from the root of the repo ([f529497](https://github.com/phantomcyber/splunk-soar-sdk/commit/f529497a397a9879dbe5e264a2b562916b6bbcf8))
+
+
+### Features
+
+* add `supports_es_polling` field to manifest ([0eb75dd](https://github.com/phantomcyber/splunk-soar-sdk/commit/0eb75dd56a7fb512fff0533bdb64317d4de776d6))
+* add a client for submitting ES findings ([23bf0b7](https://github.com/phantomcyber/splunk-soar-sdk/commit/23bf0b7bea5e9437bffecfe783a20abf9c4eb35b))
+* enable building the SDK from a local directory instead of fetching wheel ([8ca7a6c](https://github.com/phantomcyber/splunk-soar-sdk/commit/8ca7a6c007b740c56db2407306a32363d203da76))
+* update ES polling to use the new workflow ([d69784c](https://github.com/phantomcyber/splunk-soar-sdk/commit/d69784c462eccab6f5a0796cc9573cff5e816a1c))
+
+
+
+
+
+# [3.6.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.5.0...3.6.0) (2025-12-12)
+
+
+### Bug Fixes
+
+* remove the useless test files from the root of the repo ([f529497](https://github.com/phantomcyber/splunk-soar-sdk/commit/f529497a397a9879dbe5e264a2b562916b6bbcf8))
+
+
+### Features
+
+* add `supports_es_polling` field to manifest ([0eb75dd](https://github.com/phantomcyber/splunk-soar-sdk/commit/0eb75dd56a7fb512fff0533bdb64317d4de776d6))
+* add a client for submitting ES findings ([23bf0b7](https://github.com/phantomcyber/splunk-soar-sdk/commit/23bf0b7bea5e9437bffecfe783a20abf9c4eb35b))
+* enable building the SDK from a local directory instead of fetching wheel ([8ca7a6c](https://github.com/phantomcyber/splunk-soar-sdk/commit/8ca7a6c007b740c56db2407306a32363d203da76))
+* update ES polling to use the new workflow ([d69784c](https://github.com/phantomcyber/splunk-soar-sdk/commit/d69784c462eccab6f5a0796cc9573cff5e816a1c))
+
+
+
+

splunk_soar_sdk-3.6.0/release_version.txt

@@ -0,0 +1 @@
+3.6.0

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/src/soar_sdk/actions_manager.py

@@ -24,6 +24,7 @@ class ActionsManager(BaseConnector):
 
         self._actions: dict[str, Action] = {}
         self.__app_dir: Path | None = None
+        self.supports_es_polling: bool = False
 
     def get_action(self, identifier: str) -> Action | None:
         """Convenience method for getting an Action callable from its identifier.
@@ -123,13 +124,6 @@ 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.6.0/src/soar_sdk/apis/es/findings.py

@@ -0,0 +1,27 @@
+import httpx
+from pydantic import Field
+
+from soar_sdk.models.finding import Finding
+
+
+class CreateFindingResponse(Finding):
+    """The return type from creating a Finding."""
+
+    time: str = Field(alias="_time")
+    finding_id: str
+
+
+class Findings:
+    """Client for ES Findings API."""
+
+    def __init__(self, client: httpx.Client) -> None:
+        self._client = client
+
+    def create(self, finding: Finding) -> CreateFindingResponse:
+        """Create a new Finding."""
+        res = self._client.post(
+            "/services/public/v2/findings",
+            data=finding.model_dump(),
+        )
+        res.raise_for_status()
+        return CreateFindingResponse(**res.json())

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/src/soar_sdk/cli/manifests/processors.py

@@ -74,6 +74,8 @@ class ManifestProcessor:
                 f"{module_name}.{app_instance_name}.handle_webhook"
             )
 
+        app_meta.supports_es_polling = app.actions_manager.supports_es_polling
+
         return app_meta
 
     def create(self) -> None:

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

@@ -0,0 +1,187 @@
+import asyncio
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import TYPE_CHECKING, Any, get_args
+
+from pydantic import ValidationError
+
+from soar_sdk.abstract import SOARClient
+from soar_sdk.action_results import ActionResult
+from soar_sdk.es_client import ESClient
+from soar_sdk.exceptions import ActionFailure
+from soar_sdk.logging import getLogger
+from soar_sdk.meta.actions import ActionMeta
+from soar_sdk.models.container import Container
+from soar_sdk.models.finding import Finding
+from soar_sdk.params import OnESPollParams
+from soar_sdk.types import Action, action_protocol
+
+if TYPE_CHECKING:
+    from soar_sdk.app import App
+
+
+ESPollingYieldType = Finding
+ESPollingSendType = int | None
+
+
+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 or AsyncGenerator. Only one on_es_poll action is allowed per app.
+
+        Usage:
+        The generator should yield a `Finding`. Upon receiving an event from the generator, the SDK will submit the Finding to Splunk Enterprise Security and create a linked SOAR Container.
+        The generator should accept a "send type" of `int | None`. When a Finding is successfully delivered to ES and linked to a Container, the SDK will send the Container ID back into the generator. The Container is useful for storing large attachments included with the Finding.
+        If the Finding cannot be successfully delivered to ES, the SDK will stop polling and return a failed result for the action run.
+        """
+        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)
+
+        generator_type = inspect.signature(function).return_annotation
+        generator_type_args = get_args(generator_type)
+
+        if not (is_generator or is_async_generator) or len(generator_type_args) < 2:
+            raise TypeError(
+                "The on_es_poll function must be a Generator or AsyncGenerator (use 'yield')."
+            )
+
+        yield_type = generator_type_args[0]
+        send_type = generator_type_args[1]
+
+        if yield_type != ESPollingYieldType:
+            raise TypeError(
+                f"@on_es_poll generator should have yield type {ESPollingYieldType}."
+            )
+        if send_type != ESPollingSendType:
+            raise TypeError(
+                f"@on_es_poll generator should have send type {ESPollingSendType}."
+            )
+
+        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:
+                action_params = validated_params_class.model_validate(params)
+            except ValidationError 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,
+                )
+            es = ESClient(params.es_base_url, params.es_session_key)
+            kwargs = self.app._build_magic_args(function, soar=soar, **kwargs)
+            generator = function(action_params, *args, **kwargs)
+
+            if is_async_generator:
+
+                def polling_step(
+                    last_container_id: ESPollingSendType,
+                ) -> ESPollingYieldType:
+                    return asyncio.run(generator.asend(last_container_id))
+            else:
+
+                def polling_step(
+                    last_container_id: ESPollingSendType,
+                ) -> ESPollingYieldType:
+                    return generator.send(last_container_id)
+
+            last_container_id = None
+            while True:
+                try:
+                    item = polling_step(last_container_id)
+                except (StopIteration, StopAsyncIteration):
+                    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,
+                    )
+
+                if type(item) is not ESPollingYieldType:
+                    logger.info(
+                        f"Warning: expected {ESPollingYieldType}, got {type(item)}, skipping"
+                    )
+                    continue
+                finding = es.findings.create(item)
+                logger.info(f"Created finding {finding.finding_id}")
+
+                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.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, last_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:
+                    raise ActionFailure(f"Failed to create container: {message}")
+
+        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.actions_manager.supports_es_polling = True
+        self.app._dev_skip_in_pytest(function, inner)
+        return inner

splunk_soar_sdk-3.6.0/src/soar_sdk/es_client.py

@@ -0,0 +1,43 @@
+import httpx
+from httpx_retries import Retry, RetryTransport
+from httpx_retries.retry import HTTPMethod, HTTPStatus
+
+from soar_sdk.apis.es.findings import Findings
+
+RETRYABLE_METHODS = [
+    HTTPMethod.GET,
+    HTTPMethod.PUT,
+    HTTPMethod.POST,
+    HTTPMethod.PATCH,
+    HTTPMethod.DELETE,
+]
+RETRYABLE_STATUSES = [
+    HTTPStatus.TOO_MANY_REQUESTS,
+    HTTPStatus.BAD_GATEWAY,
+    HTTPStatus.SERVICE_UNAVAILABLE,
+    HTTPStatus.GATEWAY_TIMEOUT,
+]
+
+
+class ESClient:
+    """A client for accessing Splunk Enterprise Security APIs."""
+
+    def __init__(self, base_url: str, session_key: str, verify: bool = True) -> None:
+        transport = RetryTransport(
+            transport=httpx.HTTPTransport(verify=verify),
+            retry=Retry(
+                allowed_methods=RETRYABLE_METHODS,
+                status_forcelist=RETRYABLE_STATUSES,
+                total=5,
+            ),
+        )
+        self._client = httpx.Client(
+            base_url=base_url,
+            transport=transport,
+            headers={"Authorization": f"Splunk {session_key}"},
+        )
+
+    @property
+    def findings(self) -> Findings:
+        """The ES /public/v2/findings API."""
+        return Findings(self._client)

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/src/soar_sdk/meta/app.py

@@ -45,6 +45,7 @@ class AppMeta(BaseModel):
     pip314_dependencies: DependencyList = Field(default_factory=DependencyList)
 
     webhook: WebhookMeta | None = None
+    supports_es_polling: bool = False
 
     @field_validator("python_version", mode="before")
     @classmethod

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/src/soar_sdk/meta/dependencies.py

@@ -52,7 +52,8 @@ remove_when_soar_newer_than(
     "If the Splunk SDK is available as a wheel now, remove it, and remove all of the code for building wheels from source.",
 )
 DEPENDENCIES_TO_BUILD = {
-    "splunk_sdk",  # https://github.com/splunk/splunk-sdk-python/pull/656
+    "splunk_sdk",  # https://github.com/splunk/splunk-sdk-python/pull/656,
+    "splunk_soar_sdk",  # Useful to build from source when developing the SDK
 }
 
 
@@ -189,6 +190,23 @@ class UvSourceDistribution(BaseModel):
                 return Path(wheel_path).name, f.read()
 
 
+class UvSourceDirectory(BaseModel):
+    """Represents a Python dependency to be built from a source directory on the local filesystem."""
+
+    directory: str
+
+    def build(self) -> tuple[str, bytes]:
+        """Build a wheel from a local source directory."""
+        with TemporaryDirectory() as build_dir:
+            builder = build.ProjectBuilder(
+                self.directory,
+                runner=UvSourceDistribution._builder_runner,
+            )
+            wheel_path = builder.build("wheel", build_dir)
+            with open(wheel_path, "rb") as f:
+                return Path(wheel_path).name, f.read()
+
+
 class DependencyWheel(BaseModel):
     """Represents a Python package dependency with all the information required to fetch its wheel(s) from the CDN."""
 
@@ -199,6 +217,7 @@ class DependencyWheel(BaseModel):
     wheel: UvWheel | None = Field(exclude=True, default=None)
     wheel_aarch64: UvWheel | None = Field(exclude=True, default=None)
     sdist: UvSourceDistribution | None = Field(exclude=True, default=None)
+    source_dir: UvSourceDirectory | None = Field(exclude=True, default=None)
 
     async def collect_wheels(self) -> AsyncGenerator[tuple[str, bytes]]:
         """Collect a list of wheel files to fetch for this dependency across all platforms."""
@@ -208,6 +227,12 @@ class DependencyWheel(BaseModel):
             yield (f"wheels/shared/{wheel_name}", wheel_bytes)
             return
 
+        if self.wheel is None and self.source_dir is not None:
+            logger.info(f"Building local sources for {self.input_file}")
+            wheel_name, wheel_bytes = self.source_dir.build()
+            yield (f"wheels/shared/{wheel_name}", wheel_bytes)
+            return
+
         if self.wheel is None:
             raise ValueError(
                 f"Could not find a suitable wheel or source distribution for {self.module} in uv.lock"
@@ -247,6 +272,13 @@ class UvDependency(BaseModel):
     name: str
 
 
+class UvSource(BaseModel):
+    """Represents the source of a Python package in the uv lock."""
+
+    registry: str | None = None
+    directory: str | None = None
+
+
 class UvPackage(BaseModel):
     """Represents a Python package loaded from the uv lock."""
 
@@ -258,6 +290,7 @@ class UvPackage(BaseModel):
     )
     wheels: list[UvWheel] = []
     sdist: UvSourceDistribution | None = None
+    source: UvSource
 
     def _find_wheel(
         self,
@@ -366,6 +399,12 @@ class UvPackage(BaseModel):
         ):
             wheel.sdist = self.sdist
 
+        if (
+            self.source.directory is not None
+            and UvLock.normalize_package_name(self.name) in DEPENDENCIES_TO_BUILD
+        ):
+            wheel.source_dir = UvSourceDirectory(directory=self.source.directory)
+
         try:
             wheel_x86_64 = self._find_wheel(
                 abi_precedence, python_precedence, self.platform_precedence_x86_64
@@ -373,7 +412,7 @@ class UvPackage(BaseModel):
             wheel.input_file = f"{wheel_x86_64.basename}.whl"
             wheel.wheel = wheel_x86_64
         except FileNotFoundError as e:
-            if wheel.sdist is None:
+            if wheel.sdist is None and wheel.source_dir is None:
                 raise FileNotFoundError(
                     f"Could not find a suitable x86_64 wheel or source distribution for {self.name}"
                 ) from e

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/src/soar_sdk/models/finding.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 
 
 class DrilldownSearch(BaseModel):
@@ -27,10 +27,7 @@ class Finding(BaseModel):
     for investigation workflow.
     """
 
-    class Config:
-        """Pydantic config."""
-
-        extra = "forbid"
+    model_config = ConfigDict(extra="forbid")
 
     rule_title: str
     rule_description: str
@@ -52,4 +49,4 @@ class Finding(BaseModel):
 
     def to_dict(self) -> dict[str, Any]:
         """Convert the finding to a dictionary."""
-        return self.dict(exclude_none=True)
+        return self.model_dump(exclude_none=True)

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/src/soar_sdk/params.py

@@ -207,17 +207,24 @@ class OnESPollParams(Params):
         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,
     )
 
+    es_base_url: str = Param(
+        description="Base URL for the Splunk Enterprise Security API",
+        required=True,
+    )
+    es_session_key: str = Param(
+        description="Session token for the Splunk Enterprise Security API",
+        required=True,
+    )
+
 
 class MakeRequestParams(Params):
     """Canonical parameters for the special make request action."""

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/tests/cli/test_convert_cli.py

@@ -158,7 +158,7 @@ def test_convert_cli(runner, tmp_path, app_meta):
 
     app_dir = tmp_path / "test_app"
     app_dir.mkdir()
-    (app_dir / "app.json").write_text(app_meta.json())
+    (app_dir / "app.json").write_text(app_meta.model_dump_json())
     (app_dir / app_meta.logo).touch()
     (app_dir / app_meta.logo_dark).touch()
 
@@ -198,11 +198,11 @@ def test_convert_cli_updates_py_versions(runner, tmp_path, app_meta):
         )
     }
 
-    app_meta.python_version = [PythonVersion.PY_3_13]
+    app_meta.python_version = PythonVersion.PY_3_13
 
     app_dir = tmp_path / "test_app"
     app_dir.mkdir()
-    (app_dir / "app.json").write_text(app_meta.json())
+    (app_dir / "app.json").write_text(app_meta.model_dump_json())
     (app_dir / app_meta.logo).touch()
     (app_dir / app_meta.logo_dark).touch()
 
@@ -244,7 +244,7 @@ def test_convert_cli_with_default_output(runner, tmp_path, app_meta):
 
     app_dir = tmp_path / "test_app"
     app_dir.mkdir()
-    (app_dir / "app.json").write_text(app_meta.json())
+    (app_dir / "app.json").write_text(app_meta.model_dump_json())
     (app_dir / app_meta.logo).touch()
     (app_dir / app_meta.logo_dark).touch()
 

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/tests/cli/test_deserializers.py

@@ -574,7 +574,7 @@ def test_action_deserializer_with_underscored_params():
         "test_action", {"_underscore": {"data_type": "string"}}
     )
 
-    field = result.__fields__["underscore"]
+    field = result.model_fields["underscore"]
     assert field.alias == "_underscore"
 
 
@@ -717,8 +717,8 @@ def test_parse_parameters_with_complex_params():
     assert "param3" in result.__annotations__
     assert "param4" not in result.__annotations__
 
-    assert "param5" in result.__fields__
-    assert result.__fields__["param5"].alias == "_param5"
+    assert "param5" in result.model_fields
+    assert result.model_fields["param5"].alias == "_param5"
 
 
 def test_complex_output_specification():

{splunk_soar_sdk-3.5.0 → splunk_soar_sdk-3.6.0}/tests/conftest.py

@@ -22,6 +22,7 @@ from soar_sdk.meta.dependencies import (
     UvDependency,
     UvLock,
     UvPackage,
+    UvSource,
     UvSourceDistribution,
     UvWheel,
 )
@@ -308,8 +309,14 @@ def fake_uv_lockfile(fake_wheel) -> UvLock:
                 dependencies=[
                     UvDependency(name="fakepkg"),
                 ],
+                source=UvSource(registry="https://pypi.python.org/simple"),
+            ),
+            UvPackage(
+                name="fakepkg",
+                version="1.0.0",
+                wheels=[fake_wheel],
+                source=UvSource(registry="https://pypi.python.org/simple"),
             ),
-            UvPackage(name="fakepkg", version="1.0.0", wheels=[fake_wheel]),
         ]
     )