splunk-soar-sdk 2.3.6__py3-none-any.whl → 3.0.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,6 +1,7 @@
-from typing import Optional, Any
+from typing import Any
 import os
 
+from soar_sdk.compat import remove_when_soar_newer_than
 from soar_sdk.input_spec import InputSpecification
 from soar_sdk.shims.phantom.base_connector import BaseConnector
 
@@ -8,13 +9,9 @@ from soar_sdk.meta.actions import ActionMeta
 from soar_sdk.types import Action
 from pydantic import ValidationError
 from soar_sdk.shims.phantom.action_result import ActionResult as PhantomActionResult
+from soar_sdk.shims.phantom.install_info import is_onprem_broker_install
 from soar_sdk.logging import getLogger
 
-try:
-    from phantom_common import install_info
-except ImportError:
-    install_info = None
-
 
 _INGEST_STATE_KEY = "ingestion_state"
 _AUTH_STATE_KEY = "auth_state"
@@ -34,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
@@ -63,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"
@@ -89,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}"
@@ -150,8 +145,10 @@ class ActionsManager(BaseConnector):
 
         Returns APP_HOME directly on brokers, which contains the correct SDK app path.
         """
+        # Remove when 7.1.0 is the min supported broker version
+        remove_when_soar_newer_than("7.1.1")
         # On AB, APP_HOME is set by spawn to the full app path at runtime
-        if install_info and install_info.is_onprem_broker_install():
+        if is_onprem_broker_install():
             return os.getenv("APP_HOME", "")
 
         # For non-broker just proceed as we did before

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.