Tutorial: Specify parameters in

Most actions require at least one parameter to function. Parameters are lists of dictionaries that are passed to the action. The specific action dictates the format and set of required parameters. Refer to the API documentation for the app you're leveraging to get the required parameters.

This example uses the WHOIS app to execute a simple WHOIS query. The WHOIS domain action requires one parameter: a domain name.

import phantom.rules as phantom
import json

def whois_domain_cb(action, success, container, results, handle):

    if not success:
        return

    return

def on_start(incident):

    params = [ { "domain": "phantom.us" },
               { "domain": "splunk.com" } ]
    
    phantom.act('whois domain', parameters=params, callback=whois_domain_cb)
    return

The playbook runs and produces results that you can view on the container detail screen or in Investigation in the WHOIS app.

2015-03-14T23:21:02.688000:  Processing incident: '4' [2a76c74c-5713-11e4-8a26-9b99986c1e2a]
2015-03-14T23:21:02.690000:  act(): Warning: For action 'whois domain' no assets were specified. The action shall execute on all matching assets
2015-03-14T23:21:02.704000:  act(): No assets found for action 'whois domain'.
2015-03-14T23:21:02.705000:  act(): action details: [whois domain] parameters: [[{"domain": "phantom.us"}, {"domain": "splunk.com"}]] assets: [] callback function: [whois_domain_cb] and NO user specified for reviewing params
2015-03-14T23:21:02.711000:  act(): No action parameter review or asset approval requests generated.
2015-03-14T23:21:02.712000: Starting action 'whois domain' on asset ''
2015-03-14T23:21:02.717000: running: The connector 'WHOIS App' started successfully. Execution parameters sent.
2015-03-14T23:21:02.970000: running: Loaded action execution configuration
2015-03-14T23:21:04.845000: success: 3 of 3 actions succeeded
2015-03-14T23:21:04.864000: Command 'whois domain' success. 3 of 3 actions succeeded
2015-03-14T23:21:04.869000:  calling action callback function: whois_domain_cb
 *** The Rule has completed. Result: success *** 

Dynamically build parameters from container data

Hard coding parameters into you scripts doesn't allow much flexibility. The key is to use data from a container and operate on it by using it as parameters to actions. You can extract data from the container itself either by directly indexing into the JSON elements or through the collect() call.

collect() uses data paths as a method to index into the JSON elements by searching for the appropriate key and retrieving the associated values. Data paths and collect() help simplify this.

In this example, you have an incident with some artifacts that have domain names in them within the Common Event Format (CEF) structure. You can use the following function to extract all domain names.

import phantom.rules as phantom
import json

def whois_domain_cb(action, success, container, results, handle):

    if not success:
        return

    return

def on_start(incident):

    params = []

    hosts = phantom.collect(incident, 'artifact:*.cef.sourceDnsDomain', 'all', 100)
    for host in hosts:
        params.append({ 'domain': host })     

    phantom.act('whois domain', parameters=params, callback=whois_domain_cb)
    return

Example result:

2015-03-14T23:51:36.309000:  Processing incident: '4' [2a76c74c-5713-11e4-8a26-9b99986c1e2a]
2015-03-14T23:51:36.336000:  act(): Warning: For action 'whois domain' no assets were specified. The action shall execute on all matching assets
2015-03-14T23:51:36.345000:  act(): No assets found for action 'whois domain'.
2015-03-14T23:51:36.345000:  act(): action details: [whois domain] parameters: [[{"domain": "phantom.us"}, {"domain": "splunk.com"}]] assets: [] callback function: [whois_domain_cb] and NO user specified for reviewing params
2015-03-14T23:51:36.357000:  act(): No action parameter review or asset approval requests generated.
2015-03-14T23:51:36.359000: Starting action 'whois domain' on asset ''
2015-03-14T23:51:36.394000: running: The connector 'WHOIS App' started successfully. Execution parameters sent.
2015-03-14T23:51:36.852000: running: Loaded action execution configuration
2015-03-14T23:51:38.103000: success: 3 of 3 actions succeeded
2015-03-14T23:51:38.116000: Command 'whois domain' success. 3 of 3 actions succeeded
2015-03-14T23:51:38.121000:  calling action callback function: whois_domain_cb
 *** The Rule has completed. Result: success ***