Configure a Custom Auditing Filter¶
On this page
This feature is not available for M0 free clusters, M2, and
M5 clusters. To learn more about which features are unavailable,
see Atlas M0 (Free Cluster), M2, and M5 Limitations.
Serverless instances are in preview and do not support this feature at this time. To learn more, see Serverless Instance Limitations.
Atlas supports specifying a JSON-formatted audit filter for customizing MongoDB Auditing.
Custom audit filters allow users to forgo the managed Atlas UI auditing filter builder in favor of hand-tailored granular control of event auditing. Atlas only checks that the custom filter uses valid JSON syntax, and does not validate or test the filter's functionality.
The audit filter document must resolve to a query that matches one or more fields in the audit event message. The filter document can use combinations of query operators and equality conditions to match the desired audit messages.
For a selection of example auditing filters, see Example Auditing Filters. For complete documentation on configuring MongoDB auditing filters, see Configure Audit Filter.
Atlas uses a rolling upgrade strategy for enabling or updating audit configuration settings across all clusters in the Atlas project. Rolling upgrades require at least one election per replica set.
For instructions on testing application resilience to replica set elections, see Test Failover. For more information on how Atlas provides high availability, see Atlas High Availability.
Procedure¶
Log in to your Atlas project.¶
In the Security section of the left navigation, click Advanced.¶
Toggle the button next to Database Auditing to On.¶
Select Use Custom JSON Filter.¶
Enter your audit filter into the text box.¶
Optional: Toggle Audit authorization successes.¶
Enabling Audit authorization successes can severely impact cluster performance. Enable this option with caution.
For audit filters specifying the
authCheck action type,
by default the
auditing system logs only authorization
failures for any specified param.command. Enabling
Audit authorization successes directs the auditing
system to also log authorization successes. For more information,
see auditAuthorizationSuccess
Click Save.¶
Edit a Custom Auditing Filter¶
You can edit your filter at any time:
- In the Security section of the left navigation, click Advanced.
- Under Database Auditing Configure Your Auditing Filter, click Use Custom JSON Filter.
- Make the required changes.
- Click Save.
Example Auditing Filters¶
Use the following example auditing filters for guidance in constructing your own filters.
These examples are not intended for use in production environments, nor are they a replacement for familiarity with the MongoDB Auditing Documentation.
Audit all authentication events for known users¶
{ "atype": "authenticate" }
Audit all authentication events for known users and authentication failures for unknown users¶
{ "$or": [ { "users": [] }, { "atype": "authenticate" } ] }
The authenticate action is required to log authentication
failures from known and unknown users.
Audit authentication events for the "myClusterAdministrator" user¶
{ "atype": "authenticate", "param": { "user": "myClusterAdministrator", "db": "admin", "mechanism": "SCRAM-SHA-1" } }
Audit unauthorized attempts at executing the selected commands¶
{ "atype": "authCheck", "param.command": { "$in": [ "insert", "update", "delete" ] } }