Build playbooks compatible with the dispatch_input_playbooks utility

The dispatch_input_playbooks utility provides a standardized method for routing data to input playbooks, as well as playbooks in the playbook pack. The utility finds data in the event or container that the utility is being run against, finds registered playbooks, and then routes data to the correct playbooks. After those playbooks finish running, the utility unifies outputs and then passes them downstream.

The dispatch_input_playbooks utility is available from the Playbook block.

Understand the flow of data through the dispatch_input_playbooks utility

1. Check whether inputs can cause accidental playbook execution.
2. Find playbooks that match the criteria you specify in your input configuration.
3. Find available data types in the specified event or container.
4. Enumerate accepted data types for each playbook and then route data to the correct sub-playbook inputs.
5. Run sub-playbooks.
6. Provide reports for sub-playbook runs, aggregate the resulting data, unify the output, and pass the output downstream.

Inputs

The dispatch_input_playbooks utility accepts up to five inputs.

• playbook_tags: Access this input from the find matching playbooks block. Use this input to find only playbooks that conform to all the tags you provide. You must provide at least one tag or else the dispatcher raises an error.
• playbook_repo: Access this input from the find matching playbooks block. Use this input to find available playbooks that are located in repositories you provide. If you don't specify a repository, the default is "local." If you try to launch "community" playbooks, an exception is raised.
• indicator_tags_include: Access this input from the collect indicator block. This input is an enhanced "or" filter used to make sure indicators with certain tags are included.
• indicator_tags_exclude: Access this input from the collect indicatorblock. This input is an enhanced "or" filter used to make sure indicators with certain tags are excluded.
• artifact_ids_include: Access this input from the collect indicatorblock. This input is an enhanced filter to make sure artifacts with certain IDs are included.

Outputs

The dispatch_input_playbooks has two universal outputs and two situational outputs.

Universal outputs

Universal outputs pass data from the dispatch_input_playbooks utility downstream. Universal outputs aren't required. Unless a sub-playbook you dispatch contains universal outputs, they don't exist.

• note_content: Use this output to pass downstream a list of formatted strings that you can use to add workbook tasks, comments, or notes. Sample data path: playbook_dispatch_input_playbooks_1:playbook_output:note_content.
• verdict: Use this output to pass downstream a list of strings representing overall playbook verdicts, instead of any specific indicator verdicts. Sample data path: playbook_dispatch_input_playbooks_1:playbook_output:verdict.

Situational outputs

• sub_playbook_outputs: Use this output to pass downstream a list of dictionaries representing all outputs generated by sub-playbook runs, organized by playbook_name. Each unique playbook represents one entry in the list, which you can filter by. If no dispatched playbooks have outputs, the path and its contents don't exist. Sample data path: playbook_dispatch_input_playbooks_1:playbook_output:sub_playbook_outputs.
  • playbook_name: This output is a single-value string that represents the human-readable name of the playbook that was launched, not an auto-generated block name. Sample data path: playbook_dispatch_input_playbooks_1:playbook_output:sub_playbook_outputs.playbook_name.
  • <output1>: A playbook's output displays in the same dictionary where the playbook's name is. You can't filter nested paths beyond this key. Sample data path (filterable): playbook_dispatch_input_playbooks_1:playbook_output:sub_playbook_outputs.ip_reputation.
    

Sample data path (not filterable): playbook_dispatch_input_playbooks_1:playbook_output:sub_playbook_outputs.ip_list.*.ip_reputation

• sub_playbook_inputs: Use this output to pass downstream a list of dictionaries that contain all inputs sent to sub-playbook runs, organized by the name of the playbook. Each unique playbook represents one entry in the list, which you can filter by. Unlike sub_playbook_outputs, this output exists so long you launch any input_playbooks. Sample data path: playbook_dispatch_input_playbooks_1:playbook_output:sub_playbook_inputs.
  • playbook_name: This output is a single-value string that represents the human-readable name of the playbook that was launched, not an auto-generated block name. Sample data path: playbook_dispatch_input_playbooks_1:playbook_output:sub_playbook_inputs.playbook_name.
  • <input1>: A playbook's input displays in the same dictionary where the playbook's name is. Sample data path: playbook_dispatch_input_playbooks_1:playbook_output:sub_playbook_inputs.username.

Safety measures

The playbook pack has multiple safety measures that ensure the content is performant and doesn't negatively affect Splunk SOAR deployments.

• Content can't be launched directly from the community. Prohibiting launches from the community ensures that no content is launched without the SOAR admin or automation engineer's explicit direction, so playbooks must be copied to local or another non-community repository before you launch a playbook using this method.
• Content must be launched with a tag. Making tags required reduces the likelihood of content being launched without a content author explicitly declaring that an input_playbook be used for the intended purpose.
• Data types must be gathered in a performant way. The method of gathering playbooks, gathering available data, and routing them has been stress tested against a SOAR environment with thousands of indicators, and thousands of containers being generated per hour.
• Data types must match accepted input types. No input playbook that accepts one data type can be given a data type the input playbook isn't able to handle. However, a playbook can receive data that is miscategorized. For that reason, playbook authors should ensure their playbooks handle those situations by filtering or erroring out appropriately.