Building an App¶
Creating the App Skeleton¶
To build an app with the Splunk SOAR SDK, you can either start from scratch, or migrate an existing app built with the older BaseConnector framework.
To create a new, empty app, simply run soarapps init in an empty directory.
Usage: soarapps init [OPTIONS] COMMAND [ARGS]...
Initialize a new SOAR app.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --name TEXT [required] │
│ * --description TEXT [required] │
│ --authors TEXT [default: <class │
│ 'list'>] │
│ --python-version -p [3.13|3.14] Supported Python │
│ versions for the │
│ app. │
│ [default: <bound │
│ method │
│ PythonVersion.all │
│ of <enum │
│ 'PythonVersion'>… │
│ --dependencies TEXT [default: <class │
│ 'list'>] │
│ --appid UUID [default: │
│ (dynamic)] │
│ --app-dir DIRECTORY [default: │
│ /home/runner/wor… │
│ --copyright TEXT [default: │
│ Copyright (c) │
│ {year} Splunk │
│ Inc.] │
│ --version TEXT [default: 1.0.0] │
│ --type TEXT [default: │
│ generic] │
│ --vendor TEXT [default: Splunk │
│ Inc.] │
│ --publisher TEXT [default: Splunk │
│ Inc.] │
│ --product TEXT │
│ --fips-compliant --no-fips-compli… [default: │
│ no-fips-complian… │
│ --overwrite --no-overwrite [default: │
│ no-overwrite] │
│ --help Show this message │
│ and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
This will interactively create the basic directory structure for your app, which you can open in your editor of choice.
See also
See The app structure below for more information about the files created.
To migrate an existing app, myapp, that was written in the old BaseConnector framework, run soarapps convert myapp.
Usage: soarapps convert [OPTIONS] APP_DIR [OUTPUT_DIR] COMMAND [ARGS]...
Convert a SOAR connector to a SOAR SDK app.
This command will convert a SOAR connector directory into a SOAR SDK app
directory.
The connector directory should contain the necessary files and structure for
conversion.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * app_dir DIRECTORY [required] │
│ output_dir [OUTPUT_DIR] Directory to output the converted SDK │
│ app. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --overwrite --no-overwrite [default: no-overwrite] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
This 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)
Initialization code
Action summaries
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
See also
See the dedicated app structure documentation for more details on each of these files and their purposes.
The src Directory and the app.py File¶
In this directory you will develop your app source code. Apps typically start with an app.py file with the main module code. Larger apps can be split into multiple modules for better organization.
All apps must create one single App instance. Typically, that object is created in the app.py file. The file which contains the App instance is called the main module of the app. The instance must be referenced in the project’s pyproject.toml file:
[tool.soar.app]
main_module = "src.app:app"
Read the detailed documentation on the app.py file contents.
The logo*.svg Files¶
These files are used by the Splunk SOAR platform to present your app in the web UI. You should generally provide two versions of the logo. The regular one is used in light mode and the _dark file is used in dark mode.
PNG files are acceptable, but SVGs are preferred because they scale more easily.
The pyproject.toml Configuration File¶
This file contains critical metadata about your app, like its name, license, version, and dependencies. Learn more in the detailed documentation on the pyproject.toml file.
Configuring a Development Environment¶
After creating an app skeleton, it’s time to set up a development environment.
First, it’s recommended to create a Git repository:
git init
In the app directory, install the pre-commit hooks defined by pre-commit-config.yaml:
pre-commit install
Then, set up the environment using uv. It will set up the virtual environment and install necessary dependencies. Add the SDK as a dependency:
uv add splunk-soar-sdk
uv sync
It’s also useful to activate the virtual environment created by uv, so that shell commands run in context of the app’s environment:
source .venv/bin/activate