Splunk® SOAR (Cloud)

Develop Apps for Splunk SOAR (Cloud)

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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 devops, email, endpoint, identity management, information, network device, network security, reputation, sandbox, siem, ticketing, and virtualization.
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 Required 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.
  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": {},.

During app updates, configuration requirements may change. If the new app version adds a new parameter that is required, the currently configured asset will become invalid and user intervention is required for the app to function. For a smoother upgrade process, the app author tries to set the new asset configuration values as optional and with a default value instead of adding a required value. The default value is specified in the app JSON and is also handled in the app code.

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. The identifier is maximum five characters.
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.
Last modified on 10 November, 2021
PREVIOUS
Connector module development
  NEXT
Use the contains parameter to configure contextual actions

This documentation applies to the following versions of Splunk® SOAR (Cloud): current


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters