Skip to main content

CloudTrail Insights Enabled

Overview​

This check verifies that your AWS CloudTrail trails have Insights enabled. CloudTrail Insights uses machine learning to automatically detect unusual API activity patterns in your AWS account, such as sudden spikes in API calls or elevated error rates. When anomalies are detected, CloudTrail generates Insights events to alert you.

Risk​

Without CloudTrail Insights enabled, unusual patterns of API activity can go unnoticed until damage is already done. This creates security blind spots where:

  • Credential abuse (e.g., compromised access keys being used aggressively) may not be detected
  • Privilege escalation attempts that trigger unusual API patterns slip by unnoticed
  • Runaway automation or misconfigured scripts can delete or alter resources before anyone realizes
  • Data exfiltration through rapid API calls may not trigger alerts
  • Incident response is delayed because there are no anomaly-based alerts

Remediation Steps​

Prerequisites​

You need:

  • AWS Console access with permissions to modify CloudTrail trails
  • An existing CloudTrail trail that logs management events
Required IAM permissions (for administrators)

Your IAM user or role needs these permissions:

  • cloudtrail:DescribeTrails
  • cloudtrail:GetInsightSelectors
  • cloudtrail:PutInsightSelectors

AWS Console Method​

  1. Open CloudTrail in the AWS Console

  2. Select your trail

    • Click Trails in the left sidebar
    • Click on the trail name you want to configure

  3. Edit Insights settings

    • Scroll to the Insights section
    • Click Edit

  4. Enable Insights

    • Check the box for Insights events
    • Select the insight types you want to enable:
      • API call rate - Detects unusual volume of write management API calls
      • API error rate - Detects unusual patterns of API errors
    • AWS recommends enabling both types for comprehensive coverage

  5. Save your changes

    • Click Save changes
    • CloudTrail will begin analyzing your events and establishing a baseline (this takes about 7 days)
AWS CLI (optional)
aws cloudtrail put-insight-selectors \
    --trail-name <your-trail-name> \
    --insight-selectors '[{"InsightType":"ApiCallRateInsight"},{"InsightType":"ApiErrorRateInsight"}]' \
    --region us-east-1

Enable only API call rate Insights​

aws cloudtrail put-insight-selectors \
    --trail-name <your-trail-name> \
    --insight-selectors '[{"InsightType":"ApiCallRateInsight"}]' \
    --region us-east-1

Enable only API error rate Insights​

aws cloudtrail put-insight-selectors \
    --trail-name <your-trail-name> \
    --insight-selectors '[{"InsightType":"ApiErrorRateInsight"}]' \
    --region us-east-1

Replace <your-trail-name> with the name of your CloudTrail trail.

CloudFormation (optional)

This template creates a CloudTrail trail with Insights enabled:

AWSTemplateFormatVersion: '2010-09-09'
Description: CloudTrail trail with Insights enabled

Parameters:
  TrailName:
    Type: String
    Description: Name for the CloudTrail trail
    Default: my-insights-trail

  S3BucketName:
    Type: String
    Description: S3 bucket where CloudTrail logs will be stored

Resources:
  CloudTrailWithInsights:
    Type: AWS::CloudTrail::Trail
    Properties:
      TrailName: !Ref TrailName
      S3BucketName: !Ref S3BucketName
      IsLogging: true
      IsMultiRegionTrail: true
      IncludeGlobalServiceEvents: true
      EnableLogFileValidation: true
      InsightSelectors:
        - InsightType: ApiCallRateInsight
        - InsightType: ApiErrorRateInsight

Outputs:
  TrailArn:
    Description: ARN of the CloudTrail trail
    Value: !GetAtt CloudTrailWithInsights.Arn

Deploy with:

aws cloudformation deploy \
    --template-file cloudtrail-insights.yaml \
    --stack-name cloudtrail-insights \
    --parameter-overrides TrailName=my-insights-trail S3BucketName=my-cloudtrail-bucket \
    --region us-east-1

Note: If you are updating an existing trail managed by CloudFormation, simply add the InsightSelectors property to your existing template and run an update.

Terraform (optional)
# Variables
variable "trail_name" {
  description = "Name of the CloudTrail trail"
  type        = string
  default     = "my-insights-trail"
}

variable "s3_bucket_name" {
  description = "S3 bucket for CloudTrail logs"
  type        = string
}

# CloudTrail trail with Insights enabled
resource "aws_cloudtrail" "main" {
  name                          = var.trail_name
  s3_bucket_name                = var.s3_bucket_name
  is_multi_region_trail         = true
  include_global_service_events = true
  enable_log_file_validation    = true

  # Enable Insights
  insight_selector {
    insight_type = "ApiCallRateInsight"
  }

  insight_selector {
    insight_type = "ApiErrorRateInsight"
  }
}

# Output
output "trail_arn" {
  description = "ARN of the CloudTrail trail"
  value       = aws_cloudtrail.main.arn
}

Deploy with:

terraform init
terraform plan -var="trail_name=my-insights-trail" -var="s3_bucket_name=my-cloudtrail-bucket"
terraform apply -var="trail_name=my-insights-trail" -var="s3_bucket_name=my-cloudtrail-bucket"

Note: If you have an existing aws_cloudtrail resource, simply add the insight_selector blocks to enable Insights.

Verification​

After enabling Insights, verify the configuration is correct:

  1. In the AWS Console:

    • Go to CloudTrail > Trails and select your trail
    • Check the Insights section shows your selected insight types as enabled
    • Note: It takes about 7 days for CloudTrail to establish a baseline before generating Insights events

  2. Check for Insights events:

    • Go to CloudTrail > Insights in the left sidebar
    • If any anomalies have been detected after the baseline period, they will appear here
CLI verification commands

Check if Insights is enabled on a trail:

aws cloudtrail get-insight-selectors \
    --trail-name <your-trail-name> \
    --region us-east-1

Expected output when Insights is enabled:

{
    "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/my-trail",
    "InsightSelectors": [
        {
            "InsightType": "ApiCallRateInsight"
        },
        {
            "InsightType": "ApiErrorRateInsight"
        }
    ]
}

If Insights is not enabled, you will see an empty InsightSelectors array.

List recent Insights events (if any exist):

aws cloudtrail lookup-events \
    --lookup-attributes AttributeKey=EventSource,AttributeValue=cloudtrail.amazonaws.com \
    --region us-east-1 \
    --max-results 5

Additional Resources​

Notes​

  • Baseline period: CloudTrail needs approximately 7 days of management event data to establish a baseline. Insights events will not be generated during this initial period.
  • Trail requirements: Insights only works on trails that log management events. Ensure your trail is configured to capture write events at minimum (read events are optional).
  • Costs: CloudTrail Insights incurs additional charges. You are billed based on the number of events analyzed. Review the pricing page before enabling.
  • Multi-region trails: For organization-wide coverage, enable Insights on your organization trail or a multi-region trail.
  • Event data stores: If you use CloudTrail Lake with event data stores, Insights can also be enabled there, but only for management events (not data events).
  • Data events Insights: If you need Insights for data events (like S3 object-level operations), this is only supported on trails, not event data stores.