Keep an account audit trail

$ grim infra:aws-cloudtrail --preset=minimal

Sooner or later someone asks who opened that port, who deleted that bucket, or when that access key was created. Without a trail, AWS keeps ninety days of that history, one region at a time. grim infra:aws-cloudtrail sets up the record before you need it: one trail for the whole account, every region, written to a bucket nothing else can write to.

The decision it asks of you is how much to record, because past the basic level CloudTrail charges by the event.

Usage

$ grim infra:aws-cloudtrail --dry-run                     # pick a preset, see the estimate, create nothing
$ grim infra:aws-cloudtrail --preset=minimal              # account activity only
$ grim infra:aws-cloudtrail --preset=compliance           # plus writes to your buckets, plus Insights
$ grim infra:aws-cloudtrail --preset=s3-audit-only --buckets=acme-shared-assets --s3-event-type=write

Run it from anywhere. It needs the aws CLI, terraform and working AWS credentials; grim infra:doctor checks them. One trail per account: the state is keyed by the account number.

Arguments and options

Set up an account-wide multi-region audit trail with opinionated preset library

Usage

grim infra:aws-cloudtrail [--preset PRESET] [--region REGION] [--name NAME] [--buckets BUCKETS] [--s3-event-type S3-EVENT-TYPE] [--cw-logs-retention CW-LOGS-RETENTION] [--insights] [--data-events] [--profile PROFILE] [--dry-run] [--force]

Options

The four presets

Management events are the control-plane calls: IAM changes, instance launches, bucket creation, every KMS call. Every preset records them. Data events are reads and writes of objects inside buckets and invocations of Lambda functions, and they are what makes a trail expensive.

Those labels are rough. The plan prints an estimate for your preset from the price snapshot built into grim, and says itself that the real bill follows the number of API calls. Without --preset the wizard asks, with minimal preselected; a run without interaction takes minimal.

What it actually does

Printed as Step 1/5 to Step 5/5.

1. Shows the AWS identity and asks whether to create resources in that account. The default answer is no.
2. Resolves the preset.
3. Fills in the configuration. Trail name grim-audit-trail, home region eu-central-1, log bucket grim-cloudtrail-<account>-<region>. For presets with bucket events it offers the buckets made by grim infra:aws-s3, all ticked. --buckets takes any bucket names instead, and a run without interaction takes all of grim's.
4. Prints the estimate. With --dry-run it stops here.
5. Runs Terraform in ~/.grim/infra/cloudtrail-<account>/ after a second confirmation, then records the trail under aws_resources in ~/.grim/servers.json as cloudtrail-<account> with the preset and every setting.

What exists in AWS afterwards

The trail, multi-region, with global service events and log file validation on. Validation writes digest files next to the logs, so a log that was altered later can be told from one that was not.

The log bucket, private and encrypted, whose policy lets only the CloudTrail service write into it. Logs land under AWSLogs/<account>/CloudTrail/ and move to the Glacier Instant Retrieval class after 30 days. Nothing ever expires them.

With security-focused only, a CloudWatch log group and the IAM role that lets CloudTrail write to it. The log group keeps entries for 90 days, or --cw-logs-retention.

Pitfalls

Changing the preset means starting over

CloudTrail state already exists for this account. stops a second run. Run grim infra:destroy cloudtrail-<account> first, then create the trail with the new preset. The message also offers --force, and warns in the same breath that Terraform will fail on the resources that already exist.

Event type and retention are never asked

--s3-event-type and --cw-logs-retention have defaults, all and 90, so the wizard takes those and moves on. all on a busy bucket is the costly choice. Pass the flag when you want write or a longer retention.

The old --data-events flag records every bucket

With the minimal preset, --data-events turns on read and write events for every bucket in the account. The command itself calls it deprecated. Use --preset=s3-audit-only and name the buckets.

The log bucket outlives the trail

The bucket refuses deletion while it holds objects, and grim has no option that empties it. After grim infra:destroy the trail stops recording, the destroy reports a failure on the bucket, and the history stays where it was. Empty and delete the bucket in the AWS console if you really want it gone.

After it finishes

Logs start arriving in the bucket and cost storage from then on. The trail shows in grim infra:list with its preset and estimate.

$ grim infra:list
$ aws s3 ls s3://grim-cloudtrail-123456789012-eu-central-1/AWSLogs/ --recursive | head

Questions

Does s3-audit-only really record nothing else?

It adds no data events beyond your buckets, but management events are part of every trail this command makes. AWS does not charge for the first copy of those in an account.

Do I need this if I am the only one with access?

That is when it is cheapest to have. The trail is how you find out that you were not the only one.

Related spells