# 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 collects Permissions Setup Verify Remove What 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_scale` or `cloud_security`) and an action (for example `deployed`, `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`, `environment` or `Environment` tag;
- a service name, when the resource carries a `service`, `app`, `app.kubernetes.io/name` or `service.name` tag, 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:PrincipalArn` condition) 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_trust` and 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:LookupEvents` cannot 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.

1. An Epok API key with write scope, and your Epok account ID. You also need `curl`, `jq` and the `aws` CLI, logged in to the AWS account as someone who may create CloudFormation stacks and IAM roles. The stack names its role, so it needs `CAPABILITY_NAMED_IAM`.
2. **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_url` that 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
```

1. **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](https://epok-cfn-templates-b6e84052.s3.eu-central-1.amazonaws.com/templates/1b02ac7062c7fe88179195946b11871196c00e2eef30e8f5a61af7b58fd4296e/epok-readonly-role.yaml) (SHA-256 1b02ac7062c7fe88179195946b11871196c00e2eef30e8f5a61af7b58fd4296e)
- [The us-east-1 read-only role template](https://epok-cfn-templates-b6e84052-us-east-1.s3.us-east-1.amazonaws.com/templates/1b02ac7062c7fe88179195946b11871196c00e2eef30e8f5a61af7b58fd4296e/epok-readonly-role.yaml) (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 its `RoleArn` output.
- `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.json
```

Deleting 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_security` changes. 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](https://epok.cloud/docs/install/aws).
