Getting started
In this section we will guide you through the basic process of creating your first draft of the SOAR App.
Actions philosophy
Apps (aka Connectors) in Splunk SOAR are extensions that enrich the platform functionality. Each app provides a new set of actions that can be used for the security investigation (also automated one, when used in playbooks). Usually, a single app adds actions for one specific tool or 3rd party service (e.g. whois lookup or geolocation).
When building your app, you will focus on implementing the actions like sending data to the external service or updating the containers on SOAR platform.
This SDK is a set of tools to build, test and run your own app that will extend the SOAR installation by implementing actions.
Your first app
The following guide will get you through the process of building your first app, explaining its crucial components and functionality.
Setting up your machine
You will need a Mac or Linux machine. Windows is not supported.
First, install some necessary tools:
Git
uv: the Python version and environment manager used by the SDK
Next, install Python 3.9 and 3.13. These are the two versions currently supported for SOAR apps:
uv python install 3.9
uv python install 3.13
Finally, install the SOAR SDK as a command-line tool:
uv tool install splunk-soar-sdk
It may also be helpful to install ruff and pre-commit, as these are used often when building SOAR apps:
uv tool install ruff
uv tool install pre-commit
Creating a new app
To create a new, empty app, simply run:
soarapps init
This will create the basic directory structure for your app, which you can open in your editor. See The app structure below for more information.
Migrating an existing app
To migrate an existing app, myapp, that was written in the old BaseConnector framework, run:
soarapps convert myapp
The conversion script will create a new SDK app, migrating the following aspects of your existing app:
Asset configuration parameters
Action names, descriptions, and other metadata
Action parameters and outputs
You will need to re-implement the code for each of your actions yourself.
Automatic migration is not yet supported for the following features, and you will need to migrate these yourself:
Custom views
Webhook handlers
Custom REST handlers (must be converted to webhooks, as the SDK does not support Custom REST)
The app structure
Running the soarapps init or soarapps convert commands will create the following directory structure:
my_app/
├─ src/
│ ├─ __init__.py
│ ├─ app.py
├─ .pre-commit-config.yaml
├─ logo.svg
├─ logo_dark.svg
├─ pyproject.toml
We describe and explain each of the files in full in the dedicated documentation pages about the app structure.
For now, let’s shortly go over each of the components in the structure, so we can create our first action.
The src directory and the app.py file
In this directory you will develop your app source code. We typically place here the app.py file
with the main module code. Keep in mind you can always add more python modules to this directory and import
them in the app.py file to create cleaner maintainable code.
In the app.py file we typically create the App instance and define actions and provide its implementation.
This module will be used in our pyproject.toml app configuration to point the app object as main_module for
use in SOAR platform when running actions.
Read the detailed documentation on the app.py file contents
Note that the test_connectivity action is mandatory for each app. It is used when installing the app in
the SOAR platform and checked usually when a new asset is added for the app. This is why it is always provided
in the app scratch files.
The logo*.svg files
These files are used by SOAR platform to present your application in the web UI. You should generally provide
two versions of the logo. The regular one is used for light mode and the _dark file is used for the dark mode.
PNG files are also acceptable, but SVGs are preferred because they scale more easily.
pyproject.toml configuration file
This file defines the app development parameters, dependencies, and also configuration data for the app.
In this file you will define poetry dependencies (including this SDK) and basic information like the name of the app, its version, description, authors, and other params.
Read the detailed documentation on the pyproject.toml file contents
Configuring the environment
Once you have your starting app file structure, you will need to set up your app development environment.
First, set up a Git repository:
git init
In your app directory, install the pre-commit hooks:
pre-commit install
Then you need to set up the environment using uv. It will set up the virtual environment and install necessary dependencies. You should also add the SDK to your project:
uv add splunk-soar-sdk
uv sync
It’s also useful to activate the virtual environment created by uv, so that all your shell commands run in context of your app:
source .venv/bin/activate
Creating your first action
Your app should already have the app object instance created in the app.py file. In the future you will
initialize it with extra arguments, like the asset configuration, to specify the asset data. You can read more on
how to initialize the app in the App Configuration documentation.
For now let’s focus on creating a very simple action and see the basics of its structure. You should already have
one action defined in your app.py file called test_connectivity which must be created in every app. You can check
how it is constructed. Our first action will be very similar to it.
The app instance provides the action decorator which is used to turn your python functions into SOAR App actions.
Here’s the code of the simplest action you can create:
@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.
App.action decorator
@app.action()
The decorator is connecting your function with the app instance and the SOAR engine.
It’s responsible for many things related to running the app under the hood, so you can focus on developing the action. Here are some things it takes care of:
registers your action, so it is invoked when running the app in SOAR platform
sets the configuration values for the action (which you can define by providing extra params in the call parenthesis)
checks if the action params are provided, valid and of the proper type
inspects your action arguments types and validates them
For more information about the App.action decorator, see the API Reference.
The action declaration
def my_action(params: Params, asset: BaseAsset) -> ActionOutput:
my_action is the identifier of the action and as such it will be visible later in the SOAR platform.
App.action decorator automatically converts this to “my action” string name that will be used when generating
the app Manifest file and the documentation.
Each action should accept and define params and asset arguments with proper typehints.
The params argument should always be of the class type inherited from soar_sdk.params.Params.
You can read more on defining action params in the API Reference.
If your action takes no parameters, it’s fine to use the Params base class here.
The asset argument contains your asset configuration, which is discussed further in the App Configuration documentation. It should be of a type that inherits from soar_sdk.asset.BaseAsset, and should be the same type that is specified as the asset_cls of your app.
Your action must have a return type that extends from soar_sdk.action_results.ActionOutput. This is discussed further in the Action Outputs documentation. The return type must be hinted.
The action description docstring
"""This is the first custom action in the app. It doesn't really do anything yet."""
You should always provide the docstring for your action. It makes your code easier to understand and maintain, but
also, the docstring is (by defualt) used by the App.action decorator to generate the action description for the
app documentation in SOAR platform.
The description should be kept short and simple, explaining what the action does.
The action result
return ActionOutput()
Each action must return at least one action result. While you can create multiple instances of the action result and pass more than one values, the one that is most important is the general action result.
Prior to SDK, the connectors had to define and create their own ActionResult instances. This is simplified now
in SDK. If your action succeeds, it should return an instance of your output class. If it fails, it should raise an exception.
Our example action simply returns the ActionOutput base class, as it does not yet generate any results.
Read more on action results and outputs in the Action Outputs section of the API Reference.
As you can see, this simple action is taking bare Params object, so with no defined params and simply returns
the result of successful run.
Testing and building the app
Running from the command line
You can run any of your app’s actions directly in your CLI, without installing a full copy of SOAR. Simply invoke the Python file that contains your app:
python src/app.py action my-action -p test_params.json -a test_asset.json
You should provide a parameters file (-p) which contains the JSON-encoded parameters for your action.
The asset file (-a) contains the asset config in JSON format.
This command will run your action on your local machine, and print its output to the command line.
Building an app package
Run soarapps package build to generate an app package.
By default, this creates <appname>.tgz in the root directory of your app.
This package contains all the code and metadata for your app.
It also contains all the dependency wheels for your app, which are sourced from the PyPI CDN based on uv.lock.
Because of this, you should ensure that your uv.lock is always up to date.
Installing and running the app
Now you can install the app in your SOAR platform to test how it works. You can do this by using the web interface of the platform.
You can also do this from the command line:
soarapps package install myapp.tgz soar.example.com
Getting help
If you need help, please file a GitHub issue at https://github.com/phantomcyber/splunk-soar-sdk/issues.
Next steps
Now that you have a working app, you can start its development. Here’s what you can check next when working with the app you create: