splunk-soar-sdk 1.4.1__tar.gz → 1.5.1__tar.gz

{splunk_soar_sdk-1.4.1 → splunk_soar_sdk-1.5.1}/.pre-commit-config.yaml

@@ -34,6 +34,13 @@ repos:
         additional_dependencies: [tomli]
         verbose: true
 
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+
   - repo: local
     hooks:
       - id: uv-lock

{splunk_soar_sdk-1.4.1 → splunk_soar_sdk-1.5.1}/PKG-INFO

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

@@ -5,7 +5,7 @@ API Reference
 
 This section documents the public API of the Splunk SOAR SDK.
 
-Jump to a section:
+Jump to a Section:
 ------------------
 
 - :ref:`api_ref_core_label`
@@ -13,6 +13,7 @@ Jump to a section:
 - :ref:`asset-configuration-label`
 - :ref:`action-param-label`
 - :ref:`action-output-label`
+- :ref:`soar-client-label`
 - :ref:`api_ref_apis_label`
 - :ref:`api_ref_data_models_label`
 - :ref:`api_ref_logging_label`
@@ -64,7 +65,7 @@ BaseAsset
 Action Parameters
 ~~~~~~~~~~~~~~~~~
 
-Action parameters are defined in Pydantic models, which extend the ``soar_sdk.params.Params`` class.
+Action parameters are defined in Pydantic models, which extend the :class:`soar_sdk.params.Params` class.
 At their most basic, parameters can have a simple data type such as ``str`` or ``int``.
 
 .. code-block:: python
@@ -81,10 +82,10 @@ At their most basic, parameters can have a simple data type such as ``str`` or `
       uid: int
 
 
-Adding extra metadata
+Adding Extra Metadata
 ^^^^^^^^^^^^^^^^^^^^^
 
-You can use the ``Param`` function to add extra information to a parameter type.
+You can use the :func:`~soar_sdk.params.Param` function to add extra information to a parameter type.
 For example, let's give the ``uid`` field a Common Event Format (CEF) type and make it optional.
 
 .. code-block:: python
@@ -100,20 +101,21 @@ 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"])
 
-For a full list of Param options, see the ``Params`` class and ``Param`` function below:
+Defining Parameters
+^^^^^^^^^^^^^^^^^^^
 
 .. autoclass:: soar_sdk.params.Params
 
 .. autofunction:: soar_sdk.params.Param
 
-Parameters for on poll
-^^^^^^^^^^^^^^^^^^^^^^
+Parameters For ``on poll``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 On poll functions require a specific parameter class called `OnPollParams`. YYou should use this class as-is, instead of overriding it.
 
 .. autoclass:: soar_sdk.params.OnPollParams
 
-Parameters for generic action
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Parameters for the Generic Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Generic action functions require a specific parameter class called `GenericActionParams`. You should use this class as-is, instead of overriding it.
 
 .. autoclass:: soar_sdk.params.GenericActionParams
@@ -124,9 +126,9 @@ Generic action functions require a specific parameter class called `GenericActio
 Action Outputs
 ~~~~~~~~~~~~~~
 
-Action outputs are defined in Pydantic models, which extend the ``soar_sdk.action_results.ActionOutput`` class.
+Action outputs are defined in Pydantic models, which extend the :class:`~soar_sdk.action_results.ActionOutput` class.
 
-Much like parameters, outputs can have simple data types such as ``str`` or ``int``, or be annotated with the ``OutputField`` function to add extra metadata.
+Much like parameters, outputs can have simple data types such as ``str`` or ``int``, or be annotated with the :func:`~soar_sdk.action_results.OutputField` function to add extra metadata.
 
 .. code-block:: python
 
@@ -154,7 +156,7 @@ Output models can be nested, allowing you to create complex data structures:
    class ListUsersOutput(ActionOutput):
       users: list[UserDetails]
 
-You can add summary data and a result message to your action, by calling `client.set_message` and `client.set_summary`. Summary objects are also subclasses of `ActionOutput`, and you must register them in your action decorator:
+You can add summary data and a result message to your action, by calling :func:`soar_sdk.abstract.SOARClient.set_message` and :func:`soar_sdk.abstract.SOARClient.set_summary`. Summary objects are also subclasses of :class:`~soar_sdk.action_results.ActionOutput`, and you must register them in your action decorator:
 
 .. code-block:: python
 
@@ -174,7 +176,8 @@ You can add summary data and a result message to your action, by calling `client
        return ListUsersOutput(users=users)
 
 
-For more details, see the ``ActionOutput`` class and the ``OutputField`` function below:
+Defining Action Outputs
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. autoclass:: soar_sdk.action_results.ActionOutput
 
@@ -186,6 +189,16 @@ For generic action functions we have provided a convenience class called `Generi
 
 .. autoclass:: soar_sdk.action_results.GenericActionOutput
 
+.. _soar-client-label:
+
+SOARClient
+~~~~~~~~~~~
+
+The ``SOARClient`` class is an app's gateway to the Splunk SOAR platform APIs. It provides methods for creating and manipulating platform objects such as containers, artifacts, and vault items.
+
+.. autoclass:: soar_sdk.abstract.SOARClient
+   :show-inheritance:
+
 .. _api_ref_apis_label:
 
 APIs

{splunk_soar_sdk-1.4.1 → splunk_soar_sdk-1.5.1}/docs/app_structure/index.rst

@@ -1,6 +1,6 @@
 .. _app-structure:
 
-App structure
+App Structure
 =============
 
 In these documentation pages you will find detailed information on the contents of the basic/default app files.

{splunk_soar_sdk-1.4.1 → splunk_soar_sdk-1.5.1}/docs/app_structure/pre-commit-config.yaml.rst

@@ -1,7 +1,7 @@
 .. _app-structure-pre-commit:
 
 ``.pre-commit-config.yaml``
-==========================
+===========================
 
 This file is the official configuration file for the `pre-commit <https://pre-commit.com>`_ tool. It adds some automation to
 the process of committing changes when developing the app, and is a required file for all app repos in the official Splunk SOAR app Github organization. ``pre-commit`` is a framework for managing and maintaining multi-language pre-commit hooks. It helps ensure that code meets certain standards before it is committed to a repository, such as formatting, linting, and static security checks.

{splunk_soar_sdk-1.4.1 → splunk_soar_sdk-1.5.1}/docs/app_structure/src_app.rst

@@ -19,14 +19,14 @@ Here's an example ``app.py`` file which uses a wide variety of the features avai
    :language: python
    :linenos:
 
-Components of the ``app.py`` file
+Components of the ``app.py`` File
 ---------------------------------
 
 Let's dive deeper into each part of the ``app.py`` file above:
 
 .. _app-structure-logger-init:
 
-Logger initialization
+Logger Initialization
 ~~~~~~~~~~~~~~~~~~~~~
 
 .. literalinclude:: ../../tests/example_app/src/app.py
@@ -47,7 +47,7 @@ When running locally via the CLI, all log messages are printed to the console, i
 
 .. _app-structure-asset-def:
 
-Asset definition
+Asset Definition
 ~~~~~~~~~~~~~~~~
 
 .. literalinclude:: ../../tests/example_app/src/app.py
@@ -60,7 +60,7 @@ Apps should define an asset class to hold configuration information for the app.
 
 .. _app-structure-app-init:
 
-App initialization
+App Initialization
 ~~~~~~~~~~~~~~~~~~
 
 .. literalinclude:: ../../tests/example_app/src/app.py
@@ -74,25 +74,111 @@ This is how you initialize the basic :class:`~soar_sdk.app.App` instance. The ap
 
 .. _app-structure-actions-def:
 
-Actions definitions
-~~~~~~~~~~~~~~~~~~~
+Action Definitions
+~~~~~~~~~~~~~~~~~~
+
+Actions are defined as standalone functions, with a few important rules and recommendations.
+
+Action Metadata
+^^^^^^^^^^^^^^^
+
+Action definition carry with them important metadata which is used by the Splunk SOAR platform to present the action in the UI, and to generate the app's manifest. Often, this metadata can be derived automatically from the action function's signature:
+
+- The action's "identifier" is, by default, the name of the action function (e.g. ``my_action``).
+- The action's "name" is, by default, the action function's name with spaces instead of underscores (e.g. ``my action``).
+- The action's "description" is, by default, the action function's docstring.
+- The action's "type" is, by default, ``generic`` unless the action is one of the reserved names like ``test connectivity`` or ``on poll``.
+
+.. note::
+    By convention, action names should be lowercase, with 2-3 words. Keep action names short but descriptive, and avoid using the name of the app or external service in action names. Where feasible, it's recommended to consider reusing action names across different apps (e.g. ``get email``) to provide a more consistent user experience.
+
+.. _app-structure-actions-args:
+
+Action Arguments
+^^^^^^^^^^^^^^^^
 
-action anatomy
+There is a magic element, similar to `pytest fixtures <https://docs.pytest.org/en/stable/how-to/fixtures.html#requesting-fixtures>`_, in the action arguments. The type hints for the argument definitions of an action function are critical to this mechanism. The rules are as follows:
+
+- The first positional argument of an action function must be the ``params`` argument, and its type hint must be a `Pydantic model <https://docs.pydantic.dev/1.10/usage/models/#basic-model-usage>`_ inheriting from :class:`~soar_sdk.params.Params`. The position and type of this argument are required. The name ``params`` is a convention, but not strictly required.
+- If an action function has any argument named ``soar``, at runtime the SDK will provide an instance of a :class:`~soar_sdk.abstract.SOARClient` implementation as that argument, which is already authenticated with Splunk SOAR. The type hint for this argument should be :class:`~soar_sdk.abstract.SOARClient`.
+- If an action function has any argument named ``asset``, at runtime the SDK will provide an instance of the app's asset class, populated with the asset configuration for the current action run. The type hint for this argument should be the app's asset class.
+
+.. note::
+    The special actions which define their own decorators have stricter rules about the type of the ``params`` argument. For example, the ``on poll`` action must take an :class:`~soar_sdk.params.OnPollParams` instance as its ``params`` argument, and ``test connectivity`` must take no ``params`` argument at all.
+
+.. _app-structure-action-returns:
+
+Action Returns
 ^^^^^^^^^^^^^^
 
-Actions are defined as standalone functions, which typically take arguments:
+An action's return type annotation is critical for the Splunk SOAR platform to understand, via datapaths, what an action's output looks like. In practice, this means that you must define a class inheriting from :class:`~soar_sdk.action_results.ActionOutput` to represent the action's output, and then return an instance of that class from your action function:
 
-- ``params`` - a `pydantic model <https://docs.pydantic.dev/1.10/usage/models/#basic-model-usage>`_ class inheriting from :class:`~soar_sdk.params.Params`.
-- ``soar`` - Optional, an instance of the :class:`~soar_sdk.abstract.SOARClient` implementation providing APIs for interacting with the Splunk SOAR platform.
-- ``asset`` - Optional, an instance of the app's asset class, populated with the asset configuration for the current action run.
+.. code-block:: python
 
-The action's type hints are required by the SDK; the type hint for the ``params`` argument, as well as the action's return type (which must be a `pydantic model <https://docs.pydantic.dev/1.10/usage/models/#basic-model-usage>`_ class inheriting from :class:`~soar_sdk.action_results.ActionOutput`), are used to generate the action's datapaths in the manifest.
+    from soar_sdk.action_results import ActionOutput
 
+    class MyActionOutput(ActionOutput):
+        field1: str
+        field2: int
 
-Similarly, the action function's docstring is used to generate the action's description in the manifest and the Splunk SOAR platform UI. Also, the type hints for the ``soar`` and ``asset`` arguments are used at runtime to dynamically inject the appropriate arguments when the action is executed.
+    @app.action()
+    def my_action(params: MyActionParams) -> MyActionOutput:
+        # action logic here
+        return MyActionOutput(field1="value", field2=42)
 
-test connectivity action
-^^^^^^^^^^^^^^^^^^^^^^^^
+Advanced Return Types
+*********************
+
+For more advanced use cases, an action's return type can be a ``list``, ``Iterator``, or ``AsyncGenerator`` that yields multiple :class:`~soar_sdk.action_results.ActionOutput` objects:
+
+.. tab-set::
+    .. tab-item:: ``list``
+
+        .. code-block:: python
+
+            @app.action()
+            def my_action_list(params: MyActionParams) -> list[MyActionOutput]:
+                # action logic here
+                return [
+                    MyActionOutput(field1="value1", field2=1),
+                    MyActionOutput(field1="value2", field2=2)
+                ]
+
+    .. tab-item:: ``Iterator``
+
+        .. code-block:: python
+
+            from typing import Iterator
+
+            @app.action()
+            def my_action_iterator(params: MyActionParams) -> Iterator[MyActionOutput]:
+                # action logic here
+                yield MyActionOutput(field1="value1", field2=1)
+                yield MyActionOutput(field1="value2", field2=2)
+
+
+    .. tab-item:: ``AsyncGenerator``
+
+        .. code-block:: python
+
+            from typing import AsyncGenerator
+
+            @app.action()
+            async def my_action_async_generator(
+                params: MyActionParams,
+                asset: Asset,
+            ) -> AsyncGenerator[MyActionOutput]:
+                async with client = httpx.AsyncClient() as client:
+                    async for i in range(10):
+                        response = await client.get(
+                            f"{asset.base_url}/data",
+                            params={"page": i}
+                        )
+                        yield MyActionOutput(**response.json())
+
+
+``test connectivity`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. literalinclude:: ../../tests/example_app/src/app.py
     :caption: Test connectivity action definition
@@ -100,7 +186,7 @@ test connectivity action
     :lineno-match:
     :pyobject: test_connectivity
 
-All apps must register exactly one ``test_connectivity`` action in order to be considered valid by Splunk SOAR. This action takes no parameters, and is used to verify that the app and its associated asset configuration are working correctly. Running ``test connectivity`` on the Splunk SOAR platform should answer the questions:
+All apps must register exactly one ``test connectivity`` action in order to be considered valid by Splunk SOAR. This action takes no parameters, and is used to verify that the app and its associated asset configuration are working correctly. Running ``test connectivity`` on the Splunk SOAR platform should answer the questions:
 
 - Can the app connect to the external service?
 - Can the app authenticate with the external service?
@@ -108,8 +194,8 @@ All apps must register exactly one ``test_connectivity`` action in order to be c
 
 A successful ``test connectivity`` action should return ``None``, and a failure should raise an :class:`~soar_sdk.exceptions.ActionFailure` with a descriptive error message.
 
-on poll action
-^^^^^^^^^^^^^^
+``on poll`` Action
+^^^^^^^^^^^^^^^^^^
 
 .. literalinclude:: ../../tests/example_app/src/app.py
     :caption: on poll action definition
@@ -119,7 +205,7 @@ on poll action
 
 ``on poll`` is another special action that apps may choose to implement. This action always takes an :class:`~soar_sdk.params.OnPollParams` instance as its parameter. If defined, this action will be called in order to ingest new data into the Splunk Splunk SOAR platform. The action should yield  :class:`~soar_sdk.models.container.Container` and/or :class:`~soar_sdk.models.artifact.Artifact` instances representing the new data to be ingested. The SDK will handle actually creating the containers and artifacts in the platform.
 
-generic action
+Generic Action
 ^^^^^^^^^^^^^^
 
 .. literalinclude:: ../../tests/example_app/src/app.py
@@ -134,7 +220,7 @@ We create an action by decorating a function with the ``app.action`` decorator.
 is ``generic``, so usually you will not have to provide this argument for the decorator. This is not the
 case for the ``test`` action type though, so we provide this type here explicitly.
 
-custom actions
+Custom Actions
 ^^^^^^^^^^^^^^
 
 Actions can be registered one of two ways:
@@ -166,7 +252,7 @@ The two methods are functionally equivalent. The decorator method is often more
 
 .. _app-structure-app-cli:
 
-App CLI invocation
+App CLI Invocation
 ~~~~~~~~~~~~~~~~~~
 
 .. literalinclude:: ../../tests/example_app/src/app.py

splunk_soar_sdk-1.5.1/docs/cli_reference.rst

@@ -0,0 +1,51 @@
+.. _cli_reference:
+
+CLI Reference
+=============
+
+The ``soarapps`` command-line tool is the main interface for working with Splunk SOAR apps from the command line. It provides commands for creating, building, and managing apps.
+
+.. typer:: soar_sdk.cli.cli.app
+    :prog: soarapps
+    :width: 80
+    :preferred: text
+    :show-nested:
+    :make-sections:
+
+App CLI
+-------
+
+The :class:`~soar_sdk.app.App` class automatically generates a command-line interface (CLI) for your app. This CLI can be used to run actions (and verify their behavior) from the command line.
+
+.. code-block:: console
+
+    $ python src/app.py --help
+    usage: app.py [-h] [--soar-url SOAR_URL] [--soar-user SOAR_USER] [--soar-password SOAR_PASSWORD] {action,webhook} ...
+
+    positional arguments:
+    {action,webhook}
+        action              Run an action
+        webhook             Invoke a webhook handler
+
+    options:
+    -h, --help            show this help message and exit
+    --soar-url SOAR_URL   SOAR URL to connect to. Can be provided via PHANTOM_BASE_URL environment variable as well.
+    --soar-user SOAR_USER
+                            Username to connect to SOAR instance. Can be provided via PHANTOM_USER environment variable as well
+    --soar-password SOAR_PASSWORD
+                            Password to connect to SOAR instance. Can be provided via PHANTOM_PASSWORD environment variable as well
+
+
+You can run any action defined in your app by using the ``action`` command. For example:
+
+.. code-block:: console
+
+    $ python src/app.py action my-action --help
+    usage: app.py action my-action [-h] -p PARAMS_FILE -a ASSET_FILE
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    -p PARAMS_FILE, --params-file PARAMS_FILE
+                            JSON file containing action parameters
+    -a ASSET_FILE, --asset-file ASSET_FILE
+                            JSON file containing asset configuration

splunk_soar_sdk-1.5.1/docs/getting_started/defining_asset.rst

@@ -0,0 +1,32 @@
+Defining Your App's Asset Configuration
+=======================================
+
+
+Much of the functionality of a Splunk SOAR app depends on its ability to connect to external systems. This is done using an asset configuration, which provides the necessary connection details and credentials.
+
+Like much of the definitions for objects in a Splunk SOAR app, the asset configuration is defined using `Pydantic models <https://docs.pydantic.dev/1.10/usage/models/#basic-model-usage>`_. The power of Pydantic models allows you to define complex data structures with validation and serialization capabilities, in a way where your code editor will be able to provide autocompletions and type checking.
+
+.. note::
+    Users familiar with the ``BaseConnector`` style of Splunk SOAR apps may remember defining asset configuration with JSON. The Splunk SOAR SDK prefers to define all configuration in Python, and generate the JSON schema automatically. This ensures that the code and configuration are always in sync, and provides developers with significantly more useful editor support.
+
+In the case of assets, these models must be subclasses of :class:`~soar_sdk.app.Asset`. An example Asset definition looks something like this:
+
+.. literalinclude:: ../../tests/example_app/src/app.py
+    :caption: Asset definition
+    :language: python
+    :lineno-match:
+    :pyobject: Asset
+
+.. seealso::
+
+    For more information on how to define an asset configuration, see the :ref:`App Structure <app-structure-asset-def>` documentation.
+
+
+Finally, in order to register the asset configuration with the app, it must be provided to the :class:`~soar_sdk.app.App` instance as the ``asset_cls`` parameter. For example::
+
+    app = App(
+        name="My App",
+        description="An example app",
+        version="1.0.0",
+        asset_cls=Asset,  # <--- Asset class provided here
+    )

splunk_soar_sdk-1.5.1/docs/getting_started/first_action.rst

@@ -0,0 +1,119 @@
+Creating Your First Actions
+===========================
+
+All actions are defined as standalone functions, which are then registered with the :class:`~soar_sdk.app.App` object. Further, all apps are expected to implement a special ``test connectivity`` action, which is used to verify that the app can connect and authenticate to its external service.
+
+The ``test connectivity`` Action
+--------------------------------
+
+Every app must implement a ``test connectivity`` action. This action takes no parameters, and is used to verify that the app and its associated asset configuration are working correctly. Running ``test connectivity`` on the Splunk SOAR platform should answer the questions:
+
+- Can the app connect to the external service?
+- Can the app authenticate with the external service?
+- Does the app have the necessary permissions to perform its actions?
+
+For example:
+
+.. code-block:: python
+
+    @app.test_connectivity()
+    def test_connectivity(asset: Asset) -> None:
+        logger.info("Testing connectivity")
+
+        with httpx.Client() as client:
+            response = client.get("https://example.com/api/health", headers={
+                "Authorization": f"Bearer {asset.api_token}"
+            })
+            if not response.ok:
+                raise ActionFailure(
+                    f"Connectivity test failed with status code {response.status_code}"
+                )
+
+        logger.info("Connectivity test succeeded")
+
+Your First Action
+-----------------
+
+Actions can be registered in multiple ways, with advantages and trade-offs to each. For a smaller app, the easiest method is to use the :func:`~soar_sdk.app.App.action` decorator directly on a function.
+
+.. seealso::
+
+    See :ref:`Defining actions <app-structure-actions-def>` and/or :ref:`Action API Reference <api_ref_key_methods_label>` for more information.
+
+The simplest action to create would look like this::
+
+    @app.action()
+    def my_action(params: Params, asset: BaseAsset) -> ActionOutput:
+        """This is the first custom action in the app. It doesn't really do anything yet."""
+        return ActionOutput()
+
+Let's break down this example to explain what happens here.
+
+:func:`~soar_sdk.app.App.action` Decorator
+------------------------------------------
+
+.. code-block:: python
+
+    @app.action()
+    def my_action(...):
+
+The decorator registers new action functions against :class:`~soar_sdk.app.App` instances. It is responsible for many things related to running the app under the hood. Here are some things it takes care of:
+
+- registers new action functions, so they are invoked when running the app in Splunk SOAR platform
+- sets the configuration values for the action (which can be defined by providing extra parameters to the decorator)
+- ensures that the action name (by default, derived from the function name) is unique within the app
+- checks if the action params are provided, valid and of the proper type
+- ensures that the action output type is provided via return type annotation, and is valid
+- inspects action argument types and validates them
+
+.. seealso::
+
+    For more information about action registration, see the :ref:`App structure <app-structure-actions-def>` or :ref:`API Reference <api_ref_key_methods_label>` docs.
+
+The Action Declaration
+----------------------
+
+.. code-block:: python
+
+    def my_action(params: Params, asset: BaseAsset) -> ActionOutput:
+
+``my_action`` is the identifier of the action, and is used to derive the action's name (``my action``). This name will be used in the Splunk SOAR platform UI, and will be added to the app's generated manifest at packaging time.
+
+Each action may accept and define ``params`` and ``asset`` arguments with proper type hints.
+
+The ``params`` argument should always be the first argument, and of a type inherited from :class:`~soar_sdk.params.Params`. If an action takes no parameters, it's fine to use the ``Params`` base class here.
+
+.. seealso::
+
+    Read more on defining action params in the :ref:`API Reference <action-param-label>` or :ref:`App structure <app-structure-actions-def>` docs.
+
+The ``asset`` argument contains an instance of the app's asset configuration. It should be the same type that is specified as the ``asset_cls`` of the app.
+
+Actions must have a return type that resolves to a type which extends from :class:`~soar_sdk.action_results.ActionOutput`. This is discussed further in the :ref:`Action Outputs <action-output-label>` and :ref:`App structure <app-structure-actions-def>` docs. The return type must be hinted.
+
+The Action Docstring
+--------------------
+
+.. code-block:: python
+
+        """This is the first custom action in the app. It doesn't really do anything yet."""
+
+All actions should have a docstring. Beyond the general best practice it represents, the docstring is (by default) used by the SDK to generate the action description for the app documentation in Splunk SOAR.
+
+The description should be kept short and simple, explaining what the action does.
+
+The Action Result
+-----------------
+
+.. code-block:: python
+
+        return ActionOutput()
+
+Each successful action run must return at least one action result.
+Actions can fail gracefully by raising an :class:`~soar_sdk.exceptions.ActionFailure` exception. Other exceptions will be treated as unexpected errors.
+
+The given example action simply returns the :class:`~soar_sdk.action_results.ActionOutput` base class, as it does not yet generate any results.
+
+.. seealso::
+
+    Read more on action results and outputs in the :ref:`API Reference <action-output-label>` or :ref:`App structure <app-structure-action-returns>` docs.

{splunk_soar_sdk-1.4.1 → splunk_soar_sdk-1.5.1}/docs/getting_started/index.rst

@@ -10,3 +10,6 @@ In this section we will guide you through the basic process of creating your fir
 
     installation
     init_app
+    defining_asset
+    first_action
+    testing_and_building