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 use this feature.
When auditing is enabled, Amazon DocumentDB records Data Definition Language (DDL), Data Manipulation Language (DML), 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:
-
Data Definition Language (DDL) - includes database management operations, connections, user management, and authorization.
-
Data Manipulation Language read events (DML reads) - includes
find()
and the various aggregation operators, arithmetic operators, boolean operators, and other read query operators. -
Data Manipulation Language write events (DML writes) - includes
insert(), update(), delete(),
andbulkWrite()
operators
The event types are as follows.
Event Type | Category | Description |
---|---|---|
authCheck |
Authorization | Result code 0: Success |
Result code 13: Unauthorized attempts to perform an operation. | ||
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. |
modifyChangeStreams |
DDL | Change stream was created. |
renameCollection |
DDL | Renaming of a collection within a database. |
createRole |
Role Management | Creating a role. |
dropAllRolesFromDatabase |
Role Management | Dropping all roles within a database. |
dropRole |
Role Management | Dropping a role. |
grantPrivilegesToRole |
Role Management | Granting privileges to a role. |
grantRolesToRole |
Role Management | Granting roles to a user-defined role. |
revokePrivilegesFromRole |
Role Management | Revoking privileges from a role. |
revokeRolesFromRole |
Role Management | Revoking roles from a user-defined role. |
updateRole |
Role Management | Updating a role. |
createUser |
User Management | Creation of a new user. |
dropAllUsersFromDatabase |
User Management | Dropping of all users within a database. |
dropUser |
User Management | Dropping of an existing user. |
grantRolesToUser |
User Management | Granting roles to a user. |
revokeRolesFromUser |
User Management | Revoking roles from a user. |
updateUser |
UserManagement | Updating of an existing user. |
insert |
DML write | Inserts a document or documents into a collection. |
delete |
DML write | Deletes a document or documents from a collection. |
update |
DML write | Modifies an existing document or documents in a collection. |
bulkWrite |
DML write | Performs multiple write operations with controls for order of execution. |
count |
DML read | Returns the count of documents that would match a find() query for the collection or view. |
countDocuments |
DML read | Returns the count of documents that match the query for a collection or view. |
find |
DML read | Selects documents in a collection or view and returns a cursor to the selected documents. |
findAndModify |
DML read and DML write | Modifies and returns a single document. |
findOneAndDelete |
DML read and DML write | Deletes a single document based on the filter and sort criteria, returning the deleted document. |
findOneAndReplace |
DML read and DML write | Replaces a single document based on the specified filter. |
findOneAndUpdate |
DML read and DML write | Updates a single document based on the filter and sort criteria. |
aggregate |
DML read and DML write | Supports APIs in the aggregation pipeline. |
distinct |
DML read | Finds the distinct values for a specified field across a single collection or view and returns the results in an array. |
Note
Values in the DML event document parameter field have a 1KB size limit. Amazon DocumentDB truncates the value if it exceeds 1KB.
Note
TTL delete events are not audited at this time.
Enabling Auditing
Enabling auditing on a cluster is a two-step process. Ensure that both steps are completed, or audit logs will not be sent to CloudWatch Logs.
Step 1. Enable the audit_logs cluster parameter
To enable auditing, you need to modify the audit_logs
parameter in the parameter group.
audit_logs
is a comma-delimited list of events to log. Events must be specified in lowercase and there should be no white space
between the list elements.
You can set the following values for the parameter group:
Value | Description |
---|---|
ddl |
Setting this will enable auditing for DDL events such as createDatabase, dropDatabase, createCollection, dropCollection, createIndex, dropIndex, authCheck, authenticate, createUser, dropUser, grantRolesToUser, revokeRolesFromUser, updateUser, and dropAllUsersFromDatabase |
dml_read |
Setting this will enable auditng for DML read events such as find, sort count, distinct, group, projecta, unwind, geoNear, geoIntersects, geoWithin and other MongoDB read query operators. |
dml_write |
Setting this will enable auditing for DML write events such as insert(), update(), delete(), and bulkWrite() |
all |
Setting this will enable auditing for your database events, such as read queries, write queries, database actions and administrator actions. |
none |
Setting this will disable auditing |
enabled (legacy) |
This is a legacy parameter setting that is equivalent to 'ddl'. Setting this will enable auditing for DDL events such as createDatabase, dropDatabase, createCollection, dropCollection, createIndex, dropIndex, authCheck, authenticate, createUser, dropUser, grantRolesToUser, revokeRolesFromUser, updateUser, and dropAllUsersFromDatabase. We do not recommend using this setting because it is a legacy setting. |
disabled (legacy) |
This is a legacy parameter setting that is equivalent to 'none'. We do not recommend using this setting because it is a legacy setting. |
You can also use the above mentioned values in combinations.
Value | Description |
---|---|
ddl, dml_read |
Setting this will enable auding for DDL events and DML read events. |
ddl, dml_write |
Setting this will enable auding for DDL events and DML write |
dml_read, dml_write |
Setting this will enable auditing for all DML events |
Note
You cannot modify a default parameter group.
For more information, see the following:
-
Creating Amazon DocumentDB cluster parameter groups
After creating a custom parameter group, modify it by changing the
audit_logs
parameter value toenabled
.
Step 2. Enable Amazon CloudWatch Logs Export
When the value of the audit_logs
cluster parameter is enabled
, ddl
, dml_read
, or dml_write
, 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.
Disabling Auditing
You can disable auditing 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.
Disabling the audit_logs Parameter
To disable the audit_logs
parameter for your cluster, you can modify the
cluster so that it uses a parameter group where the audit_logs
parameter
value is disabled
. Or you can modify the audit_logs
parameter
value in the cluster's parameter group so that it is disabled
.
For more information, see the following topics:
Accessing Your Audit Events
Use following steps to access your audit events on Amazon CloudWatch.
Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/
. -
Make sure that you are in the same Region as your Amazon DocumentDB cluster.
-
In the navigation pane, choose Logs.
-
To find the audit logs for your cluster, from the list locate and choose
/aws/docdb/
.yourClusterName
/auditThe auditing events for each of your instances are available under each of the respective instance names.