splunk-soar-sdk 2.3.7__py3-none-any.whl → 3.1.0__py3-none-any.whl

soar_sdk/abstract.py

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from typing import Any, Optional, Union, Generic, TypeVar
+from typing import Any, Generic, TypeVar
 from collections.abc import Mapping, Iterable, AsyncIterable
 
 from soar_sdk.apis.vault import Vault
@@ -8,9 +8,9 @@ from soar_sdk.apis.container import Container
 from soar_sdk.action_results import ActionOutput
 import httpx
 from pydantic.dataclasses import dataclass
-from pydantic import validator
+from pydantic import field_validator
 
-JSONType = Union[dict[str, Any], list[Any], str, int, float, bool, None]
+JSONType = dict[str, Any] | list[Any] | str | int | float | bool | None
 SummaryType = TypeVar("SummaryType", bound=ActionOutput)
 
 
@@ -23,7 +23,8 @@ class SOARClientAuth:
     password: str = ""
     user_session_token: str = ""
 
-    @validator("base_url")
+    @field_validator("base_url")
+    @classmethod
     def validate_phantom_url(cls, value: str) -> str:
         """Validate and format the base URL for the SOAR API."""
         return (
@@ -74,13 +75,13 @@ class SOARClient(Generic[SummaryType]):
         self,
         endpoint: str,
         *,
-        params: Optional[Union[dict[str, Any], httpx.QueryParams]] = None,
-        headers: Optional[dict[str, str]] = None,
-        cookies: Optional[dict[str, str]] = None,
-        timeout: Optional[httpx.Timeout] = None,
-        auth: Optional[Union[httpx.Auth, tuple[str, str]]] = None,
+        params: dict[str, Any] | httpx.QueryParams | None = None,
+        headers: dict[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
+        timeout: httpx.Timeout | None = None,
+        auth: httpx.Auth | tuple[str, str] | None = None,
         follow_redirects: bool = False,
-        extensions: Optional[Mapping[str, Any]] = None,
+        extensions: Mapping[str, Any] | None = None,
     ) -> httpx.Response:
         """Perform a GET request to the specific endpoint using the SOAR client."""
         response = self.client.get(
@@ -100,19 +101,17 @@ class SOARClient(Generic[SummaryType]):
         self,
         endpoint: str,
         *,
-        content: Optional[
-            Union[str, bytes, Iterable[bytes], AsyncIterable[bytes]]
-        ] = None,
-        data: Optional[Mapping[str, Any]] = None,
-        files: Optional[dict[str, Any]] = None,
-        json: Optional[JSONType] = None,
-        params: Optional[dict[str, Any]] = None,
-        headers: Optional[dict[str, str]] = None,
-        cookies: Optional[dict[str, str]] = None,
-        auth: Optional[Union[httpx.Auth, tuple[str, str]]] = None,
-        timeout: Optional[Union[float, httpx.Timeout]] = None,
+        content: str | bytes | Iterable[bytes] | AsyncIterable[bytes] | None = None,
+        data: Mapping[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        json: JSONType | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
+        auth: httpx.Auth | tuple[str, str] | None = None,
+        timeout: float | httpx.Timeout | None = None,
         follow_redirects: bool = True,
-        extensions: Optional[Mapping[str, Any]] = None,
+        extensions: Mapping[str, Any] | None = None,
     ) -> httpx.Response:
         """Perform a POST request to the specific endpoint using the SOAR client."""
         headers = headers or {}
@@ -138,19 +137,17 @@ class SOARClient(Generic[SummaryType]):
         self,
         endpoint: str,
         *,
-        content: Optional[
-            Union[str, bytes, Iterable[bytes], AsyncIterable[bytes]]
-        ] = None,
-        data: Optional[Mapping[str, Any]] = None,
-        files: Optional[dict[str, Any]] = None,
-        json: Optional[JSONType] = None,
-        params: Optional[dict[str, Any]] = None,
-        headers: Optional[dict[str, str]] = None,
-        cookies: Optional[dict[str, str]] = None,
-        auth: Optional[Union[httpx.Auth, tuple[str, str]]] = None,
-        timeout: Optional[Union[float, httpx.Timeout]] = None,
+        content: str | bytes | Iterable[bytes] | AsyncIterable[bytes] | None = None,
+        data: Mapping[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        json: JSONType | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
+        auth: httpx.Auth | tuple[str, str] | None = None,
+        timeout: float | httpx.Timeout | None = None,
         follow_redirects: bool = True,
-        extensions: Optional[Mapping[str, Any]] = None,
+        extensions: Mapping[str, Any] | None = None,
     ) -> httpx.Response:
         """Perform a PUT request to the specific endpoint using the SOAR client."""
         headers = headers or {}
@@ -176,13 +173,13 @@ class SOARClient(Generic[SummaryType]):
         self,
         endpoint: str,
         *,
-        params: Optional[Union[dict[str, Any], httpx.QueryParams]] = None,
-        headers: Optional[dict[str, str]] = None,
-        cookies: Optional[dict[str, str]] = None,
-        auth: Optional[Union[httpx.Auth, tuple[str, str]]] = None,
-        timeout: Optional[httpx.Timeout] = None,
+        params: dict[str, Any] | httpx.QueryParams | None = None,
+        headers: dict[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
+        auth: httpx.Auth | tuple[str, str] | None = None,
+        timeout: httpx.Timeout | None = None,
         follow_redirects: bool = False,
-        extensions: Optional[Mapping[str, Any]] = None,
+        extensions: Mapping[str, Any] | None = None,
     ) -> httpx.Response:
         """Perform a DELETE request to the specific endpoint using the SOAR client."""
         headers = headers or {}
@@ -229,7 +226,7 @@ class SOARClient(Generic[SummaryType]):
         pass
 
     @abstractmethod
-    def get_summary(self) -> Optional[SummaryType]:
+    def get_summary(self) -> SummaryType | None:
         """Get the summary for the action run."""
         pass
 

soar_sdk/action_results.py

@@ -1,12 +1,15 @@
-from typing import Optional, Union, get_origin, get_args, Any
+from typing import Union, get_origin, get_args, Any
 from collections.abc import Iterator
-from typing_extensions import NotRequired, TypedDict
-from pydantic import BaseModel, Field
+from typing_extensions import TypedDict
+from typing import NotRequired
+from pydantic import BaseModel, Field, ConfigDict
 import itertools
+import types
 
 from soar_sdk.compat import remove_when_soar_newer_than
 from soar_sdk.shims.phantom.action_result import ActionResult as PhantomActionResult
 from soar_sdk.meta.datatypes import as_datatype
+from soar_sdk.field_utils import parse_json_schema_extra
 
 remove_when_soar_newer_than(
     "7.0.0", "NotRequired from typing_extensions is in typing in Python 3.11+"
@@ -40,7 +43,7 @@ class ActionResult(PhantomActionResult):
         self,
         status: bool,
         message: str,
-        param: Optional[dict] = None,
+        param: dict | None = None,
     ) -> None:
         """Initialize an ActionResult with status, message, and optional parameters.
 
@@ -82,16 +85,16 @@ class OutputFieldSpecification(TypedDict):
     data_path: str
     data_type: str
     contains: NotRequired[list[str]]
-    example_values: NotRequired[list[Union[str, float, bool]]]
+    example_values: NotRequired[list[str | float | bool]]
     column_name: NotRequired[str]
     column_order: NotRequired[int]
 
 
 def OutputField(
-    cef_types: Optional[list[str]] = None,
-    example_values: Optional[list[Union[str, float, bool]]] = None,
-    alias: Optional[str] = None,
-    column_name: Optional[str] = None,
+    cef_types: list[str] | None = None,
+    example_values: list[str | float | bool] | None = None,
+    alias: str | None = None,
+    column_name: str | None = None,
 ) -> Any:  # noqa: ANN401
     """Define metadata for an action output field.
 
@@ -121,11 +124,18 @@ def OutputField(
         ...     )
         ...     count: int = OutputField(example_values=[1, 5, 10])
     """
+    json_schema_extra: dict[str, Any] = {}
+    if cef_types is not None:
+        json_schema_extra["cef_types"] = cef_types
+    if example_values is not None:
+        json_schema_extra["examples"] = example_values
+    if column_name is not None:
+        json_schema_extra["column_name"] = column_name
+
     return Field(
-        examples=example_values,
+        default=...,
         alias=alias,
-        cef_types=cef_types,
-        column_name=column_name,
+        json_schema_extra=json_schema_extra if json_schema_extra else None,
     )
 
 
@@ -158,11 +168,14 @@ class ActionOutput(BaseModel):
         Nested ActionOutput classes are supported for complex data structures.
     """
 
+    # Allow instantiation with both field names and aliases for backward compatibility
+    model_config = ConfigDict(populate_by_name=True)
+
     @classmethod
     def _to_json_schema(
         cls,
         parent_datapath: str = "action_result.data.*",
-        column_order_counter: Optional[itertools.count] = None,
+        column_order_counter: itertools.count | None = None,
     ) -> Iterator[OutputFieldSpecification]:
         """Convert the ActionOutput class to SOAR-compatible JSON schema.
 
@@ -191,15 +204,18 @@ class ActionOutput(BaseModel):
         if column_order_counter is None:
             column_order_counter = itertools.count()
 
-        for _field_name, field in cls.__fields__.items():
+        for _field_name, field in cls.model_fields.items():
             field_name = alias if (alias := field.alias) else _field_name
 
             field_type = field.annotation
+            if field_type is None:
+                continue
+
             datapath = parent_datapath + f".{field_name}"
 
             # Handle lists and optional types, even nested ones
             origin = get_origin(field_type)
-            while origin in [list, Union, Optional]:
+            while origin in [list, Union, types.UnionType]:
                 type_args = [
                     arg
                     for arg in get_args(field_type)
@@ -221,6 +237,11 @@ class ActionOutput(BaseModel):
                 field_type = type_args[0]
                 origin = get_origin(field_type)
 
+            if not isinstance(field_type, type):
+                raise TypeError(
+                    f"Output field {field_name} has invalid type annotation: {field_type}"
+                )
+
             if issubclass(field_type, ActionOutput):
                 # If the field is another ActionOutput, recursively call _to_json_schema
                 yield from field_type._to_json_schema(datapath, column_order_counter)
@@ -237,15 +258,17 @@ class ActionOutput(BaseModel):
                 data_path=datapath, data_type=type_name
             )
 
-            if cef_types := field.field_info.extra.get("cef_types"):
+            json_schema_extra = parse_json_schema_extra(field.json_schema_extra)
+
+            if cef_types := json_schema_extra.get("cef_types"):
                 schema_field["contains"] = cef_types
-            if examples := field.field_info.extra.get("examples"):
+            if examples := json_schema_extra.get("examples"):
                 schema_field["example_values"] = examples
 
             if field_type is bool:
                 schema_field["example_values"] = [True, False]
 
-            column_name = field.field_info.extra.get("column_name")
+            column_name = json_schema_extra.get("column_name")
 
             if column_name is not None:
                 schema_field["column_name"] = column_name

soar_sdk/actions_manager.py

@@ -1,4 +1,4 @@
-from typing import Optional, Any
+from typing import Any
 import os
 
 from soar_sdk.compat import remove_when_soar_newer_than
@@ -31,7 +31,7 @@ class ActionsManager(BaseConnector):
         self.auth_state: dict = {}
         self.asset_cache: dict = {}
 
-    def get_action(self, identifier: str) -> Optional[Action]:
+    def get_action(self, identifier: str) -> Action | None:
         """Convenience method for getting an Action callable from its identifier.
 
         Returns None if there are no actions managed by this object matching the given
@@ -60,14 +60,12 @@ class ActionsManager(BaseConnector):
         """
         self._actions[action_identifier] = wrapped_function
 
-    def handle(
-        self, input_data: InputSpecification, handle: Optional[int] = None
-    ) -> str:
+    def handle(self, input_data: InputSpecification, handle: int | None = None) -> str:
         """Runs handling of the input data on connector."""
         action_id = input_data.identifier
         if self.get_action(action_id):
             self.print_progress_message = True
-            return self._handle_action(input_data.json(), handle or 0)
+            return self._handle_action(input_data.model_dump_json(), handle or 0)
         else:
             raise RuntimeError(
                 f"Action {action_id} not recognized"
@@ -86,7 +84,7 @@ class ActionsManager(BaseConnector):
 
         if handler := self.get_action(action_id):
             try:
-                params = handler.meta.parameters.parse_obj(param)
+                params = handler.meta.parameters.model_validate(param)
             except (ValueError, ValidationError) as e:
                 self.save_progress(
                     f"Validation Error - the params data for action could not be parsed: {e!s}"

soar_sdk/apis/utils.py

@@ -1,5 +1,5 @@
 import httpx
-from typing import Optional, Any
+from typing import Any
 from collections.abc import Generator
 
 
@@ -11,9 +11,9 @@ def is_client_authenticated(client: httpx.Client) -> bool:
 def get_request_iter_pages(
     client: httpx.Client,
     endpoint: str,
-    params: Optional[dict] = None,
+    params: dict | None = None,
     page_size: int = 50,
-) -> Generator[Any, None, None]:
+) -> Generator[Any]:
     """Iterate through REST JSON results using the provided paging."""
     params = params or {}
 

soar_sdk/apis/vault.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING
 from soar_sdk.models.vault_attachment import VaultAttachment
 from soar_sdk.shims.phantom.vault import PhantomVault, VaultBase
 
@@ -47,9 +47,9 @@ class Vault:
     def create_attachment(
         self,
         container_id: int,
-        file_content: Union[str, bytes],
+        file_content: str | bytes,
         file_name: str,
-        metadata: Optional[dict[str, str]] = None,
+        metadata: dict[str, str] | None = None,
     ) -> str:
         """Create a vault attachment from file content.
 
@@ -87,7 +87,7 @@ class Vault:
         container_id: int,
         file_location: str,
         file_name: str,
-        metadata: Optional[dict[str, str]] = None,
+        metadata: dict[str, str] | None = None,
     ) -> str:
         """Add an existing file to the vault as an attachment.
 
@@ -121,9 +121,9 @@ class Vault:
 
     def get_attachment(
         self,
-        vault_id: Optional[str] = None,
-        file_name: Optional[str] = None,
-        container_id: Optional[int] = None,
+        vault_id: str | None = None,
+        file_name: str | None = None,
+        container_id: int | None = None,
     ) -> list[VaultAttachment]:
         """Retrieve attachment(s) from the vault.
 
@@ -161,9 +161,9 @@ class Vault:
 
     def delete_attachment(
         self,
-        vault_id: Optional[str] = None,
-        file_name: Optional[str] = None,
-        container_id: Optional[int] = None,
+        vault_id: str | None = None,
+        file_name: str | None = None,
+        container_id: int | None = None,
         remove_all: bool = False,
     ) -> list[str]:
         """Delete attachment(s) from the vault.

soar_sdk/app.py

@@ -3,7 +3,8 @@ import inspect
 import json
 from pathlib import Path
 import sys
-from typing import Any, Optional, Union, Callable
+from typing import Any
+from collections.abc import Callable
 from collections.abc import Iterator
 from zoneinfo import ZoneInfo
 
@@ -101,7 +102,7 @@ class App:
         product_name: str,
         publisher: str,
         appid: str,
-        python_version: Optional[Union[list[PythonVersion], str]] = None,
+        python_version: list[PythonVersion] | str | None = None,
         min_phantom_version: str = MIN_PHANTOM_VERSION,
         fips_compliant: bool = False,
         asset_cls: type[BaseAsset] = BaseAsset,
@@ -164,13 +165,13 @@ class App:
         runner = AppCliRunner(self)
         runner.run()
 
-    def handle(self, raw_input_data: str, handle: Optional[int] = None) -> str:
+    def handle(self, raw_input_data: str, handle: int | None = None) -> str:
         """Runs handling of the input data on connector.
 
         NOTE: handle is actually a pointer address to spawn's internal state.
         In versions of SOAR >6.4.1, handle will not be passed to the app.
         """
-        input_data = InputSpecification.parse_obj(json.loads(raw_input_data))
+        input_data = InputSpecification.model_validate(json.loads(raw_input_data))
         self._raw_asset_config = input_data.config.get_asset_config()
 
         # Decrypt sensitive fields in the asset configuration
@@ -221,27 +222,27 @@ class App:
     def asset(self) -> BaseAsset:
         """Returns the asset instance for the app."""
         if not hasattr(self, "_asset"):
-            self._asset = self.asset_cls.parse_obj(self._raw_asset_config)
+            self._asset = self.asset_cls.model_validate(self._raw_asset_config)
         return self._asset
 
     def register_action(
         self,
         /,
-        action: Union[str, Callable],
+        action: str | Callable,
         *,
-        name: Optional[str] = None,
-        identifier: Optional[str] = None,
-        description: Optional[str] = None,
+        name: str | None = None,
+        identifier: str | None = None,
+        description: str | None = None,
         verbose: str = "",
         action_type: str = "generic",  # TODO: consider introducing enum type for that
         read_only: bool = True,
-        params_class: Optional[type[Params]] = None,
-        output_class: Optional[type[ActionOutput]] = None,
-        render_as: Optional[str] = None,
-        view_handler: Union[str, Callable, None] = None,
-        view_template: Optional[str] = None,
+        params_class: type[Params] | None = None,
+        output_class: type[ActionOutput] | None = None,
+        render_as: str | None = None,
+        view_handler: str | Callable | None = None,
+        view_template: str | None = None,
         versions: str = "EQ(*)",
-        summary_type: Optional[type[ActionOutput]] = None,
+        summary_type: type[ActionOutput] | None = None,
         enable_concurrency_lock: bool = False,
     ) -> Action:
         """Dynamically register an action function defined in another module.
@@ -415,18 +416,18 @@ class App:
     def action(
         self,
         *,
-        name: Optional[str] = None,
-        identifier: Optional[str] = None,
-        description: Optional[str] = None,
+        name: str | None = None,
+        identifier: str | None = None,
+        description: str | None = None,
         verbose: str = "",
         action_type: str = "generic",  # TODO: consider introducing enum type for that
         read_only: bool = True,
-        params_class: Optional[type[Params]] = None,
-        output_class: Optional[type[ActionOutput]] = None,
-        render_as: Optional[str] = None,
-        view_handler: Optional[Callable] = None,
+        params_class: type[Params] | None = None,
+        output_class: type[ActionOutput] | None = None,
+        render_as: str | None = None,
+        view_handler: Callable | None = None,
         versions: str = "EQ(*)",
-        summary_type: Optional[type[ActionOutput]] = None,
+        summary_type: type[ActionOutput] | None = None,
         enable_concurrency_lock: bool = False,
     ) -> ActionDecorator:
         """Decorator for registering an action function.
@@ -497,7 +498,7 @@ class App:
     def view_handler(
         self,
         *,
-        template: Optional[str] = None,
+        template: str | None = None,
     ) -> ViewHandlerDecorator:
         """Decorator for custom view functions with output parsing and template rendering.
 
@@ -525,7 +526,7 @@ class App:
         return ViewHandlerDecorator(self, template=template)
 
     def make_request(
-        self, output_class: Optional[type[ActionOutput]] = None
+        self, output_class: type[ActionOutput] | None = None
     ) -> MakeRequestDecorator:
         """Decorator for registering a ``make request`` action function.
 
@@ -556,7 +557,7 @@ class App:
     def _validate_params_class(
         action_name: str,
         spec: inspect.FullArgSpec,
-        params_class: Optional[type[Params]] = None,
+        params_class: type[Params] | None = None,
     ) -> type[Params]:
         """Validates the class used for params argument of the action.
 
@@ -572,7 +573,7 @@ class App:
                     "Action function must accept at least the params positional argument"
                 )
             params_arg = spec.args[0]
-            annotated_params_type: Optional[type] = spec.annotations.get(params_arg)
+            annotated_params_type: type | None = spec.annotations.get(params_arg)
             if annotated_params_type is None:
                 raise TypeError(
                     f"Action {action_name} has no params type set. "
@@ -594,7 +595,7 @@ class App:
         """
         # The reason we wrap values in callables is to avoid evaluating any lazy attributes
         # (like asset) unless they're actually going to be used in the action function.
-        magic_args: dict[str, Union[object, Callable[[], object]]] = {
+        magic_args: dict[str, object | Callable[[], object]] = {
             "soar": self.soar_client,
             "asset": lambda: self.asset,
         }
@@ -626,18 +627,16 @@ class App:
 
     @staticmethod
     def _adapt_action_result(
-        result: Union[
-            ActionOutput,
-            ActionResult,
-            list[ActionOutput],
-            Iterator[ActionOutput],
-            tuple[bool, str],
-            bool,
-        ],
+        result: ActionOutput
+        | ActionResult
+        | list[ActionOutput]
+        | Iterator[ActionOutput]
+        | tuple[bool, str]
+        | bool,
         actions_manager: ActionsManager,
-        action_params: Optional[Params] = None,
+        action_params: Params | None = None,
         message: str = "",
-        summary: Optional[ActionOutput] = None,
+        summary: ActionOutput | None = None,
     ) -> bool:
         """Handles multiple ways of returning response from action.
 
@@ -657,13 +656,21 @@ class App:
                 )
             # Handle empty list/iterator case
             if not statuses:
-                result = ActionOutput(status=True, message=message)
+                # Create ActionResult directly for empty list
+                param_dict = action_params.model_dump() if action_params else None
+                result = ActionResult(
+                    status=True,
+                    message=message,
+                    param=param_dict,
+                )
+                if summary:
+                    result.set_summary(summary.model_dump(by_alias=True))
             else:
                 return all(statuses)
 
         if isinstance(result, ActionOutput):
-            output_dict = result.dict(by_alias=True)
-            param_dict = action_params.dict() if action_params else None
+            output_dict = result.model_dump(by_alias=True)
+            param_dict = action_params.model_dump() if action_params else None
 
             result = ActionResult(
                 status=True,
@@ -672,7 +679,7 @@ class App:
             )
             result.add_data(output_dict)
             if summary:
-                result.set_summary(summary.dict(by_alias=True))
+                result.set_summary(summary.model_dump(by_alias=True))
 
         if isinstance(result, ActionResult):
             actions_manager.add_result(result)
@@ -695,14 +702,14 @@ class App:
 
             pytest.mark.skip(inner)
 
-    webhook_meta: Optional[WebhookMeta] = None
-    webhook_router: Optional[Router] = None
+    webhook_meta: WebhookMeta | None = None
+    webhook_router: Router | None = None
 
     def enable_webhooks(
         self,
         default_requires_auth: bool = True,
-        default_allowed_headers: Optional[list[str]] = None,
-        default_ip_allowlist: Optional[list[str]] = None,
+        default_allowed_headers: list[str] | None = None,
+        default_ip_allowlist: list[str] | None = None,
     ) -> "App":
         """Enable webhook functionality for the app.
 
@@ -731,7 +738,7 @@ class App:
             default_ip_allowlist = ["0.0.0.0/0", "::/0"]
 
         self.webhook_meta = WebhookMeta(
-            handler=None,  # The handler is set by the ManifestProcessor when generating the final manifest
+            handler=None,
             requires_auth=default_requires_auth,
             allowed_headers=default_allowed_headers,
             ip_allowlist=default_ip_allowlist,
@@ -742,7 +749,7 @@ class App:
         return self
 
     def webhook(
-        self, url_pattern: str, allowed_methods: Optional[list[str]] = None
+        self, url_pattern: str, allowed_methods: list[str] | None = None
     ) -> WebhookDecorator:
         """Decorator for registering a webhook handler."""
         return WebhookDecorator(self, url_pattern, allowed_methods)
@@ -752,8 +759,8 @@ class App:
         method: str,
         headers: dict[str, str],
         path_parts: list[str],
-        query: dict[str, Union[str, list[str], None]],
-        body: Optional[str],
+        query: dict[str, str | list[str] | None],
+        body: str | None,
         asset: dict,
         soar_rest_client: SoarRestClient,
     ) -> dict:
@@ -801,4 +808,4 @@ class App:
             raise TypeError(
                 f"Webhook handler must return a WebhookResponse, got {type(response)}"
             )
-        return response.dict()
+        return response.model_dump()