Configure metadata in a JSON schema to define your app's configuration

Use a JSON schema to define the configuration of your Splunk SOAR app. The JSON may vary in complexity depending on the sophistication of the app and whether you want to customize how data produced by your app is rendered.

Top level definition

The following top level keys define the primary facets of the app:

{
  "appid" : "fd4dc1ce-b63c-4d0e-94e6-df0ae680d99c",
  "name" : "SampleApp",
  "description" : "Query the Sample reputation service",
  "type" : "reputation",
  "main_module" : "sampleapp_connector.py",
  "app_version" : "1.0.0",
  "product_vendor" : "Contoso",
  "product_name" : "Contoso Reputation",
  "product_version_regex": ".*",
  "logo": "contoso.svg",
  "logo_dark": "contoso_dark.svg",
  "min_phantom_version": "1.0.240",
  "publisher" : "Contoso Corp",
  "package_name": "phantom_whois",
  "license": "Copyright (c) 2019 Splunk, Inc.",
  "configuration": {},
  "actions": []
}

Key	Required?	Description
appid	Required	The ID of the app for unique identification. This ID is in GUID/UUID version 4 format. It can be generated applications for the required platform such as uuidgen for linux, guidgen.exe for windows, or www.guidgenerator.com on the web.
name	Required	This is the name of the app.
description	Required	This is a more verbose description of the app. This is used to display a description of the app in the user interface, and also for automatically generated documentation on an app.
type	Required	This is the app type. The type is used to group apps at a level higher than the product_vendor name. Some of the types currently defined by Splunk SOAR apps include siem, email, endpoint, firewall, forensic, information, investigative, network access control, reputation, sandbox, threat intel, ticketing, virtualization and generic.
main_module	Required	This is the file name containing the module with the entry point code. It usually contains the action implementations for this app. This file is loaded when an action that this app supports is run. The Python code is located in the current app's directory.
app_version	Required	This is the app version. There may be multiple versions of an app on a given system in order to support different versions of a vendor/product combination. Versions start at 1.0.
pip_dependencies	Optional	Use this to specify pip dependencies that need to be installed for the app to function. See Specifying pip dependencies for more information.
pip3_dependencies	Optional	Use this key to specify any dependencies that must be installed for your Python 3 app. If this key is present, pip_dependencies is ignored. If this key is not present, but pip_dependencies is, that information will be used for both Python 2 and Python 3.
min_phantom_version	Optional	Use this key to specify the minimum version that the app supports. The platform will validate the version during app installation and fail if the minimum criteria is not met.
product_vendor	Required	This is the vendor associated with the product that this app supports. For example, ReversingLabs, Cisco, IBM, FireEye.
product_name	Required	This is the name of the product that this app supports.
product_version_regex	Required	This is the supported version of the product that your app uses. It is a regex and is rendered by the platform in the app documentation. The app requires code to extract and validate the version from the third party device or service that it uses. A '.*' represents all versions.
publisher	Required	This is your name, as the publisher and creator of this app. This is your company name if you are a vendor, or your own name if you are an individual.
package_name	Required	This is the package name that will be used to install the app through the yum/rpm commands.
license	Required	This is the license that the app is released under. This is the license string that is to be displayed in the yum/rpm info commands output.
consolidate_widgets	Optional	If false, the platform will render every action in its own widget, or if true, a single widget will contain all actions consolidated.
configuration	Required	A set of asset configuration variables, defined in more detail in the following sections. Configuration can be empty if none are needed.
url	Optional	This is the URL associated with the app. It is a landing page that gives brief information about the app or extra documentation.
logo	Optional	This is the name of the icon file that is rendered at multiple places in the product in Light Theme. It has to be in the app folder with the rest of the files. SVG, PNG and JPEG files are supported, but SVGs are preferred. The logo must have a transparent background and is represented by the product being integrated. A product icon is preferred over the vendor icon.
logo_dark	Optional	This is the icon that is rendered in Dark Theme.
actions	Required	Detailed specification of the actions that this app supports. This defines the input parameters that the app needs for each action and the output that they generate.
rest_handler	Optional	This is the path to an optional REST handler function.
python_version	Required.	Defines the Python version used to run the app's actions. This value must be "3."

Specifying pip dependencies

You can specify the Python modules that the platform installs during the app installation. See the following example for the format of this dictionary:

"pip_dependencies": {
   "pypi": [
      {"module": "requests_ntlm"}
   ],
   "wheel": [
      {"module": "python-rtkit", "input_file": "wheels/python_rtkit-0.7.0-py27-none-any.whl"}
   ]
},

The pip_dependencies dictionary supports two keys, but only one of the following keys is required:

1. pypi: A list of modules that need to be installed for the app to work properly. The name to use as a parameter for the pip install is the [module_name] command. You can specify the required version of the module by typing the <$module_name>==<version_number>. If no version is specified, pypi will attempt to install the most recent release available.
   Example: {"module": "cryptography==41.0.1"} This specifies that pypi should be used to install the module cryptography, using version 41.0.1.
2. wheel: Use wheel to install app dependencies without direct connectivity to the internet. However, all Splunk SOAR apps have this capability. runs pip with the --no-deps parameter during wheel file installation. Each item in the list is a dictionary with the following keys:

• module: The module name.
• input_file: Path to the wheel file relative to the app directory in the app TAR file.

We pull from pypi when the pypi dictionary is defined. See the following for an example of an app install of the requests_ntlm package in both the Python 2 and Python 3 environments:

"pip_dependencies": {
   "pypi": [
      {"module": "requests_ntlm"}
   ]
},
"pip3_dependencies": {
  "pypi": [
      {"module": "requests_ntlm"}
   ]
}

For Splunk SOAR, Python 3 is required.

Here is an example of an app specifying pip dependencies for Python 2 and Python 3.

"pip_dependencies": {
        "wheel": [
            {
                "module": "certifi",
                "input_file": "wheels/py2/certifi-2019.11.28-py2.py3-none-any.whl"
            },
            {
                "module": "chardet",
                "input_file": "wheels/py2/chardet-3.0.4-py2.py3-none-any.whl"
            },
            {
                "module": "geoip2",
                "input_file": "wheels/py2/geoip2-2.9.0-py2.py3-none-any.whl"
            },
            {
                "module": "idna",
                "input_file": "wheels/py2/idna-2.8-py2.py3-none-any.whl"
            },
            {
                "module": "ipaddress",
                "input_file": "wheels/py2/ipaddress-1.0.23-py2.py3-none-any.whl"
            },
            {
                "module": "maxminddb",
                "input_file": "wheels/py2/maxminddb-1.5.1-cp27-none-any.whl"
            },
            {
                "module": "requests",
                "input_file": "wheels/py2/requests-2.22.0-py2.py3-none-any.whl"
            },
            {
                "module": "urllib3",
                "input_file": "wheels/py2/urllib3-1.25.7-py2.py3-none-any.whl"
            }
        ]
    },
    "pip3_dependencies": {
        "wheel": [
            {
                "module": "certifi",
                "input_file": "wheels/py3/certifi-2019.11.28-py2.py3-none-any.whl"
            },
            {
                "module": "chardet",
                "input_file": "wheels/py3/chardet-3.0.4-py2.py3-none-any.whl"
            },
            {
                "module": "geoip2",
                "input_file": "wheels/py3/geoip2-2.9.0-py2.py3-none-any.whl"
            },
            {
                "module": "idna",
                "input_file": "wheels/py3/idna-2.8-py2.py3-none-any.whl"
            },
            {
                "module": "maxminddb",
                "input_file": "wheels/py3/maxminddb-1.5.1-py3-none-any.whl"
            },
            {
                "module": "requests",
                "input_file": "wheels/py3/requests-2.22.0-py2.py3-none-any.whl"
            },
            {
                "module": "urllib3",
                "input_file": "wheels/py3/urllib3-1.25.7-py2.py3-none-any.whl"
            }
        ]
    },
 

For Splunk SOAR, Python 3 is required.

Configuration Section

In order to run an action, an app must operate on an asset that has been configured by the end user within . First, the platform must have one or more instances of an asset configured; at least one that is directly supported by the app, and that matches the vendor and product that the app supports.

The configuration section contains variables that are used when configuring an asset, essentially serving as a template for that. As a result, the configuration of an asset is data-driven based on the variables defined here. Each asset vendor/product combination will typically have a single app that operates on it. For example, a single app that supports and operates on Cisco ASA devices, and the configuration variables required by the app to connect to that device are defined here. These are static configuration variables for an asset that serve as a template when configuring the asset under the Administration menu, such as a username, password, or API key as shown in the following example. Dynamic parameters that change each time an app runs an action are defined in the parameters section of the corresponding action and are not configuration variables.

{
  ...
  "configuration": {
    "apikey" : {
      "data_type": "string",
      "description": "Contoso API key",
      "required": true
    }
  },

The configuration section contains a list of variables (keys) that each contain a dictionary to describe that key. This defines how that variable is rendered and used within the system:

Key	Required?	Description
data_type	Required	The type of variable. Supported types are string, password, numeric, and boolean.
description	Required	A description of this variable. This value is used as a label that is displayed on the UI next to the input control. Keep this brief, preferably a single line, since it is displayed on the UI. If you need to explain the app, or asset configuration in more detail use a readme.html file.
required	Optional	Whether or not the variable is mandatory. If mandatory, the variable must be configured by the user when defining an asset that this variable operates on. Default is False.
value_list	Optional	To allow the user to choose from a pre-defined list of values displayed in a drop-down, specify them as a list. For example, ["one", "two", "three"]
default	Optional	To set the default value of a variable in the UI, use this key. The user will be able to modify this value, so the app will need to validate it. This key also works in conjunction with value_list.
order	Optional	The order key, starting at 0, allows the app author to control the display order of the controls in the UI.

Not all apps require a configuration section. For example, the MaxMind app has no need for one, since there is nothing to configure. It can be left empty as shown by "configuration": {},.

Configuration changes with app version changes

As part of an app upgrade, downgrade, or reinstall, automatically performs the following actions for any asset configurations associated with that app:

• adds new fields present in the version you are changing to, along with their default values if the app provides a default value
• removes fields not present in the version you are changing to, along with any values associated with them

When switching back and forth between versions: If you set a configuration setting to a custom value, then switch to a version of the app that removes that configuration setting, then switch back to the original version, your custom value will either:

• revert to the default value, if the app provides a default value, or
• not be present in the asset configuration, if the app does not provide a default value.

README file

An app author can bundle a readme.html file in the app directory, which the platform renders as part of the app documentation. It is rendered between the app description and the asset configuration parameters.

Place Holder Data Type

The order key allows an app author to specify the order in which the controls are displayed to the user. In order to insert a blank, no control, at a specific location use the ph data_type with the order key. For example, to display a blank space between the first and second control define the configuration as shown in the following example:

{
  ...
    "configuration": {
      "server": {
        "data_type": "string",
        "description": "Server IP/Hostname",
        "order": 0,
        "required": true
      },
      "ph": {
        "data_type": "ph",
        "order": 1
      },
      "username": {
        "data_type": "string",
        "description": "Username",
        "order": 2,
        "required": false
      },
      "password": {
        "data_type": "password",
        "description": "Password",
        "order": 3,
        "required": false
      },

This data type is also supported for action parameters.

Actions Section

The actions key defines an array of actions that this app supports. This exposes the core functionality that the app makes available to .

{
  ...
  actions": [
    {
      "action": "file reputation",
      "description": "Queries Contoso for file info",
      "type": "investigate",
      "read_only": true,

Parameter	Required?	Description
action	Required	The name of the action. Action names are high level primitives that are used throughout . They are used in playbooks when an action is requested and in the UI when an action is run.
identifier	Required	A unique identifier for this action. The action key is mapped to this identifier and that is what is passed down to the app. The app code then uses this unique identifier to determine which action to run.
description	Required	A description of this variable. This value is used as a label that is displayed on the UI next to the input control. Keep the description brief, preferably a single line, since it is displayed on the UI. If you want to explain things in more detail regarding a parameter, or the action in general, use the verbose key.
verbose	Optional	Use this key to fill in any information that you want to document about the action. This text supports HTML formatting.
type	Required	The type of action. This is used to organize actions into logical groups based on their purpose. Type must be one of the following: contain, correct, generic, investigate or test. The only test connectivity action uses the test type. The test type of actions are not displayed in the UI in the Run Action dialog.
read_only	Required	Indicates whether the action is "read-only", or in other words, non-destructive. Executing this action will have no adverse affect on the asset. This typically applies to information gathering actions that do not make any configuration changes to an asset.
undo	Optional	The action that reverts this action.

Naming Actions

Splunk SOAR users are used to a particular naming convention for action names. To aid user's understanding, it helps to reuse action names. The following tips can help you understand how to best name actions:

• Review apps to see if they expose the same action. For example, there may be a "block ip" action exposed by a Cisco ASA app, a Palo Alto Networks app, and a Microsoft Windows app. If available, match your action name to an existing name that has the same purpose. This is useful as your app can benefit from Playbooks that already run this action.
• Keep action names as short as possible while still conveying their intent. App names may contain spaces.
• Utilize the app's documentation or the Run Action dialog box to study the action names in the product.

Action Section: Versions

The versions key specifies which versions of the product that this action supports. This key contains a regular expression that is matched against a configured asset to find the app and action within that app that best supports a specific asset.

"versions": "EQ(*)"

The versions key supports a short number of matching functions which can be one of the following:

Function	Description
EQ()	Equal: The version matches a specific version: EQ(*), or EQ(12.*)
NEQ()	Not Equal: The version does not match a specific version: NEQ(12.*)
IN()	In: The version matches a list of comma separated versions: IN(12.*, 13.*)
NIN()	Not In: The version is not in a list of comma separated versions: NIN(12.*, 13.*)

Version matching is used to find the best app to run on a given asset, while allowing you to maintain support for various versions of a vendor's product.

There are two ways to handle multiple versions of a product. You can create a new action within your JSON which has a different version expression and calls a different function within your app. In this case, your app code has two different functions each one supporting a different version or versions of a product. Or, you can create a separate JSON which contains the required metadata for the version that you support. In this case, you can have a separate app altogether, with its own appid; one that supports only the versions specified in this separate JSON.

Action Section: Parameters

Within an action entry, the parameters key defines a list of parameters that are passed to this action. These parameters are typically specified in automation playbooks and pass through to the app when an action is run. The name of the key represents the parameter name. For example, in the following example hash is the name of the parameter. Each action and its parameters are documented on the platform, take a look at the names used by action parameters of the same action in other apps. For example, an action like list processes take as input an ip address or host name named ip_hostname, another example domain reputation takes a parameter named domain.

"parameters": {
   "hash": {
      "description": "the hash of the file to be queried",
      "data_type": "string",
      "contains": ["hash", "sha256", "sha1", "md5"],
      "required": true,
      "allow_list": true
   }
},

Parameter	Required?	Description
description	Required	A short description of this parameter. The description is shown in the user interface when running an action manually.
data_type	Required	The type of variable. Supported types are string, password, numeric, boolean.
contains	Optional	Specifies what kind of content this field contains.
required	Optional	Whether or not this parameter is mandatory for this action to function. If this parameter is not provided, the action fails.
primary	Optional	Specifies if the action acts primarily on this parameter or not. It is used in conjunction with the contains field to display a list of contextual actions where the user clicks on a piece of data in the UI.
value_list	Optional	To allow the user to choose from a pre-defined list of values displayed in a drop-down for this parameter, specify them as a list for example, ["one", "two", "three"]. An action can be run from the playbook, in which case the user can pass an arbitrary value for the parameter, so the app needs to validate this parameter on its own.
default	Optional	To set the default value of a variable in the UI, use this key. The user will be able to modify this value, so the app will need to validate it. This key also works in conjunction with value_list.
order	Optional	The order key, starting at 0, allows the app author to control the display order of the controls in the UI.
allow_list	Optional	Use this key to specify if the parameter supports specifying multiple values as a comma separated string.

Even before the action is passed onto the app, it reaches the BaseConnector first. The BaseConnector parses the app JSON and matches it against the configuration and action parameters that were passed from the Splunk SOAR Core. If the BaseConnector finds that any of the parameters marked as required are missing, it reports an error back to the Splunk SOAR Core. This allows the app writer to write code without checking for the presence of a required parameter.

Action Section: Synchronization

Within an action entry, the optional lock key defines a set of parameters that app authors can set to synchronize actions.

• A lock is represented by its name.
• Multiple actions locking on the same name will be serialized even if the actions are from different apps.
• In the absence of a lock dictionary, the platform will synchronize the action using the asset as the lock name.
• To disable synchronization for an action, the lock dictionary must be present and the 'enabled' key set to false.

"lock": {
   "enabled": true,
   "data_path": "parameters.hash",
   "timeout": 600
}

Parameter	Required?	Description
enabled	Required	Boolean value that specifies if the lock is enabled or not for this action.
data_path	Optional	The name of the lock. Only valid if lock is enabled. This value can be one of three things. Either a data path that points to a parameter of the action for e.g. "parameters.hash" where 'hash' is one of the parameters of the action, or a data path that points to a config parameter for e.g. "configuration.server". At runtime the platform will read the value stored in these data paths and use it as a name of the lock. The third option that the app author can use is a constant string. I.e. any string that does not start with "configuration." or "parameters.". The platform will use this value as is. In case the data_path is not specified, the asset will be used as the lock name.
timeout	Optional	Specifies the number of seconds to wait to acquire the lock, before an error condition is reported.

Action Section: Render key

Within an action entry, the render key specifies how output from this app will be displayed to the user within . This section is required. Output is typically displayed in two places. First, in the results from an action when viewing a specific action, and second in the Investigation panel of the product. In Investigation, the output is encapsulated within a widget container that can be displayed, expanded, and moved by the user when managing security operations.

The value associated with this key is a dictionary which must contain a key called type.

"render": {
   "type": "custom",
   "width": 4,
   "height": 5,
   "view": "sampleapp_view.file_reputation",
   "title": "FILE REPUTATION",
   "menu_name": "SampleApp File Lookup"
}

Parameter	Required?	Description
type	Required	This specifies the type of render function to use when displaying output from this app. supports a number of built in widgets that display data and also gives you the ability to define your own view to render data from your app in any form you want. Values are: json, table, or custom. The default is table.
width	Required	Specifies the width, in columns, of the container that houses this content. The Investigation screen is 12 columns wide and widgets can be anywhere from one to six columns in width.
height	Required	Specifies the height, in rows, of the container that houses this content. The height must be between 0 and 10.
view	Optional	Specifies the custom view to load when rendering data produced by this app. The format of this value is file.function, referring to the Django Python view file that you authored, and the function for Splunk SOAR to call when rendering your view.
title	Required	Specifies the title that is displayed within the widget header on the Investigation screen.
menu_name	Optional	Specifies the name to be displayed in the widget menu on the Investigation screen when listing this widget.

Action Section: Output

Within an action entry, the output key defines an array of results that are generated by this app. Each member of the array is one variable that matches the corresponding variable in the CommandResult class that the Python app code produces.

"output":[
   {
      "data_path": "action_result.data.*.permalink",
      "data_type": "string"
   },
   {
   "data_path": "action_result.data.*.sha1",
   "data_type": "string",
   "contains": ["sha1"],
   "example_values": [
      "f0eb87677a689a88b58a0613dfd7252fb850393c",
      "d969e7e0b0571370cd6763192bc24ac56c255472"
      ]
   },

Parameter	Required?	Description
data_path	Optional	Specifies the data path of this field. Data paths are a method of indexing into the JSON in an abstract fashion that allows others who want to access that data to do so by specifying the appropriate path. The data path specified here must be populated by the app code that creates and returns this field.
data_type	Required	The type of variable. Supported types are string, password, numeric, boolean.
contains	optional	Specifies what kind of content this field contains. The purpose of contains is to allow matching of output from one action to another action's parameters.
column_name	Optional	If the output from this app is rendered in the default table widget, when render "type" is table, then column_name specifies the name of this column within the rendered widget when it is displayed. This is a convenient way to show data in Investigation and when viewer action results in tabular form.
column_order	Optional	If the output from this app is to be rendered in the default table widget, when render "type" is table, then column_order specifies the order of this column. Column ordering starts at 0.
example_values	Optional	A list of example values for the data path. These are displayed in the app's documentation page.
map_info	Optional	If the output from this app is to be rendered in the default map widget, when render "type" is map, then map_info specifies the name of this field within the details for this item.