# Understanding custom insights in Security Hub CSPM
<a name="securityhub-custom-insights"></a>

In addition to AWS Security Hub CSPM managed insights, you can create custom insights in Security Hub CSPM to track issues that are specific to your environment. Custom insights help you track a curated subset of issues.

Here are some examples of custom insights that may be useful to set up:
+ If you own an administrator account, you can set up a custom insight to track critical and high severity findings that are affecting member accounts.
+ If you rely on a specific [integrated AWS service](securityhub-internal-providers.md), you can set up a custom insight to track critical and high severity findings from that service.
+ If you rely on a [third party integration](securityhub-partner-providers.md), you can set up a custom insight to track critical and high severity findings from that integrated product.

You can create completely new custom insights, or start from an existing custom or managed insight.

Each insight can be configured with the following options:
+ **Grouping attribute** – The grouping attribute determines which items are displayed in the insight results list. For example, if the grouping attribute is **Product name**, the insight results display the number of findings that are associated with each finding provider.
+ **Optional filters** – The filters narrow down the matching findings for the insight.

  A finding is included in the insight results only if it matches all of the provided filters. For example, if the filters are "Product name is GuardDuty" and "Resource type is `AwsS3Bucket`", matching findings must match both of these criteria.

  However, Security Hub CSPM applies boolean OR logic to filters that use the same attribute but different values. For example, if the filters are "Product name is GuardDuty" and "Product name is Amazon Inspector", a finding matches if it was generated by either Amazon GuardDuty or Amazon Inspector.

If you use the resource identifier or resource type as the grouping attribute, the insight results include all of the resources that are in the matching findings. The list is not limited to resources that match a resource type filter. For example, an insight identifies findings that are associated with S3 buckets, and groups those findings by resource identifier. A matching finding contains both an S3 bucket resource and an IAM access key resource. The insight results include both resources.

If you enable [cross-region aggregation](finding-aggregation.md) and then create a custom insight, the insight applies to matching findings in the aggregation Region and linked Regions. The exception is if your insight includes a Region filter.

# Creating a custom insight
<a name="securityhub-custom-insight-create-api"></a>

In AWS Security Hub CSPM, custom insights can be used to collect a specific set of findings and track issues that are unique to your environment. For background information about custom insights, see [Understanding custom insights in Security Hub CSPM](securityhub-custom-insights.md).

Choose your preferred method, and follow the steps to create a custom insight in Security Hub CSPM

------
#### [ Security Hub CSPM console ]

**To create a custom insight (console)**

1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/).

1. In the navigation pane, choose **Insights**.

1. Choose **Create insight**.

1. To select the grouping attribute for the insight:

   1. Choose the search box to display the filter options.

   1. Choose **Group by**.

   1. Select the attribute to use to group the findings that are associated with this insight.

   1. Choose **Apply**.

1. Optionally, choose any additional filters to use for this insight. For each filter, define the filter criteria, and then choose **Apply**.

1. Choose **Create insight**.

1. Enter an **Insight name**, and then choose **Create insight**.

------
#### [ Security Hub CSPM API ]

**To create a custom insight (API)**

1. To create a custom insight, use the [https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_CreateInsight.html](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_CreateInsight.html) operation of the Security Hub CSPM API. If you use the AWS CLI, run the [https://docs.aws.amazon.com/cli/latest/reference/securityhub/create-insight.html](https://docs.aws.amazon.com/cli/latest/reference/securityhub/create-insight.html) command.

1. Populate the `Name` parameter with a name for your custom insight.

1. Populate the `Filters` parameter to specify which findings to include in the insight.

1. Populate the `GroupByAttribute` parameter to specify which attribute is used to group the findings that are included in the insight.

1. Optionally, populate the `SortCriteria` parameter to sort the findings by a specific field.

The following example creates a custom insight that includes critical findings with the `AwsIamRole` resource type. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.

```
$ aws securityhub create-insight --name "Critical role findings" --filters '{"ResourceType": [{ "Comparison": "EQUALS", "Value": "AwsIamRole"}], "SeverityLabel": [{"Comparison": "EQUALS", "Value": "CRITICAL"}]}' --group-by-attribute "ResourceId"
```

------
#### [ PowerShell ]

**To create a custom insight (PowerShell)**

1. Use the `New-SHUBInsight` cmdlet.

1. Populate the `Name` parameter with a name for your custom insight.

1. Populate the `Filter` parameter to specify which findings to include in the insight.

1. Populate the `GroupByAttribute` parameter to specify which attribute is used to group the findings that are included in the insight.

If you've enabled [cross-region aggregation](finding-aggregation.md) and use this cmdlet from the aggregation Region, the insight applies to matching findings from the aggregation and linked Regions.

**Example**

```
$Filter = @{
    AwsAccountId = [Amazon.SecurityHub.Model.StringFilter]@{
        Comparison = "EQUALS"
        Value = "XXX"
    }
    ComplianceStatus = [Amazon.SecurityHub.Model.StringFilter]@{
        Comparison = "EQUALS"
        Value = 'FAILED'
    }
}
New-SHUBInsight -Filter $Filter -Name TestInsight -GroupByAttribute ResourceId
```

------

## Creating a custom insight from a managed insight (console only)
<a name="securityhub-custom-insight-frrom-managed"></a>

You can't save changes to or delete a managed insight. However, you can use a managed insight as the basis for a custom insight. This is an option on the Security Hub CSPM console only.

**To create a custom insight from a managed insight (console)**

1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/).

1. In the navigation pane, choose **Insights**.

1. Choose the managed insight to work from.

1. Edit the insight configuration as needed.
   + To change the attribute used to group findings in the insight:

     1. To remove the existing grouping, choose the **X** next to the **Group by** setting.

     1. Choose the search box.

     1. Select the attribute to use for grouping.

     1. Choose **Apply**.
   + To remove a filter from the insight, choose the circled **X** next to the filter.
   + To add a filter to the insight:

     1. Choose the search box.

     1. Select the attribute and value to use as a filter.

     1. Choose **Apply**.

1. When your updates are complete, choose **Create insight**.

1. When prompted, enter an **Insight name**, and then choose **Create insight**.

# Editing a custom insight
<a name="securityhub-custom-insight-modify-console"></a>

You can edit an existing custom insight to change the grouping value and filters. After you make the changes, you can save the updates to the original insight, or save the updated version as a new insight.

In AWS Security Hub CSPM, custom insights can be used to collect a specific set of findings and track issues that are unique to your environment. For background information about custom insights, see [Understanding custom insights in Security Hub CSPM](securityhub-custom-insights.md).

To edit a custom insight, choose your preferred method, and follow the instructions.

------
#### [ Security Hub CSPM console ]

**To edit a custom insight (console)**

1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/).

1. In the navigation pane, choose **Insights**.

1. Choose the custom insight to modify.

1. Edit the insight configuration as needed.
   + To change the attribute used to group findings in the insight:

     1. To remove the existing grouping, choose the **X** next to the **Group by** setting.

     1. Choose the search box.

     1. Select the attribute to use for grouping.

     1. Choose **Apply**.
   + To remove a filter from the insight, choose the circled **X** next to the filter.
   + To add a filter to the insight:

     1. Choose the search box.

     1. Select the attribute and value to use as a filter.

     1. Choose **Apply**.

1. When you complete the updates, choose **Save insight**.

1. When prompted, do one of the following:
   + To update the existing insight to reflect your changes, choose **Update *<Insight\$1Name>*** and then choose **Save insight**.
   + To create a new insight with the updates, choose **Save new insight**. Enter an **Insight name**, and then choose **Save insight**.

------
#### [ Security Hub CSPM API ]

**To edit a custom insight (API)**

1. Use the [https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_UpdateInsight.html](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_UpdateInsight.html) operation of the Security Hub CSPM API. If you use the AWS CLI run the [https://docs.aws.amazon.com/cli/latest/reference/securityhub/update-insight.html](https://docs.aws.amazon.com/cli/latest/reference/securityhub/update-insight.html) command.

1. To identify the custom insight that you want to update, provide the insight's Amazon Resource Name (ARN). To get the ARN of a custom insight, use the [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetInsights.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetInsights.html) operation or the [https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-insights.html](https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-insights.html) command.

1. Update the `Name`, `Filters`, and `GroupByAttribute` parameters as needed.

The following example updates the specified insight. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.

```
$ aws securityhub update-insight --insight-arn "arn:aws:securityhub:us-west-1:123456789012:insight/123456789012/custom/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" --filters '{"ResourceType": [{ "Comparison": "EQUALS", "Value": "AwsIamRole"}], "SeverityLabel": [{"Comparison": "EQUALS", "Value": "HIGH"}]}' --name "High severity role findings"
```

------
#### [ PowerShell ]

**To edit a custom insight (PowerShell)**

1. Use the `Update-SHUBInsight` cmdlet.

1. To identify the custom insight, provide the insight's Amazon Resource Name (ARN). To get the ARN of a custom insight, use the `Get-SHUBInsight` cmdlet.

1. Update the `Name`, `Filter`, and `GroupByAttribute` parameters as needed.

**Example**

```
$Filter = @{
    ResourceType = [Amazon.SecurityHub.Model.StringFilter]@{
        Comparison = "EQUALS"
        Value = "AwsIamRole"
    }
    SeverityLabel = [Amazon.SecurityHub.Model.StringFilter]@{
        Comparison = "EQUALS"
        Value = "HIGH"
    }
}

Update-SHUBInsight -InsightArn "arn:aws:securityhub:us-west-1:123456789012:insight/123456789012/custom/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" -Filter $Filter -Name "High severity role findings"
```

------

# Deleting a custom insight
<a name="securityhub-custom-insight-delete-console"></a>

In AWS Security Hub CSPM, custom insights can be used to collect a specific set of findings and track issues that are unique to your environment. For background information about custom insights, see [Understanding custom insights in Security Hub CSPM](securityhub-custom-insights.md).

To delete a custom insight, choose your preferred method, and follow the instructions. You can't delete a managed insight.

------
#### [ Security Hub CSPM console ]

**To delete a custom insight (console)**

1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/).

1. In the navigation pane, choose **Insights**.

1. Locate the custom insight to delete.

1. For that insight, choose the more options icon (the three dots in the top-right corner of the card).

1. Choose **Delete**.

------
#### [ Security Hub CSPM API ]

**To delete a custom insight (API)**

1. Use the [https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_DeleteInsight.html](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_DeleteInsight.html) operation of the Security Hub CSPM API. If you use the AWS CLI run the [https://docs.aws.amazon.com/cli/latest/reference/securityhub/delete-insight.html](https://docs.aws.amazon.com/cli/latest/reference/securityhub/delete-insight.html) command.

1. To identify the custom insight to delete, provide the insight's ARN. To get the ARN of a custom insight, use the [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetInsights.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetInsights.html) operation or [https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-insights.html](https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-insights.html) command.

The following example deletes the specified insight. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.

```
$ aws securityhub delete-insight --insight-arn "arn:aws:securityhub:us-west-1:123456789012:insight/123456789012/custom/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```

------
#### [ PowerShell ]

**To delete a custom insight (PowerShell)**

1. Use the `Remove-SHUBInsight` cmdlet.

1. To identify the custom insight, provide the insight's ARN. To get the ARN of a custom insight, use the `Get-SHUBInsight` cmdlet.

**Example**

```
-InsightArn "arn:aws:securityhub:us-west-1:123456789012:insight/123456789012/custom/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```

------