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

Use a JSON schema to define the configuration of your Splunk Phantom app. The JSON key-value pairs you need to include depends on features of the app and on whether you want to customize how data produced by your app is rendered.

Top level definition

This is an example of the top level keys to define your 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": []
}

This table contains a list of the JSON keys you use to define your app and its capabilities.

Key	Required?	Description
actions	Required	Detailed specification of the actions that this app supports. This section defines the input parameters that the app needs for each action and the output that the actions generate.
app_version	Required	This is the app version number. There may be multiple versions of an app on a given system to support different combinations of a vendor and product. Version numbers start at 1.0.
appid	Required	The ID of the app for unique identification. This ID is in GUID/UUID version 4 format. You must generate the GUID/UUID using tools for your development platform, such as: uuidgen for linux guidgen.exe for Windows www.guidgenerator.com on the web.
configuration	Required	A set of asset configuration variables, defined in more detail in later sections of this topic. Configuration can be empty if none are needed.
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.
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.
license	Required	This is the license for the app. This is the license string is displayed in the yum/rpm info commands output.
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. The logo must have a transparent background and is represented by the product being integrated.
logo_dark	Optional	This is the icon that is rendered in Splunk Phantom's dark theme.
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.
min_phantom_version	Optional	Use this key to specify the minimum Splunk Phantom version that the app supports. The platform will validate the Splunk Phantom version during app installation and fail if the minimum criteria is not met.
name	Required	This is the name of the app.
package_name	Required	This is the package name that will be used to install the app through the yum/rpm commands.
pip_dependencies	Optional	The platform allows the app author to specify pip dependencies that need to be installed on the OVA for the app to properly work. See Specifying pip dependencies for more information.
pip3_dependencies	Required if the app supports both Python 2 and Python 3	Use this key to specify dependencies that must be installed for Python 3 apps. If this key is present, pip_dependencies is ignored for Python 3 apps. If this key is not present, but pip_dependencies is, the values for pip_dependencies is used for both Python 2 and Python 3.
product_name	Required	This is the name of the product that this app supports.
product_vendor	Required	This is the vendor associated with the product that this app supports. For example, ReversingLabs, Cisco, IBM, FireEye.
product_version_regex	Required	Set the version of the product the app supports. This value is a regex and is rendered by the platform in the app documentation. Use .* to represent all versions.Your app requires code to get the version from the 3rd party device or service that it integrates with and must run any required validation.
publisher	Required	This is your name, as the publisher and creator of this app. Use your company name if you are a vendor, or your name if you are an individual.
python_version	Optional when using Python 2.7, but required when using Python 3.	Set the Python version used by the app. Set either "2.7" or "3". If not specified, "2.7" is assumed.
rest_handler	Optional	This is the path to an optional REST handler function.
type	Required	Use 'type' to group apps at into categories for sorting in the user interface. Some of the types currently defined by Splunk Phantom apps include: SIEM email endpoint firewall forensic information investigative network access control reputation sandbox threat intel ticketing virtualization generic
uber_view	Optional	The fallback view for apps which do not define a custom view format for a custom view. See Use custom views to render results in your app for more information on setting custom views.
version	Optional	App definition JSON schema version. The current version is 1.

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 Phantom apps have this capability. Splunk Phantom 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"}
   ]
}

Python 3 is the recommended environment.

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"
            }
        ]
    },
 

Python 3 is the recommended environment.

Modules that require compilation

Some modules when downloaded require compilation before they can be used by a Splunk Phantom app. In these cases when the module is downloaded, it is a zip file that contains source files that need to be compiled before a self contained wheel file can be used. One way to do this is to create a wheel file using pip3. Since the module must be compiled to create a wheel file, gcc or g++ and so on require installation on the OVA that is creating the wheel file. Once the wheel file is created, it can be packaged with the app and installed without any other compilers.

Create a requirements.txt file that contains the list of modules. One module per line. Then run the following command:

...]$ phenv pip3 wheel --wheel-dir=./wheels/ -r ./requirements.txt

This command will download and compile the module if required and create a wheel file that can be packaged with the app. Make sure that the license of the module that you are packaging with the app allows this.

Configuration Section

In order to run an action, an app must operate on an asset that has been configured by the end user within the Splunk Phantom platform. 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, Splunk Phantom's 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 might 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 1st and 2nd 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 the Splunk Phantom platform.

{
  ...
  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 the Splunk Phantom platform. 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 Phantom 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 Splunk Phantom 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 Phantom Core. If the BaseConnector finds that any of the parameters marked as required are missing, it reports an error back to the Splunk Phantom 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 the Splunk Phantom product. 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. Splunk Phantom 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 Phantom 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.