Hi! My name is Tristan and I head up the user experience team for InsightConnect. Today we’re going to talk about Triggers—which at first might seem like a simple topic, but I think there are some great opportunities for how you approach orchestration hidden under the surface.
A Trigger is the first step of any Workflow, and kicks off the workflow based on just about anything you want.
Triggers come in several forms, from simple “API Trigger” that can be set off by any web service or system that can open a URL; to Insight Platform triggers, which come from other Rapid7 Insight products; to triggers from many of our over 300 plugins available on the Rapid7 Extension Library.
- An API Trigger allows you to trigger a workflow with a simple URL, which many services or even scripts support with ease. This is the most flexible trigger method.
- Insight Platform triggers are built-in triggers from Rapid7. If you own other Rapid7 products, you can find a variety of ways to kick off workflows from them!
- Plugin triggers are the most varied of the triggers. Any plugin you have installed might have one or more triggers, although not every plugin does. Each trigger is a bit different and can do different things depending on the product or service; for example Microsoft Teams can start a workflow based on a specific posted message, and Jira can trigger on the creation of a ticket matching certain criteria.
When a trigger runs, it brings with it any data about what started it—for example, for Microsoft Teams it might include the message, the user who posted it, what channel it was in, and more; and for Jira it might include the ticket ID, the title, the project it was in, etc. You can (and should) use this information in your workflow to do the right thing for whatever specific event happened.
Let’s take a look at a couple example workflows to understand how the trigger works and what the workflow does with its data.
Example 1: A Simple API Trigger
The first trigger we’ll look into more deeply is a simple API trigger from the workflow, “Enrich Hash with Threat Intelligence from ThreatCrowd” from the Extension Library by clicking “Import,” and then dive right into the Workflow Builder by pressing the “Edit Workflow” button. The trigger is the first step at the top of the workflow.
To start simple, let’s take a look at the API trigger starting off this workflow. API triggers are great to start with if you’re not sure what trigger to choose, since they can be run easily from within InsightConnect using the “Run” action on the workflow for testing and practice. You can see below that with an API trigger, you control what gets sent to the workflow: whether it’s an indicator, a username, an email address, or anything else.
In this workflow, all we’re asking for in our trigger is a hash, which is a String (AKA text) input. You can choose other types depending on what you want to restrict users enter or send for each input, but when in doubt, String is a good general input type that will take anything.
Let’s take a look at how that hash input is used in the workflow…
In the second step, which is the “Lookup Hash” action from the ThreatCrowd plugin, we then click into the “Search Hash” field and click the “+” menu for selecting inputs, and choose the “hash” from our API trigger. Then, this action looks up the hash that was sent into the trigger, and the output of the action gets formatted in the artifact (which is just a text output step) step to provide a readable report of any relevant findings from ThreatCrowd.
This workflow is relatively simple, with one input going into one action, but what about something more complicated?
Example 2: Triggering the From InsightIDR Alerts
The “Alert on InsightIDR Multi Country Auth Alert” workflow shows how much data might come along with a workflow trigger. The InsightIDR UBA Alert trigger contains a ton of useful information, from the asset to the user to the specifics of the alert. You may not need all of this information—but that’s okay! You can pick and choose what you need even if there are dozens of inputs to your workflow.
In this case, we primarily want the IP Addresses of the associated alert, which tell us where the login to an account is coming from. We can use just that variable from the trigger and ignore the rest, no problem.
Once we have the IP addresses of the alert, we send them straight into a loop, which geolocates the IP address using a GeoIP service action. From there you can imagine how the workflow proceeds—checking the user’s previous login and comparing what countries the access came from to determine if this particular login might be suspicious.
Pretty cool right? Triggering on InsightIDR’s numerous alerts can be extremely powerful.
Using Triggers as a Trigger for Your Imagination 
If you’re like me, one of the biggest challenges with automation is dreaming up what you can automate next. Automation in SOAR is like a blank canvas—infinite opportunity, but also, infinite opportunity. It can be hard to know where to begin. That’s where triggers come in.
When I’m stumped for what to automate, I find a very good place to start is with the events I’m getting out of my environment. If you think of some of the main tools, services, or hardware in your environment and connect them up, then looking at the triggers available for them and the data you get from those triggers can give you all kinds of great ideas for what to do with it.
I like to start as simple as I can: make a two-step workflow with a trigger and an Artifact step that just prints out what the trigger sends. For example, if I have SentinelOne endpoint detection, then I might connect it and add the available trigger to a very simple workflow, then print out a detected threat in an Artifact step.
Reviewing the jobs from a workflow like that will then show all of the data you get from each event that happens, and the ideas for what you can do with it start flowing. “Oh look, if a threat is detected we have the username and the IP; what if we used that to send the user a message on Teams to confirm their behavior?” And so on.
Triggers are one of the most foundational concepts in InsightConnect—everything starts with a trigger! By understanding where they come from and how you can use them, you’ll be well on your way to taking advantage of all of the opportunity of SOAR for your organization.
Let’s keep the conversation going. What have you found to be useful triggers for workflows? What do you wish you could do?