Creating Bots

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

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.

1544

Bots Listing Page

As with any of our features, if you have questions or need assistance, reach out to us through the Customer Support Portal.

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, Query Filters, and Insights

    • For Bots that are not based on an existing Insight, you will want to have a good understanding of the Query 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".

1325

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
1078

Create Bot - About Bot Details

4. Define the scope of your Bot by selecting the appropriate "Resource Types", "Badges", "Exclusion 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.
  • Exclusion Badges - If "Select All Clouds" is checked, the "Exclusion Badges" field becomes available. Any cloud with one or more of the selected badges will be excluded from the Bot's 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 Query Filters and actions are only applicable to certain types of resources. Available Bot actions will be scoped based on the specified resource types.

1384

Create Bot - Define Your Scope

5. Define the Query Filters for your Bot by selecting the appropriate Query Filter or Filters (you can add multiple Query Filters).

  • Click "Add Query Filters" to search for your desired filter. Click on the Query 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 Query Filters, resources are matched only if they match all of the filters specified.
898

Create Bot - Select Query Filters

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

864

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.
977

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 Created (Delayed) - 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, however the Bot will run after a default period of time (currently 20 minutes). Note: the default delay can be modified but you will need to reach out through Getting Support to have this modified.
    • This option is most useful when Event-driven Harvesting (EDH) is enabled and when examining resources that require additional time to configure for Bot analysis or to achieve a ready state for Bot corrective action. With the speed of EDH, a Bot using the Resource Created without the delay can be triggered to evaluate or act before the cloud provider is ready -- a function of the cloud provider's guarantee of eventual consistency.
  • 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.
  • In addition, after a Bot is created, the schedule enabled cadence will display (in the Bot Overview --> Info & Settings section) for any Bot that is running.
900

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.

1512

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 Query 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
1039

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 Query 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.

  • Exclusion Badges - If "Select All Clouds" is checked, the "Exclusion Badges" field becomes available. Any cloud with one or more of the selected badges will be excluded from the Bot's 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 Query 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 Query Filters for your Bot by selecting the appropriate Query Filter or Filters (you can add multiple Query Filters).

  • Note: If a Bot has more than one Query Filter, resources are matched only if they match all of the Query 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.

1556

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.

1280

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 Created(Delayed) - 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, however the Bot will run after a default period of time (currently 20 minutes). Note: the default delay can be modified but you will need to reach out through Getting Support to have this modified.
    • This option is most useful when Event-driven Harvesting (EDH) is enabled and when examining resources that require additional time to configure for Bot analysis or to achieve a ready state for Bot corrective action. With the speed of EDH, a Bot using the Resource Created without the delay can be triggered to evaluate or act before the cloud provider is ready -- a function of the cloud provider's guarantee of eventual consistency.
  • 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".

1196

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.

1399

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.