splunk-soar-sdk 3.8.1__tar.gz → 3.9.0__tar.gz

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunk-soar-sdk
-Version: 3.8.1
+Version: 3.9.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-3.8.1 → splunk_soar_sdk-3.9.0}/docs/api_reference.rst

@@ -51,6 +51,11 @@ AssetField
 
 .. autofunction:: soar_sdk.asset.AssetField
 
+.. note::
+   The ``required`` keyword argument is deprecated and will be removed in the next
+   major version. Prefer Optional type hints (``str | None``) to indicate optional
+   asset fields.
+
 BaseAsset
 ^^^^^^^^^
 
@@ -101,6 +106,11 @@ For example, let's give the ``uid`` field a Common Event Format (CEF) type and m
       is_admin: bool
       uid: int = Param(required=False, cef_types=["user id"])
 
+.. note::
+   The ``required`` keyword argument is deprecated and will be removed in the next
+   major version. Prefer Optional type hints (``str | None``) to indicate optional
+   action parameters.
+
 Defining Parameters
 ^^^^^^^^^^^^^^^^^^^
 

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/pyproject.toml

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

splunk_soar_sdk-3.9.0/release_notes.txt

@@ -0,0 +1,33 @@
+# [3.9.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.8.2...3.9.0) (2026-02-03)
+
+
+### Bug Fixes
+
+* allow optional type annotations in params/fields ([8b4ab75](https://github.com/phantomcyber/splunk-soar-sdk/commit/8b4ab75419241949baa93c67fea3c218c20956c8))
+* don't render required=True because it's redundant ([7fe4842](https://github.com/phantomcyber/splunk-soar-sdk/commit/7fe4842d1822e007e9ccf44e07a5575ab023bba7))
+
+
+### Features
+
+* use new union syntax for soarapps convert ([121020e](https://github.com/phantomcyber/splunk-soar-sdk/commit/121020ec6465d2ce7fce4dda862d961feafe024f))
+
+
+
+
+
+# [3.9.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.8.2...3.9.0) (2026-02-03)
+
+
+### Bug Fixes
+
+* allow optional type annotations in params/fields ([8b4ab75](https://github.com/phantomcyber/splunk-soar-sdk/commit/8b4ab75419241949baa93c67fea3c218c20956c8))
+* don't render required=True because it's redundant ([7fe4842](https://github.com/phantomcyber/splunk-soar-sdk/commit/7fe4842d1822e007e9ccf44e07a5575ab023bba7))
+
+
+### Features
+
+* use new union syntax for soarapps convert ([121020e](https://github.com/phantomcyber/splunk-soar-sdk/commit/121020ec6465d2ce7fce4dda862d961feafe024f))
+
+
+
+

splunk_soar_sdk-3.9.0/release_version.txt

@@ -0,0 +1 @@
+3.9.0

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/src/soar_sdk/action_results.py

@@ -1,13 +1,12 @@
 import itertools
-import types
 from collections.abc import Iterator
-from typing import Any, NotRequired, Union, get_args, get_origin
+from typing import Any, NotRequired
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from typing_extensions import TypedDict
 
 from soar_sdk.compat import remove_when_soar_newer_than
-from soar_sdk.field_utils import parse_json_schema_extra
+from soar_sdk.field_utils import normalize_field_annotation, parse_json_schema_extra
 from soar_sdk.meta.datatypes import as_datatype
 from soar_sdk.shims.phantom.action_result import ActionResult as PhantomActionResult
 
@@ -164,13 +163,32 @@ class ActionOutput(BaseModel):
         ...     )  # Model fields can't start with an underscore, so we're using an alias to create the proper JSON key
 
     Note:
-        Fields cannot be Union or Optional types. Use specific types only.
+        Fields cannot be Union types other than Optional.
         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)
 
+    @model_validator(mode="before")
+    @classmethod
+    def _apply_optional_defaults(cls, values: Any) -> Any:  # noqa: ANN401
+        """Populate missing optional fields with ``None`` before validation."""
+        for field_name, field in cls.model_fields.items():
+            if field_name in values or (field.alias and field.alias in values):
+                continue
+
+            normalized = normalize_field_annotation(
+                field.annotation,
+                field_name=field_name,
+                context="Output",
+                allow_list=True,
+            )
+            if normalized.is_optional:
+                values[field_name] = None
+
+        return values
+
     @classmethod
     def _to_json_schema(
         cls,
@@ -193,7 +211,7 @@ class ActionOutput(BaseModel):
             OutputFieldSpecification objects describing each field in the schema.
 
         Raises:
-            TypeError: If a field type cannot be serialized, is Union/Optional,
+            TypeError: If a field type cannot be serialized, is an unsupported Union,
                 or if a nested ActionOutput type is encountered incorrectly.
 
         Note:
@@ -211,36 +229,18 @@ class ActionOutput(BaseModel):
             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, types.UnionType]:
-                type_args = [
-                    arg
-                    for arg in get_args(field_type)
-                    if arg is not type(None) and arg is not None
-                ]
-
-                if origin is list:
-                    if len(type_args) != 1:
-                        raise TypeError(
-                            f"Output field {field_name} is invalid: List types must have exactly one non-null type argument."
-                        )
-                    datapath += ".*"
-                else:
-                    if len(type_args) != 1:
-                        raise TypeError(
-                            f"Output field {field_name} is invalid: the only valid Union type is Optional, or Union[X, None]."
-                        )
-
-                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}"
-                )
+            normalized = normalize_field_annotation(
+                field_type,
+                field_name=field_name,
+                context="Output",
+                allow_list=True,
+            )
+
+            datapath = (
+                parent_datapath + f".{field_name}" + (".*" * normalized.list_depth)
+            )
+
+            field_type = normalized.base_type
 
             if issubclass(field_type, ActionOutput):
                 # If the field is another ActionOutput, recursively call _to_json_schema

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/src/soar_sdk/asset.py

@@ -9,7 +9,11 @@ from typing_extensions import TypedDict
 from soar_sdk.asset_state import AssetState
 from soar_sdk.compat import remove_when_soar_newer_than
 from soar_sdk.exceptions import AppContextRequired
-from soar_sdk.field_utils import parse_json_schema_extra
+from soar_sdk.field_utils import (
+    normalize_field_annotation,
+    parse_json_schema_extra,
+    resolve_required,
+)
 from soar_sdk.input_spec import AppConfig
 from soar_sdk.meta.datatypes import as_datatype
 
@@ -28,7 +32,7 @@ class FieldCategory(str, Enum):
 
 def AssetField(
     description: str | None = None,
-    required: bool = True,
+    required: bool | None = None,
     default: Any | None = None,  # noqa: ANN401
     value_list: list | None = None,
     sensitive: bool = False,
@@ -41,7 +45,9 @@ def AssetField(
     Args:
         description: Human-friendly label for the field shown in the asset form.
         required: Whether the field must be provided. When True and ``default`` is
-            ``None``, the field is marked as required in the manifest.
+            ``None``, the field is marked as required in the manifest. Deprecated:
+            this will be removed in the next major version. Prefer Optional type
+            hints (``str | None``) to indicate optional fields.
         default: Default value for optional fields. Ignored when ``required`` is
             True and no explicit default is provided.
         value_list: Optional dropdown options presented to the user.
@@ -65,13 +71,20 @@ def AssetField(
         json_schema_extra["is_file"] = True
 
     # Use ... for required fields
-    field_default: Any = ... if default is None and required else default
+    field_default: Any = (
+        ... if default is None and (required is True or required is None) else default
+    )
+    validate_default = None
+    if required is False and default is None:
+        # Preserve legacy optional behavior for non-optional type hints
+        validate_default = False
 
     return Field(
         default=field_default,
         description=description,
         alias=alias,
         json_schema_extra=json_schema_extra,
+        validate_default=validate_default,
     )
 
 
@@ -137,6 +150,25 @@ class BaseAsset(BaseModel):
         arbitrary_types_allowed=True,
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _apply_optional_defaults(cls, values: Any) -> Any:  # noqa: ANN401
+        """Populate missing optional fields with ``None`` before validation."""
+        for field_name, field in cls.model_fields.items():
+            if field_name in values or (field.alias and field.alias in values):
+                continue
+
+            normalized = normalize_field_annotation(
+                field.annotation,
+                field_name=field_name,
+                context="Asset field",
+                allow_list=False,
+            )
+            if normalized.is_optional:
+                values[field_name] = None
+
+        return values
+
     @model_validator(mode="before")
     @classmethod
     def validate_no_reserved_fields(cls, values: dict[str, Any]) -> dict[str, Any]:
@@ -211,8 +243,15 @@ class BaseAsset(BaseModel):
             if field_type is None:
                 continue
 
+            normalized = normalize_field_annotation(
+                field_type,
+                field_name=field_name,
+                context="Asset field",
+                allow_list=False,
+            )
+
             try:
-                type_name = as_datatype(field_type)
+                type_name = as_datatype(normalized.base_type)
             except TypeError as e:
                 raise TypeError(
                     f"Failed to serialize asset field {field_name}: {e}"
@@ -221,16 +260,16 @@ class BaseAsset(BaseModel):
             json_schema_extra = parse_json_schema_extra(field.json_schema_extra)
 
             if json_schema_extra.get("sensitive", False):
-                if field_type is not str:
+                if normalized.base_type is not str:
                     raise TypeError(
-                        f"Sensitive parameter {field_name} must be type str, not {field_type.__name__}"
+                        f"Sensitive parameter {field_name} must be type str, not {normalized.base_type.__name__}"
                     )
                 type_name = "password"
 
             if json_schema_extra.get("is_file", False):
-                if field_type is not str:
+                if normalized.base_type is not str:
                     raise TypeError(
-                        f"File parameter {field_name} must be type str, not {field_type.__name__}"
+                        f"File parameter {field_name} must be type str, not {normalized.base_type.__name__}"
                     )
                 type_name = "file"
 
@@ -239,7 +278,7 @@ class BaseAsset(BaseModel):
 
             params_field = AssetFieldSpecification(
                 data_type=type_name,
-                required=bool(json_schema_extra.get("required", True)),
+                required=resolve_required(json_schema_extra, normalized.is_optional),
                 description=description,
                 order=field_order,
                 category=json_schema_extra.get("category", FieldCategory.CONNECTIVITY),
@@ -300,3 +339,29 @@ class BaseAsset(BaseModel):
         if self._ingest_state is None:
             raise AppContextRequired()
         return self._ingest_state
+
+
+class ESIngestMixin:
+    """Mixin for apps that support ES polling (on_es_poll).
+
+    Add this mixin to your Asset class to include ES Ingest Settings fields.
+    These fields are configured in the ES UI and control how findings are created.
+
+    Example:
+        >>> class Asset(BaseAsset, ESIngestMixin):
+        ...     server: str = AssetField(description="API server URL")
+        ...     api_key: str = AssetField(description="API key", sensitive=True)
+    """
+
+    es_security_domain: str = AssetField(
+        required=False,
+        description="Security domain for ES findings",
+        default="threat",
+        category=FieldCategory.INGEST,
+    )
+    es_urgency: str = AssetField(
+        required=False,
+        description="Urgency level for ES findings",
+        default="medium",
+        category=FieldCategory.INGEST,
+    )

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/src/soar_sdk/cli/manifests/serializers.py

@@ -4,7 +4,7 @@ from logging import getLogger
 from typing import Any
 
 from soar_sdk.action_results import ActionOutput, OutputFieldSpecification
-from soar_sdk.field_utils import parse_json_schema_extra
+from soar_sdk.field_utils import normalize_field_annotation, parse_json_schema_extra
 from soar_sdk.meta.datatypes import as_datatype
 from soar_sdk.params import Params
 
@@ -42,9 +42,18 @@ class OutputsSerializer:
             if annotation is None:
                 continue
 
+            normalized = normalize_field_annotation(
+                annotation,
+                field_name=field_name,
+                context="Action parameter",
+                allow_list=False,
+            )
+
+            parameter_name = field.alias or field_name
+
             spec = OutputFieldSpecification(
-                data_path=f"action_result.parameter.{field_name}",
-                data_type=as_datatype(annotation),
+                data_path=f"action_result.parameter.{parameter_name}",
+                data_type=as_datatype(normalized.base_type),
             )
 
             json_schema_extra = parse_json_schema_extra(field.json_schema_extra)

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/src/soar_sdk/code_renderers/action_renderer.py

@@ -1,5 +1,4 @@
 import ast
-import typing
 from collections.abc import Iterator
 from typing import ClassVar
 
@@ -8,7 +7,11 @@ from pydantic_core import PydanticUndefined
 from soar_sdk.action_results import ActionOutput
 from soar_sdk.cli.utils import normalize_field_name
 from soar_sdk.code_renderers.renderer import AstRenderer
-from soar_sdk.field_utils import parse_json_schema_extra
+from soar_sdk.field_utils import (
+    normalize_field_annotation,
+    parse_json_schema_extra,
+    resolve_required,
+)
 from soar_sdk.meta.actions import ActionMeta
 from soar_sdk.params import Params
 
@@ -171,6 +174,23 @@ class ActionRenderer(AstRenderer[ActionMeta]):
         """
         return self.context
 
+    @staticmethod
+    def _build_annotation(base_type: type, list_depth: int, required: bool) -> ast.expr:
+        annotation: ast.expr = ast.Name(id=base_type.__name__, ctx=ast.Load())
+        for _ in range(list_depth):
+            annotation = ast.Subscript(
+                value=ast.Name(id="list", ctx=ast.Load()),
+                slice=annotation,
+                ctx=ast.Load(),
+            )
+        if not required:
+            annotation = ast.BinOp(
+                left=annotation,
+                op=ast.BitOr(),
+                right=ast.Constant(value=None),
+            )
+        return annotation
+
     def render_ast(self) -> Iterator[ast.stmt]:
         """Generates the AST for the action.
 
@@ -284,16 +304,15 @@ class ActionRenderer(AstRenderer[ActionMeta]):
             if annotation is None:
                 continue
 
-            annotation_str = "{name}"
-            while typing.get_origin(annotation) is list:
-                annotation_str = f"list[{annotation_str}]"
-                annotation = typing.get_args(annotation)[0]
-
-            # Ensure annotation is a valid type after unwrapping
-            if not isinstance(annotation, type):
-                continue
+            normalized = normalize_field_annotation(
+                annotation,
+                field_name=field_name_str,
+                context="Output",
+                allow_list=True,
+            )
 
-            annotation_str = annotation_str.format(name=annotation.__name__)
+            json_schema_extra = parse_json_schema_extra(field.json_schema_extra)
+            required = resolve_required(json_schema_extra, normalized.is_optional)
 
             field_name = normalize_field_name(field_name_str)
             if field.alias is not None and field.alias != field_name.normalized:
@@ -302,14 +321,16 @@ class ActionRenderer(AstRenderer[ActionMeta]):
 
             field_def_ast = ast.AnnAssign(
                 target=ast.Name(id=field_name.normalized, ctx=ast.Store()),
-                annotation=ast.Name(id=annotation_str, ctx=ast.Load()),
+                annotation=self._build_annotation(
+                    normalized.base_type, normalized.list_depth, required
+                ),
                 simple=1,
             )
 
-            if isinstance(annotation, type) and issubclass(annotation, ActionOutput):
+            if issubclass(normalized.base_type, ActionOutput):
                 # If the field is a Pydantic model, recursively print its fields
                 # In Pydantic v2, use annotation directly (no field.type_)
-                for model_ast in self.render_outputs_ast(annotation):
+                for model_ast in self.render_outputs_ast(normalized.base_type):
                     model_tree[model_ast.name] = model_ast
 
                 if field_name.modified:
@@ -325,7 +346,7 @@ class ActionRenderer(AstRenderer[ActionMeta]):
                     )
             else:
                 keywords = []
-                extras = {**parse_json_schema_extra(field.json_schema_extra)}
+                extras = {**json_schema_extra}
 
                 if extras or field_name.modified:
                     extras["example_values"] = extras.pop("examples", None)
@@ -388,7 +409,18 @@ class ActionRenderer(AstRenderer[ActionMeta]):
             if field_def.annotation is None:
                 continue
 
-            field_type = ast.Name(id=field_def.annotation.__name__, ctx=ast.Load())
+            normalized = normalize_field_annotation(
+                field_def.annotation,
+                field_name=field_name,
+                context="Action parameter",
+                allow_list=False,
+            )
+
+            json_schema_extra = parse_json_schema_extra(field_def.json_schema_extra)
+            required = resolve_required(json_schema_extra, normalized.is_optional)
+            field_type = self._build_annotation(
+                normalized.base_type, normalized.list_depth, required
+            )
 
             param = ast.Call(
                 func=ast.Name(id="Param", ctx=ast.Load()),
@@ -396,8 +428,6 @@ class ActionRenderer(AstRenderer[ActionMeta]):
                 keywords=[],
             )
 
-            json_schema_extra = parse_json_schema_extra(field_def.json_schema_extra)
-
             if field_def.description:
                 param.keywords.append(
                     ast.keyword(
@@ -405,10 +435,6 @@ class ActionRenderer(AstRenderer[ActionMeta]):
                         value=ast.Constant(value=field_def.description),
                     )
                 )
-            if not json_schema_extra.get("required", True):
-                param.keywords.append(
-                    ast.keyword(arg="required", value=ast.Constant(value=False))
-                )
             if json_schema_extra.get("primary", False):
                 param.keywords.append(
                     ast.keyword(arg="primary", value=ast.Constant(value=True))
@@ -445,6 +471,14 @@ class ActionRenderer(AstRenderer[ActionMeta]):
                     ast.keyword(arg="allow_list", value=ast.Constant(value=True))
                 )
 
+            if field_def.alias and field_def.alias != field_name:
+                param.keywords.append(
+                    ast.keyword(
+                        arg="alias",
+                        value=ast.Constant(value=field_def.alias),
+                    )
+                )
+
             field_def_ast = ast.AnnAssign(
                 target=ast.Name(id=field_name, ctx=ast.Store()),
                 annotation=field_type,

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/src/soar_sdk/code_renderers/asset_renderer.py

@@ -56,11 +56,15 @@ class AssetRenderer(AstRenderer[list[AssetContext]]):
 
         for field in self.context:
             field_name = ast.Name(id=field.name, ctx=ast.Store())
-            field_type = ast.Name(id=field.py_type, ctx=ast.Load())
+            field_type: ast.expr = ast.Name(id=field.py_type, ctx=ast.Load())
+            if not field.required:
+                field_type = ast.BinOp(
+                    left=field_type,
+                    op=ast.BitOr(),
+                    right=ast.Constant(value=None),
+                )
 
-            field_kwargs = [
-                ast.keyword(arg="required", value=ast.Constant(value=field.required)),
-            ]
+            field_kwargs = []
             if field.description is not None:
                 field_kwargs.append(
                     ast.keyword(

splunk_soar_sdk-3.9.0/src/soar_sdk/field_utils.py

@@ -0,0 +1,92 @@
+import types
+from dataclasses import dataclass
+from typing import Any, Union, get_args, get_origin
+
+
+def parse_json_schema_extra(json_schema_extra: Any) -> dict[str, Any]:  # noqa: ANN401
+    """Extract json_schema_extra as a dict, handling both dict and callable forms."""
+    if callable(json_schema_extra):
+        return {}
+    return json_schema_extra or {}
+
+
+@dataclass(frozen=True)
+class NormalizedFieldType:
+    """Normalized field annotation details."""
+
+    base_type: type
+    list_depth: int
+    is_optional: bool
+
+
+def normalize_field_annotation(
+    annotation: Any,  # noqa: ANN401
+    *,
+    field_name: str,
+    context: str,
+    allow_list: bool,
+) -> NormalizedFieldType:
+    """Normalize an annotation by unwrapping Optional and list types.
+
+    Args:
+        annotation: The field annotation to normalize.
+        field_name: Name of the field for error reporting.
+        context: Context string for error reporting (e.g., "parameter").
+        allow_list: Whether list types are allowed.
+
+    Returns:
+        NormalizedFieldType describing the base type, list nesting, and optionality.
+
+    Raises:
+        TypeError: If unsupported unions or list shapes are encountered.
+    """
+    list_depth = 0
+    is_optional = False
+
+    while True:
+        origin = get_origin(annotation)
+        if origin is list:
+            type_args = get_args(annotation)
+            if len(type_args) != 1:
+                raise TypeError(
+                    f"{context} field {field_name} is invalid: list types must have exactly one type argument."
+                )
+            list_depth += 1
+            annotation = type_args[0]
+            continue
+
+        if origin in (types.UnionType, Union):
+            # types.UnionType is for `X | Y` (Python 3.10+)
+            type_args = tuple(
+                arg for arg in get_args(annotation) if arg is not type(None)
+            )
+            if len(type_args) != 1:
+                raise TypeError(
+                    f"{context} field {field_name} is invalid: only Optional[T] is supported for unions."
+                )
+            is_optional = True
+            annotation = type_args[0]
+            continue
+
+        break
+
+    if list_depth and not allow_list:
+        raise TypeError(
+            f"{context} field {field_name} is invalid: list types are not supported."
+        )
+
+    if not isinstance(annotation, type):
+        raise TypeError(
+            f"{context} field {field_name} has invalid type annotation: {annotation}"
+        )
+
+    return NormalizedFieldType(
+        base_type=annotation, list_depth=list_depth, is_optional=is_optional
+    )
+
+
+def resolve_required(json_schema_extra: dict[str, Any], is_optional: bool) -> bool:
+    """Resolve required flag using JSON schema metadata and optionality."""
+    if "required" in json_schema_extra:
+        return bool(json_schema_extra.get("required"))
+    return not is_optional

{splunk_soar_sdk-3.8.1 → splunk_soar_sdk-3.9.0}/src/soar_sdk/models/finding.py

@@ -21,20 +21,26 @@ class DrilldownDashboard(BaseModel):
 
 
 class Finding(BaseModel):
-    """Represents a finding to be created during on_finding.
+    """Represents a finding to be created during on_es_poll.
 
     Findings are stored in ES and can be associated with SOAR containers/artifacts
     for investigation workflow.
+
+    Only rule_title and security_domain are required. All other fields are optional
+    and will use ES defaults if not provided.
     """
 
     model_config = ConfigDict(extra="forbid")
 
+    # Required fields
     rule_title: str
-    rule_description: str
     security_domain: str
-    risk_object: str
-    risk_object_type: str
-    risk_score: float
+
+    # Optional fields
+    rule_description: str | None = None
+    risk_object: str | None = None
+    risk_object_type: str | None = None
+    risk_score: float | None = None
     status: str | None = None
     urgency: str | None = None
     owner: str | None = None