Skip to main content
OpenSRE uses AWS CloudTrail to answer the first question of every cloud post-mortem: “who changed what, and when?” When an AWS alert fires, the planner can look up recent management events — IAM changes, security-group mutations, EKS/Lambda config updates, and resource deletions — scoped to a resource, a principal, or a time window. CloudTrail lookups are read-only and routed through the shared aws_sdk_client allowlist, so the integration cannot mutate any resources.

​
Prerequisites

  • AWS credentials configured per the AWS integration (role ARN recommended) — CloudTrail reuses the same account credentials and region, so no extra setup is needed
  • IAM permission for the single read-only CloudTrail action listed below

​
How it works

CloudTrail is account-wide, so the tool becomes available to the planner whenever the AWS integration is configured — there is nothing resource-specific to set up. The region comes from the AWS integration (or AWS_REGION, defaulting to us-east-1).

​
Tools

ToolAWS API callWhat it returns
lookup_cloudtrail_eventscloudtrail:LookupEventsRecent management events — event name, time, source, acting username, affected resources, AWS region, source IP, and any error code.

​
Parameters

ParameterDefaultDescription
resource_name—Filter to events touching a specific resource name/ARN (the most specific filter).
event_source—Filter by AWS service event source, e.g. iam.amazonaws.com, ec2.amazonaws.com.
username—Filter by the acting principal / IAM username.
regionus-east-1AWS region to query.
duration_minutes60Look-back window. CloudTrail retains 90 days of history (the upper bound).
max_results50Maximum events to return (CloudTrail caps this at 50 per call).
next_token—Pagination token from a previous truncated response; pass it to fetch the next page.
CloudTrail’s LookupEvents API accepts only one filter attribute per call. When more than one filter is supplied, the tool sends the most specific one, in priority order: resource_name → username → event_source. With no filter, it returns recent account-wide events for the window.
CloudTrail returns at most 50 events per page. When more matching events exist, the response sets truncated: true and returns a next_token — pass it back via the next_token parameter to fetch the next page, so a busy account or wide window never silently drops events.

​
Use cases

  • Finding who modified an IAM policy, role, or security group just before an incident
  • Tracing configuration changes to a specific resource (by resource name)
  • Auditing every action taken by a principal (by username)
  • Reviewing recent activity from a single AWS service (by event source)
  • Establishing change causality at the start of a post-mortem

​
IAM permissions

The tool only needs one read-only CloudTrail action: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudtrail:LookupEvents"
      ],
      "Resource": "*"
    }
  ]
}
Attach this policy to the same IAM role or user already configured for the AWS integration. If you are already using the AWS managed ReadOnlyAccess policy, this action is already covered.
Execution identity: the AWS integration’s role_arn / credentials gate availability and supply the region, but the lookup itself runs through boto3’s standard credential chain (environment variables, shared config, or the host’s instance role) — the configured role is not assumed for the call. Ensure the identity the OpenSRE process runs as can perform cloudtrail:LookupEvents. This matches the other AWS tools (RDS/EKS).

​
Troubleshooting

SymptomFix
AccessDenied on cloudtrail:LookupEventsAdd the IAM policy above to the role or user used by the AWS integration.
No events returnedWiden duration_minutes, loosen the filter, or confirm you are querying the region where the activity occurred. Only management events are returned; data events are not.
ThrottlingExceptionCloudTrail LookupEvents is rate-limited to two requests per second per account per region. Retry with a narrower window.
Tool reports the wrong regionSet AWS_REGION, or check the region field on the configured AWS integration.