Build an InsightIDR Enrichment Workflow!

InsightConnect Workflows
1

Whether you are brand new to SOAR or have been building workflows for years, this post should help you learn more about how to use actions with connections in InsightConnect!

Start from Scratch

This tutorial will walk through building our Enrich InsightIDR Alerts with Threat Intelligence from VirusTotal workflow. I like this workflow because enrichment is an extremely common use case and you can build this workflow without deploying an Orchestrator!

To start, create a new workflow from scratch (login to InsightConnect > Workflows tab > Add Workflow > Start from Scratch). Name, describe, tag, and mark time savings for your workflow as you see fit. I recommend adding a tag and a time savings metric so you can visualize ROI data when the workflow is up and running. Here’s my setup (note: Dark Mode!):
image

Choose the InsightIDR User Behavior Analytics (UBA) Alert alert trigger and name your trigger. I like to give steps short but clear names, like IDR UBA Trigger, so it’s easy to find the right step output in the variable picker (more on that later).

Now, take a quick look at the Input variables in the trigger. These are all the data points InsightIDR is going to pass into the InsightConnect workflow for us to build around. See the contents object? That contains the indicators of compromise (IOCs) that we are going to build our enrichment workflow around!
image

Some triggers allow you to customize these trigger variables. The IDR UBA Alert trigger, however, does not, so you can go ahead and save the trigger step now.

Now We’re Building!

To get started quickly, let’s pretend this workflow is only meant to be used for enriching a certain type of indicator. That could be an IP address, a URL, a domain, or a hash. I’m going to start with an IP address, though you can choose a different indicator type if you so desire!

Add a Loop step to your workflow:
image

In the Variable to repeat over dropdown, choose the <your trigger name>.contents.ipAddresses array.
image

Throw Me for a Loop

Now, you might be asking: Why are we adding a loop step? Why are we choosing this ipAddresses array?

Since Investigations in InsightIDR can involve multiple indicators of the same type, we need to make sure our workflow handles multiple IPs gracefully. Using a loop step allows us to iterate over each IP address in the investigation. We can then run one or more workflow steps targeting each individual IP address.

For more on Loop Steps, check out our Help Docs!

Lights, Camera, Action!

Inside the loop, let’s add an Action step:
image

Search for and select the VirusTotal plugin.
image

If you don’t see VirusTotal, then just click Add Plugin and import it!

If you see an older version (< 10.0.0) of the VirusTotal plugin, hop over to Settings > Plugins & Tools and update the VirusTotal plugin. You can also click the link in the banner to update all your plugins.

Choose the IP Address Report action and continue.

Creating a Connection

Connections are vital when automating your processes. Each connection creates an opportunity to integrate your tools together and orchestrate work across your apps and services. While you may choose to run all your connections from your on-premise Orchestrator, we at Rapid7 are working hard to make as many connections as possible cloud-native!

VirusTotal is one of our cloud-native plugins. Let’s walk through how you can set up a cloud connection, which will run your VirusTotal action steps on the Rapid7 cloud. Running actions on the cloud is faster and more reliable, as InsightConnect doesn’t need to depend on your Orchestrator and network to run action steps.

Creating a Cloud Connection

Now we need to set up a VirusTotal Connection. All you need is a free VirusTotal user account and your API key.

For more guidance on setting up a VirusTotal connection, see our VirusTotal Connection Setup Guide.

Choose Add a New Connection. Name your connection and choose Add Credential in the Select Credential dropdown menu. Add a name and description for your VirusTotal API key, then paste the key itself into the Secret Key field. Finally, you may choose to make this credential available in other Rapid7 products that use the Platform Credentials feature. At the time of writing this post, InsightConnect is the only product using this feature.

image

Now, click Save & Test Connection! You’ll see a connection test run and confirm your connection is working! Go ahead and close the pop-up and click Continue in the step configuration panel.

If you receive an error, you may need to try re-entering your VirusTotal API key.

Creating an Orchestrator Connection

Should you prefer to keep your credentials and automation workload closer to home, you may choose to setup an Orchestrator connection instead. Just flip the toggle at the top of the Connection panel to “Orchestrator” and proceed through the same connection creation steps outlined above!

Configuring the IP Address Report Action

Now, let’s get this step configured! You’ll notice there is just one input field, IP Address for this action. We’re going to use an input variable here. Click in the input field, then click the
discuss4 button:
image

This will open the Variable Picker, which shows all the output variables from all previous workflow steps in reverse order (the most recent step output variables are shown first). We’re going to choose the IP Addresses.$item.ip variable here:

image

Let’s break down what this IP Addresses.$item.ip variable is:

  • IP Addresses is the name of our loop step where this variable is originating from
  • $item is the current object in the loop
  • ip is the variable from the current object

Once you’ve selected the variable, go ahead and click Save!

Decision Time

Since we can’t guarantee this IP address will be found in VirusTotal, let’s configure our workflow to gracefully handle the case when the IP is not found. Add a step after the IP Lookup, and choose the Decision step type. Name the step IP Found?, and name the two paths Found and Not Found. Choose Not Found as the default path and click Continue.

On the next screen, we’ll enter a condition to automatically determine which path to take. Click the
discuss4 button again, and select the Lookup IP.found variable. You’ll notice this is a boolean type – it will return true if the provided IP address is found in VirusTotal, and it will return false if the IP address is not found. Since our default path is Not Found, we can enter {{["Lookup IP"].[found]}}=true to go down the Found path when the Lookup IP address step successfully finds the provided IP address:
image

Artifacts!

Finally, let’s add some Artifacts to the end of each path to describe the outcome of the workflow!

Start by adding a step along the Not Found path, and choose the Artifact step type. This one can be short and sweet because we just want to indicate that the IP address was not found in VirusTotal’s database. Our workflow template does this with the following format:

## IP Address Report

*No results found for {{["IP Addresses"].[$item].[ip]}}*

Go ahead and save this step.

Our artifact for events where the IP address is found will need to be more comprehensive. Since this post is getting a little long and we have several artifact examples out there, I am going to share the raw artifact input here.

## IP Addresses Report
---
**Report for {{["IP Addresses"].[$item].[ip]}}**

{{#if ["Lookup IP"].[report].[country]}}
**Hosting country:** {{["Lookup IP"].[report].[country]}}
{{/if}}
{{#if ["Lookup IP"].[report].[network]}}
**Network:** {{["Lookup IP"].[report].[network]}}
{{/if}}
{{#if ["Lookup IP"].[report].[asn]}}
**ASN:** {{["Lookup IP"].[report].[asn]}}
{{/if}}
{{#if ["Lookup IP"].[report].[reputation]}}
**Reputation:** {{["Lookup IP"].[report].[reputation]}}
{{/if}}

Number of engines that detected malicious URLs associated with this IP: `{{["Lookup IP"].[report].[last_analysis_stats].[malicious]}}`

**Complete VirusTotal Report:** [https://www.virustotal.com/gui/ip-address/{{["IP Addresses"].[$item].[ip]}}](https://www.virustotal.com/gui/ip-address/{{["IP Addresses"].[$item].[ip]}})

Now you have all the tools you need to reconstruct our Enrich InsightIDR Alerts with Threat Intelligence from VirusTotal workflow!!! I hope this post helped you learn more about workflow steps, connections, actions, and more. To finish the workflow, you’ll need to:

  1. Add a Decision Step after the trigger to automatically identify the indicator type.
  2. Add loops for each indicator type.
  3. Add the VirusTotal lookup, automated decision, and artifacts in each loop.

Remember, you can activate the workflow and test it from an InsightIDR investigation with an indicator of compromise! Just open the investigation, click Take Action > Custom Workflow > Choose this workflow > select the indicator(s) > Take Action.

All comments, questions, and feedback are welcome!

Happy SOARing :star_struck:

3 Likes