Create an adaptive response action

To integrate with the Adaptive Response framework in Splunk Enterprise Security, write your own custom alert actions using the Common Action Model. Following the JSON spec and the cim_actions.py library, or by using Add-on Builder, you can develop your action in such a way that it becomes available in Splunk Enterprise Security as a response action.

 Use Add-on Builder to create a response action

To use Splunk Add-on Builder 2.0.0 to create an adaptive response action, follow the wizard within the Add-on Builder UI. The Add-on Builder does not support Splunk Cloud Platform adaptive response actions. See Create an adaptive response action for Enterprise Security.

After you are finished building and packaging your response action, test it in Enterprise Security. See Validate your response action in Enterprise Security.

 Create an adaptive response action manually

To create a response action manually, you follow the same steps that you would to create an alert action, with a few additions.

The directions in this section describe the steps required to create a custom alert action that is compatible with the common action model and fully functional in Splunk Enterprise Security as an adaptive response action. You can also refer to the Example adaptive response action for a detailed example of a functioning response action.

Prerequisite

Install the Common Information Model Add-on from Splunkbase. Refer to the Common Information Model Add-on documentation for reference information about the common action model and its components. See Use the common action model to build custom alert actions.

Steps

1. Set up the file structure and permissions
2. Define the parameters for your action
3. Write your response action script
4. Provide a user interface and validation
5. Create event types and tags
6. Package your add-on
7. Validate your response action in Enterprise Security

 Set up the file structure and permissions

Set up the file structure for your action.

[TA-add-on_name]
    appserver
        static
            [app_icon].png
    bin
        [custom_alert_action_script]
...
Show More

In addition to the standard files required for creating a custom alert action, a response action includes a tags.conf and an eventtypes.conf file in the default directory.

Apply permissions in default.meta which allow everyone to read the configurations and only admins to write them. This allows all users to invoke your adaptive response action.

## shared Application-level permissions
[]
access = read : [ * ], write : [ admin ]
export = system

 Define the parameters for your action

Before you begin, determine which parameters the alert needs once, which ones it needs for every action, and which ones need to be exposed for end users to provide when they configure the action.

1. Create your default/alert_actions.conf. To begin, include all of the expected parameters of a custom action in your stanza, as shown in the example below.

   [<actionname>]
   is_custom= 1
   label= <friendly name for the action>
   description= <brief description of the action>
   icon_path= <icon file name>
   payload_format= json
   ttl= 240
   command= sendalert $action_name$ results_file="$results.file$" results_link="$results.url$" param.action_name=$action_name$ | stats count
   ...
   

2. Next, add all of the custom parameters you need for your action logic to this stanza, using the format param.<customparameter> for each one.

3. Include the param._cam parameter, following the format and examples provided in the alert_actions.conf.spec and alert_actions.conf.example in the Common Information Model Add-on README directory.

4. In parallel with your edits to alert_actions.conf, edit your alert_actions.conf.spec to include all your custom parameters. Place them under a stanza name that matches the name of your action. You do not need to add param._cam here because the CIM has this defined in its spec file already.

5. Create your savedsearches.conf.spec and repeat the specs for the custom parameters that need to be exposed to users on a per-action basis.

6. If you have any global parameters, create a setup page to prompt the admin for these settings when they first install and configure your add-on. See Enable first-run configuration with setup pages in Splunk Cloud Platform or Splunk Enterprise.

For more details and developer reference links for any of the above steps, see Set up custom alert configuration files and Optional custom alert action components.

 Write your response action script

Next, write the Python script to carry out the logic of your response action, log its progress, and write out result events. The name of your script file should match the stanza name in alert_actions.conf exactly.

When the action is invoked either by a search or on the Incident Review dashboard, this script runs with a standard payload. The payload provides a link to the results file, which the script opens and iterates through. As the script iterates through the result set, it invokes methods provided in cim_actions.py that log the activities of the action. The script finishes by writing arbitrary Splunk events per your definition. For example, if your action collects data, you can write out new Splunk events with that data.

Refer to Example response action for a sample script created manually using the cim_actions.py library.

 Provide a user interface and validation

Create your <action_name>.html file to define the user interface for configuring the response action. Place this file in default/data/ui/alerts. See HTML file for the response action form for an example of this file.

Write up your parameter validation in default/restmap.conf. See restmap.conf for an example of this file. The validation you provide here only applies to response actions attached to saved searches. For this reason, you should also include validation within your alert action script to cover cases when the alert action is invoked as an ad hoc action.

 Create event types and tags

Tag the results that your action produces with the tag modaction_result. Apply this tag to the result data produced by the action so that Splunk Enterprise Security can retrieve and display those results to users. The tag enables the default drilldown behavior for a response action on the Incident Review dashboard in Splunk Enterprise Security, and you can also use it to display results in custom apps or views.

1. Create a default/eventtypes.conf. This file should define the results produced by the action as an event type, using the source type that you specified when you used the writeevents() method in your script. If your script specifies a specific index, also include that for best performance. For example,

   [<actionname>]
   search = index=myaction_results sourcetype=myactionname:results
   

2. Create a default/tags.conf. This file should contain a stanza that tags the event type you created in the previous step with the tag modaction_result. For example,

   [eventtype=<actioname>]
   modaction_result = enabled
   

 Package your add-on

Package your add-on and install it on an instance running Splunk Enterprise Security for testing.

 Validate your response action in Enterprise Security

After you have packaged up your response action and installed it on an instance of Splunk Enterprise Security, verify that it functions as expected.

 Test that your action appears in Splunk Enterprise Security

Your response action should appear as an option under Adaptive Response Actions when you create or edit a correlation search from Content Management. For more information, see Add an adaptive response action to a correlation search.

If your response action supports ad hoc invocation, it should also be available in the list of actions you can run on any notable event on the Incident Review dashboard. For more information about running response actions from Incident Review, see Run an adaptive response action.

After your action has been dispatched, either from a correlation search or as an ad hoc action, it should appear in the details view of a notable event on the Incident Response dashboard. In the Adaptive Responses table, click the action name to view the result events produced by the action. If the action included a custom drilldown URL, clicking the action name should direct you to the correct custom view instead.

To view introspection events for the action, click View Adaptive Response Invocations immediately below the Adaptive Responses table. For more information about reviewing notable event details, see Investigate notable event on Incident Review in Splunk Enterprise Security.

 Test your action using the search language

To test using the search language, pass all the parameters that lack a default.

| makeresults | eval <include any parameters here that are required for your action to execute upon> 
| sendalert <action_name> param.<custom_parameter1>=<somevalue> param.<custom_parameter2>=<somevalue>

Your search should return a result in a statistics view.

 Test ad hoc invocation of your action using the search language

To test ad hoc invocation, make a notable event.

Prerequisite

In order to run an adaptive response action that uses the credential store, you must have the list_storage_passwords capability.

Steps

1. Run | makeresults | eval<include any parameters here that are required for your action to run>| sendalert notable
2. After the search completes, go to the Incident Review dashboard and find the row that corresponds to the manual notable event you just created.
3. Choose Run Adaptive Response Action in that row.
4. Select your response action and fill out the form.
5. Dismiss the window.
6. Expand the notable event to view its details.
7. Click the name of your action in the Adaptive Responses section.

If you did not specify a custom drilldown, you see the event or events that you created from your action. If you specified a custom drilldown, you are redirected to the custom view you specified.