How to Track Who Did What in Your MongoDB Database (Auditing Basics)

Database auditing is a cornerstone of enterprise security, providing the necessary traceability to meet global compliance standards like GDPR. This guide explores how to implement and optimize auditing in both MongoDB Atlas and self-managed Enterprise environments, ensuring comprehensive visibility into user activity without compromising cluster performance.

Database Auditing in MongoDB

• Knowing what happened to your data, when, and by whom is becoming a necessity. Whether you are building a small app or managing a global enterprise product, security goes through auditing to understand what is happening in your database.
• Without auditing, your database is a blind spot. If a sensitive collection is dropped or an unauthorized user attempts to access sensitive data, how do you trace it back? Relying solely on application logs can miss direct database access or inter-company bad actors.
• Regulatory frameworks like GDPR mandate the ability to prove the lawfulness of access to personal data.
• Auditing is about accountability and traceability. It allows organizations to reconstruct events, detect anomalies, and prove that security controls are working as intended.
• MongoDB provides a robust auditing framework that tracks activities. In this guide, we will focus on understanding and implementing these features within MongoDB.
• Database auditing is a feature available for MongoDB Atlas (M10+) and MongoDB Enterprise Edition for self-managed deployments.

Steps to Enable Auditing in MongoDB Atlas

• Ensure you are on a page of the project that contains the clusters you want to audit.
• In the side panel under the Security section, navigate to the Database & Network Access tab.
• Select Advanced in the side panel.
• Toggle Database Auditing to "On".
• Choose your Audit Filter (see below).
• Click Save.

Once enabled, MongoDB Atlas starts collecting audit events and stores them securely, separate from operational logs. Auditing is available only on M10+ clusters and may incur additional costs depending on log volume.

How to enable auditing on self-managed MongoDB servers

For self-managed deployments, you enable auditing via the configuration file (mongod.conf). This allows you to choose where logs are sent: the console, a JSON/BSON file, or the system syslog.

To enable file-based JSON auditing, add this to your configuration files in the nodes of your cluster:

auditLog:
 destination: file
 format: JSON
 path: /folder/auditLog.json

After making the change, restart the mongod services of each node, one at the time. You might want to set runtimeConfiguration too. Before restarting, see Configuring filters on self-managed MongoDB clusters.

What can (and should) you Audit?

What you should audit depends on what data you handle and your goals.

We can divide audits into three categories:

• Authentication: Track successful logins and, optionally, failed attempts to authenticate. Authentication logs are often the first indicator of a security incident. Multiple failed logins from a single IP can signal a brute-force attack.
• Administrative Actions: Those operations, such as creating indexes, dropping collections, or modifying users, are often audited. These are high-impact changes that affect the structure and security of your database.
• AuthChecks: Operations such as CRUDs can be tracked to know who read or modified specific documents.

Auditing everything can create a volume of logs difficult to read and cause a performance degradation. This is why we advise audit AuthChecks (CRUDs) sparingly. Logging every successful find or update on a high-traffic collection can significantly impact performance. Use it only for highly sensitive collections like user passwords or financial records. Remember that to add a further level of security on sensitive data, you can also use client-side field-level encryption (CSFLE).

Filtering Audit Logs

Auditing everything can create massive log files and overhead. Filtering allows you to capture only the "interesting" events, saving storage costs, making analysis easier, and saving your MongoDB instance's performance.

How to Configure Audit Filters in MongoDB Atlas

• To manage filters for a MongoDB Atlas cluster, navigate to your project's "Database Access" section, then select the "Advanced" tab. Locate the Auditing toggle and click the "Edit" button situated just below it to configure your auditing filters.
• In the section “Configure Your Auditing Filter,” the "Audit authentication failures" checkbox in the filter section enables logging of failed authentication attempts. Keeping this option enabled is generally recommended, as it allows you to identify malicious actors who tried but failed to gain access. For instance, in the event of a brute-force attack, the logs will show the duration and method of the attempted access.
• The first section allows you to select which users and roles will be audited. By default, all users and roles are audited, which is suitable for most scenarios. While you might occasionally want to audit only a specific user or role/group—for example, when inviting an external analyst—you might select only them. Leaving the default setting is generally recommended.
• The second section is where you decide which actions to audit. By default, all authentication attempts (the first item in the list) are logged, unless you have disabled logging for authentication failures in the checkbox above, in which case only successful logins will be recorded.
• Administrative actions are also logged by default and constitute most of the list, excluding the "AuthCheck" item. Auditing administrative actions is beneficial as it helps identify unauthorized operations, such as an analyst attempting to grant themselves the root role.
• We previously noted that AuthChecks (CRUDs) operations require careful consideration when auditing, as excessive logging can impact cluster performance and generate a large volume of audit logs. By default, only failed CRUD operations are logged.
• To specify which actions, users, and collections should be audited in detail, you can define them in a JSON using the "Use custom JSON filter" button.
• Under the JSON filter textbox, you will see a checkbox: “Audit authorization successes.” Activating this option will record successful AuthChecks (CRUDs). Further details are below in the section about the JSON filter.

Configuring Filters on Self-Managed MongoDB Clusters

For self-managed servers, there are two ways to filter audit events. The recommended approach is to define and modify the filter at runtime. Alternatively, you can set the filter in your configuration file, but this requires editing each configuration file and restarting the cluster nodes to make subsequent changes.

Runtime configuration (MongoDB 5.0+):

In the configuration file (mongod.conf), set auditLog.runtimeConfiguration: true:

auditLog:
  destination: file
  format: JSON
  path: /folder/auditLog.json
  runtimeConfiguration: true

After making the change, restart the mongod services of each node, one at a time.

From this moment on, to change the audit filter, use the following command from mongoshell:

db.adminCommand( { setClusterParameter: { auditConfig: <value> } } )

To view the current filter, use:

db.adminCommand( { getClusterParameter: "auditConfig" } )

If you want to audit also successful AuthChecks (CRUDs), use this command:

db.adminCommand( { setParameter: 1, auditAuthorizationSuccess: true } )

Static configuration

Define the filter in your configuration file (mongod.conf) using the filter field under auditLog:

auditLog:
  destination: file
  format: JSON
  path: /folder/auditLog.json
  filter: 'your filter'

After making the change and after any future change of the filter, restart the mongod services of each node, one at a time.

If you want to audit also successful AuthChecks (CRUDs), use this command in a connected mongoshell:

db.adminCommand( { setParameter: 1, auditAuthorizationSuccess: true } )

How JSON Filters Work (Both for MongoDB Atlas and Self-Managed MongoDB Clusters)

Whether you are on MongoDB Atlas or on-premises, the filter syntax is the same. The JSON filter contains MongoDB Query Language, like the one you use in find queries or aggregate $match stages. It operates on audit logs whose structure can be seen in the section Anatomy of an audit log entry.

For example, to log CRUD operations to the collection personalData of the database users, we defined this in the JSON filter:

{
  "atype": "authCheck", # Action type, CRUDs
  "param.ns": "users.personalData", # db.collection
  "param.command": { # specific commands to audit
    "$in": [
      "aggregate",
      "count",
      "distinct",
      "group",
      "mapReduce",
      "geoNear",
      "geoSearch",
      "eval",
      "find",
      "getLastError",
      "getMore",
      "getPrevError",
      "parallelCollectionScan",
      "delete",
      "findAndModify",
      "insert",
      "update",
      "resetError"
    ]
  }
}

A full list of filters can be found on the Configure Audit Filters MongoDB documentation page.

Steps to Download Audit Logs in MongoDB Atlas

To access your audit logs in MongoDB Atlas, simply:

1. Go to the Clusters view.
2. Click the ... (ellipsis) button next to your cluster and select Download Logs.
3. Choose audit logs from the first option menu, the server of interest, and the time period.
4. Click Download.

Note that logs are retained for 30 days.

Anatomy of an Audit Log Entry

A MongoDB audit log is a JSON object defined in the documentation page MongoDB Schema Audit Messages. An Open Cybersecurity Schema Framework (OCSF) can be used, but it is out of the scope of this guide.

Understanding the structure is key to troubleshooting and filtering.

The example below shows that the analyst has successfully accessed our personalData collection as they have access to all databases:

{
    "atype": "authCheck",
    "ts": {
        "$date": "2026-01-19T08:10:06.341+00:00"
    },
    //...
    "remote": {
        "ip": "104.30.162.12",
        "port": 76350
    },
    "users": [
        {
            "user": "analyst",
            "db": "admin"
        }
    ],
    "roles": [
        {
            "role": "readWriteAnyDatabase",
            "db": "admin"
        }
    ],
    "param": {
        "command": "find",
        "ns": "users.personalData",
        "args": {
            "find": "personalData",
            "filter": {},
            //...
        "$db": "users"
        }
    },
    "result": 0
}

Log Redaction (Privacy within Privacy)

The logs themselves can become a security risk. If a user runs a query containing a Social Security Number (SSN) or a password in plain text, that sensitive data might be recorded in the audit log.

Log redaction prevents this by masking the command and param fields in the audit output. When enabled, MongoDB replaces sensitive values with placeholders, ensuring that even if an attacker gains access to your logs, they cannot see the actual data being queried.

To activate it in MongoDB Atlas:

1. Go to your Clusters page.
2. Click the ... (three dots/More) button next to the cluster you want to configure and select Edit Configuration.
3. Scroll down to the bottom and expand the Additional Settings section.
4. Look for the More Configuration Options dropdown.
5. Find the toggle labeled Enable Log Redaction.
6. Click Review Changes and then Apply Changes.

Enabling this will trigger a rolling restart of your cluster as the configuration change is applied to each node.

The equivalent configuration for self-managed Enterprise clusters is:

security:

redactClientLogData: true

As we have explored, the goal is not to log every single operation, which can lead to performance bottlenecks and a huge amount of logs, but to capture high-value events that tell a clear story of your data's lifecycle. When configured correctly, it can transform a black box database into a compliant and transparent one.

Key Takeaways

• Focus on authentication, administrative (DDL), and highly sensitive AuthChecks (CRUD) to maintain high performance.
• Both MongoDB Atlas and on-premises use the same MQL-based syntax for filters, allowing for highly specific rules (like auditing a specific user or a single sensitive collection).
• MongoDB Atlas (M10+) offers a UI-driven approach with optional JSON configuration, while self-managed requires the Enterprise Edition and configuration via mongod.conf.
• For self-managed nodes (5.0+), enabling runtimeConfiguration allows you to update audit filters via the shell without a server restart.
• To ensure your logs don't become a liability, enable redaction to mask sensitive values in query parameters with log redaction.

Key Considerations for MongoDB Auditing

• Audit logging is not available in MongoDB Community Edition, it is supported only in MongoDB Atlas (M10 and above) and MongoDB Enterprise Edition.
• On self-managed servers, audit filters can be updated without downtime if runtimeConfiguration: true is enabled. This allows changes using the setClusterParameter command without restarting nodes.
• The performance impact of auditing depends on what you log. Tracking authentication and administrative actions has minimal overhead, while logging high-volume CRUD operations can significantly affect performance. Using targeted filters helps reduce this impact.
• In MongoDB Atlas, audit logs are retained for 30 days. For longer retention requirements, such as compliance needs, logs must be exported and stored in an external system.