Understanding callbacks

In the context of playbooks, callbacks are Python callables that can accept the keyword arguments described in this section. For more information see https://docs.python.org/3.6/library/functions.html#callable

Callbacks can be used in the following two ways:

1. Through playbook code. For example, the code generated by a decision block will only call the callback if the return value of the call to phantom.decision is 'True'.
2. Through the automation engine. There are three playbook APIs that accept a callback keyword argument: phantom.act, phantom.custom_function, and phantom.playbook. When you pass a callable to these APIs, that callback will be invoked from within the automation engine once the action, custom function, or child playbook completes execution.

Callback functions can be invoked with any of the following keyword arguments: action, success, container, results, handle, filtered artifacts, filtered results, and custom function, depending on what the preceding block provides. Each of these parameters is discussed in greater detail in the following table.

Parameter	Description
action	This is a JSON object that specifies the action name and the action run ID. The action run ID uniquely identifies that instance of action execution and can be used to retrieve the details of the action execution. The following is an example of an action parameter from a callback: { "action_run_id": 205, "action_name": "whois ip", "action" : "whois ip", "name": "my_whois_ip_action" } The 'action' field replaces the action_name field. The action_name field will be removed in a future release.
success	Either 'True' or 'False'. An action is considered failed only if the action has failed on all assets and with all specified parameters. If any part of the action succeeds, it is not considered failed. Use the utility functions like parse_errors() or parse_success() to get a flat listing of all errors and success. These utility functions parse the results to give the user a different view of the overall results.
container	This is the container JSON object. Here is an example of container parameter from a callback: { "sensitivity": "amber", "create_time": "2016-01-14 18:25:55.921199+00", "owner": "admin", "id": 7, "close_time": "", "severity": "medium", "label": "incident", "due_time": "2016-01-15 06:24:00+00", "version": "1", "current_rule_run_id": 1, "status": "open", "owner_name": "", "hash": "093d1d4d22cab1c5931bbfb1b16ce12c", "description": "this is my test incident", "tags": ["red-network"], "start_time": "2016-01-14 18:25:55.926468+00", "asset_name": "", "artifact_update_time": "2016-01-14 18:26:33.55643+00", "container_update_time": "2016-01-14 18:28:43.859814+00", "kill_chain": "", "name": "test", "ingest_app_id": "", "source_data_identifier": "48e4ab9c-2ec1-44a5-9d05-4e83bec05f87", "end_time": "", "artifact_count": 1 }
results	This is a JSON object that has the full details and status of the complete action on all assets for each parameter. Here is an example where the geolocate ip action is run: parameters = [] parameters.append({ "ip" : '1.1.1.1' }) phantom.act('geolocate ip', parameters=parameters, assets=["maxmind"], callback=geolocate_ip_cb, name='my_geolocate_action') This simple action can result in various execution strategies and outcomes, depending on how the system is configured. In this simple form, one app supports the geolocate IP action and there is one 'Maxmind' asset that is configured which results in one IP being queried once on one asset. In a more complex example, if there are two Apps, both of which support file reputation, then this one simple action will result in a file hash being queried on both of the assets. The single action file reputation will result in the hash being queried twice, once on each asset. The two queries still constitute one action, so the callback 'file_reputation_cb' will be called once when both the queries have completed. The parameters in the example is a list of dictionaries and contains one IP. But, in one action call the user can specify many different IP addresses. The results JSON object provides full visibility into the execution of the action on all matching assets using all matching apps for all specified parameters. Here are the results of the geolocate ip action. [ { "asset_id": 63, "status": "success", "name": "geolocate_ip_1", "app": "MaxMind", "action_results": [ { "status": "success", "data": [ { "state_name": "Victoria", "latitude": -37.7, "country_iso_code": "AU", "time_zone": "Australia/Melbourne", "longitude": 145.1833, "state_iso_code": "VIC", "city_name": "Research", "country_name": "Australia", "continent_name": "Oceania", "postal_code": "3095" } ], "message": "City: Research, State: VIC, Country: Australia", "parameter": { "ip": "1.1.1.1", "context": { "guid": "f42fd73f-...-8194aaa9bc11", "artifact_id": 0, "parent_action_run": [] } }, "summary": { "city": "Research", "state": "VIC", "country": "Australia" } } ], "app_id": 83, "summary": { "total_objects": 1, "total_objects_successful": 1 }, "asset": "maxmind", "action": "geolocate ip", "message": "'geolocate_ip_1' on asset 'maxmind': 1 action succeeded. (1)For Parameter: {\"ip\":\"1.1.1.1\"} Message: \"City: Research, State: VIC, Country: Australia\"", "app_run_id": 51, "action_run_id": 11 } ]
handle	A string object that was specified in the action phantom.act() call for passing data between action and callbacks.
filtered_artifacts	Refers to a field in the artifact that was filtered from a previous decision block. For example, filtered_artifact:*.cef.bytesIn.
filtered_results	Refers to a field in the action result object of a named action that has been filtered. The phantom.condition() statement returns those action_result objects or artifact IDs that match the condition. Requires that the filtered results be provided as the parameters. For example, geolocate_ip_1:filtered-action_result.parameter.ip.
custom_function	Use custom_function to call a custom function from a playbook.

The simplest callback looks like this:

def do_nothing(**kwargs):
    pass

This callback can accept all of the keyword arguments that are passed to it, but it doesn't do so. This callback function does not callback into any other function so playbook execution along this branch ends when this callback is invoked.

The following is an example of a callback that makes a debug call and then calls another callback. This callback isn't very useful in a real playbook, but it demonstrates how callbacks work.

def call_a_friend(**kwargs):
    phantom.debug('Invoking geolocate_ip_1')
    geolocate_ip_1(**kwargs)