Think about all the different types of information you might encounter in a typical workday: some text in an email you receive; a particular number you’ve written down on a sticky note; a list of IP’s. All of these things may not only influence which particular task you choose to tackle next, but also how you go about accomplishing it.
When it comes to InsightConnect workflows, we can store these bits and pieces of information as something called a variable. A variable simply holds data that you can use to accomplish something in the context of an InsightConnect workflow.
There are two types: input and output variables. Let’s take a closer look at what each of these mean.
- Input variable: A piece of information that you pass into a workflow step. For example, say I want to look up a particular IP with WHOIS. The IP would be an input for the WHOIS step in my workflow, because I’m passing it in to perform the lookup.
- Output variable: A piece of information that a workflow step produces. For example, say I’ve completed a WHOIS lookup in my workflow. The pieces of information that step produces, like the address, org, and other info relating to the IP, would be outputs.
When building workflows, we regularly use output variables from upstream workflow steps as input variables later on in the workflow. These variables enable us to pass information throughout our workflow and take some sort of action with their values.
If you’ve configured a step in your InsightConnect workflow and you’d like to see what output variables are available for use, click on that step in the workflow builder, and then scroll down to the bottom of the panel that pops up.
These are some of the output variables that you would see when using the Domain Lookup action of the WHOIS plugin. We might use one of these outputs to determine how we want to handle this domain that we’ve just looked up. This is how we can begin to build out workflows to automate various processes in our environment!
Anyway, now that we know a little more about what a variable is, let’s take a look at some examples with actual workflows from our Extension Library.
Example
Let’s start with a simple workflow (available here!) where we want to check the block status of a particular host.
This workflow is triggered by a Slack message (though you could also configure it to use Microsoft Teams!) where the user enters “block-status” followed by an IP. The full command may look like this: “block-status 1.2.3.4”
And guess what - with this workflow trigger, we already have our first output variables! If you click into the trigger step and look at the Output section, you can start to see what variables are available for use in future workflow steps.
In this case, the “Message.text” variable is what we want. It refers to the full text command that the user entered in Slack: “block-status 1.2.3.4.” We’ll use that as an input variable for our next step, because we want to take the user’s Slack message and extract just the IP from it.
Also, notice the little blue + icon that’s highlighted in the image below? That’s called the variable picker, and you can click it to see all the output variables from previous workflow steps that are available to use as input variables in the step you’re configuring.
We’re using a Pattern Match step here to identify and extract the IP from the user’s original command (which we’re using as an input variable).
Now that we’ve configured our Extract IP step, we’re ready to do a lookup for this IP! Similar to the previous step, we’re going to use the output variable from Extract IP as an input variable for our IP lookup step.
In this example we’re using Check Point Firewall to perform the lookup, but you could use any other tool that you have available to accomplish the same thing.
Here’s what the configuration looks like for this step:
And there we go! The output from this step will tell us whether the IP has been blocked, and then the workflow proceeds to inform us of the host’s block status via Slack. This workflow could certainly be enhanced as well, if there are additional actions you want to take after learning whether the host is blocked.
This workflow is a great example of how variables are passed between workflow steps, and how the output of one step may be used as the input of another step (or even several steps!)
Let’s take a look at one more example - this time using a workflow that integrates with InsightIDR.
InsightIDR Workflow
The workflow Alert on InsightIDR Multi-Country Authentication triggers on an InsightIDR User Behavior Analytics (UBA) alert that fires when a user is logged in from two or more countries. UBA alert triggers have a LOT of great data that you can use in your workflow - things like user details, related assets, and any indicators.
In this case, the UBA alert provides us with an array (AKA a list) of IP’s that we can use in our workflow. The first thing we want to do is look up what countries these IP’s are associated with. This occurs in a loop step, where we perform that lookup for every IP in the list we have.
This is what our loop step configuration looks like. We’re taking the list of IP’s from the UBA trigger and iterating over each item in the list to perform a particular action. In this case, those IP’s are an input variable for our loop step.
For each IP in our list, we’re going to use the IPStack plugin to look up geographical information for that IP.
Once we’ve completed each lookup, we’re going to have some more info about our IP’s in the form of output variables. This includes detailed location info like the region, country name, and potentially even address info.
This is great to have because now we can start to take action based on each IP’s location info!
From here, the workflow follows a pattern that we’ve seen in the other steps we’ve walked through in this post. The output variables we see above are later used in an Artifact card, which can be reviewed by the user who’s investigating this login incident. These output variables are also used in an Email step, where an email is sent to further alert users of this suspicious login.
This is another great example of using both input and output variables to accomplish a larger task in an InsightConnect workflow.
Further Reading
There is one more type of variable that we haven’t talked about here, and that is Workflow Parameters.
Workflow Parameters enable you to create your own custom variables that you can use throughout your workflow. This is extremely helpful if there’s a particular piece of data that you know will be leveraged across multiple steps, as parameters enable you to input that value once and then reference it by name.
That’s all for now! Hopefully, these examples have given you a better understanding of variables and the power they have when used throughout your workflows. If you’re looking to automate something but are uncertain of exactly what to do or how to do it, try configuring a single trigger for a tool that you use, and then take a look at its Output section. This will enable you to see what output variables are available for usage elsewhere, and perhaps spark ideas for how you could use those variables to accomplish a task.
And if you have any questions or other information you’d like to share related to workflow variables, please post away!