Description

Ensure that CloudTrail Insights is enabled on every AWS CloudTrail trail that is logging. CloudTrail Insights analyzes management events and records Insights events when it detects unusual API call rates or API error rates compared with the account's normal activity.

Rationale

Without CloudTrail Insights, abnormal bursts of API calls or errors can go unnoticed. Such patterns may point to compromised credentials, privilege escalation attempts or runaway automation that deletes resources or exfiltrates data. Enabling both the API call rate and API error rate insight types on logging trails, and sending the resulting events to monitoring and alerting, helps detect these incidents earlier.

Impact

  • Detects unusual API activity and error rates automatically

  • Supports faster investigation of credential misuse and faulty automation

  • CloudTrail Insights is charged per number of events analyzed

  • Insights events are delivered to the trail's S3 bucket and, if configured, to CloudWatch Logs; the first events can take up to 36 hours to appear

Default Value

CloudTrail Insights is not enabled on new trails by default.

Pre-Requisites

  • IAM permissions: cloudtrail:DescribeTrails, cloudtrail:GetTrailStatus, cloudtrail:GetInsightSelectors and cloudtrail:PutInsightSelectors

  • The trail must log management events, because Insights analyzes them

Remediation

Test Plan

Console:

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Open the AWS CloudTrail console and select Trails.

  3. Select a trail whose status is Logging.

  4. In the Insights events section, check whether any insight type is enabled.

  5. Repeat for each trail in each region in use.

  6. If a logging trail has no Insights enabled, follow the implementation steps.

CLI:

List the trails, their home region and whether Insights is configured:

aws cloudtrail describe-trails --region <REGION> --query "trailList[].[Name,HomeRegion,TrailARN,HasInsightSelectors]" --output table

Check whether a trail is logging:

aws cloudtrail get-trail-status --name <TRAIL_ARN> --region <REGION> --query IsLogging

Show the insight types enabled on a trail:

aws cloudtrail get-insight-selectors --trail-name <TRAIL_ARN> --region <REGION> --query "InsightSelectors[].InsightType"

A trail fails if it is logging and has no insight selectors (HasInsightSelectors is False or empty, or the last command returns no insight type). Trails that are not logging are not evaluated.

Implementation Steps

Console:

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Open the AWS CloudTrail console and select Trails.

  3. Select the trail that is logging.

  4. In the Insights events section, choose Edit.

  5. Enable Insights events and select API call rate and API error rate.

  6. Choose Save changes.

  7. Repeat for each affected trail in each region in use.

CLI:

Enable both insight types on a trail (run in the trail's home region):

aws cloudtrail put-insight-selectors --trail-name <TRAIL_NAME> --region <REGION> --insight-selectors '[{"InsightType":"ApiCallRateInsight"},{"InsightType":"ApiErrorRateInsight"}]'

Backout Plan

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Open the AWS CloudTrail console and select the trail.

  3. In the Insights events section, choose Edit.

  4. Disable Insights events, or clear the insight types that were added.

  5. Choose Save changes.

CLI:

aws cloudtrail put-insight-selectors --trail-name <TRAIL_NAME> --region <REGION> --insight-selectors '[]'

Note: turning off Insights stops the detection of unusual API activity on the trail.

Reference