View a markdown version of this page

CloudTrail examples using AWS CLI - AWS SDK Code Examples
Actions

There are more AWS SDK examples available in the AWS Doc SDK Examples GitHub repo.

CloudTrail examples using AWS CLI

The following code examples show you how to perform actions and implement common scenarios by using the AWS Command Line Interface with CloudTrail.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.

Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use add-tags.

AWS CLI

To add tags to trail

The following add-tags example adds tags for Trail1.

aws cloudtrail add-tags \
    --resource-id arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1 \
    --tags-list Key=name,Value=Alice Key=location,Value=us

This command produces no output.

For more information, see Managing trails with the AWS CLI in the AWS CloudTrail User Guide.

  • For API details, see AddTags in AWS CLI Command Reference.

The following code example shows how to use create-trail.

AWS CLI

To create a trail

The following create-trail example creates a multi-region trail named Trail1 and specifies an S3 bucket.

aws cloudtrail create-trail \
    --name Trail1 \
    --s3-bucket-name amzn-s3-demo-bucket \
    --is-multi-region-trail

Output:

{
    "IncludeGlobalServiceEvents": true,
    "Name": "Trail1",
    "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1",
    "LogFileValidationEnabled": false,
    "IsMultiRegionTrail": true,
    "S3BucketName": "amzn-s3-demo-bucket"
}

For more information, see Using the create-trail command to create a trail in the AWS CloudTrail User Guide.

  • For API details, see CreateTrail in AWS CLI Command Reference.

The following code example shows how to use delete-trail.

AWS CLI

To delete a trail

The following delete-trail example deletes a trail named Trail1.

aws cloudtrail delete-trail \
    --name Trail1

This command produces no output.

For more information, see Managing trails with the AWS CLI in the AWS CloudTrail User Guide.

  • For API details, see DeleteTrail in AWS CLI Command Reference.

The following code example shows how to use describe-trails.

AWS CLI

To describe a trail

The following describe-trails example returns the settings for Trail1 and Trail2.

aws cloudtrail describe-trails \
    --trail-name-list Trail1 Trail2

Output:

{
    "trailList": [
        {
            "IncludeGlobalServiceEvents": true,
            "Name": "Trail1",
            "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1",
            "LogFileValidationEnabled": false,
            "IsMultiRegionTrail": false,
            "S3BucketName": "amzn-s3-demo-bucket",
            "CloudWatchLogsRoleArn": "arn:aws:iam::123456789012:role/CloudTrail_CloudWatchLogs_Role",
            "CloudWatchLogsLogGroupArn": "arn:aws:logs:us-west-2:123456789012:log-group:CloudTrail:*",
            "SnsTopicName": "my-topic",
            "HomeRegion": "us-west-2"
        },
        {
            "IncludeGlobalServiceEvents": true,
            "Name": "Trail2",
            "S3KeyPrefix": "my-prefix",
            "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail2",
            "LogFileValidationEnabled": false,
            "IsMultiRegionTrail": false,
            "S3BucketName": "amzn-s3-demo-bucket2",
            "KmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "HomeRegion": "us-west-2"
        }
    ]
}

For more information, see Managing trails with the AWS CLI in the AWS CloudTrail User Guide.

The following code example shows how to use get-event-selectors.

AWS CLI

To view the event selector settings for a trail

The following get-event-selectors example returns the settings for Trail1.

aws cloudtrail get-event-selectors \
    --trail-name Trail1

Output:

{
    "EventSelectors": [
        {
            "IncludeManagementEvents": true,
            "DataResources": [],
            "ReadWriteType": "All"
        }
    ],
    "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1"
}

For more information, see Logging management events in the AWS CloudTrail User Guide.

The following code example shows how to use get-trail-status.

AWS CLI

To get the status of a trail

The following get-trail-status example returns the delivery and logging details for Trail1.

aws cloudtrail get-trail-status \
    --name Trail1

Output:

{
    "LatestNotificationTime": 1454022144.869,
    "LatestNotificationAttemptSucceeded": "2016-01-28T23:02:24Z",
    "LatestDeliveryAttemptTime": "2016-01-28T23:02:24Z",
    "LatestDeliveryTime": 1454022144.869,
    "TimeLoggingStarted": "2015-11-06T18:36:38Z",
    "LatestDeliveryAttemptSucceeded": "2016-01-28T23:02:24Z",
    "IsLogging": true,
    "LatestCloudWatchLogsDeliveryTime": 1454022144.918,
    "StartLoggingTime": 1446834998.695,
    "StopLoggingTime": 1446834996.933,
    "LatestNotificationAttemptTime": "2016-01-28T23:02:24Z",
    "TimeLoggingStopped": "2015-11-06T18:36:36Z"
}

For more information, see Managing trails with the AWS CLI in the AWS CloudTrail User Guide.

The following code example shows how to use list-public-keys.

AWS CLI

To list all public keys for a trail

The following list-public-keys example returns all public keys whose private keys were used to sign the digest files within the specified time range.

aws cloudtrail list-public-keys \
    --start-time 2016-01-01T20:30:00.000Z

Output:

{
    "PublicKeyList": [
        {
            "ValidityStartTime": 1453076702.0,
            "ValidityEndTime": 1455668702.0,
            "Value": "MIIBCgKCAQEAlSS3cl92HDycr/MTj0moOhas8habjrraXw+KzlWF0axSI2tcF+3iJ9BKQAVSKxGwxwu3m0wG3J+kUl1xboEcEPHYoIYMbgfSw7KGnuDKwkLzsQWhUJ0cIbOHASox1vv/5fNXkrHhGbDCHeVXm804c83nvHUEFYThr1PfyP/8HwrCtR3FX5OANtQCP61C1nJtSSkC8JSQUOrIP4CuwJjc+4WGDk+BGH5m9iuiAKkipEHWmUl8/P7XpfpWQuk4h8g3pXZOrNXr08lbh4d39svj7UqdhvOXoBISp9t/EXYuePGEtBdrKD9Dz+VHwyUPtBQvYr9BnkF88qBnaPNhS44rzwIDAQAB",
            "Fingerprint": "7f3f401420072e50a65a141430817ab3"
        }
    ]
}

For more information, see Validating CloudTrail log file integrity with the AWS CLI in the AWS CloudTrail User Guide.

The following code example shows how to use list-tags.

AWS CLI

To list the tags for a trail

The following list-tags example lists the tags for Trail1 and Trail2.

aws cloudtrail list-tags \
    --resource-id-list arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1 arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail2

Output:

{
    "ResourceTagList": [
        {
            "ResourceId": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1",
            "TagsList": [
                {
                    "Value": "Alice",
                    "Key": "name"
                },
                {
                    "Value": "us",
                    "Key": "location"
                }
            ]
        },
        {
            "ResourceId": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail2",
            "TagsList": [
                {
                    "Value": "Bob",
                    "Key": "name"
                }
            ]
        }
    ]
}

For more information, see Managing trails with the AWS CLI in the AWS CloudTrail User Guide.

  • For API details, see ListTags in AWS CLI Command Reference.

The following code example shows how to use lookup-events.

AWS CLI

To look up events for a trail

The following lookup-events example looks up API activity events by the attribute EventName.

aws cloudtrail lookup-events \
    --lookup-attributes AttributeKey=EventName,AttributeValue=ConsoleLogin

Output:

{
    "Events": [
        {
            "EventId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "Username": "my-session-name",
            "EventTime": "2021-11-18T09:41:02-08:00",
            "CloudTrailEvent": "{\"eventVersion\":\"1.02\",\"userIdentity\":{\"type\":\"AssumedRole\",\"principalId\":\"AROAJIKPFTA72SWU4L7T4:my-session-name\",\"arn\":\"arn:aws:sts::123456789012:assumed-role/my-role/my-session-name\",\"accountId\":\"123456789012\",\"sessionContext\":{\"attributes\":{\"mfaAuthenticated\":\"false\",\"creationDate\":\"2016-01-26T21:42:12Z\"},\"sessionIssuer\":{\"type\":\"Role\",\"principalId\":\"AROAJIKPFTA72SWU4L7T4\",\"arn\":\"arn:aws:iam::123456789012:role/my-role\",\"accountId\":\"123456789012\",\"userName\":\"my-role\"}}},\"eventTime\":\"2016-01-26T21:42:12Z\",\"eventSource\":\"signin.amazonaws.com\",\"eventName\":\"ConsoleLogin\",\"awsRegion\":\"us-west-2\",\"sourceIPAddress\":\"72.21.198.70\",\"userAgent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36\",\"requestParameters\":null,\"responseElements\":{\"ConsoleLogin\":\"Success\"},\"additionalEventData\":{\"MobileVersion\":\"No\",\"MFAUsed\":\"No\"},\"eventID\":\"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111\",\"eventType\":\"AwsConsoleSignIn\",\"recipientAccountId\":\"123456789012\"}",
            "EventName": "ConsoleLogin",
            "Resources": []
        }
    ]
}

For more information, see Viewing recent management events with the AWS CLI in the AWS CloudTrail User Guide.

  • For API details, see LookupEvents in AWS CLI Command Reference.

The following code example shows how to use put-event-selectors.

AWS CLI

Example 1: To configure a trail to log management events and data events by using advanced event selectors

The following put-event-selectors example creates an advanced event selector for a trail named myTrail to log all management events, log S3 PutObject and DeleteObject API calls for all but one S3 bucket, log data API calls for a Lambda function named myFunction, and log Publish API calls on an SNS topic named myTopic.

You can add advanced event selectors, and conditions for your advanced event selectors, up to a maximum of 500 values for all conditions and selectors on a trail. You can use advanced event selectors to log all available data event types. You can use either advanced event selectors or basic event selectors, but not both. If you apply advanced event selectors to a trail, any existing basic event selectors are overwritten.

aws cloudtrail put-event-selectors \
    --trail-name myTrail \
    --advanced-event-selectors '[{"Name": "Log all management events", "FieldSelectors": [{ "Field": "eventCategory", "Equals": ["Management"] }] },{"Name": "Log PutObject and DeleteObject events for all but one bucket","FieldSelectors": [{ "Field": "eventCategory", "Equals": ["Data"] },{ "Field": "resources.type", "Equals": ["AWS::S3::Object"] },{ "Field": "eventName", "Equals": ["PutObject","DeleteObject"] },{ "Field": "resources.ARN", "NotStartsWith": ["arn:aws:s3:::amzn-s3-demo-bucket/"] }]},{"Name": "Log data events for a specific Lambda function","FieldSelectors": [{ "Field": "eventCategory", "Equals": ["Data"] },{ "Field": "resources.type", "Equals": ["AWS::Lambda::Function"] },{ "Field": "resources.ARN", "Equals": ["arn:aws:lambda:us-west-2:123456789012:function:myFunction"] }]},{"Name": "Log all Publish API calls on a specific SNS topic","FieldSelectors": [{ "Field": "eventCategory", "Equals": ["Data"] },{ "Field": "resources.type", "Equals": ["AWS::SNS::Topic"] },{ "Field": "eventName", "Equals": ["Publish"] },{ "Field": "resources.ARN", "Equals": ["arn:aws:sns:us-west-2:123456789012:myTopic.fifo"] }]}]'

Output:

{
    "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/myTrail",
    "AdvancedEventSelectors": [
        {
            "Name": "Log all management events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        },
        {
            "Name": "Log PutObject and DeleteObject events for all but one bucket",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Data"
                    ]
                },
                {
                    "Field": "resources.type",
                    "Equals": [
                        "AWS::S3::Object"
                    ]
                },
                {
                    "Field": "eventName",
                    "Equals": [
                        "PutObject",
                        "DeleteObject"
                    ]
                },
                {
                    "Field": "resources.ARN",
                    "NotStartsWith": [
                        "arn:aws:s3:::amzn-s3-demo-bucket/"
                    ]
                }
            ]
        },
        {
            "Name": "Log data events for a specific Lambda function",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Data"
                    ]
                },
                {
                    "Field": "resources.type",
                    "Equals": [
                        "AWS::Lambda::Function"
                    ]
                },
                {
                    "Field": "resources.ARN",
                    "Equals": [
                        "arn:aws:lambda:us-west-2:123456789012:function:myFunction"
                    ]
                }
            ]
        },
        {
            "Name": "Log all Publish API calls on a specific SNS topic",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Data"
                    ]
                },
                {
                    "Field": "resources.type",
                    "Equals": [
                        "AWS::SNS::Topic"
                    ]
                },
                {
                    "Field": "eventName",
                    "Equals": [
                        "Publish"
                    ]
                },
                {
                    "Field": "resources.ARN",
                    "Equals": [
                        "arn:aws:sns:us-west-2:123456789012:myTopic.fifo"
                    ]
                }
            ]
        }
    ]
}

For more information, see Log events by using advanced event selectors in the AWS CloudTrail User Guide.

Example 2: To configure event selectors for a trail to log all management events and data events

The following put-event-selectors example creates an event selector for a trail named TrailName to include all management events, data events for two Amazon S3 bucket/prefix combinations, and data events for a single AWS Lambda function named hello-world-python-function.

You can configure up to 5 event selectors for a trail and up to 250 data resources for a trail. Event selectors are also referred to as basic event selectors. You can use event selectors to log management events and data events for S3 objects, Lambda functions, and DynnamoDB tables. To log data events for other resource types, you must use advanced event selectors.

aws cloudtrail put-event-selectors \
    --trail-name TrailName \
    --event-selectors '[{"ReadWriteType": "All","IncludeManagementEvents": true,"DataResources": [{"Type":"AWS::S3::Object", "Values": ["arn:aws:s3:::amzn-s3-demo-bucket/prefix","arn:aws:s3:::amzn-s3-demo-bucket2/prefix2"]},{"Type": "AWS::Lambda::Function","Values": ["arn:aws:lambda:us-west-2:123456789012:function:hello-world-python-function"]}]}]'

Output:

{
    "EventSelectors": [
        {
            "IncludeManagementEvents": true,
            "DataResources": [
                {
                    "Values": [
                        "arn:aws:s3:::amzn-s3-demo-bucket/prefix",
                        "arn:aws:s3:::amzn-s3-demo-bucket2/prefix2"
                    ],
                    "Type": "AWS::S3::Object"
                },
                {
                    "Values": [
                        "arn:aws:lambda:us-west-2:123456789012:function:hello-world-python-function"
                    ],
                    "Type": "AWS::Lambda::Function"
                }
            ],
            "ReadWriteType": "All"
        }
    ],
    "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/TrailName"
}

For more information, see Log events by using basic event selectors in the AWS CloudTrail User Guide.

Example 3: To configure event selectors for a trail to log management events, all S3 data events on S3 objects, and all Lambda data events on functions in your account

The following put-event-selectors example creates an event selector for a trail named TrailName2 that includes all management events, and all data events for all Amazon S3 buckets and AWS Lambda functions in the AWS account.

aws cloudtrail put-event-selectors \
    --trail-name TrailName2 \
    --event-selectors '[{"ReadWriteType": "All","IncludeManagementEvents": true,"DataResources": [{"Type":"AWS::S3::Object", "Values": ["arn:aws:s3"]},{"Type": "AWS::Lambda::Function","Values": ["arn:aws:lambda"]}]}]'

Output:

{
    "EventSelectors": [
        {
            "IncludeManagementEvents": true,
            "DataResources": [
                {
                    "Values": [
                        "arn:aws:s3"
                    ],
                    "Type": "AWS::S3::Object"
                },
                {
                    "Values": [
                        "arn:aws:lambda"
                    ],
                    "Type": "AWS::Lambda::Function"
                }
            ],
            "ReadWriteType": "All"
        }
    ],
    "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/TrailName2"
}

For more information, see Log events by using basic event selectors in the AWS CloudTrail User Guide.

The following code example shows how to use remove-tags.

AWS CLI

To remove tags for a trail

The following remove-tags example removes the specified tags for Trail1.

aws cloudtrail remove-tags \
    --resource-id arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1 \
    --tags-list Key=name Key=location

This command produces no output.

For more information, see Managing trails with the AWS CLI in the AWS CloudTrail User Guide.

  • For API details, see RemoveTags in AWS CLI Command Reference.

The following code example shows how to use start-logging.

AWS CLI

To start logging for a trail

The following start-logging example turns on logging for Trail1.

aws cloudtrail start-logging \
    --name Trail1

This command produces no output.

For more information, see Managing trails with the AWS CLI in the AWS CloudTrail User Guide.

  • For API details, see StartLogging in AWS CLI Command Reference.

The following code example shows how to use stop-logging.

AWS CLI

To stop logging a trail

The following stop-logging example turns off logging for Trail1.

aws cloudtrail stop-logging \
    --name Trail1

This command produces no output.

For more information, see Turning off logging for a trail in the AWS CloudTrail User Guide.

  • For API details, see StopLogging in AWS CLI Command Reference.

The following code example shows how to use update-trail.

AWS CLI

To update a trail

The following update-trail example updates a trail to use an existing bucket for log delivery.

aws cloudtrail update-trail \
    --name Trail1 \
    --s3-bucket-name amzn-s3-demo-bucket

Output:

{
    "IncludeGlobalServiceEvents": true,
    "Name": "Trail1",
    "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1",
    "LogFileValidationEnabled": false,
    "IsMultiRegionTrail": true,
    "S3BucketName": "amzn-s3-demo-bucket"
}

For more information, see Using the update-trail command to update a trail in the AWS CloudTrail User Guide.

  • For API details, see UpdateTrail in AWS CLI Command Reference.

The following code example shows how to use validate-logs.

AWS CLI

To validate a log file

The following validate-logs example validates the logs for Trail1.

aws cloudtrail validate-logs \
    --trail-arn arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1 \
    --start-time 20160129T19:00:00Z

Output:

Validating log files for trail arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail1 between 2016-01-29T19:00:00Z and 2016-01-29T22:15:43Z
Results requested for 2016-01-29T19:00:00Z to 2016-01-29T22:15:43Z
Results found for 2016-01-29T19:24:57Z to 2016-01-29T21:24:57Z:
3/3 digest files valid
15/15 log files valid

For more information, see Validating CloudTrail log file integrity with the AWS CLI in the AWS CloudTrail User Guide.

  • For API details, see ValidateLogs in AWS CLI Command Reference.