AWS CloudTrail change events
Updated Nov 18, 2026 · today
Status: not yet available on Epok's hosted service. Use OpenTelemetry (OTLP) for now.
OpenTelemetry does not carry CloudTrail events, so until this path is on, Epok does not see changes made in your AWS account. Epok has not switched it on for customer accounts. The API calls on this page answer 404 on an account where it is off.
With it on, you create one IAM role in your AWS account from our CloudFormation template. Epok assumes that role, reads your account's CloudTrail management events, and stores the changes that matter for an incident (a deploy, a scale change, a security group rule) as change events. Nothing runs in your account and the role cannot change anything.
On this page: What Epok collectsPermissionsSetupVerifyRemoveWhat was tested
What Epok collects
Every 5 minutes, for each region you register (up to 4), Epok calls cloudtrail:LookupEvents for write events only. The first poll looks back at most 24 hours. Epok keeps an event only when it is a successful call and its name is in this list:
| Service | CloudTrail event names |
|---|---|
| EC2 | AuthorizeSecurityGroupIngress, AuthorizeSecurityGroupEgress, RevokeSecurityGroupIngress, RevokeSecurityGroupEgress, ModifySecurityGroupRules, RunInstances, TerminateInstances, StopInstances, StartInstances, RebootInstances, ModifyInstanceAttribute, CreateLaunchTemplateVersion |
| Lambda | UpdateFunctionCode, PublishVersion, UpdateAlias, UpdateFunctionConfiguration, PutFunctionConcurrency, CreateFunction, DeleteFunction |
| ECS | UpdateService, CreateService, DeleteService, CreateTaskSet, UpdateServicePrimaryTaskSet |
| RDS | ModifyDBInstance, RebootDBInstance, ModifyDBCluster, FailoverDBCluster, ModifyDBParameterGroup |
| Elastic Load Balancing (v2) | ModifyListener, ModifyRule, CreateRule, DeleteRule, ModifyTargetGroup, ModifyTargetGroupAttributes, ModifyLoadBalancerAttributes |
Each kept event becomes one change event with:
- a kind (
cloud_deploy,cloud_config,cloud_scaleorcloud_security) and an action (for exampledeployed,scaled,rule_added); - the resource ARN, the time of the change and a link to the event in the CloudTrail console;
- a few named values, such as a Lambda version, an ECS task definition revision or a desired count. For a configuration change, Epok stores only the names of the parameters that changed, never their values. Environment variables, user data, passwords and policies are not copied;
- for a security group rule change, the direction and up to 10 rules, each as protocol, port range and the CIDR or security group it allows;
- for an instance start, stop, reboot, run or terminate, the instance IDs (up to 10), their count and, on run, the instance type;
- who made the change, stored as a hash of the IAM ARN, not the ARN;
- the environment, when the resource carries an
env,environmentorEnvironmenttag; - a service name, when the resource carries a
service,app,app.kubernetes.io/nameorservice.nametag, or when its name equals a service Epok already sees in your telemetry. Otherwise no service.
Epok drops read-only events, failed calls, the calls of its own session and every event not in the list. CloudTrail returns whole events to the caller, so the full event reaches Epok's worker; only the fields above are stored. The same role also lets Epok list resources and their tags for these five services, which is how a change gets its service name.
The exact permissions, and why read-only is safe
This is the role's whole permissions policy, as the template creates it. With EnableChangeEvents=false the ChangeEventsReadOnly statement is left out, and Epok then gets no CloudTrail events.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InventoryReadOnly",
"Effect": "Allow",
"Action": [
"tag:GetResources",
"ec2:DescribeInstances",
"ec2:DescribeSecurityGroups",
"ec2:DescribeRegions",
"rds:DescribeDBInstances",
"rds:DescribeDBClusters",
"lambda:ListFunctions",
"elasticloadbalancing:DescribeLoadBalancers",
"elasticloadbalancing:DescribeTargetGroups",
"elasticloadbalancing:DescribeListeners",
"ecs:ListClusters",
"ecs:ListServices",
"ecs:DescribeServices"
],
"Resource": "*"
},
{
"Sid": "ChangeEventsReadOnly",
"Effect": "Allow",
"Action": [
"cloudtrail:LookupEvents",
"cloudtrail:DescribeTrails"
],
"Resource": "*"
},
{
"Sid": "DenyDataPlaneAndSecrets",
"Effect": "Deny",
"Action": [
"s3:GetObject*",
"s3:ListBucket*",
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Query",
"dynamodb:Scan",
"dynamodb:ExportTableToPointInTime",
"sqs:ReceiveMessage",
"lambda:GetFunction",
"lambda:GetFunctionConfiguration",
"lambda:InvokeFunction",
"ec2:DescribeInstanceAttribute",
"ec2:DescribeLaunchTemplateVersions",
"ec2:GetPasswordData",
"ec2:GetConsoleOutput",
"ec2:GetConsoleScreenshot",
"ecs:DescribeTaskDefinition",
"ecs:DescribeTasks",
"rds:DescribeDBSnapshotAttributes",
"secretsmanager:*",
"ssm:GetParameter*",
"kms:Decrypt",
"rds:DownloadDBLogFilePortion",
"rds:DownloadCompleteDBLogFile",
"logs:GetLogEvents",
"logs:FilterLogEvents",
"logs:StartQuery",
"lambda:GetFunctionUrlConfig"
],
"Resource": "*"
},
{
"Sid": "DenyApiGatewaySecrets",
"Effect": "Deny",
"Action": "apigateway:GET",
"Resource": [
"arn:aws:apigateway:*::/apikeys*",
"arn:aws:apigateway:*::/usageplans/*/keys*",
"arn:aws:apigateway:*::/restapis/*/exports/*",
"arn:aws:apigateway:*::/domainnames*",
"arn:aws:apigateway:*::/clientcertificates*"
]
}
]
}And the trust policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EpokAssumeWithExternalId",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::<EpokPrincipalAccountId>:root" },
"Action": "sts:AssumeRole",
"Condition": {
"ArnEquals": { "aws:PrincipalArn": "<EpokPrincipalArn>" },
"StringEquals": { "sts:ExternalId": ["<ExternalId>"] }
}
}
]
}- No write action. Every allowed action is a List, Describe, Get or Lookup call. The role cannot create, change or delete anything.
- One identity, one secret.Only Epok's single assuming identity (the
aws:PrincipalArncondition) may assume the role, and only with your integration's External ID. Epok generates a new random External ID for each integration and stores it encrypted. - Epok checks the trust itself. At verify, Epok assumes the role three times: with the External ID (must work), with a wrong one and with none (both must be denied). If a wrong or missing ID works, the integration is marked
insecure_trustand Epok does not use it. - An explicit Deny for data and secrets. S3 objects, DynamoDB items, queue messages, Lambda code and configuration, task definitions, Secrets Manager, SSM parameters, KMS decrypt, log events and API Gateway keys are denied. In IAM an explicit Deny wins over any Allow, so this holds even if someone attaches a broader policy to the role later.
- Short and visible sessions. A session lasts at most one hour. Its name is
epok-<account>-<integration>, so Epok's calls are attributable in your own CloudTrail. - What it can still see.
cloudtrail:LookupEventscannot be narrowed to some services in IAM: it returns every management event in the region. Epok asks for write events only and stores only the list above, but the permission itself is account-wide.
Setup
Status: not yet available on Epok's hosted service. Use OpenTelemetry (OTLP) for now.
- An Epok API key with write scope, and your Epok account ID. You also need
curl,jqand theawsCLI, logged in to the AWS account as someone who may create CloudFormation stacks and IAM roles. The stack names its role, so it needsCAPABILITY_NAMED_IAM. - Register the AWS account in Epok. Give the 12-digit account ID and the regions to read. The answer holds the integration ID, your new External ID, the template URL and the stack parameters, plus a
quick_create_urlthat opens the AWS console with all of it filled in.
export EPOK_API_KEY="<API key with write scope>"
export EPOK_ACCOUNT_ID="<your Epok account ID>"
export AWS_REGION="eu-central-1"curl -fsS -X POST "https://app.epok.cloud/api/v1/tenants/$EPOK_ACCOUNT_ID/integrations/aws" \
-H "X-API-Key: $EPOK_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"aws_account_id": "123456789012", "regions": ["eu-central-1"]}' \
> epok-aws.json
chmod 600 epok-aws.json
jq '{id, state, cloudformation}' epok-aws.json- Create the stack. Open the
quick_create_url, review the template and create it, or use the CLI as below. Create it in the first region you registered. IAM roles are global, so one stack covers every region.
# The External ID is in these files. Keep them private and delete them after.
jq '[.cloudformation.parameters | to_entries[] | {ParameterKey: .key, ParameterValue: .value}]' \
epok-aws.json > epok-role-params.json
chmod 600 epok-role-params.json
aws cloudformation create-stack --region "$AWS_REGION" --stack-name EpokReadOnly \
--template-url "$(jq -r .cloudformation.template_url epok-aws.json)" \
--parameters file://epok-role-params.json \
--capabilities CAPABILITY_NAMED_IAM
aws cloudformation wait stack-create-complete --region "$AWS_REGION" --stack-name EpokReadOnly
rm epok-role-params.json
ROLE_ARN=$(aws cloudformation describe-stacks --region "$AWS_REGION" --stack-name EpokReadOnly \
--query "Stacks[0].Outputs[?OutputKey=='RoleArn'].OutputValue" --output text)
echo "$ROLE_ARN"Read the template before you create it. It is the same file in every region:
- The eu-central-1 read-only role template (SHA-256 1b02ac7062c7fe88179195946b11871196c00e2eef30e8f5a61af7b58fd4296e)
- The us-east-1 read-only role template (SHA-256 1b02ac7062c7fe88179195946b11871196c00e2eef30e8f5a61af7b58fd4296e)
The role ARN has the form arn:aws:iam::<your-account>:role/epok/EpokReadOnly-i<integration-id>. Keep the /epok/ path: Epok refuses an ARN outside it, or in another account, before it calls AWS.
Verify
Send the role ARN to Epok. Epok runs the three-way trust check described above.
INTEGRATION_ID=$(jq -r .id epok-aws.json)
curl -fsS -X POST "https://app.epok.cloud/api/v1/tenants/$EPOK_ACCOUNT_ID/integrations/aws/$INTEGRATION_ID/verify" \
-H "X-API-Key: $EPOK_API_KEY" \
-H 'Content-Type: application/json' \
-d "{\"role_arn\": \"$ROLE_ARN\"}" | jq '{state, probe}'A good answer:
{
"state": "verified",
"probe": {
"with_external_id": "ok",
"wrong_external_id": "denied",
"no_external_id": "denied"
}
}revoked: every attempt was denied. Check that the stack finished and that you sent the ARN from itsRoleArnoutput.insecure_trust: the role accepted a wrong or missing External ID. Delete the stack and create it again from the unchanged template.- A 503 with
probe_inconclusive: AWS did not give a clear answer (for example, throttling). Send the same request again.
Then make a change you can undo (for example, add and remove a security group rule) and, after a few minutes, look for it:
# State and the last CloudTrail poll per region
curl -fsS "https://app.epok.cloud/api/v1/tenants/$EPOK_ACCOUNT_ID/integrations/aws" \
-H "X-API-Key: $EPOK_API_KEY" | jq '.integrations[] | {id, state, regions_status}'
# AWS changes stored in the last 24 hours (the feed returns at most 500 rows of all kinds)
curl -fsS "https://app.epok.cloud/api/v1/tenants/$EPOK_ACCOUNT_ID/changes?limit=500" \
-H "X-API-Key: $EPOK_API_KEY" \
| jq '.changes[] | select(.source == "aws_cloudtrail") | {kind, action, subject, changed_at, link_url}'CloudTrail itself takes a few minutes to show an event; in our run, changes were stored about two and a half minutes after they were made.
Remove
# 1. Stop Epok polling. purge=true also deletes the AWS changes Epok stored.
curl -fsS -X DELETE \
"https://app.epok.cloud/api/v1/tenants/$EPOK_ACCOUNT_ID/integrations/aws/$INTEGRATION_ID?purge=true" \
-H "X-API-Key: $EPOK_API_KEY"
# 2. Delete the role. This ends Epok's access to the account.
aws cloudformation delete-stack --region "$AWS_REGION" --stack-name EpokReadOnly
aws cloudformation wait stack-delete-complete --region "$AWS_REGION" --stack-name EpokReadOnly
rm -f epok-aws.jsonDeleting the integration in Epok stops polling and deletes the resource list Epok kept. Without purge=true, the AWS changes already stored stay in Epok. Deleting the stack removes the role and its policy; from then on every call Epok could make is denied by AWS. Delete the stack even if you have already deleted the integration in Epok.
What was tested
One run on 2026-11-10, with this template unchanged, between two real AWS accounts (eu-central-1) and a local Epok stack, not the hosted service:
- Stack creation took 57 s and deletion 47 s.
- Verify answered
verified: the correct External ID worked; a wrong one and a missing one were both denied. A role without Epok in its trust policy was denied too. - 6 of 6 security group rule changes (3 added, 3 removed) were stored once each, as
cloud_securitychanges. Median time from change to stored: 143 s. - 6 extra overlapping polls found the same events again; none was stored twice.
- A second Epok account could not see, verify or delete the first account's integration, and stored no AWS data.
- After the stack was deleted, no role, policy or test resource was left in the account.
The other event names in the list are covered by tests on CloudTrail events captured from a real AWS test account, not yet by an end-to-end run. Firehose logs and metrics are a separate stack: AWS: logs and metrics.