Splunk SOAR: Make the Most of Your HUD Space with Pin Lists

By Marvin Martinez, Team Lead, Automation Engineering

Splunk SOAR, sometimes affectionately referred to by its prior name, Phantom, comes bundled with a plethora of custom functions and API calls to make playbook development easier.  These include the ability to add comments or notes to a container, set a label or set a status. One useful and, frankly, cool feature is the ability to add a pin to the HUD of the container.  You can add little “post-it” style notes to the HUD to show some messages or pertinent field values. 

This is achieved by using the “pin” utility function, shown below. It allows a Splunk SOAR developer to pin a piece of information and designate a color for the pin as well as a name for later reference in case the data needs to be updated.

While these pin cards can be very handy, the limited amount of real estate in the HUD can quickly constrain how many pins you can realistically display in the HUD before having to click arrows to scroll and see pins that are off-screen. However, did you know that these pin cards in Splunk SOAR can also contain lists of data?

As implied in the image above, let’s explore a situation where you want to display a list of field values that may be relevant to the container. There could be one or many fields to display. Instead of pinning up one card for each field/value combination, you could pin up one single card with a list of all of the field/value pairs that you want and only take up one card space in the HUD. So, how to achieve this? It can be done by leveraging a documented, but somewhat hidden, feature of the container_pin REST call in Splunk SOAR. The key input to notice is the input_type and input_choices parameter fields in the container¬_pin call. You can designate the input_type to be “text” or “select”. The “pin” function included with Splunk SOAR does not have an option to define what input_type is and only allows for “text” when generating a pin card using it.

There’s 2 ways to put this REST into effect:

  • Using the post_data¬ function of the HTTP SOAR app.
  • Using custom code to programmatically generate the REST API calls

For the purposes of this article, we will leverage the Splunk SOAR/Phantom HTTP app to make this call. If you don’t already have an asset configured for this app, it is a straightforward configuration. Simply configure a new asset of this app and you’ll need to configure the following:

  • Base URL
    • Your base SOAR URL with “/rest” at the end
  • Authentication Token
    • ph-auth-token
  • Value of authentication token
    • Token value of the automation user to be used for this asset

Once your asset is ready for use, create a new action block in your playbook and select the HTTP post_data action.  Select the asset for your SOAR instance and populate the inputs.

For the location input, type in “container_pin” (no double-quotes). For the body, you’ll need to populate the JSON payload of the request.  The following fields need to be passed in (or are at least recommended):

  • container_id
    • ID of the container for pin card
  • order
    • Number where pin card will slot in. Set to “1” if you just want it at the beginning
  • message
    • A bit misleading, but it is the title of the pin card (i.e. the label that shows up as the header of the pin card)
  • data
    • Leave as an empty string (i.e. “”)
  • pin_type
    • manual_card
  • pin_style
    • This is the color you want for the pin card. Valid options are blue, red, gray (default)
  • name
    • This is the identifier of the pin card. If you want to update the pin card later, you can use the reference name (i.e. “field_values”) to overwrite the existing card instead of inserting a new one in the HUD and cluttering it up.
  • input_choices
    • This is a JSON list of strings containing list items.

For example, for the pin card displayed above, the JSON payload to the container_pin REST call would look as follows:

{
     "container_id":"<container_id>",
     "order":1,
     "message":"Multivalue Pin",
     "data":"",
     "pin_type":"manual card",
     "pin_style":"blue",
     "name":"FIELD_VALUES ",
     "input_type":"select",
     "input_choices":["Field 1: Value 1","Field 2: Value 2","Field 3: Value 3"]
}

One word of caution: please note that this request is very sensitive! If the input_choices parameter is not passed in as a valid JSON list of strings, it could cause your container view window to not load correctly. Should that happen, you’ll need to basically make a rest call again to post it correctly before the container will display as expected.  For this reason, it is heavily advised to code this up inside a custom function that can be leveraged consistently and be augmented with proper error handling in case the input_choice string is not well-formed.

There you have it!  An innovative way to pin lists to the HUD that should make your SOAR/Phantom playbook development that much more exciting!