InsightCloudSec Docs

Welcome to the InsightCloudSec Docs!

InsightCloudSec by Rapid7 (formerly DivvyCloud) is a Cloud-Native Security Platform that provides real-time analysis and automated remediation for continuous security and compliance for your multi-cloud environment.

For questions reach out to us through [email protected].

Take Me to the Docs!    Release Notes

Creating Bots

Instructions for Using the InsightCloudSec Automation Feature, or "Creating a Bot"

Overview

There are a number of workflow options within InsightCloudSec for creating Bots.

  • You can create and launch a new Bot from the BotFactory landing page by selecting the "Create Bot" button
  • You can use an existing Insight to launch the "Create Bot" process
  • You can use an existing template (created custom within your environment)

For any of these workflows we recommend reviewing the Prerequisites for Creating Bots below to ensure you have the details you need before getting started.

Bots Listing PageBots Listing Page

Bots Listing Page

As with any of our features, if you have questions or need assistance, reach out to us through [email protected].

Prerequisites for Creating Bots

Before you create a new Bot you will want to have a few details in order:

  • First, ensure that you have a good understanding of Resources, Filters, and Insights

    • For Bots that are not based on an existing Insight, you will want to have a good understanding of the Filters you want to apply and the requirements for maintaining them.
    • Check out Working with Bots (Best Practices & Examples) documentation for more details on our recommendations.
  • Second, assemble any details about the actions you want your Bot to perform. For example, if you want to create an automated notification to generate an email or send out a Slack notification, you will want to ensure access to those details before you create the Bot.

    • Read more about Integrations (for things like Slack and PagerDuty).
    • Learn more about using Jinja2 for notifications.

Creating a Bot in BotFactory

These steps walk through the creation of a new Bot from the BotFactory landing page.

1. Locate "Automation --> BotFactory" under the main navigation and click on "BotFactory" to open the page.

2. Click on "Create Bot".

BotFactory Landing Page - Create BotBotFactory Landing Page - Create Bot

BotFactory Landing Page - Create Bot

3. Complete the "About Your Bot" details as follows:

  • Give your Bot a useful "Name" and "Description"
  • Select the appropriate "Category" for the type of Bot you want to create
Create Bot - About Bot DetailsCreate Bot - About Bot Details

Create Bot - About Bot Details

4. Define the scope of your Bot by selecting the appropriate "Resource Types", "Badges", and "Cloud/Resource Group Scope".

  • Resource Types - Use the search to locate and select one or more resource types. Selecting multiple resource types will modify the available filters/actions.

  • Badges - Use the search to locate and select one or more Badges.

    • Unless the "Must have all badges" checkbox is set, any cloud with one or more badges specified will be included in the scope.
    • If "Must have all badges" is checked, only clouds with all specified badges will be included in the scope.
  • Cloud/Groups - Use the search to locate and select one or more clouds or Resource Groups.

๐Ÿ“˜

Scoping Multiple Resource Types

You may select multiple resource types for the scope of your Bot. However, it is important to note that some filters and actions are only applicable to certain types of resources. Available Bot actions will be scoped based on the specified resource types.

Create Bot - Define Your ScopeCreate Bot - Define Your Scope

Create Bot - Define Your Scope

5. Define the Filters for your Bot by selecting the appropriate filter or filters. You can add multiple filters.

  • Click "Add Filters" to search for your desired filter. Click on the Filter you want to apply until you have added all of your desired filters and select "Next" when you have finished.
  • Note: If a Bot has more than one filter, resources are matched only if they match all of the filters specified.
Create Bot - Select FiltersCreate Bot - Select Filters

Create Bot - Select Filters

6. Define the "Actions" your Bot should take.

Create Bot - Defining Actions for Your BotCreate Bot - Defining Actions for Your Bot

Create Bot - Defining Actions for Your Bot

Notes on Actions

  • Certain actions support Jinja2 templating in the message body. This enables Bot authors to insert useful data about resources into Bot-generated messages. To learn more visit Jinja2 for details.
  • If you want to review other options for "Notifications", check out the Integrations Overview for details on various integration options, including Slack, PagerDuty, and ServiceNow.

๐Ÿ“˜

Bot Actions (Quantity and Order)

Bots may have more than one action. Actions are executed for a single resource at a time. When a Bot includes multiple actions, the actions are executed in parallel. If you want actions to run in a specific order, some actions have a "delay" option that can be set to wait a certain amount of time after the Bot is triggered.

7. Choose "Run Options" for when to run your Bot.

  • The options for running your Bot are Reactive and Scheduled.
  • You may choose one or both of these options depending on your needs.
Create Bot - Choosing When Your Bot Will RunCreate Bot - Choosing When Your Bot Will Run

Create Bot - Choosing When Your Bot Will Run

Reactive
The Bot will take action as a response to changes detected by harvesting. For example, a reactive action is a smart choice for a break/fix scenario where you want to be notified the moment something isn't working as expected.
Reactive changes are:

  • Resource Created - a new resource appears in a cloud account already connected to InsightCloudSec, or any resource is discovered within a cloud account newly connected to InsightCloudSec.
  • Resource Modified - a resource in an already-connected cloud account changes, e.g., you up-size or down-size an instance.
  • Resource Tags Modified - a tag associated with a resource is changed or removed
  • Resource Threat Finding - (Note: Only available with Storage Containers, IAM Users, and Compute Instances) applies to resources where cloud native threat detection services identify issues.
  • Resource Destroyed - an existing resource is destroyed.

Scheduled
The Bot will take action according to a recurring schedule, as specified (No Schedule, Hourly, Daily, Weekly, Monthly).

  • For example, you can specify that the Bot should run at nightly shutdown by selecting Daily and then specifying the time of nightly shutdown.
Scheduled Bot OptionsScheduled Bot Options

Scheduled Bot Options

๐Ÿ“˜

To Run Your Bot Immediately

Bots are created in a paused state. This default allows you to review your Bot before running your Bot.

You can review your Bot using the Bot Overview, available via "Automation --> Botfactory" by clicking on the name of the target Bot on the Listing page.

When you are ready to run your Bot, on the Bot Listing page, select the target Bot and then "Enable" from the action submenu next to the name of your Bot. Return to the action submenu and select "On demand Scan."

8. Click "Save" to finish creating your Bot. After saving you will be returned to the BotFactory main page. From here, you can click on your newly created Bot to review the settings.

Creating a Bot from an Insight

In addition to creating Bots directly from the BotFactory landing page, you can also create a Bot from an existing Insight. "Create Bot" is available from the actions menu to the left of the Insight name.

Creating a Bot From an InsightCreating a Bot From an Insight

Creating a Bot From an Insight

1. Navigate to "Security --> Insights" from the main navigation menu.

2. Select the "Insight" you want to use to create your new Bot. Click on the action menu to the left of the Insight name.

โ—๏ธ

Creating Multiple Bots From the Same Insight

Warning! Use caution when creating multiple Bots from the same Insight to avoid Bots that overlap and perform the same actions on the same resources.

Configuration Required! Bots created from Insights require the configuration of scope and actions. By pressing "SUBMIT", a Bot will be created with defaults based on the Insight you selected; you will be prompted to edit it.

Note: While there is no specific audit capability for existing Bots, you can review Bots through the Filters page (to view any Bots associated with a specific filter); and through the Insights Library (associated Bots built from Insights will be linked).

3. Verify/complete the "About Bot" details as follows:
Note: When you use an existing Insight to create your Bot these fields will be pre-populated.

  • Give your Bot a useful "Name" and "Description"
  • Select the appropriate "Category" for the type of Bot you want to create
Create Bot - About Bot DetailsCreate Bot - About Bot Details

Create Bot - About Bot Details

4. Define the "scope" of your Bot by selecting the appropriate "resource types", "Badges", and "Cloud/Resource Group Scope".

Note: If you use a Custom Insight to create a Bot, the scope from that Insight will be applied by default and can be modified.

  • Resource Types - Use the search box to select or modify your resource types. Selecting multiple resource types will modify the available filters/actions.

  • Badges - Use the search box to select one or more badges. Unless the "Must have all badges" checkbox is set, any cloud with one or more badges specified will be included in the scope. If "Must have all badges" is checked, only clouds with all specified badges will be included in the scope.

  • Cloud/Groups - Use the search box to select one or more clouds or resource groups.

๐Ÿ“˜

Scoping Multiple Resource Types

You may select multiple resource types for the scope of your Bot, however some filters and actions are only applicable to certain types of resources. Available Bot actions will be scoped based on the specified resource types.

5. Define the Filters for your Bot by selecting the appropriate filter or filters. You can add multiple filters.

  • Note: Bots may have more than one filter specified. If a Bot has more than one filter, resources are matched only if they match all of the filters specified.

๐Ÿšง

Unlock

When creating a Bot from an Insight, users have the ability to "Unlock" the Bot from the Insight. This removes the association between the Insight and the Bot. If you select "Unlock" and save the Bot, the link to the initial Insight used to create the Bot will no longer exist. This will prevent your Bot from updating based on changes to the Insight (e.g., if it is updated or exemptions are added) and is something we generally do not recommend.

Otherwise your Bot will continue to function as initially configured.

Create Bot - Select FiltersCreate Bot - Select Filters

Create Bot - Select Filters

6. Define the "Actions" your Bot should take.
Note: When you create a Bot from an Insight, by default it will include the action "Mark Resource Noncompliant" - this can be removed if it does not apply to your desired configuration.

Create Bot - Defining Actions for Your BotCreate Bot - Defining Actions for Your Bot

Create Bot - Defining Actions for Your Bot

Notes on Actions

  • Certain actions have the ability to use Jinja2 templating in the message body. This enables Bot authors to insert useful data about resources into the message. To learn more visit Jinja2 for details.
  • If you want to review other options for "Notifications", check out the Integrations Overview for details on various integration options, including Slack, PagerDuty, and ServiceNow.

๐Ÿ“˜

Bot Actions (Order and Quantity)

Bots may have more than one action. Actions are executed for a single resource at a time. When a Bot includes multiple actions, the actions are executed in parallel. If you want actions to run in a specific order, some actions have a "delay" option that can be set to wait a certain amount of time after the Bot is triggered.

7. Choose the "Run Options" for when to run your Bot.

  • The basic options for running your Bot are Reactive and Scheduled.
  • You may choose one or more of these options.

Reactive
The Bot will take action as a response to changes detected by harvesting. For example, a reactive action is a smart choice for a break/fix scenario, where you want to be notified the moment something isn't working as expected.
Reactive changes are:

  • Resource Created - a new resource appears in a cloud account already connected to InsightCloudSec, or any resource is discovered within a cloud account newly connected to InsightCloudSec.
  • Resource Modified - a resource in an already-connected cloud account changes, e.g., you up-size or down-size an instance.
  • Resource Tags Modified - a tag associated with a resource is changed or removed
  • Resource Threat Finding - (Note: Only available with Storage Containers, IAM Users, and Compute Instances) applies to resources where cloud native threat detection services identify issues.
  • Resource Destroyed - an existing resource is destroyed.

Scheduled
The Bot will take action according to a recurring schedule, as specified (No Schedule, Hourly, Daily, Weekly, Monthly).

  • For example, you can specify that the Bot should run at nightly shutdown by selecting Daily and then specifying the time of nightly shutdown.

๐Ÿ“˜

To Run Your Bot Immediately

Bots are created in a paused state. This default allows you to review your Bot before running your Bot.

You can review your Bot using the Bot Overview, available via "Automation --> BotFactory", by clicking on the name of the target Bot on the Listing page.

When you are ready to run your Bot, on the Bot Listing page, select the target Bot and then "Enable" from the action submenu next to the name of your Bot. Return to the action submenu and select "On demand Scan."

8. Click Save to finish creating your Bot. After saving you will be returned to the BotFactory main page. From here, click on your newly created Bot to review the settings.

Creating a Bot from a Template

In addition to creating a Bot from the BotFactory landing page, or from an existing Insight, users also have the ability to create a Bot from a template. This can be helpful if you need to create a copy of a Bot in use in your organization or if InsightCloudSec support needs to replicate a Bot for testing.

To Copy An Existing Bot

1. Navigate to "Automation --> BotFactory" and locate the Bot you want to copy.
2. Click on the "Name" of the target Bot to open the Bot Listing details.
3. Scroll to the Bot Configuration details and select "Copy".

Copy a Bot ConfigurationCopy a Bot Configuration

Copy a Bot Configuration

4. Save these details somewhere or immediately navigate to the Bot creation process.

Create a Bot Template

Templates are available from "Automation --> BotFactory" on the "Templates" tab. To create a new Template refer to the following steps.

1. Navigate to "Automation --> BotFactory" and open the "Templates" tab.
2. Click on "Import Template" and paste the JSON you copied from your target Bot.

BotFactory - TemplatesBotFactory - Templates

BotFactory - Templates

3. Click "Submit" to create a new Template.

If you are interested in creating a new Bot from a template, the steps are the same as those provided in Creating a Bot from an Insight.

You can read more about creating templates in the Managing Bots documentation here.

Helpful Bot Details

Resource Group Curation

One best practice action is resource group curation. Resource Groups simplify automation, management, and permissions at scale. End-users can leverage InsightCloudSec curation capabilities to automatically add/remove resources to these groups.

New Topics and Notifications

For the Bot action "Publish to Cloud Notification Topic", InsightCloudSec will only send notifications to topics that it sees. So, if you make a new topic and then immediately try to post a message to this topic, it won't work. You will need to wait for InsightCloudSec to see the topic before it'll let you post a message to it.

Using Badges for Bot Scoping

Badges are key-value pairs that allow you to customize the organization of your cloud accounts within InsightCloudSec. Badges, as key-value pairs, are similar to AWS tags or GCP labels. However where tags and labels are applied to resources, badges are applied to entire cloud accounts.

Configuration of badges is available within the Bot creation process, and they are a great capability for scoping your Bot. Check out our Badges page for details on using and implementing badges throughout InsightCloudSec.

Updated about a month ago

Creating Bots


Instructions for Using the InsightCloudSec Automation Feature, or "Creating a Bot"

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.