splunk-soar-sdk 3.6.1__tar.gz → 3.7.0__tar.gz

{splunk_soar_sdk-3.6.1 → splunk_soar_sdk-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunk-soar-sdk
-Version: 3.6.1
+Version: 3.7.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
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.13
+Requires-Dist: authlib>=1.3.0
 Requires-Dist: beautifulsoup4>=4.10.0
 Requires-Dist: bleach>=6.2.0
 Requires-Dist: build>=1.3.0
@@ -29,6 +30,7 @@ Requires-Dist: humanize>=4.12.2
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: packaging>=25.0
 Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyjwt[crypto]>=2.8.0
 Requires-Dist: requests<3
 Requires-Dist: setuptools>=80.9.0
 Requires-Dist: toml<1,>=0.10.2

splunk_soar_sdk-3.7.0/docs/authentication/basic.rst

@@ -0,0 +1,18 @@
+.. _basic_auth:
+
+Basic Authentication
+====================
+
+For APIs that use HTTP Basic Authentication (username/password):
+
+.. code-block:: python
+
+    from soar_sdk.auth import BasicAuth
+    import httpx
+
+    auth = BasicAuth(asset.username, asset.password)
+
+    with httpx.Client(auth=auth) as client:
+        response = client.get("https://api.example.com/data")
+
+This sends the ``Authorization: Basic <base64(username:password)>`` header with each request.

splunk_soar_sdk-3.7.0/docs/authentication/index.rst

@@ -0,0 +1,13 @@
+.. _authentication:
+
+Authentication
+==============
+
+These pages cover authentication mechanisms supported by the SDK for integrating with external services.
+
+.. toctree::
+   :maxdepth: 2
+
+   basic
+   static_token
+   oauth

splunk_soar_sdk-3.7.0/docs/authentication/oauth.rst

@@ -0,0 +1,168 @@
+.. _oauth:
+
+OAuth 2.0 Authentication
+========================
+
+The SDK provides OAuth 2.0 support for SOAR connectors, with automatic token management and secure storage.
+
+Supported Flows
+---------------
+
+- **Authorization Code** (with PKCE support) - For user-delegated access
+- **Client Credentials** - For service-to-service authentication
+- **Certificate-based** - For certificate authentication (e.g., Microsoft Entra ID)
+
+Client Credentials Flow
+-----------------------
+
+The simplest flow for service accounts:
+
+.. code-block:: python
+
+    from soar_sdk.auth import ClientCredentialsFlow
+
+    flow = ClientCredentialsFlow(
+        auth_state=asset.auth_state,
+        client_id=asset.client_id,
+        client_secret=asset.client_secret,
+        token_endpoint="https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
+        scope=["https://graph.microsoft.com/.default"],
+    )
+
+    token = flow.get_token()
+
+Authorization Code Flow
+-----------------------
+
+For user-delegated access requiring browser authorization:
+
+.. code-block:: python
+
+    from soar_sdk.auth import AuthorizationCodeFlow
+
+    flow = AuthorizationCodeFlow(
+        auth_state=asset.auth_state,
+        asset_id=soar.get_asset_id(),
+        client_id=asset.client_id,
+        client_secret=asset.client_secret,
+        authorization_endpoint=asset.auth_url,
+        token_endpoint=asset.token_url,
+        redirect_uri=app.get_webhook_url("oauth_callback"),
+        scope=["openid", "profile", "email"],
+        use_pkce=True,
+    )
+
+    auth_url = flow.get_authorization_url()
+    logger.progress(f"Please authorize: {auth_url}")
+    token = flow.wait_for_authorization()
+
+Using with HTTPX
+----------------
+
+For automatic token injection in HTTP requests, use ``create_oauth_client``:
+
+.. code-block:: python
+
+    from soar_sdk.auth import create_oauth_client
+
+    with create_oauth_client(asset) as client:
+        response = client.get("https://api.example.com/resource")
+
+The factory infers ``client_id``, ``client_secret``, and ``token_endpoint`` from common
+asset field names and returns a fully configured ``httpx.Client``.
+
+For more control over the client, you can pass additional httpx options:
+
+.. code-block:: python
+
+    with create_oauth_client(asset, timeout=60.0, follow_redirects=True) as client:
+        response = client.get("https://api.example.com/resource")
+
+If you need just the auth handler (e.g., for async clients), use ``create_oauth_auth``:
+
+.. code-block:: python
+
+    from soar_sdk.auth import create_oauth_auth
+    import httpx
+
+    auth = create_oauth_auth(asset)
+
+    with httpx.Client(auth=auth) as client:
+        response = client.get("https://api.example.com/resource")
+
+For custom configuration:
+
+.. code-block:: python
+
+    from soar_sdk.auth import OAuthBearerAuth, OAuthConfig, SOARAssetOAuthClient
+
+    config = OAuthConfig(
+        client_id=asset.client_id,
+        client_secret=asset.client_secret,
+        token_endpoint=asset.token_url,
+        scope=["custom_scope"],
+    )
+    oauth_client = SOARAssetOAuthClient(config, asset.auth_state)
+    auth = OAuthBearerAuth(oauth_client)
+
+The auth handler automatically:
+
+- Fetches tokens on first request
+- Refreshes expired tokens when a refresh token is available
+- Retries on 401 responses
+
+Token Storage
+-------------
+
+Tokens are automatically stored in the asset's ``auth_state`` and encrypted at rest. The SDK handles:
+
+- Token persistence across action runs
+- Automatic refresh when tokens expire
+- Credential change detection (forces re-authorization if client_id changes)
+
+Certificate-based Authentication
+---------------------------------
+
+For certificate-based authentication (e.g., Microsoft Entra ID):
+
+.. code-block:: python
+
+    from soar_sdk.auth import CertificateCredentials, CertificateOAuthClient, OAuthConfig
+
+    config = OAuthConfig(
+        client_id=asset.client_id,
+        token_endpoint=f"https://login.microsoftonline.com/{asset.tenant_id}/oauth2/v2.0/token",
+        scope=["https://graph.microsoft.com/.default"],
+    )
+
+    certificate = CertificateCredentials(
+        certificate_thumbprint=asset.cert_thumbprint,
+        private_key=asset.private_key,
+    )
+
+    client = CertificateOAuthClient(config, asset.auth_state, certificate)
+    token = client.fetch_token_with_certificate()
+
+OAuth Callback Webhook
+----------------------
+
+For Authorization Code flow, register a webhook to receive the OAuth callback.
+Use ``create_oauth_callback_handler`` to reduce boilerplate:
+
+.. code-block:: python
+
+    from soar_sdk.auth import create_oauth_callback_handler, OAuthConfig, SOARAssetOAuthClient
+
+    def get_oauth_client(asset: Asset) -> SOARAssetOAuthClient:
+        config = OAuthConfig(
+            client_id=asset.client_id,
+            client_secret=asset.client_secret,
+            token_endpoint=asset.token_url,
+        )
+        return SOARAssetOAuthClient(config, asset.auth_state)
+
+    @app.webhook("oauth_callback")
+    def oauth_callback(request: WebhookRequest[Asset]) -> WebhookResponse:
+        return create_oauth_callback_handler(get_oauth_client)(request)
+
+The factory handles error checking, code extraction, and success responses automatically.

splunk_soar_sdk-3.7.0/docs/authentication/static_token.rst

@@ -0,0 +1,46 @@
+.. _static_token:
+
+Static Token Authentication
+===========================
+
+For APIs that use API keys or pre-obtained tokens, use ``StaticTokenAuth`` with httpx:
+
+.. code-block:: python
+
+    from soar_sdk.auth import StaticTokenAuth
+    import httpx
+
+    auth = StaticTokenAuth(asset.api_key)
+
+    with httpx.Client(auth=auth) as client:
+        response = client.get("https://api.example.com/data")
+
+Custom Token Types
+------------------
+
+By default, tokens are sent as ``Bearer`` tokens. For APIs that use different token types:
+
+.. code-block:: python
+
+    # For APIs expecting "ApiKey" prefix
+    auth = StaticTokenAuth(asset.api_key, token_type="ApiKey")
+
+    # For APIs expecting "Token" prefix
+    auth = StaticTokenAuth(asset.api_key, token_type="Token")
+
+This sends the header as ``Authorization: ApiKey <token>`` or ``Authorization: Token <token>``.
+
+Custom Header Names
+-------------------
+
+For APIs that expect tokens in headers other than ``Authorization``:
+
+.. code-block:: python
+
+    # For APIs using X-API-Key header
+    auth = StaticTokenAuth(asset.api_key, header_name="X-API-Key", token_type="")
+
+    # For SOAR's ph-auth-token header
+    auth = StaticTokenAuth(asset.token, header_name="ph-auth-token", token_type="")
+
+Setting ``token_type=""`` sends the raw token without a prefix.

{splunk_soar_sdk-3.6.1 → splunk_soar_sdk-3.7.0}/docs/index.rst

@@ -48,6 +48,7 @@ Contents
    getting_started/index
    app_structure/index
    custom_views/index
+   authentication/index
    api_reference
    cli_reference
    changelog

{splunk_soar_sdk-3.6.1 → splunk_soar_sdk-3.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "splunk-soar-sdk"
-version = "3.6.1"
+version = "3.7.0"
 description = "The official framework for developing and testing Splunk SOAR Apps"
 readme = "README.md"
 requires-python = ">=3.13, <3.15"
@@ -46,6 +46,9 @@ dependencies = [
     "setuptools>=80.9.0",
     "httpx-retries>=0.4.5",
     "hatchling>=1.28.0",
+    # OAuth 2.0 support
+    "authlib>=1.3.0",
+    "pyjwt[crypto]>=2.8.0",
 ]
 
 [project.urls]

splunk_soar_sdk-3.7.0/release_notes.txt

@@ -0,0 +1,41 @@
+# [3.7.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.6.1...3.7.0) (2025-12-18)
+
+
+### Bug Fixes
+
+* cleanup webhook port access and webhook state storage ([54da088](https://github.com/phantomcyber/splunk-soar-sdk/commit/54da0889cf1b5202194964f5ac1b1adb744141d3))
+* cleanup webhook state access ([0cdf11e](https://github.com/phantomcyber/splunk-soar-sdk/commit/0cdf11e568bffffe9b80160dfd051f383c19d307))
+* improve webhook state access ([9d3b650](https://github.com/phantomcyber/splunk-soar-sdk/commit/9d3b650dc349395937d07d1c481ed84c605f0f2d))
+
+
+### Features
+
+* add a category to asset fields ([8e03fa5](https://github.com/phantomcyber/splunk-soar-sdk/commit/8e03fa5289c93213ac02286a4f9f5dd1ee00bc1a))
+* add other auth types to standardize sdk authorization ([7a1b753](https://github.com/phantomcyber/splunk-soar-sdk/commit/7a1b7531a34c94c6a15f4d446e517fa62c06467c))
+* implement sdk oauth flow ([31396fb](https://github.com/phantomcyber/splunk-soar-sdk/commit/31396fb14ff42145f9a56692b1817d4f9abb24a0))
+* improve webhook redirect url generation and usage ([cfbc0f0](https://github.com/phantomcyber/splunk-soar-sdk/commit/cfbc0f02096593af7caf39866431957876a707bc))
+
+
+
+
+
+# [3.7.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/3.6.1...3.7.0) (2025-12-18)
+
+
+### Bug Fixes
+
+* cleanup webhook port access and webhook state storage ([54da088](https://github.com/phantomcyber/splunk-soar-sdk/commit/54da0889cf1b5202194964f5ac1b1adb744141d3))
+* cleanup webhook state access ([0cdf11e](https://github.com/phantomcyber/splunk-soar-sdk/commit/0cdf11e568bffffe9b80160dfd051f383c19d307))
+* improve webhook state access ([9d3b650](https://github.com/phantomcyber/splunk-soar-sdk/commit/9d3b650dc349395937d07d1c481ed84c605f0f2d))
+
+
+### Features
+
+* add a category to asset fields ([8e03fa5](https://github.com/phantomcyber/splunk-soar-sdk/commit/8e03fa5289c93213ac02286a4f9f5dd1ee00bc1a))
+* add other auth types to standardize sdk authorization ([7a1b753](https://github.com/phantomcyber/splunk-soar-sdk/commit/7a1b7531a34c94c6a15f4d446e517fa62c06467c))
+* implement sdk oauth flow ([31396fb](https://github.com/phantomcyber/splunk-soar-sdk/commit/31396fb14ff42145f9a56692b1817d4f9abb24a0))
+* improve webhook redirect url generation and usage ([cfbc0f0](https://github.com/phantomcyber/splunk-soar-sdk/commit/cfbc0f02096593af7caf39866431957876a707bc))
+
+
+
+

splunk_soar_sdk-3.7.0/release_version.txt

@@ -0,0 +1 @@
+3.7.0

{splunk_soar_sdk-3.6.1 → splunk_soar_sdk-3.7.0}/src/soar_sdk/actions_manager.py

@@ -1,4 +1,7 @@
+import json
 import os
+import shutil
+import tempfile
 from pathlib import Path
 from typing import Any
 
@@ -135,3 +138,40 @@ class ActionsManager(BaseConnector):
         This is useful for contexts such as Webhooks, where the app dir isn't necessarily the cwd, but we still need to load the app JSON reliably.
         """
         self.__app_dir = app_dir
+
+    def _get_state_file_path(self, asset_id: str) -> Path:
+        """Get the state file path for an asset."""
+        return Path(self.get_state_dir()) / f"{asset_id}_state.json"
+
+    def load_state_from_file(self, asset_id: str) -> dict:
+        """Load state directly from file."""
+        state_file = self._get_state_file_path(asset_id)
+        if state_file.exists():
+            return json.loads(state_file.read_text())
+        return {}
+
+    def save_state_to_file(self, asset_id: str, state: dict) -> None:
+        """Save state directly to file using atomic write."""
+        state_file = self._get_state_file_path(asset_id)
+        state_file.parent.mkdir(parents=True, exist_ok=True)
+
+        fd, tmp_path = tempfile.mkstemp(dir=state_file.parent)
+        tmp_file = Path(tmp_path)
+        try:
+            with os.fdopen(fd, "w") as f:
+                f.write(json.dumps(state))
+            shutil.move(tmp_file, state_file)
+        except Exception:
+            if tmp_file.exists():
+                tmp_file.unlink()
+            raise
+
+    def reload_state_from_file(self, asset_id: str) -> dict:
+        """Reload state from file and update in-memory state.
+
+        Needed for OAuth flow where one process (webhook) updates the state file and another process (action) needs to see those changes.
+        """
+        state = self.load_state_from_file(asset_id)
+        if state:
+            self.save_state(state)
+        return state

{splunk_soar_sdk-3.6.1 → splunk_soar_sdk-3.7.0}/src/soar_sdk/app.py

@@ -6,6 +6,7 @@ import uuid
 from collections.abc import Callable, Iterator
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlparse
 from zoneinfo import ZoneInfo
 
 from soar_sdk.abstract import SOARClient, SOARClientAuth
@@ -226,12 +227,16 @@ class App:
             self._asset = self.asset_cls.model_validate(self._raw_asset_config)
 
             asset_id = self.soar_client.get_asset_id()
-            self._asset._auth_state = AssetState(self.actions_manager, "auth", asset_id)
+            app_id = str(self.app_meta_info["appid"])
+
+            self._asset._auth_state = AssetState(
+                self.actions_manager, "auth", asset_id, app_id=app_id
+            )
             self._asset._cache_state = AssetState(
-                self.actions_manager, "cache", asset_id
+                self.actions_manager, "cache", asset_id, app_id=app_id
             )
             self._asset._ingest_state = AssetState(
-                self.actions_manager, "ingest", asset_id
+                self.actions_manager, "ingest", asset_id, app_id=app_id
             )
         return self._asset
 
@@ -789,6 +794,47 @@ class App:
         """Decorator for registering a webhook handler."""
         return WebhookDecorator(self, url_pattern, allowed_methods)
 
+    def get_webhook_url(self, route: str) -> str:
+        """Build the full URL for a webhook route (used for OAuth flow)."""
+        system_info = self.soar_client.get("rest/system_info").json()
+        base_url = system_info.get("base_url", "").rstrip("/")
+        parsed = urlparse(base_url)
+
+        webhook_port = self._get_webhook_port()
+        webhook_base = f"{parsed.scheme}://{parsed.hostname}:{webhook_port}"
+
+        config = self.actions_manager.get_config()
+        directory = config.get(
+            "directory", f"{self.app_meta_info['name']}_{self.app_meta_info['appid']}"
+        )
+        asset_id = str(self.soar_client.get_asset_id())
+
+        return f"{webhook_base}/webhook/{directory}/{asset_id}/{route}"
+
+    def _get_webhook_port(self) -> int:
+        """Get the webhook port from the feature flag configuration."""
+        try:
+            response = self.soar_client.get("rest/feature_flag/webhooks")
+            if response.status_code == 200:
+                data = response.json()
+                config = data.get("config", {})
+                if port := config.get("webhooks_port"):
+                    return int(port)
+        except Exception:  # noqa: S110
+            pass
+        return 3500
+
+    def _load_webhook_state(self, asset_id: str) -> None:
+        """Load state from file for webhooks."""
+        state = self.actions_manager.load_state_from_file(asset_id)
+        if state:
+            self.actions_manager.save_state(state)
+
+    def _save_webhook_state(self, asset_id: str) -> None:
+        """Save state to file for webhooks."""
+        state = self.actions_manager.load_state() or {}
+        self.actions_manager.save_state_to_file(asset_id, state)
+
     def handle_webhook(
         self,
         method: str,
@@ -813,7 +859,7 @@ class App:
             user_session_token=soar_auth_token,
             base_url=soar_base_url,
         )
-        self.soar_client.update_client(soar_auth, asset_id)
+        self.soar_client.update_client(soar_auth, str(asset_id))
 
         normalized_query = {}
         for key, value in query.items():
@@ -829,6 +875,7 @@ class App:
 
         self.actions_manager.override_app_dir(self.app_root)
         self.actions_manager._load_app_json()
+        self._load_webhook_state(str(asset_id))
         request = WebhookRequest(
             method=method,
             headers=headers,
@@ -846,4 +893,5 @@ class App:
             raise TypeError(
                 f"Webhook handler must return a WebhookResponse, got {type(response)}"
             )
+        self._save_webhook_state(str(asset_id))
         return response.model_dump()