Tutorial: Create a simple playbook in Splunk Phantom

One of the simplest examples of a playbook is one that executes a single action and does nothing with the results. The following geolocate ip action is one such example:

import phantom.rules as phantom

def on_start(container):

    phantom.act(action="geolocate ip",
                parameters=[{'ip': "1.1.1.1"}])

def on_finish(container, summary):
    return

The only parameter required by the geolocate ip action is provided with a hard-coded value. Because you haven't specified an asset or an asset tag to operate on, Splunk Phantom finds all assets that have a supporting app which support the geolocate ip action and runs the action against each of them. In a default Splunk Phantom installation, this will only use the MaxMind app, but other possibilities include services like FreeGeoIP and HackerTarget.

Incorporate a callback

The previous example executed the first action. While it queried MaxMind for the location of an IP address, it didn't leverage the results or take any further action. Because Splunk Phantom runs all actions asynchronously to minimize waiting periods, you must incorporate a callback function to parse the results and act on the location information discovered by the geolocate ip action.

To incorporate a callback, pass the callback parameter to the act() function with a callback function that receives these results. The following example shows how to incorporate a callback:

Example

Example function

import phantom.rules as phantom

def on_start(container):

    phantom.act(action="geolocate ip",
                parameters=[{'ip': "1.1.1.1"}],
                callback=geolocate_ip_cb
               )
def geolocate_ip_cb(action=None, success=None, container=None, results=None, handle=None, filtered_artifacts=None, filtered_results=None, custom_function=None):

    if not success:
        return

    return

def on_finish(container, summary):
    return

For more information about the callback function, see callback in the Python Playbook API Reference for Splunk Phantom.

Insert debug statements

Add the debug() function to insert debug statements that you can see when running your playbook on a container. The following example demonstrates how to insert debug statements:

Example

Example function

import phantom.rules as phantom

def on_start(container):

    phantom.act(action="geolocate ip",
                parameters=[{'ip': "1.1.1.1"}],
                callback=geolocate_ip_cb
               )

def geolocate_ip_cb(action=None, success=None, container=None, results=None, handle=None, filtered_artifacts=None, filtered_results=None, custom_function=None):

    if not success:
        phantom.debug("failed action: {}".format(action))
        return

    phantom.debug("successful action: {}".format(action))
    return

def on_finish(container, summary):
    return

The function produces debug output in the debug console when you execute your playbook. Use the output to inspect and debug your playbook before deploying it in production.

Example output

Fri May 01 2020 11:42:36 GMT-0400 (Eastern Daylight Time): Starting playbook 'local/tutorial (version: 10, id: 76)' on 'events'(id: 1) with playbook run id: 10, running as user 'admin(root@localhost)'(id: 1) with scope 'all'
Fri May 01 2020 11:42:36 GMT-0400 (Eastern Daylight Time): calling on_start() on events 'tester 1'(id: 1). 
Fri May 01 2020 11:42:36 GMT-0400 (Eastern Daylight Time): phantom.act(): for action 'geolocate ip' no assets were specified and hence the action shall execute on all assets the app (supporting the action) can be executed on
Fri May 01 2020 11:42:36 GMT-0400 (Eastern Daylight Time): phantom.act(): action 'geolocate ip' on assets: maxmind, callback function: 'geolocate_ip_cb', with no action reviewer, no delay to execute the action, no user provided name for the action, no tags, no asset type
Fri May 01 2020 11:42:36 GMT-0400 (Eastern Daylight Time): 'geolocate ip' shall be executed now on asset 'maxmind'(id:2) using app 'MaxMind'
Fri May 01 2020 11:42:36 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': app 'MaxMind' started successfully. Execution parameters sent.
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': Loaded action execution configuration
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': MaxMind DB loaded
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': 1 action succeeded. (1)For Parameter: {"ip":"1.1.1.1"} Message: "City: Research, State: VIC, Country: Australia"
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): 'geolocate ip'  on asset 'maxmind' completed with status: 'success'. Action Info: [{"app_name":"MaxMind","asset_name":"maxmind","param":{"ip": "1.1.1.1", "context": {"guid": "945257ce-b1f4-424a-9541-f11fd8bb48bd", "artifact_id": 0, "parent_action_run": []}},"status":"success","message":"City: Research, State: VIC, Country: Australia"}]
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): calling action 'geolocate ip''s callback function 'geolocate_ip_cb()'
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): successful action: {'action': 'geolocate ip', 'action_name': 'geolocate ip', 'type': 'investigate', 'action_run_id': 9, 'name': 'geolocate ip'}
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): finished action 'geolocate ip''s callback function 'geolocate_ip_cb()'
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): 

Playbook 'tutorial' (playbook id: 76) executed (playbook run id: 10) on events 'tester 1'(container id: 1).
   Playbook execution status is 'success'
	Total actions executed: 1
	Action 'geolocate ip'(geolocate ip)
	   Status: success
		App 'MaxMind' executed the action on asset 'maxmind'
		   Status: success
		   Parameter: {"ip":"1.1.1.1"}

Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): *** Playbook 'local/tutorial' execution (10) has completed with status: SUCCESS ***
Fri May 01 2020 11:42:37 GMT-0400 (Eastern Daylight Time): 1 action succeeded

Perform final actions

After the playbook runs and all actions finish executing, call the on_finish() handler to perform any final actions. For example, you might send a summary email, close an incident, or update a ticketing system with a status.

The following example shows how to incorporate an on_finish() handler:

Example

Example function

import phantom.rules as phantom

def on_start(container):

    phantom.act(action="geolocate ip",
                parameters=[{'ip': "1.1.1.1"}],
                callback=geolocate_ip_cb
               )

def geolocate_ip_cb(action=None, success=None, container=None, results=None, handle=None, filtered_artifacts=None, filtered_results=None, custom_function=None):

    if not success:
        phantom.debug("failed action: {}".format(action))
        return

    phantom.debug("successful action: {}".format(action))
    return

def on_finish(container, summary):

    phantom.debug(summary)
    return

Example response

Fri May 01 2020 11:44:14 GMT-0400 (Eastern Daylight Time): Starting playbook 'local/tutorial (version: 11, id: 77)' on 'events'(id: 1) with playbook run id: 11, running as user 'admin(root@localhost)'(id: 1) with scope 'all'
Fri May 01 2020 11:44:14 GMT-0400 (Eastern Daylight Time): calling on_start() on events 'tester 1'(id: 1). 
Fri May 01 2020 11:44:14 GMT-0400 (Eastern Daylight Time): phantom.act(): for action 'geolocate ip' no assets were specified and hence the action shall execute on all assets the app (supporting the action) can be executed on
Fri May 01 2020 11:44:14 GMT-0400 (Eastern Daylight Time): phantom.act(): action 'geolocate ip' on assets: maxmind, callback function: 'geolocate_ip_cb', with no action reviewer, no delay to execute the action, no user provided name for the action, no tags, no asset type
Fri May 01 2020 11:44:14 GMT-0400 (Eastern Daylight Time): 'geolocate ip' shall be executed now on asset 'maxmind'(id:2) using app 'MaxMind'
Fri May 01 2020 11:44:14 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': app 'MaxMind' started successfully. Execution parameters sent.
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': Loaded action execution configuration
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': MaxMind DB loaded
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): 'geolocate ip' on asset 'maxmind': 1 action succeeded. (1)For Parameter: {"ip":"1.1.1.1"} Message: "City: Research, State: VIC, Country: Australia"
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): 'geolocate ip'  on asset 'maxmind' completed with status: 'success'. Action Info: [{"app_name":"MaxMind","asset_name":"maxmind","param":{"ip": "1.1.1.1", "context": {"guid": "16cc5fdc-88d1-42b3-9385-fdcdf3700bd2", "artifact_id": 0, "parent_action_run": []}},"status":"success","message":"City: Research, State: VIC, Country: Australia"}]
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): calling action 'geolocate ip''s callback function 'geolocate_ip_cb()'
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): successful action: {'action': 'geolocate ip', 'action_name': 'geolocate ip', 'type': 'investigate', 'action_run_id': 10, 'name': 'geolocate ip'}
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): finished action 'geolocate ip''s callback function 'geolocate_ip_cb()'
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): 

Playbook 'tutorial' (playbook id: 77) executed (playbook run id: 11) on events 'tester 1'(container id: 1).
   Playbook execution status is 'success'
	Total actions executed: 1
	Action 'geolocate ip'(geolocate ip)
	   Status: success
		App 'MaxMind' executed the action on asset 'maxmind'
		   Status: success
		   Parameter: {"ip":"1.1.1.1"}

Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): 

Playbook 'tutorial' (playbook id: 77) executed (playbook run id: 11) on events 'tester 1'(container id: 1).
   Playbook execution status is 'success'
	Total actions executed: 1
	Action 'geolocate ip'(geolocate ip)
	   Status: success
		App 'MaxMind' executed the action on asset 'maxmind'
		   Status: success
		   Parameter: {"ip":"1.1.1.1"}

Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): *** Playbook 'local/tutorial' execution (11) has completed with status: SUCCESS ***
Fri May 01 2020 11:44:15 GMT-0400 (Eastern Daylight Time): 1 action succeeded