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


Information on Viewing and Configuring Badge Functionality Within InsightCloudSec

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.

  • For example, one badge might have a key of “environment” and a value of “production” and another might use "environment" with the value "testing", allowing your organization to group cloud accounts based on usage.
  • Most badge features require appropriate permissions. Learn more about required permissions in our Users, Groups, and Roles (Administration) documentation.

The Badges functionality is accessible for configuration in a number of ways: on the Clouds Listing page, through the configuration of Insights, via Resources, and when configuring a Bot.

Navigate to "Cloud --> Clouds" to display the Clouds Listing page, and locate the Badges column for access to add, modify, and edit Badges.

Clouds Listing Page - BadgesClouds Listing Page - Badges

Clouds Listing Page - Badges

Understanding Badging Implementation

Badging within InsightCloudSec is a very powerful system that allows you to establish a taxonomy across your cloud and Kubernetes footprint. It can be used for reporting and automation purposes as well as authorization within the Role Based Access Control (RBAC) system. There are three types of badges outlined below:

System Generated Badges

System Generated badges are automatically applied when services such as AWS, Microsoft Azure, Google Cloud Platform (GCP), and Kubernetes are connected to the product. There are two badges that fall into this category which are always assigned: system.cloud_type and system.resource_type. These badges cannot be modified and remain in a fixed state within the database.


Example values:

  • system.cloud_type: amazon web services
  • system.cloud_type: microsoft azure
  • system.cloud_type: google cloud platform

Example use case:

You can use system.resource_type: cloud to ensure that a Bot automation remains in scope for all cloud accounts, including ones that will be added in the future.

  • For example, you can configure a Bot to alert your SecOps team when a critical AWS GuardDuty finding is observed across their entire AWS fleet of accounts. As InsightCloudSec automatically onboards additional accounts and assigns the system.cloud_type: amazon web services system badge the new accounts will be incorporated into the scope of this existing Bot. This is a great maintenance-free way to scale your Bot automation alongside the growth of your cloud footprint


Example values:

  • system.resource_type: cloud
  • system.resource_type: k8s cluster

Example use case:

You can use system.resource_type: cloud for automation via a Bot that you want to scope to include every cloud account to monitor for public object storage such as AWS S3, Google Cloud Storage, or Azure Blob Containers. Any time one of these resources is exposed to the public and puts an organization's data at risk, the Bot can respond. This particular badge can be configured to monitor accounts that exist in the InsightCloudSec platform today as well as those that are added in the future.

Auto-Generated Badges

Auto-Generated badges are similar to System Badges in that they cannot be modified within the product; however, they are inherited from the tags/labels associated with the top level account within the cloud itself. If you associate tags with your AWS Cloud Accounts (this requires AWS Organizations), labels on your GCP Projects, or tags on your Azure Subscriptions they will automatically funnel into the system as auto-generated badges. Note that this capability is only supported when connecting InsightCloudSec to the top level of your AWS, Microsoft Azure, or Google Cloud Platform organization. Documentation on this capability for each provider can be found here:

Customer Supplied Badges

Customer supplied badges are defined within InsightCloudSec. They can be created, modified, and deleted by any user with administrative privileges. If your organization does not have a pre-built taxonomy which can be auto-inherited from your cloud accounts or Kubernetes clusters using the Auto-Generated Badges outlined above, then these can be used as alternative.

  • There's no limit to the number of customer supplied badges that can be associated; however, the maximum length for both the key and value is 255 characters.
  • InsightCloudSec customers regularly leverage this badge type to apply the following metadata to their fleet of Cloud accounts and Kubernetes clusters:

Example values:

  • owner: [email protected]
  • risk: high
  • environment: production
  • slack_channel: #acmecorp-ics-alerts

In the example above, the badges can be used to organize reporting to identify alerts and vulnerabilities associated with resources that are owned by Joe Smith or those associated with accounts that are high risk based on the classification of data.

Badges also enable customers who leverage InsightCloudSec's automation through Bots to dynamically route alerts and notifications to any number of integration options including Slack, Microsoft Teams Channels, email distribution lists and more based on the value of a target badge.


Review of Default Badges and Badge Requirements

  • When a cloud account is added, InsightCloudSec automatically assigns it two system badges: system.cloud_type and system.resource_type.

  • In addition, no user-specified badge may begin with system.

  • Badge keys and values are case sensitive.

  • You must use shift + space to add a space when adding badges.

Adding, Modifying, and Removing Badges

To add or remove a badge, refer to the steps outlined below.

Adding or Modifying a Badge

1. Open "Cloud --> Clouds" from the main navigation to display the Clouds Listing page.

2. Locate the Cloud Account in which you want to make changes to Badges, and in the row for that cloud account, locate the column labelled "Badges" and click on the linked number displayed.

3. The “Add Cloud Badges” window will appear. Click the plus icon (+) to create a line for your new badge.

4. For new badges, add the key and value as desired. Repeat this process for as many new badges as you want to add:

  • Badge keys may not begin with the string system
  • Both badge keys and badge values are case-sensitive

For existing badges, edit as desired. Repeat this process for as many existing badges as you want to revise.

5. When you are finished adding or modifying badges, click "Submit" to save your changes.

Adding, Modifying, Removing BadgesAdding, Modifying, Removing Badges

Adding, Modifying, Removing Badges

Removing a Badge

1. Open "Cloud --> Clouds" from the main navigation to display the Clouds Listing page.

2. Locate the Cloud Account for which you want to make changes to Badges, and in the row for that cloud account, locate the column labelled "Badges" and click on the linked number that displays.

3. To remove any user-created badges, click the minus icon (-) next to each entry you want to remove.

  • System Generated badges are identified with a checkmark.

4. When you are done removing badges click "Submit" to save your changes.

Scoping With Badges

Badges can be used to scope clouds, Insights, resources, Bots, and user roles. The steps below outline the process to scope or narrow your clouds using badges.

Scope Clouds With Badges

1. To narrow your list of clouds by badge, navigate to "Cloud--> Clouds" from the main navigation to open the Clouds Listing page.

Scoping Clouds With BadgesScoping Clouds With Badges

Scoping Clouds With Badges

2. Click on the “Search Badge(s)” text box to display a drop-down list of existing badges.

3. Select the badges you want to use to scope your clouds.

  • For example, searching for/selecting the badge "environment:production" will produce a list containing only clouds with badges matching "environment:production."
Scoping Clouds With Badges - Matching at Least One BadgeScoping Clouds With Badges - Matching at Least One Badge

Scoping Clouds With Badges - Matching at Least One Badge

4. You can choose multiple badges to narrow your resulting list of clouds. By default, results shown match at least one badge in your provided criteria. To show only those results that match all selected badges, check the “Must Have All Badges” checkbox.

  • In addition, badges are sortable and included in any export from the Clouds page.

Scope Insights With Badges

Badges can be used to enhance the functionality of Insights by allowing you to filter how you view your Insights’ results. First navigate to "Security --> Insights".

1. Select an Insight pack from the "Insights Library" by clicking the checkbox next to the name and then clicking the "Scopes" option.

Accessing Scopes for an InsightAccessing Scopes for an Insight

Accessing Scopes for an Insight

2. Scopes will appear as an overlay menu. Click on the “Select Badges” text box and a drop-down list will appear with all available badges from your list of clouds.

Selecting Scopes for an InsightSelecting Scopes for an Insight

Selecting Scopes for an Insight

3. As you select badges, both the list of clouds below your selections and the grayed-out results in the center of the window will dynamically change.

  • By default, the results that appear are those that match at least one of the badges you select.
  • To require that all badges must be matched for a result to appear, select “Must Have All Badges.”

4. When you are finished filtering your Insights, click the "X" at the top-right navigation of the Scopes menu.

Scope Resources With Badges

As with Insights, resources may also be filtered by badges. The process by which you filter resources is identical to that by which you filter Insights.

Navigate to "Resource --> Resources", select your target resources, and then open the "Scopes" option.

Scoping Resources with BadgesScoping Resources with Badges

Scoping Resources with Badges

Scope Bots With Badges

As with Insights and resources, Bots can be more precisely defined using badges. Administrators and basic users with an admin or editor entitlement can configure this feature.

The process is similar to that used for scoping Insights and resources with badges. Navigate to "Automation --> BotFactory" to access Bot details.

When creating or editing Bots, the second step in this process (“2. RESOURCE TYPES & GROUPS”) allows you to specify scope, including badges.

  • You will see a text box with drop-down selection and a “Must Have All Badges” checkbox identical to those seen in Insights and Resources. Select the badges you would like to limit your Bot’s scope.
  • You can check the “Must Have All Badges” checkbox to require that each included cloud have all selected badges rather than at least one.

Refer to the complete BotFactory documentation for details on creating and modifying Bots.

Scoping Bots With BadgesScoping Bots With Badges

Scoping Bots With Badges

Viewing Badges on Bots

To view which badges, if any, are in use for a given Bot, navigate to "Automation --> BotFactory" and select the Bot of interest from your list of Bots to display details for that individual Bot.
If you scroll to the bottom half of those details, you can view the badges in the “Bot Scope” panel details.

Bot Scoping DetailsBot Scoping Details

Bot Scoping Details

Scope User Roles With Badges

Role scopes may be associated with specific badges. Navigate to "Administration --> Identity Management" and select "Basic User Roles" from the pages/tabs.

This view provides a list of roles, which includes a column that references the number of associated badges (as shown in the example below).

Viewing Badges Associated With Basic User RolesViewing Badges Associated With Basic User Roles

Viewing Badges Associated With Basic User Roles

1. To add/remove a badge to/from a role, find the “# Badges” column for the role of interest. Click on the number in that column.

2. Use the context menu to the left of the name of the Role you want to modify and select "Modify Badge Scope" to view the list of badges associated with that role.

  • Click into the content box to enable to drop-down menu and select the badges you want to add.
  • If badges already are associated with this role, click on any white space in the text box to bring up the list of additional badges.
  • To remove an existing badge from the role, click on the small "x" next to the badge name.
Modify Badges Associated with a RoleModify Badges Associated with a Role

Modify Badges Associated with a Role

3. When you finish adding and removing badges, click “Submit".

Using Badges in Notification Messages

You can include badges and badging information in messages associated with any of the following Bot actions: Send Bulk Email, Send Delayed Email, Send Slack Message, Send Hipchat Message, Post Request to URL, and Set Container Policy. To do so you will need to use Jinja2 Templating.

Example: Using Badges to Send a Slack MessageExample: Using Badges to Send a Slack Message

Example: Using Badges to Send a Slack Message

An Example Message

The following message uses Jinja2 templating and Slack formatting to send an alert via Slack when a resource is created without tags mandated by policy:

A resource of type `{{event.resource.get_resource_type()}}` was discovered
at `{{event.resource.common.creation_timestamp}}` without the required _owner_
or _contact-email_ tags. The resource name is `{{event.resource.get_resource_name()}}`.
It lives in account `{{event.resource. get_organization_service_name()}}`,
which is owned by {{event.resource.get_badge_value_by_key_for_parent_cloud('owner')}}`.\n---

As an example, a given cloud has a badge of owner and the owner for this cloud is Jane Doe. The value returned in the example above for {{event.resource.get_badge_value_by_key_for_parent_cloud('owner')}} will be [email protected]

For more information on Jinja2 templating, click here.

Viewing the Badges Summary Report

With "Viewing" permissions, you can view Total Badges by Cloud Account by navigating to "Cloud --> Clouds --> Badges", as shown in the example below.

  • Note: You must have Domain Admin privileges to view the summary of badges by cloud account.
Badges Summary ReportBadges Summary Report

Badges Summary Report

This view summarizes your top 10 badges by cloud account in a bar graph and details all badges in use in the table below the bar graph. Together, these two displays effectively provide a dictionary of your top badges. A Domain Admin can use these displays to manage available badges.


Top Badges by Cloud Count

Access to the Top Badges by Cloud report (as well as the listing of all Badges) is through the Badges option on the Clouds main page (Cloud, then Clouds from the left-side menu). This information is available only to users with appropriate permissions.

Updated 18 days ago


Information on Viewing and Configuring Badge Functionality Within InsightCloudSec

Suggested Edits are limited on API Reference Pages

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