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

soar_sdk/meta/app.py

@@ -1,5 +1,4 @@
-from pydantic import BaseModel, Field, validator
-from typing import Optional, Union
+from pydantic import BaseModel, Field, field_validator
 
 from soar_sdk.asset import AssetFieldSpecification
 from soar_sdk.compat import PythonVersion
@@ -42,13 +41,14 @@ class AppMeta(BaseModel):
     configuration: dict[str, AssetFieldSpecification] = Field(default_factory=dict)
     actions: list[ActionMeta] = Field(default_factory=list)
 
-    pip39_dependencies: DependencyList = Field(default_factory=DependencyList)
     pip313_dependencies: DependencyList = Field(default_factory=DependencyList)
+    pip314_dependencies: DependencyList = Field(default_factory=DependencyList)
 
-    webhook: Optional[WebhookMeta]
+    webhook: WebhookMeta | None = None
 
-    @validator("python_version", pre=True)
-    def convert_python_version_to_csv(cls, v: Union[list, str]) -> str:
+    @field_validator("python_version", mode="before")
+    @classmethod
+    def convert_python_version_to_csv(cls, v: list | str) -> str:
         """Converts python_version to a comma-separated string if it's a list and validates versions."""
         if isinstance(v, list):
             # Validate each version in the list and convert to CSV
@@ -64,4 +64,7 @@ class AppMeta(BaseModel):
 
     def to_json_manifest(self) -> dict:
         """Converts the AppMeta instance to a JSON-compatible dictionary."""
-        return self.dict(exclude_none=True)
+        data = self.model_dump(exclude_none=True)
+        # In Pydantic v2 nested model_dump() overrides aren't automatically called
+        data["actions"] = [action.model_dump() for action in self.actions]
+        return data

soar_sdk/meta/dependencies.py

@@ -1,3 +1,4 @@
+import functools
 import io
 import os
 from pathlib import Path
@@ -6,7 +7,7 @@ import tarfile
 from tempfile import TemporaryDirectory
 import build
 
-from typing import Optional
+from typing import ClassVar
 from collections.abc import Mapping, Sequence, AsyncGenerator
 from pydantic import BaseModel, Field
 
@@ -61,22 +62,23 @@ DEPENDENCIES_TO_BUILD = {
 class UvWheel(BaseModel):
     """Represents a Python wheel file with metadata and methods to fetch and validate it."""
 
-    url: str
+    url: str | None = None
+    filename: str | None = None
     hash: str
-    size: Optional[int] = None
+    size: int | None = None
 
     # The wheel file name is specified by PEP427. It's either a 5- or 6-tuple:
     # {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl
     # We can parse this to determine which configurations it supports.
-    @property
+    @functools.cached_property
     def basename(self) -> str:
         """The base name of the wheel file."""
-        remove_when_soar_newer_than(
-            "6.4.0",
-            "We should be able to adopt pydantic 2 now, and turn this into a cached property.",
-        )
-        filename = self.url.split("/")[-1]
-        return filename.removesuffix(".whl")
+        if self.filename:
+            return self.filename.removesuffix(".whl")
+        if self.url:
+            filename = self.url.split("/")[-1]
+            return filename.removesuffix(".whl")
+        raise ValueError("UvWheel must have either url or filename")
 
     @property
     def distribution(self) -> str:
@@ -89,7 +91,7 @@ class UvWheel(BaseModel):
         return self.basename.split("-")[1]
 
     @property
-    def build_tag(self) -> Optional[str]:
+    def build_tag(self) -> str | None:
         """An optional build tag for the wheel."""
         split = self.basename.split("-")
         if len(split) == 6:
@@ -122,6 +124,10 @@ class UvWheel(BaseModel):
 
     async def fetch(self) -> bytes:
         """Download the wheel file from the specified URL."""
+        if self.url is None:
+            raise ValueError(
+                f"Cannot fetch wheel {self.filename or 'unknown'}: no URL provided (local file reference?)"
+            )
         async with httpx.AsyncClient() as client:
             response = await client.get(self.url, timeout=10)
             response.raise_for_status()
@@ -135,7 +141,7 @@ class UvSourceDistribution(BaseModel):
 
     url: str
     hash: str
-    size: Optional[int] = None
+    size: int | None = None
 
     def validate_hash(self, sdist: bytes) -> None:
         """Validate the hash of the downloaded sdist against the expected hash."""
@@ -158,8 +164,8 @@ class UvSourceDistribution(BaseModel):
     @staticmethod
     def _builder_runner(
         cmd: Sequence[str],
-        cwd: Optional[str] = None,
-        extra_environ: Optional[Mapping[str, str]] = None,
+        cwd: str | None = None,
+        extra_environ: Mapping[str, str] | None = None,
     ) -> None:
         """Run a command in a subprocess and return its exit code, stdout, and stderr."""
         proc = subprocess.run(  # noqa: S603
@@ -191,13 +197,13 @@ class DependencyWheel(BaseModel):
 
     module: str
     input_file: str = ""
-    input_file_aarch64: Optional[str] = None
+    input_file_aarch64: str | None = None
 
-    wheel: Optional[UvWheel] = Field(exclude=True, default=None)
-    wheel_aarch64: Optional[UvWheel] = Field(exclude=True, default=None)
-    sdist: Optional[UvSourceDistribution] = Field(exclude=True, default=None)
+    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)
 
-    async def collect_wheels(self) -> AsyncGenerator[tuple[str, bytes], None]:
+    async def collect_wheels(self) -> AsyncGenerator[tuple[str, bytes]]:
         """Collect a list of wheel files to fetch for this dependency across all platforms."""
         if self.wheel is None and self.sdist is not None:
             logger.info(f"Building sdist for {self.input_file}")
@@ -229,7 +235,7 @@ class DependencyWheel(BaseModel):
 
     def __hash__(self) -> int:
         """Compute a hash for the dependency wheel so we can dedupe wheel files in a later step."""
-        return hash((type(self), *tuple(self.dict().items())))
+        return hash((type(self), *tuple(self.model_dump().items())))
 
 
 class DependencyList(BaseModel):
@@ -254,7 +260,7 @@ class UvPackage(BaseModel):
         default_factory=dict, alias="optional-dependencies"
     )
     wheels: list[UvWheel] = []
-    sdist: Optional[UvSourceDistribution] = None
+    sdist: UvSourceDistribution | None = None
 
     def _find_wheel(
         self,
@@ -287,21 +293,21 @@ class UvPackage(BaseModel):
             f"Could not find a suitable wheel for {self.name=}, {self.version=}, {abi_precedence=}, {python_precedence=}, {platform_precedence=}"
         )
 
-    _manylinux_precedence = [
+    _manylinux_precedence: ClassVar[list[str]] = [
         "_2_28",  # glibc 2.28, latest stable version, supports Ubuntu 18.10+ and RHEL/Oracle 8+
         "_2_17",  # glibc 2.17, LTS-ish, supports Ubuntu 13.10+ and RHEL/Oracle 7+
         "2014",  # Synonym for _2_17
     ]
-    platform_precedence_x86_64 = [
+    platform_precedence_x86_64: ClassVar[list[str]] = [
         *[f"manylinux{version}_x86_64" for version in _manylinux_precedence],
         "any",
     ]
-    platform_precedence_aarch64 = [
+    platform_precedence_aarch64: ClassVar[list[str]] = [
         *[f"manylinux{version}_aarch64" for version in _manylinux_precedence],
         "any",
     ]
 
-    build_from_source_warning_triggered = False
+    build_from_source_warning_triggered: bool = False
 
     def _resolve(
         self, abi_precedence: list[str], python_precedence: list[str]
@@ -348,32 +354,32 @@ class UvPackage(BaseModel):
 
         return wheel
 
-    def resolve_py39(self) -> DependencyWheel:
-        """Resolve the dependency wheel for Python 3.9."""
+    def resolve_py313(self) -> DependencyWheel:
+        """Resolve the dependency wheel for Python 3.13."""
         return self._resolve(
             abi_precedence=[
-                "cp39",  # Python 3.9-specific ABI
+                "cp313",  # Python 3.13-specific ABI
                 "abi3",  # Python 3 stable ABI
                 "none",  # Source wheels -- no ABI
             ],
             python_precedence=[
-                "cp39",  # Binary wheel for Python 3.9
-                "pp39",  # Source wheel for Python 3.9
+                "cp313",  # Binary wheel for Python 3.13
+                "pp313",  # Source wheel for Python 3.13
                 "py3",  # Source wheel for any Python 3.x
             ],
         )
 
-    def resolve_py313(self) -> DependencyWheel:
-        """Resolve the dependency wheel for Python 3.13."""
+    def resolve_py314(self) -> DependencyWheel:
+        """Resolve the dependency wheel for Python 3.14."""
         return self._resolve(
             abi_precedence=[
-                "cp313",  # Python 3.13-specific ABI
+                "cp314",  # Python 3.14-specific ABI
                 "abi3",  # Python 3 stable ABI
                 "none",  # Source wheels -- no ABI
             ],
             python_precedence=[
-                "cp313",  # Binary wheel for Python 3.13
-                "pp313",  # Source wheel for Python 3.13
+                "cp314",  # Binary wheel for Python 3.14
+                "pp314",  # Source wheel for Python 3.14
                 "py3",  # Source wheel for any Python 3.x
             ],
         )
@@ -446,21 +452,21 @@ class UvLock(BaseModel):
         packages: list[UvPackage],
     ) -> tuple[DependencyList, DependencyList]:
         """Resolve the dependencies for the given packages."""
-        py39_wheels: list[DependencyWheel] = []
         py313_wheels: list[DependencyWheel] = []
+        py314_wheels: list[DependencyWheel] = []
 
         for package in packages:
-            wheel_39 = package.resolve_py39()
             wheel_313 = package.resolve_py313()
+            wheel_314 = package.resolve_py314()
 
-            if wheel_39 == wheel_313:
-                wheel_39.add_platform_prefix("shared")
+            if wheel_313 == wheel_314:
                 wheel_313.add_platform_prefix("shared")
+                wheel_314.add_platform_prefix("shared")
             else:
-                wheel_39.add_platform_prefix("python39")
                 wheel_313.add_platform_prefix("python313")
+                wheel_314.add_platform_prefix("python314")
 
-            py39_wheels.append(wheel_39)
             py313_wheels.append(wheel_313)
+            py314_wheels.append(wheel_314)
 
-        return DependencyList(wheel=py39_wheels), DependencyList(wheel=py313_wheels)
+        return DependencyList(wheel=py313_wheels), DependencyList(wheel=py314_wheels)

soar_sdk/meta/webhooks.py

@@ -1,6 +1,5 @@
-from pydantic import BaseModel, Field, validator
+from pydantic import BaseModel, Field, field_validator
 from ipaddress import ip_network
-from typing import Optional
 
 
 class WebhookRouteMeta(BaseModel):
@@ -8,25 +7,26 @@ class WebhookRouteMeta(BaseModel):
 
     url_pattern: str
     allowed_methods: list[str] = Field(default_factory=lambda: ["GET", "POST"])
-    declaration_path: Optional[str] = None
-    declaration_lineno: Optional[int] = None
+    declaration_path: str | None = None
+    declaration_lineno: int | None = None
 
 
 class WebhookMeta(BaseModel):
     """Metadata for a complex webhook definition which may contain multiple routes."""
 
-    handler: Optional[str]
+    handler: str | None
     requires_auth: bool = True
     allowed_headers: list[str] = Field(default_factory=list)
     ip_allowlist: list[str] = Field(default_factory=lambda: ["0.0.0.0/0", "::/0"])
     routes: list[WebhookRouteMeta] = Field(default_factory=list)
 
-    @validator("ip_allowlist", each_item=True)
-    def validate_ip_allowlist(cls, value: str) -> str:
+    @field_validator("ip_allowlist")
+    @classmethod
+    def validate_ip_allowlist(cls, value: list[str]) -> list[str]:
         """Enforces all values of the 'ip_allowlist' field are valid IPv4 or IPv6 CIDRs."""
-        try:
-            ip_network(value)
-        except ValueError as e:
-            raise ValueError(f"{value} is not a valid IPv4 or IPv6 CIDR") from e
-
+        for item in value:
+            try:
+                ip_network(item)
+            except ValueError as e:
+                raise ValueError(f"{item} is not a valid IPv4 or IPv6 CIDR") from e
         return value

soar_sdk/models/artifact.py

@@ -1,5 +1,5 @@
-from typing import Optional, Any, Union
-from pydantic import BaseModel
+from typing import Any
+from pydantic import BaseModel, ConfigDict
 
 
 class Artifact(BaseModel):
@@ -8,29 +8,26 @@ class Artifact(BaseModel):
     This class allows users to create artifacts when yielding from an 'on poll' action.
     """
 
-    class Config:
-        """Pydantic config. Unknown keys are disallowed in this model."""
+    model_config = ConfigDict(extra="forbid")
 
-        extra = "forbid"
-
-    name: Optional[str] = None
-    label: Optional[str] = None
-    description: Optional[str] = None
-    type: Optional[str] = None
-    severity: Optional[str] = None
-    source_data_identifier: Optional[str] = None
-    container_id: Optional[int] = None
-    data: Optional[dict[str, Any]] = None
+    name: str | None = None
+    label: str | None = None
+    description: str | None = None
+    type: str | None = None
+    severity: str | None = None
+    source_data_identifier: str | None = None
+    container_id: int | None = None
+    data: dict[str, Any] | None = None
     run_automation: bool = False
-    owner_id: Optional[Union[int, str]] = None
-    cef: Optional[dict[str, Any]] = None
-    cef_types: Optional[dict[str, list[str]]] = None
-    ingest_app_id: Optional[Union[int, str]] = None
-    tags: Optional[Union[list[str], str]] = None
-    start_time: Optional[str] = None
-    end_time: Optional[str] = None
-    kill_chain: Optional[str] = None
+    owner_id: int | str | None = None
+    cef: dict[str, Any] | None = None
+    cef_types: dict[str, list[str]] | None = None
+    ingest_app_id: int | str | None = None
+    tags: list[str] | str | None = None
+    start_time: str | None = None
+    end_time: str | None = None
+    kill_chain: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Convert the artifact to a dictionary (needed for save_artifact)."""
-        return self.dict(exclude_none=True)
+        return self.model_dump(exclude_none=True)

soar_sdk/models/container.py

@@ -1,5 +1,5 @@
-from pydantic import BaseModel
-from typing import Optional, Any, Union
+from pydantic import BaseModel, ConfigDict
+from typing import Any
 
 
 class Container(BaseModel):
@@ -8,40 +8,37 @@ class Container(BaseModel):
     This class allows users to specify container properties when yielding from an on_poll function.
     """
 
-    class Config:
-        """Pydantic config."""
-
-        extra = "forbid"
+    model_config = ConfigDict(extra="forbid")
 
     name: str
-    label: Optional[str] = None
-    description: Optional[str] = None
-    source_data_identifier: Optional[str] = None
-    severity: Optional[str] = None
-    status: Optional[str] = None
-    tags: Optional[Union[list[str], str]] = None
-    owner_id: Optional[Union[int, str]] = None
-    sensitivity: Optional[str] = None
-    artifacts: Optional[list[dict[str, Any]]] = None
-    asset_id: Optional[int] = None
-    close_time: Optional[str] = None
-    custom_fields: Optional[dict[str, Any]] = None
-    data: Optional[dict[str, Any]] = None
-    due_time: Optional[str] = None
-    end_time: Optional[str] = None
-    ingest_app_id: Optional[int] = None
-    kill_chain: Optional[str] = None
-    role_id: Optional[Union[int, str]] = None
+    label: str | None = None
+    description: str | None = None
+    source_data_identifier: str | None = None
+    severity: str | None = None
+    status: str | None = None
+    tags: list[str] | str | None = None
+    owner_id: int | str | None = None
+    sensitivity: str | None = None
+    artifacts: list[dict[str, Any]] | None = None
+    asset_id: int | None = None
+    close_time: str | None = None
+    custom_fields: dict[str, Any] | None = None
+    data: dict[str, Any] | None = None
+    due_time: str | None = None
+    end_time: str | None = None
+    ingest_app_id: int | None = None
+    kill_chain: str | None = None
+    role_id: int | str | None = None
     run_automation: bool = False
-    start_time: Optional[str] = None
-    open_time: Optional[str] = None
-    tenant_id: Optional[Union[int, str]] = None
-    container_type: Optional[str] = None
-    template_id: Optional[int] = None
-    authorized_users: Optional[list[int]] = None
-    artifact_count: Optional[int] = None
-    container_id: Optional[str] = None
+    start_time: str | None = None
+    open_time: str | None = None
+    tenant_id: int | str | None = None
+    container_type: str | None = None
+    template_id: int | None = None
+    authorized_users: list[int] | None = None
+    artifact_count: int | None = None
+    container_id: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Convert the container to a dictionary (needed for save_container)."""
-        return self.dict(exclude_none=True)
+        return self.model_dump(exclude_none=True)

soar_sdk/models/finding.py

@@ -0,0 +1,54 @@
+from pydantic import BaseModel
+from typing import Any
+
+
+class DrilldownSearch(BaseModel):
+    """Represents a drilldown search in a finding."""
+
+    name: str
+    search: str
+    earliest: str
+    latest: str
+
+
+class DrilldownDashboard(BaseModel):
+    """Represents a drilldown dashboard in a finding."""
+
+    dashboard: str
+    name: str
+    tokens: list[str] | None = None
+
+
+class Finding(BaseModel):
+    """Represents a finding to be created during on_finding.
+
+    Findings are stored in ES and can be associated with SOAR containers/artifacts
+    for investigation workflow.
+    """
+
+    class Config:
+        """Pydantic config."""
+
+        extra = "forbid"
+
+    rule_title: str
+    rule_description: str
+    security_domain: str
+    risk_object: str
+    risk_object_type: str
+    risk_score: float
+    status: str | None = None
+    urgency: str | None = None
+    owner: str | None = None
+    disposition: str | None = None
+    drilldown_searches: list[DrilldownSearch] | None = None
+    drilldown_dashboards: list[DrilldownDashboard] | None = None
+    annotations: dict[str, list[str]] | None = None
+    risk_event_count: int | None = None
+    all_risk_objects: list[str] | None = None
+    source: list[str] | None = None
+    exclude_map_fields: list[str] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the finding to a dictionary."""
+        return self.dict(exclude_none=True)

soar_sdk/models/vault_attachment.py

@@ -1,4 +1,4 @@
-from typing import IO, Optional, Union
+from typing import IO
 from pydantic import BaseModel
 
 
@@ -11,15 +11,15 @@ class VaultAttachment(BaseModel):
     """
 
     id: int
-    created_via: Optional[str] = None
+    created_via: str | None = None
     container: str
-    task: Optional[str] = None
+    task: str | None = None
     create_time: str
     name: str
     user: str
     vault_document: int
-    mime_type: Optional[str] = None
-    es_attachment_id: Optional[str] = None
+    mime_type: str | None = None
+    es_attachment_id: str | None = None
     hash: str
     vault_id: str
     size: int
@@ -29,7 +29,7 @@ class VaultAttachment(BaseModel):
     container_id: int
     contains: list[str] = []
 
-    def open(self, mode: str = "r") -> Union[IO[str], IO[bytes]]:
+    def open(self, mode: str = "r") -> IO[str] | IO[bytes]:
         """Open the vault attachment file.
 
         Args:

soar_sdk/models/view.py

@@ -1,5 +1,5 @@
-from typing import Any, Optional, Union
-from pydantic import BaseModel
+from typing import Any
+from pydantic import BaseModel, ConfigDict
 from soar_sdk.action_results import ActionResult
 
 
@@ -10,17 +10,14 @@ class ViewContext(BaseModel):
     container: int
     app: int
     no_connection: bool
-    google_maps_key: Union[bool, str]
-    dark_title_logo: Optional[str] = None
-    title_logo: Optional[str] = None
-    app_name: Optional[str] = None
-    results: Optional[list[dict[str, Any]]] = None
-    html_content: Optional[str] = None
-
-    class Config:
-        """Pydantic config."""
-
-        extra = "allow"
+    google_maps_key: bool | str
+    dark_title_logo: str | None = None
+    title_logo: str | None = None
+    app_name: str | None = None
+    results: list[dict[str, Any]] | None = None
+    html_content: str | None = None
+
+    model_config = ConfigDict(extra="allow")
 
 
 class ResultSummary(BaseModel):