Amazon DocumentDB
Developer Guide

Auditing Amazon DocumentDB Events

With Amazon DocumentDB (with MongoDB compatibility), you can audit events that were performed in your cluster. Examples of logged events include successful and failed authentication attempts, dropping a collection in a database, or creating an index. By default, auditing is disabled on Amazon DocumentDB and requires that you opt in to this feature.

When auditing is enabled, Amazon DocumentDB records Data Definition Language (DDL), authentication, authorization, and user management events to Amazon CloudWatch Logs. When auditing is enabled, Amazon DocumentDB exports your cluster’s auditing records (JSON documents) to Amazon CloudWatch Logs. You can use Amazon CloudWatch Logs to analyze, monitor, and archive your Amazon DocumentDB auditing events.

Although Amazon DocumentDB does not charge an additional cost to enable auditing, you are charged standard rates for the usage of CloudWatch Logs. For information about CloudWatch Logs pricing, see Amazon CloudWatch Pricing.

The Amazon DocumentDB auditing feature is distinctly different from the service resource usage that is monitored with AWS CloudTrail. CloudTrail records operations that are performed with the AWS Command Line Interface (AWS CLI) or AWS Management Console on resources like clusters, instances, parameter groups, and snapshots. Auditing of AWS resources with CloudTrail is on by default and cannot be disabled. The Amazon DocumentDB auditing feature is an opt-in feature. It records operations that take place within your cluster on objects, such as databases, collections, indexes, and users.

Supported Events

Amazon DocumentDB auditing supports the following event categories: connection, data definition language (DDL), user management, and authorization. The event types are as follows.

Event Type Category Description
authenticate Connection Successful or failed authentication attempts on a new connection.
createDatabase DDL Creation of a new database.
createCollection DDL Creation of a new collection within a database.
createIndex DDL Creation of a new index within a collection.
dropCollection DDL Dropping of a collection within a database.
dropDatabase DDL Dropping of a database.
dropIndex DDL Dropping of an index within a collection.
createUser User Management Creation of a new user.
dropUser User Management Dropping of an existing user.
updateUser UserManagement Updating of an existing user.
dropAllUsersFromDatabase User Management Dropping of all users within a database.
authCheck Authorization Unauthorized attempts to perform an operation.

Enabling Auditing

Enabling auditing on a cluster is a two-step process. Ensure that both steps are completed, or auditing will not be enabled.

Step 1. Enable the audit_logs Cluster Parameter

To enable the audit_logs cluster parameter, you can create a new cluster parameter group with the audit_logs parameter value set to enabled. Or, you can modify an existing parameter group's audit_logs parameter so that its value is enabled. You cannot modify a default parameter group.

For more information, see:

Step 2. Enable Amazon CloudWatch Logs Export

When the value of the audit_logs cluster parameter is enabled, you must also enable Amazon DocumentDB to export logs to Amazon CloudWatch. If you omit either of these steps, audit logs will not be sent to CloudWatch.

When creating a cluster, performing a point-in-time-restore, or restoring a snapshot, you can enable CloudWatch Logs by following these steps.

Using the AWS Management Console

See the following to enable Amazon DocumentDB exporting logs to CloudWatch.

Using the AWS CLI

When creating a new cluster

The following code creates the cluster sample-cluster and enables CloudWatch audit logs.

For Linux, macOS, or Unix:

aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --port 27017 \ --engine docdb \ --master-username master-username \ --master-user-password password \ --db-subnet-group-name default \ --enable-cloudwatch-logs-exports audit

For Windows:

aws docdb create-db-cluster ^ --db-cluster-identifier sample-cluster ^ --port 27017 ^ --engine docdb ^ --master-username master-username ^ --master-user-password password ^ --db-subnet-group-name default ^ --enable-cloudwatch-logs-exports audit

When modifying an existing cluster

The following code modifies the cluster sample-cluster and enables CloudWatch audit logs.

For Linux, macOS, or Unix:

aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --cloudwatch-logs-export-configuration '{"EnableLogTypes":["audit"]}'

For Windows:

aws docdb modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --cloudwatch-logs-export-configuration '{"EnableLogTypes":["audit"]}'

Output from these operations looks something like the following (JSON format).

{ "DBCluster": { "HostedZoneId": "ZNKXH85TT8WVW", "StorageEncrypted": false, "DBClusterParameterGroup": "default.docdb3.6", "MasterUsername": "<user-name>", "BackupRetentionPeriod": 1, "Port": 27017, "VpcSecurityGroups": [ { "Status": "active", "VpcSecurityGroupId": "sg-77186e0d" } ], "DBClusterArn": "arn:aws:rds:us-east-1:900083794985:cluster:sample-cluster", "Status": "creating", "Engine": "docdb", "EngineVersion": "3.6.0", "MultiAZ": false, "AvailabilityZones": [ "us-east-1a", "us-east-1c", "us-east-1f" ], "DBSubnetGroup": "default", "DBClusterMembers": [], "ReaderEndpoint": "sample-cluster.cluster-ro-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "EnabledCloudwatchLogsExports": [ "audit" ], "PreferredMaintenanceWindow": "wed:03:08-wed:03:38", "AssociatedRoles": [], "ClusterCreateTime": "2019-02-13T16:35:04.756Z", "DbClusterResourceId": "cluster-YOS52CUXGDTNKDQ7DH72I4LED4", "Endpoint": "sample-cluster.cluster-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "PreferredBackupWindow": "07:16-07:46", "DBClusterIdentifier": "sample-cluster" } }

Disabling Auditing

Disabling auditing is done by disabling CloudWatch Logs export and disabling the audit_logs parameter.

Disabling CloudWatch Logs Export

You can disable exporting audit logs using either the AWS Management Console or the AWS CLI.

Using the AWS Management Console

The following procedure uses the AWS Management Console to disable Amazon DocumentDB exporting logs to CloudWatch.

  1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

  2. From the navigation pane, choose Clusters then choose the button to the left of the name of the cluster for which you want to disable exporting logs.

  3. From the Actions menu, choose Modify.

  4. Scroll down to the Log exports section and choose Disabled.

  5. Choose Continue.

  6. Review your changes then choose when you want this change applied to your cluster.

    • Apply during the next scheduled maintenance window

    • Apply immediately

  7. Choose Modify cluster.

Using the AWS CLI

The following code modifies the cluster sample-cluster and disables CloudWatch audit logs.

For Linux, macOS, or Unix:

aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["audit"]}'

For Windows:

aws docdb modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --cloudwatch-logs-export-configuration '{"DisableLogTypes":["audit"]}'

Output from this operation looks something like the following (JSON format).

{ "DBCluster": { "DBClusterParameterGroup": "default.docdb3.6", "HostedZoneId": "ZNKXH85TT8WVW", "MasterUsername": "<user-name>", "Status": "available", "Engine": "docdb", "Port": 27017, "AvailabilityZones": [ "us-east-1a", "us-east-1c", "us-east-1f" ], "EarliestRestorableTime": "2019-02-13T16:35:50.387Z", "DBSubnetGroup": "default", "LatestRestorableTime": "2019-02-13T16:35:50.387Z", "DBClusterArn": "arn:aws:rds:us-east-1:900083794985:cluster:sample-cluster2", "Endpoint": "sample-cluster2.cluster-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "ReaderEndpoint": "sample-cluster2.cluster-ro-corcjozrlsfc.us-east-1.docdb.amazonaws.com", "BackupRetentionPeriod": 1, "EngineVersion": "3.6.0", "MultiAZ": false, "ClusterCreateTime": "2019-02-13T16:35:04.756Z", "DBClusterIdentifier": "sample-cluster2", "AssociatedRoles": [], "PreferredBackupWindow": "07:16-07:46", "DbClusterResourceId": "cluster-YOS52CUXGDTNKDQ7DH72I4LED4", "StorageEncrypted": false, "PreferredMaintenanceWindow": "wed:03:08-wed:03:38", "DBClusterMembers": [], "VpcSecurityGroups": [ { "Status": "active", "VpcSecurityGroupId": "sg-77186e0d" } ] } }

Disabling the audit_logs Parameter

To disable the audit_logs parameter for your cluster, you can modify the cluster so it uses a parameter group where the audit_logs parameter value is disabled, or modify the audit_logs parameter value in the cluster's parameter group so it is disabled.

For more information, see:

Accessing Your Audit Events

Use following steps to access your audit events on Amazon CloudWatch.

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. Make sure that you are in the same Region as your Amazon DocumentDB cluster.

  3. In the navigation pane, choose Logs.

  4. To find the audit logs for your cluster, from the list locate and choose /aws/docdb/yourClusterName/audit.

    The auditing events for each of your instances are available under each of the respective instance names.