Splunk SOAR: Let’s Get That Pin

By David Burns, Senior Soar Engineer

In a previous blog post, we introduced you to adding pins to the HUD. But what if you want to do something based off the information in the pin? Unless the pin was created within a custom code block or custom function, the pin id is blind to us. That means it’s hard to update or delete the pins natively.

We’re left to trying to stash that value somewhere in the container or pass it around. What if we want to get the value of the pin? As of version 6.2.0, there isn’t a native function to get that data. Let’s build our own custom function to accomplish this!

The meat of the function will be the container_pin endpoint.

While the documentation’s example uses POST, this endpoint has a full set of CRUD operations. That means using GET will retrieve the first 10 pins that it retrieves, with the data structure below.

Parameter	Type	Description
Id	Integer	Id of the pin. Able to reference this pin directly by appending it to the endpoint rest/container/42
pin_style	String	Values are: “grey” “blue” “red”
create_time	String	Example : 2023-05-15T22:39:23.464533Z
modified_time	String	Example : 2023-05-15T22:39:23.464533Z
custom_field	String	The name of the custom field stored with in the container.
preset_metric	String	If the “pin_type” is set to “preset_metric” set the metric to use. Options are: “remaining tasks” “failed actions” “failed playbooks” “tasks exceeding sla” “time to resolve”
order	Integer	Position within the HUD
pin_type	String	It will be one of the four following options. And which one is present will determine what other fields are present. “data” “manual card” “custom field” “preset metric”
Container	Integer	Which container the pin exists in.
author	Integer	The user id of whoever created the pin
name	String	The name of the pin when it was created
message	String	The string to display above the value in data
data	String	The value to display.
input_type	String	Either text select
input_choices	JSON List	Only if input_type is select, will this show the list of choices. Example: [“one”, “two”, “three”]

If you were to just read the container_pin endpoint, you’d get swamped fast. It’s a better option to either move page to page or trying to parse the entire list with page_size=0. This means we need to use the endpoint filtering options. I highly recommend this “Cheat Sheet” to help filter down the options within the custom function.

First, you need to get all the pins that are part of a specific container.

Then, check each pin until you find the correctly named pin.

This is straight forward, yes. But there are ways to make this overall function a bit more robust, so you end up with something like this.

Now with this function, or something like it, you’ll have another way to pass information into playbooks. Imagine reading a pin that dictates what type of email to send when a playbook is kicked off. Or if you want to selectively pass IPs into a deeper investigation. The options are endless!