AWS Secrets Manager
User Guide

Monitor the Use of Your AWS Secrets Manager Secrets

As a best practice, you should monitor your secrets to ensure that usage of your secrets and log any changes. . This helps you to ensure that any unexpected usage or change can be investigated, and unwanted changes can be rolled back. AWS Secrets Manager currently supports two AWS services, AWS CloudTrail and Amazon CloudWatch Events, enabling you to audit and monitor your secrets.

Logging AWS Secrets Manager API Calls with AWS CloudTrail

AWS Secrets Manager integrates with AWS CloudTrail, a service providing a record of actions taken by a user, role or an AWS service in Secrets Manager. CloudTrail captures all API calls for Secrets Manager as events, including calls from the Secrets Manager console and from code calls to the Secrets Manager APIs. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for Secrets Manager. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can determine the request made to Secrets Manager, the IP address where the request was made, who made the request, when it was made, and additional details.

To learn more about CloudTrail see the AWS CloudTrail User Guide.

Secrets Manager Information in CloudTrail

AWS enables CloudTrail when you create the account. When activity occurs in Secrets Manager, CloudTrail records the activity in a CloudTrail event along with other AWS service events in Event history. You can view, search, and download recent events in your AWS account. For more information, see Viewing Events with CloudTrail Event History.

For an ongoing record of events in your AWS account, including events for Secrets Manager, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see:

CloudTrail logs and documents all Secrets Manager actions in the AWS Secrets Manager API Reference. For example, calls to the CreateSecret, GetSecretValue and RotateSecret sections generate entries in the CloudTrail log files.

Every event or log entry contains information about who generated the request. The identity information helps you determine the following:

  • If the request was made with root or IAM user credentials.

  • If the request was made with temporary security credentials for a role or federated user.

  • If the request was made by another AWS service.

To receive notifications when CloudTrail delivers log files, you can configure CloudTrail to publish Amazon SNS notifications whenever new log files are delivered. For more information, see Configuring Amazon SNS Notifications for CloudTrail.

You can also aggregate AWS Secrets Manager log files from multiple AWS Regions and multiple AWS accounts into a single Amazon S3 bucket.

For more information, see Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail Log Files from Multiple Accounts.

Retrieving Secrets Manager Log File Entries

You can retrieve individual events from CloudTrail using any of the following techniques:

To retrieve Secrets Manager events from CloudTrail logs

Using the AWS Management ConsoleUsing the AWS CLI or SDK Operations
Using the AWS Management Console

The CloudTrail console enables you to view events that occurred within the past 90 days.

  1. Open the CloudTrail console at

  2. Ensure the console points at the Region where your events occurred. The console shows only those events that occurred in the selected Region. Choose the Region from the list in the upper-right of the console.

  3. In the left-hand navigation pane, choose Event history.

  4. Select Filter criteria and/or a Time range to help you find the event that you're looking for. For example, to see all Secrets Manager events, for Select attribute, select Event source. Then, for Enter event source, select

  5. To see additional details, choose the expand arrow next to event you want to view. To see all of available information , choose View event.

Using the AWS CLI or SDK Operations
  1. Open a command window to run AWS CLI commands.

  2. Run a command similar to the following example. The output is shown as word wrapped here for readability, but the real output isn't.

    $ aws cloudtrail lookup-events --region us-east-1 --lookup-attributes AttributeKey=EventSource, { "Events": [ { "EventId": "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE", "EventName": "CreateSecret", "EventTime": 1525106994.0, "Username": "Administrator", "Resources": [], "CloudTrailEvent": "{\"eventVersion\":\"1.05\",\"userIdentity\":{\"type\":\"IAMUser\",\"principalId\":\"AKIAIOSFODNN7EXAMPLE\", \"arn\":\"arn:aws:iam::123456789012:user/Administrator\",\"accountId\":\"123456789012\",\"accessKeyId\":\"AKIAIOSFODNN7EXAMPLE\", \"userName\":\"Administrator\"},\"eventTime\":\"2018-04-30T16:49:54Z\",\"eventSource\":\"\", \"eventName\":\"CreateSecret\",\"awsRegion\":\"us-east-1\",\"sourceIPAddress\":\"\", \"userAgent\":\"<useragent string>\",\"requestParameters\":{\"name\":\"MyTestSecret\", \"clientRequestToken\":\"EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE\"},\"responseElements\":null, \"requestID\":\"EXAMPLE3-90ab-cdef-fedc-ba987EXAMPLE\",\"eventID\":\"EXAMPLE4-90ab-cdef-fedc-ba987EXAMPLE\", \"eventType\":\"AwsApiCall\",\"recipientAccountId\":\"123456789012\"}" } ] }

Understanding Secrets Manager Log File Entries

Secrets Manager defines a trail as a configuration enabling delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order.

The following example shows a CloudTrail log entry for a sample CreateSecret call:

{ "eventVersion": "1.05", "userIdentity": { "type": "Root", "principalId": "123456789012", "arn": "arn:aws:iam::123456789012:root", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "myusername", "sessionContext": {"attributes": { "mfaAuthenticated": "false", "creationDate": "2018-04-03T17:43:50Z" }} }, "eventTime": "2018-04-03T17:50:55Z", "eventSource": "", "eventName": "CreateSecret", "awsRegion": "us-west-2", "requestParameters": { "name": "MyDatabaseSecret", "clientRequestToken": "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE" }, "responseElements": null, "requestID": "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE", "eventID": "EXAMPLE3-90ab-cdef-fedc-ba987EXAMPLE", "eventType": "AwsApiCall", "recipientAccountId": "123456789012" }

The following example shows a CloudTrail log entry for a sample DeleteSecret call:

{ "eventVersion": "1.05", "userIdentity": { "type": "Root", "principalId": "123456789012", "arn": "arn:aws:iam::123456789012:root", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "myusername", "sessionContext": {"attributes": { "mfaAuthenticated": "false", "creationDate": "2018-04-03T17:43:50Z" }} }, "eventTime": "2018-04-03T17:51:02Z", "eventSource": "", "eventName": "DeleteSecret", "awsRegion": "us-west-2", "requestParameters": { "recoveryWindowInDays": 30, "secretId": "MyDatabaseSecret" }, "responseElements": { "name": "MyDatabaseSecret", "deletionDate": "May 3, 2018 5:51:02 PM", "aRN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyDatabaseSecret-a1b2c3" }, "requestID": "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE", "eventID": "EXAMPLE3-90ab-cdef-fedc-ba987EXAMPLE", "eventType": "AwsApiCall", "recipientAccountId": "123456789012" }

Amazon CloudWatch Events

Secrets Manager can work with CloudWatch Events to trigger alerts when administrator-specified operations occur in an organization. For example, because of the sensitivity of such operations, administrators might want to be warned when a secret deletes or when a secret rotates. You might want to create an alert if anyone tries to use a secret version while in its waiting period to be deleted. You can configure CloudWatch Events rules that look for these operations and then send the generated events to administrator defined "targets". A target could be an Amazon SNS topic that emails or text messages subscribers. You can also create a simple AWS Lambda function triggered by the event, which logs the details of the operation for your later review.

To learn more about CloudWatch Events, including how to configure and enable it, see the Amazon CloudWatch Events User Guide.

Monitoring Secret Versions Scheduled for Deletion

You can use a combination of AWS CloudTrail, Amazon CloudWatch Logs, and Amazon Simple Notification Service (Amazon SNS) to create an alarm that notifies you of any attempts to access a version of a secret pending deletion. If you receive a notification from such an alarm, you might want to cancel deletion of the secret to give yourself more time to determine whether you really want to delete it. Your investigation might result in restoring the secret because you really need it. Alternatively, you might need to update the user with details of the new secret that they really should be using.

The following procedures explain how to receive a notification when a request for the GetSecretValue operation that causes Secrets Manager to write specific error message to your CloudTrail log files. Other API operations can be performed on the version of the secret without triggering the alarm. The CloudWatch alarm detects usage that might indicate that a person or application is still trying to use invalid credentials

Before you begin these procedures, you must enable on CloudTrail in the AWS Region and account where you intend to monitor AWS Secrets ManagerAPI requests. For instructions, go to Creating a Trail for the First Time in the AWS CloudTrail User Guide.

Part 1: Configuring CloudTrail Log File Delivery to CloudWatch Logs

You must configure delivery of your CloudTrail log files to CloudWatch Logs. You do this so CloudWatch Logs can monitor them for Secrets Manager API requests to retrieve a version of a secret pending deletion.

To configure CloudTrail log file delivery to CloudWatch Logs

  1. Open the CloudTrail console at

  2. On the top navigation bar, choose the AWS Region where you want to monitor secrets.

  3. In the left navigation pane, choose Trails, and then choose the name of the trail to configure for CloudWatch.

  4. On the Trails Configuration page, scroll down to the CloudWatch Logs section, and then choose the Edit icon ( ).

  5. For New or existing log group, enter a name for the log group, such as CloudTrail/MyCloudWatchLogGroup.

  6. For the IAM role, you can use the default role called CloudTrail_CloudWatchLogs_Role. T role has a default role policy with the required permissions to deliver CloudTrail events to the log group.

  7. Choose Continue to save your configuration.

  8. On the AWS CloudTrail will deliver CloudTrail events associated with API activity in your account to your CloudWatch Logs log group page, choose Allow.

Part 2: Creating the CloudWatch Alarm

To receive a notification when a Secrets Manager GetSecretValue API operation requests to access a version of a secret pending deletion, you must create a CloudWatch alarm and configure notification.

To create a CloudWatch alarm to monitor the usage of a version of a secret pending deletion

  1. Sign in to the CloudWatch console at

  2. On the top navigation bar, choose the AWS Region to monitor secrets.

  3. In the left navigation pane, choose Logs.

  4. In the list of Log Groups, select the check box next to the log group you created in the previous procedure, such as CloudTrail/MyCloudWatchLogGroup. Then choose Create Metric Filter.

  5. For Filter Pattern, type or paste the following:

    { $.eventName = "GetSecretValue" && $.errorMessage = "*secret because it was deleted*" }

    Choose Assign Metric.

  6. On the Create Metric Filter and Assign a Metric page, perform the following steps:

    1. For Metric Namespace, type CloudTrailLogMetrics.

    2. For Metric Name, type AttemptsToAccessDeletedSecrets.

    3. Choose Show advanced metric settings, and then if necessary for Metric Value, type 1.

    4. Choose Create Filter.

  7. In the filter box, choose Create Alarm.

  8. In the Create Alarm window, do the following:

    1. For Name, type AttemptsToAccessDeletedSecretsAlarm.

    2. Whenever:, for is:, choose >=, and then type 1.

    3. Next to Send notification to:, perform one of the following options:

      • To create and use a new Amazon SNS topic, choose New list, and then type a new topic name. For Email list:, enter at least one email address. You can enter more than one email address by separating them with commas.

      • To use an existing Amazon SNS topic, choose the name of the topic to use. If a list isn't available, choose Select list.

    4. Choose Create Alarm.

You have now completed configuring your alarm.. To test it, create a version of a secret and then schedule it for deletion. Then, try to retrieve the secret value. You'll shortly receive an email at the address configured in the alarm. It alerts you to the use of a secret version that's scheduled for deletion.