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

Managing Bots

Instructions for Working with Existing Bots or Automation Including Editing, Auditing, and History

Overview

After successfully setting up a Bot (or Bots), you can manage them using a number of displays and tools.

A summary view of your Organization's Bots is available under "Automation --> BotFactory" on the Listing page, click "Show My Bots" to filter and display just the Bots you've created.

BotFactory Listing ViewBotFactory Listing View

BotFactory Listing View

Listing

You can access a listing of your Bots by opening "Automation --> BotFactory" under the main navigation. The default view after selecting BotFactory is the Listing page.

  • You can also select "Listing" from the top of the page from the other tabs.
  • In addition you can download your listing by clicking on the "Download" option to the left of the search.
BotFactory Listing - View OptionsBotFactory Listing - View Options

BotFactory Listing - View Options

The Listing page provides:

  • A download option for Bot Listings
  • A general search
  • A toggle (checkbox) to display only my Bots ("Show my Bots")
  • Options, including Toggle Columns, State Filter, Severity Filter, and Category Filter
  • Filtering based on Badge Search, Cloud Search, Action and Filter Search, and Resource Type Search
  • Pagination controls
  • Access to the Actions menu (to the left of each Bot name)

Accessing Bot Lifecycle Actions

You can access and launch Bot lifecycle actions from the BotFactory Listing page. Details on these actions are available in the Bot Overview section here.

BotFactory Listing Page - Lifecycle ActionsBotFactory Listing Page - Lifecycle Actions

BotFactory Listing Page - Lifecycle Actions

Starting and Stopping Bots

In addition to the viewing options, the BotFactory Listing page also enables you (with the appropriate permissions) to Start, Stop, and Enable or Pause a Bot. You can select the action submenu next to the Bot or click the checkbox next to the Bot you want to modify to access these options.

  • Note: "Delete" requires specific permissions.
BotFactory Listing - Context MenuBotFactory Listing - Context Menu

BotFactory Listing - Context Menu

Bot Templates

Templates can be viewed, stored, and imported under "BotFactory --> Templates", available at the top of the BotFactory page.

Users can provide an existing template through the "Import Template" button to upload their template in JSON format. Alternatively you can use an existing Bot to create a template by choosing the Actions menu next to name of the Bot and selecting "Save as Template".

Save Bot as TemplateSave Bot as Template

Save Bot as Template

Create Bot

This button, available at the top of the BotFactory landing page, launches the "Create Bot" process. Details about that process are available in the Creating Bots documentation.

Bot Overview

To launch a detailed overview of a Bot, click on the Bot name from the Listing page.

Select an Individual Bot - Bot Listing ViewSelect an Individual Bot - Bot Listing View

Select an Individual Bot - Bot Listing View

This opens an Overview page with granular detail about the selected Bot.

Bot Overview PageBot Overview Page

Bot Overview Page

Info & Settings

The Info and Settings section of the Bot Overview page includes an "Actions" button and displays:

  • Bot Created by - details on the Bot creator
  • Description - Bot description
  • Linked Insight - hyperlink to Insight Overview details (if applicable)
  • Bot Category - categories include Security, Optimization, Best Practices, Curation, and Miscellaneous
  • Current State - current states can be Running, Paused, Archived, or Scanning (see the table below for details)

State of Bot

Description

Running

The Bot is operational and functioning on select hookpoints and/or schedule.

Paused

The Bot is in a suspended state and is not taking action. This state is typically found on newly created Bots and/or Bots that are in development.

Archived

The Bot is no longer in use but is kept for historical/auditing purposes.

Scanning

The Bot is currently performing a retroactive scan of the configured scope.

  • Active Hookpoints - the number of reactive states of the Bot (Resource Created, Resource Modified, Resource Tags Modified, Resource Destroyed)
  • Schedule Enabled - shows whether Bot has a recurring execution scheduled

Actions Button
The "Actions" button is available on the Bot Overview Page under "Info & Settings". This button opens the same menu options that are available through the sub-menu next to each Bot's name on the BotFactory Listing page.

Bot Overview Info & Settings - Actions ButtonBot Overview Info & Settings - Actions Button

Bot Overview Info & Settings - Actions Button

A detailed table of Lifecycle Actions (available on the Bot Overview through the Actions button or through the Actions menu next to the Bot name on the Listing page) are below.

Lifecycle Actions

Description

On-demand Scan

Runs a scan against all known resources within the configured scope. This action is useful when you want to retroactively audit and enforce policy.

Reconfigure

Allows you to make changes to a Bot's properties, e.g., its filters/actions, schedule, and hookpoints. Note: If you reconfigure a Bot, it will change to a paused state. You will need to Enable the Bot to change its state to Running. Reconfigure will not allow you to change Bot scope. If you want to change Bot scope, copy the Bot and apply the new scope to the new Bot.

Pause

Suspends a running Bot. Typically this is done on newly created Bots or Bots that you want to suspend for maintenance. Note: This option only appears on Bots that are active.

Enable

Transitions a paused/suspended Bot to a running state. Any hookpoints and schedules configured will be used as the Bot’s execution point. Note: This option only appears on Bots that are paused.

Archive

Permanently disables a Bot. The Bot’s history and metadata are retained, but scheduled events and noncompliance data are purged.

Copy

Copies the configuration of one Bot to another. This action is useful when only changes to Bot scope are needed.

Update Information

Allows you to make changes to information about the Bot, e.g., its name, description, or category, etc., without affecting the Bot’s state.

Trigger Harvest

Allows you to enqueue a re-harvest for selected resources, facilitating testing of Bot filters against changes in the accounts.

Save as Template

Allows you to create a Bot template from which you can create new Bots simply and consistently.

Version History

Allows you to create and activate a version of your Bot. New Bot versions are created by default if any modifications are made to the Bot.

Bot Scope (Clouds/Groups/Badges)

Provides a list of the clouds, groups, or badges that are part of the selected Bot and used to define the scope.

Read more about:

Targeted Resource Types

The Targeted Resource Types section of the Bot Overview page provides a list of the targeted resources, e.g., "Instance" or "Database Snapshot". Check out the Resources documentation for more information on supported resources.

Filters

This section provides a list of the Filters that are included with the selected Bot.

Bot Overview Page -  Filters & ActionsBot Overview Page -  Filters & Actions

Bot Overview Page - Filters & Actions

Actions

The "Actions" section of the Bot Overview Page provides the summary of the Actions for the Bot you are viewing.

Bot Evaluation History (Last 5 entries)

This section provides up to 5 entries that contain history and details about the last actions performed by the selected Bot.

Bot Configuration

This section provides a JSON format of a Bot configuration. This can be exported using the "Copy" button to enable users to store or share a Bot configuration.

History

The "History" tab for a Bot displays the log history details for when the Bot runs as reactive to events and/or each resource when the Bot runs as batch or scheduled. It is available under an individually selected Bot as part of the "Overview" details. The display here includes:

  • Errors - indicating whether any errors were found
  • Context - which applies to the harvester (e.g., ondemand)
  • Scoped Resources - the number of resources to which the Bot was scoped
  • Matched - the number of matched actions and resources
  • Start time - the start time of the Bot run
  • Duration - the duration (in seconds) of the Bot run
Bot Overview - Bot HistoryBot Overview - Bot History

Bot Overview - Bot History

Scheduled Events

Scheduled Events, available as part of the details for an individually selected Bot, displays the events or actions that are scheduled for the Bot.

Bot Overview - Schedule EventsBot Overview - Schedule Events

Bot Overview - Schedule Events

Noncompliant Resources

Noncompliant Resources, available as part of the details for an individually selected Bot, displays the resources that the Bot has identified as non-compliant.

To learn more about compliance, check out the Compliance Scorecard.

Bot Overview - Non-Compliant ResourcesBot Overview - Non-Compliant Resources

Bot Overview - Non-Compliant Resources

Audit

Audit, available as part of the details for an individually selected Bot, displays a log (an API trail) of actions your selected Bot has taken. A green check for the status code indicates the action was successful; a red "X" indicates the action failed. For failed actions, you can click on the red "X" to view more information concerning the failed action.

The audit will also show who ("Name") initiated the action and the type of action executed, e.g., 'get compliance counts', 'edit', or 'validate permissions' (found in the '"Path" portion of the audit).

Bot Overview - Audit DetailsBot Overview - Audit Details

Bot Overview - Audit Details

Logs

Logs, available as part of the details for an individually selected Bot, display information for Bots that are not operating as expected to provide more details around configuration and potential issues.

  • In general, the information under the "Bots --> Logs" is completely specific to the Bot itself and its configuration.
  • This section will not include information around issues that are related to other configuration issues that may impact the Bot (e.g., Insight or Resource issues that impact the performance of a Bot).

Note: For general system logging information check out "Administration --> System Administration --> Logs."

View Logs for an individual BotView Logs for an individual Bot

View Logs for an individual Bot

Viewing All Audit Trails

Audit details available on the BotFactory listing are for the individual Bot selected. If you have
Domain Admin rights, you can view a similar audit trail for all active Bots from "System Administration --> API Activity." Details are available here.

Viewing All API ActivityViewing All API Activity

Viewing All API Activity

Updated about a month ago

Managing Bots


Instructions for Working with Existing Bots or Automation Including Editing, Auditing, and History

Suggested Edits are limited on API Reference Pages

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