CloudTrail for API auditing in AWS - Commands & Configuration

Introduction

When you want to know who did what in your AWS account, CloudTrail helps by recording all the actions taken through the AWS API. It keeps a history of these actions so you can check them later for security or troubleshooting.

When you want to track changes made to your AWS resources by users or services.

When you need to investigate a security incident by seeing who accessed or changed something.

When you want to keep a record of all API calls for compliance or auditing purposes.

When you want to monitor usage patterns of your AWS environment over time.

When you want to receive alerts or automate responses based on specific API activities.

Config File - cloudtrail.json

cloudtrail.json

{
  "TrailName": "example-trail",
  "S3BucketName": "example-cloudtrail-logs-bucket",
  "IncludeGlobalServiceEvents": true,
  "IsMultiRegionTrail": true,
  "EnableLogFileValidation": true
}

TrailName: The name of your CloudTrail trail.

S3BucketName: The bucket where CloudTrail stores log files.

IncludeGlobalServiceEvents: Records global services like IAM events.

IsMultiRegionTrail: Tracks API calls across all AWS regions.

EnableLogFileValidation: Ensures log files are not tampered with.

Commands

Create an S3 bucket to store CloudTrail logs. This bucket will hold all the recorded API activity files.

Terminal

aws s3 mb s3://example-cloudtrail-logs-bucket

Expected Output

make_bucket: example-cloudtrail-logs-bucket

Create a CloudTrail trail named 'example-trail' that records API calls from all regions, includes global services, and validates log files.

Terminal

aws cloudtrail create-trail --name example-trail --s3-bucket-name example-cloudtrail-logs-bucket --include-global-service-events --is-multi-region-trail --enable-log-file-validation

Expected Output

{

    "Name": "example-trail",

    "S3BucketName": "example-cloudtrail-logs-bucket",

    "IncludeGlobalServiceEvents": true,

    "IsMultiRegionTrail": true,

    "LogFileValidationEnabled": true

}

→

--include-global-service-events - Includes global AWS service events like IAM.

→

--is-multi-region-trail - Tracks API calls across all AWS regions.

→

--enable-log-file-validation - Ensures logs are secure and untampered.

Start recording API activity for the trail you created.

Terminal

aws cloudtrail start-logging --name example-trail

Expected Output

No output (command runs silently)

Check the details of your CloudTrail trail to confirm it is set up correctly.

Terminal

aws cloudtrail describe-trails --trail-name-list example-trail

Expected Output

{

    "trailList": [

        {

            "Name": "example-trail",

            "S3BucketName": "example-cloudtrail-logs-bucket",

            "IncludeGlobalServiceEvents": true,

            "IsMultiRegionTrail": true,

            "LogFileValidationEnabled": true

        }

    ]

}

View the last 5 recorded API events to see what actions have been logged.

Terminal

aws cloudtrail lookup-events --max-results 5

Expected Output

{

    "Events": [

        {

            "EventId": "12345678-1234-1234-1234-123456789012",

            "EventName": "ConsoleLogin",

            "Username": "alice",

            "EventTime": "2024-06-01T12:00:00Z"

        },

        {

            "EventId": "87654321-4321-4321-4321-210987654321",

            "EventName": "CreateBucket",

            "Username": "bob",

            "EventTime": "2024-06-01T11:50:00Z"

        }

    ]

}

→

--max-results - Limits the number of events returned.

Key Concept

If you remember nothing else from this pattern, remember: CloudTrail records every API action in your AWS account so you can see who did what and when.

Common Mistakes

Not creating or specifying an S3 bucket for CloudTrail logs.

CloudTrail needs a place to store logs; without a bucket, it cannot save the recorded events.

Always create an S3 bucket first and specify it when creating the CloudTrail trail.

Forgetting to start logging after creating the trail.

Creating a trail alone does not start recording; you must explicitly start logging to capture events.

Run 'aws cloudtrail start-logging' with your trail name to begin capturing API activity.

Not enabling multi-region trails when you have resources in multiple regions.

Without multi-region enabled, CloudTrail only records events in the region where the trail was created, missing others.

Use the --is-multi-region-trail flag to capture API calls from all regions.

Summary

Create an S3 bucket to store CloudTrail logs.

Create a CloudTrail trail specifying the bucket and enabling global and multi-region events.

Start logging to begin recording API activity.

Verify the trail setup and view recent API events.