Guidance for Atlas Auditing and Logging

To monitor and log Atlas platform activities, use auditing and logs.

Features for Atlas Auditing and Logging

Auditing

Available on M10+ clusters, database auditing lets you track system activity for deployments with multiple users. As an Atlas administrator, you can:

Rely on default auditing settings in Atlas. By default, Atlas performs database authentication auditing in M10+ clusters to record authentication events, including those pertaining to:
- database users
- source IP addresses
- timestamps for successful and failed attempts
Configure a JSON-formatted audit filter to customize MongoDB auditing and select the actions, database users, Atlas roles, and LDAP groups that you want to audit. If you create a custom audit filter, you can skip using the managed Atlas UI auditing filter builder and configure your own tailored filter of event auditing. For a full list of events you can configure for auditing, and for a list of examples, see MongoDB auditing and Example Auditing Filters.
You can configure manual auditing of most of the documented system event actions in Atlas. Granular MongoDB database auditing allows you to track usage of all DDL (Data Definition Language), DML (Data Manipulation Language), and DCL (Data Control Language) commands in detail. See also Set up Database Auditing.

Accessing Audit Logs

You can use the Atlas CLI, Atlas Administration API, or Atlas UI for the following auditing activities:

View and download audit logs to track system event actions for deployments with multiple users. Atlas administrators can configure a custom auditing filter to choose the actions, database users, Atlas roles, and LDAP groups that they want to audit.
View and download MongoDB logs to track log events for your deployment, including incoming connections, commands run, and issues encountered. Generally, log messages are useful for diagnosing issues, monitoring your deployment, and tuning performance.
View project and organization events in the Project Activity Feed and Organization Activity Feed. These activity feeds list all events at the organization or project level, including changes related to Atlas access, alert configurations and monitoring, billing, and more.
View database authentication attempts that users make against your cluster in your access logs (i.e. Database access history in the Atlas UI). Atlas logs both successful and unsuccessful authentication attempts, including the timestamp of each attempt and which user tried to authenticate.

Programmatic Access to Audit Logs

To integrate with tools beyond the built-in integrations, we recommend that you retrieve logs with the following programmatic tools and feed the JSON-formatted output to your external tools:

To continually push logs to an AWS S3 bucket, use the Atlas Administration API endpoints for Push-Based Log Export.
To retrieve deployment logs and lists of project events, use the Atlas Administration API endpoints for Monitoring and Logs and Project and Organization Events.
To retrieve deployment logs, use the atlas deployment logs command in the Atlas CLI.

Recommendations for Atlas Auditing and Logging

Single-Region Deployment Recommendations

Recommendations that apply only to deployments in a single region

Singe-region deployments have no unique considerations for auditing and logging. See the next section for "All Deployment Paradigm Recommendations".

Multi-Region and Multi-Cloud Deployment Recommendations

Recommendations that apply only to deployments across multiple regions or multiple cloud providers

Multi-region and multi-cloud deployments have no unique considerations for auditing and logging. See the next section for "All Deployment Paradigm Recommendations".

All Deployment Paradigm Recommendations

The following recommendations apply to all deployment paradigms.

We recommend that you set up database auditing when you provision your clusters. To perform a full audit, you can use a combination of audit logs, MongoDB log messages, and the project and organization activity feed.

Auditing puts additional load on your clusters and increases costs. To optimize cluster performance and minimize costs, we recommend that you limit the number of users that you audit, and disable auditing in development environments. Certain industries, such as healthcare and financial services, may opt to keep auditing enabled in development environments for compliance reasons.

We recommend that you audit the following events at a minimum:

Failed logon
Session activity
Logon and logoff
Attempts to perform unauthorized functions
Password change
Database User Access changes
DDL & System configuration stored procedures
Modification of Native audit
Running a backup or restore operation
Altering DBMS native audit settings
Altering security
Running database start and stop commands

By default, audit log messages are returned in a format designed by MongoDB, called the mongo schema. Audit log messages that follow the mongo schema always include the following information:

Action type (atype)
Timestamp
Client connection ID (UUID)
Client IP address and port number
Incoming connection IP address and port numbe
Username(s)
User authentication database(s)
User role(s)
User role database(s)
param document containing specific details for the event
Result value or error code

For a full list of audit action types and their associated param details and result values, see mongo Schema Audit Messages.

Automation Examples: Atlas Auditing and Logging

The following examples show how to retrieve and download logs and configure auditing using Atlas tools for automation.

In addition to the following examples, see the blogpost Streamlining Log Management to Amazon S3 Using Atlas Push-based Log Exports With HashiCorp Terraform.

Create and Enable Filter

The following document defines an audit filter that restricts audits to only the authentication operations that occur against the test database. To learn more, see Configure Audit Filters.

{ "atype": "authenticate", "param.db": "test" }

To enable an audit filter, run the atlas auditing update command with the --enabled flag and specify the audit filter document in single quotes to pass the document as a string:

atlas auditing update --enabled --auditFilter '{"atype": "authenticate", "param.db": "test"}'

The following Atlas CLI command enables an audit filter that is defined in the specified JSON configuration file:

atlas auditing update --enabled -f filter.json

Update Audit Configuration

To update your project's audit configuration, use the atlas auditing update command and specify the new audit filter. The following command replaces the existing audit filter configuration with a new filter that audits all authentication events for known users in the project:

atlas auditing update --enabled --auditFilter '{"atype": "authenticate"}'

Describe Audit Configuration

Run the atlas auditing describe command to return the auditing configuration for the specified project:

atlas auditing describe --output json

Retrieve Logs

Each mongod and mongos instance in a cluster outputs its own MongoDB log and audit log messages with potentially different contents than other instances. You can view these log messages in the Atlas CLI using the atlas deployment logs command.

To retrieve audit log entries for a mongod instance in your cluster, provide the mongod hostname and specify mongodb-audit-log.gz as the name of the audit log file:

atlas deployments logs --output json --type atlas --hostname cluster0-shard-00-00.a1b2c.mongodb.net --name mongodb-audit-log.gz

To retrieve audit log entries for a mongos instance in a sharded cluster deployment, provide the mongos hostname and specify mongos-audit-log.gz as the name of the audit log file:

atlas deployments logs --output json --type atlas --hostname cluster0-shard-00-00.a1b2c.mongodb.net --name mongos-audit-log.gz

To retrieve MongoDB log messages, provide the hostname of your mongod or mongos instance, and specify the name of the log file as mongodb.gz or mongos.gz, respectively:

atlas deployments logs --output json --type atlas --hostname cluster0-shard-00-00.a1b2c.mongodb.net --name mongodb.gz

You can also use the atlas accessLogs list command to view the access log for a node or cluster. The access log is a JSON-formatted list of all authentication requests against your specified node or cluster. To retrieve the access log, run the atlas accessLogs list command and specify the hostname or cluster name of the target node or cluster:

atlas accessLogs list --output json --clusterName Cluster0

Download Logs

Each mongod and mongos instance in a cluster has its own MongoDB log and audit log with potentially different contents than other instances. You can download each log as a compressed file using the atlas logs download Atlas CLI command.

To download the audit log for a mongod instance in your cluster, provide the mongod hostname and the audit log file name mongodb-auditlog.gz as arguments:

atlas logs download cluster0-shard-00-00.a1b2c.mongodb.net mongodb-audit-log.gz

To download the audit log for a mongos instance in a sharded cluster deployment, provide the mongos hostname and the audit log file name mongos-auditlog.gz as arguments:

atlas logs download cluster0-shard-00-00.a1b2c.mongodb.net mongos-audit-log.gz

To download the MongoDB log for a mongod or mongos instance, provide as arguments the hostname of the instance and the log file names mongodb.gz or mongos.gz, respectively:

atlas logs download cluster0-shard-00-00.a1b2c.mongodb.net mongodb.gz

Retrieve All Project Alerts

You can use the following Atlas CLI commands to return alerts triggered by events for your project or organization. Atlas provides alerts such as Replica set has no primary and User joined the project by default. These events provide a record of significant activities and changes within the project or organization, including significant database, billing, or security activities or status changes. To customize which events trigger alerts for your project and organization, see Configure Alert Settings.

Retrieve All Log Events for Your Project or Organization

You can use the following Atlas CLI commands to return project or organization events from your Project Activity Feed or Organization Activity Feed. Replica set has no primary and User joined the project by default.

To return all events for your organization, use the atlas events organizations list command and specify your organization ID. The following command returns a JSON-formatted list of events for the organization with the ID 5dd5a6b6f10fab1d71a58495:

atlas events organizations list --orgId 5dd5a6b6f10fab1d71a58495 --output json

To return all events for your project, use the atlas events projects list command and specify your project ID. The following command returns a JSON-formatted list of events for the project with the ID 64ac57bfe9810c0263e9d655:

atlas events organizations list --orgId 5dd5a6b6f10fab1d71a58495 --output json

Retrieve All Project Alerts

Retrieve All Log Events for Your Project or Organization

atlas events organizations list --orgId 5dd5a6b6f10fab1d71a58495 --output json

atlas events organizations list --orgId 5dd5a6b6f10fab1d71a58495 --output json

The following example demonstrates how to enable auditing for your deployment. Before you can create resources with Terraform, you must:

Create your paying organization and create an API key for the paying organization. Store your public and private keys as environment variables by running the following commands in the terminal:
```
export MONGODB_ATLAS_PUBLIC_KEY="<insert your public key here>"
export MONGODB_ATLAS_PRIVATE_KEY="<insert your private key here>"
```
Install Terraform.

Enable Auditing and Create an Auditing Filter for the Cluster

You can configure manual auditing of most of the documented system event actions by creating audit filters. To learn more about configuring audit filters, see Configure Audit Filters.

# Create a project
resource "mongodbatlas_project" "project_test" {
  name   = var.project_name
  org_id = var.org_id
}
# Create a cluster with three nodes
resource "mongodbatlas_advanced_cluster" "cluster_test" {
  project_id   = mongodbatlas_project.project_test.id
  name         = var.cluster_name
  cluster_type = "REPLICASET"
  replication_specs {
    region_configs {
      priority      = 7
      provider_name = "AWS"
      region_name   = "US_EAST_1"
      electable_specs {
        instance_size = "M10"
        node_count    = 3
      }
    }
  }
}
# Specify an auditing resource and enable auditing for a project.
# To configure auditing, specify the unique project ID. If you change
# this value to a different "project_id", this deletes the current audit
# settings for the original project.
# "audit_authorization_success" indicates whether the auditing system
# captures successful authentication attempts for audit filters using
# the "atype" : "authCheck" auditing event. Warning! If you set
# "audit_authorization_success" to "true", this can severely impact
# cluster performance. Enable this option with caution.
# "audit_filter" is the JSON-formatted audit filter.
# "enabled" denotes whether or not the project associated with the
# specified "{project_id}"" has database auditing enabled. Defaults to "false".
# Auditing created by API Keys must belong to an existing organization.
# In addition to arguments listed previously, the following attributes
# are exported:
# "configuration_type" denotes the configuration method for the audit filter.
# Possible values are:
# - "NONE" - auditing is not configured for the project.
# - "FILTER_BUILDER" - auditing is configured via the Atlas UI filter builder.
# - "FILTER_JSON" - auditing is configured via a custom filter in Atlas or API.
resource "mongodbatlas_auditing" "test" {
     project_id                  = "mongodbatlas_project.project_test.id"
     audit_filter                = "{ 'atype': 'authenticate', 'param': {   'user': 'auditAdmin',   'db': 'admin',   'mechanism': 'SCRAM-SHA-1' }}"
     audit_authorization_success = false
     enabled                     = true
 }

Retrieve Logs

You can't retrieve logs with Terraform. Instead, use the following Atlas Administration API endpoints:

Use Access Tracking Admin API to return access logs for all authentication attempts for the database, identified by the cluster's name or hostname.
Use Monitoring and Logs APIs to retrieve a compressed log file with log messages for the specified host.

Back

Compliance

Reliability