Lesson 3: Use Action Steps and Plugins

InsightConnect currently supports nearly 300 plugins, ranging from popular security tools to utility plugins that help you work with the data you use on a daily basis. Workflows map to your security processes while plugins map to your existing security products, allowing you to orchestrate tasks across your entire tech stack.

In this lesson, we’ll teach you how to add a free third-party security tool to your Welcome Workflow. You’ll import the Whois plugin, which uses the Linux whois tool to search WHOIS databases and return information on a domain owner. Numerous WHOIS references exist online, but you can learn more from the WHOIS Wikipedia page at https://en.wikipedia.org/wiki/WHOIS. You can also run WHOIS lookups on websites like whois.net, www.iana.org/whois, or lookup.icann.org, among others.

Here’s an overview of how to add Whois to your Welcome Workflow:

  1. Import the Whois plugin.
  2. Add a Whois action step to the Welcome Workflow.
  3. Edit the artifact step.
  4. Test the workflow.

The following example shows you how to use a plugin.

Import the Whois Plugin

To import the Whois plugin, follow these steps:

  1. Click on the Settings tab in the left navigation, then select Plugins.
  2. Click on the blue Import a Plugin button in the top right corner.
  3. Select “Marketplace” ……..
  4. In the search bar, type whois, then click on the plugin when it appears. Click the Next button.
  5. Click the Import button.

Add a Whois Action Step to the Welcome Workflow

Next, you’ll add a Whois action step to the Welcome Workflow you created in Lessons 1 and 2:

  1. Navigate to your Welcome Workflow by clicking on the Active option in the “Workflows” section of the side navigation.
  2. Click on the three dots on the right side of the “Welcome Workflow” card and click on the Create Draft or Edit Draft option. This opens the Workflow Builder for your new “Welcome Workflow” draft.
  3. To edit the trigger, click on the trigger icon on your workflow canvas to open the trigger configuration panel.
  4. Edit the trigger to take one variable called domain. To do this, delete one of the input variables by clicking on the x button in the top-right corner of the variable box. Then change the remaining variable name to domain. Keep the variable data type as “String.”
  5. Click Continue, then click Close.
  6. Click on the + sign between the trigger and artifact.
  7. Select the Action step type.
  8. In the search bar, type whois. The Whois plugin should appear after you type a few characters. Click the plugin to select it, then click Continue.
  9. Select the Domain Lookup plugin action, then click Continue.
  10. Choose an orchestrator to use with this step, then click Continue.
  11. Name the Action Step Whois Lookup. Ignore the “Continue workflow on step failure” option for now.
  12. In the Input section, insert the Welcome Trigger output variable into the “Domain” field by clicking into the text field, then clicking the + sign in the corner of the text box. Select the *Welcome Trigger.domain string variable in the list that populates, then click outside of the field.
  13. Click Continue to exit this step’s configuration panel.

Edit the Artifact Step

Lastly, edit the artifact step and test the workflow:

  1. Edit the artifact by clicking on the artifact icon in your workfl opening the configuration panel for the artifact step. Delete the current contents of the “Output format” field, then type or paste in Was the lookup successful? . Click on the blue + sign in the bottom right corner of the “Output format” field and select the Whois Lookup.$success variable. Press enter twice to create two new lines, then click on the blue + sign again and select the Whois Lookup.registrar string variable. Type a space, then type or copy/paste is the registrant for, then type a space. Click on the blue + sign again, and select the Welcome Trigger.domain boolean variable.
  2. Click Preview. Don’t worry about the way the artifact preview looks for now. In this example, it should look just like the content in the “Output Format” field you just configured.
  3. Click Add Artifact to save your changes.

Test the Workflow

  1. Test the workflow by clicking on the Test button in the workflow builder with the input rapid7.com.
  2. When the test job finishes running, click on the Artifacts tab to see the result. Your artifact will display content that looks like:
1
Was the lookup successful? True
2
MarkMonitor Inc. is the registrant for rapid7.com
3

Congratulations! You imported a plugin, created an action step, and used a third-party tool to gather security information. You also used a boolean data type -- booleans are variables that can only have true or false values.

Whenever you want to add one of your security tools or a utility plugin to InsightConnect, first check if the plugin is available on the Plugins page of the “Settings” section. If your tool doesn’t have a plugin in InsightConnect, reach out to Rapid7 support or contact us through UserVoice to request a new plugin. UserVoice is a product feedback tool you should have set up during onboarding.

An action step automates a single task from a plugin, whether that be a security tool-based action or a utility like math or data type conversion. Each plugin includes a variety of actions you can use, and each action is preconfigured to accept, operate on, and produce workflow data. Some plugins include triggers that can start workflows as well, but we’ll get to that in a later lesson. To learn more about a specific plugin, navigate to the plugin’s in-product documentation.

If you ever need a refresher on how to configure action steps, visit our page on adding action steps.

When you tested the workflow, you should have produced an artifact that said “Was the lookup successful? True | MarkMonitor Inc. is the registrant for rapid7.com.” Your workflow sent rapid7.com to the Linux WHOIS tool to gather information on the domain. Once the lookup was completed successfully, InsightConnect set the action step’s $success variable to true. InsightConnect also extracted details from the lookup and displayed one of these details, rapid7.com’s registrant, in the resulting artifact.

Try running or testing the workflow with your own company website or other popular websites to see how the artifact content changes.