Guidance for Atlas Auditing and Logging

On this page

Features for Atlas Auditing and Logging
Auditing
Accessing Audit Logs
Recommendations for Atlas Auditing and Logging
Programmatic Access to Audit Logs
Automation Examples: 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

Atlas retains the last 30 days of log messages and system event audit messages. You can download Atlas logs at any point until the end of their retention periods by using the Atlas UI, Atlas Administration API, and Atlas CLI.

To learn more, see View and Download MongoDB Logs.

You can review and update your auditing configuration per project. Use the following Atlas CLI commands:

atlas auditing describe returns the auditing configuration for the specified project.
atlas auditing update updates the auditing configuration for the specified project.

You can view authentication attempts that users make against your cluster with the Atlas CLI, Atlas Administration API, or Atlas UI. Atlas logs both successful and unsuccessful authentication attempts, including the timestamp of each attempt and which user tried to authenticate.

You can also view and filter the activity feed for an organization or project with the Atlas CLI, Atlas Administration API, or Atlas UI. The activity feed lists all events at the organization or project level.

To perform a full audit, you can use a combination of audit logs, MongoDB log messages, and the project and organization activity feed.

Recommendations for Atlas Auditing and Logging

We recommend that you set up database auditing when you provision your clusters. Auditing puts additional load on your clusters and increases costs. To optimize costs, you can disable auditing in lower environments for development. Certain industries, such as healthcare and financial services, may opt to keep auditing enabled in development environments for compliance reasons.

Enabling auditing for all database users, including application service users, might affect cluster performance. We recommend that you audit only the actions of users that require auditing.

For staging and production environments, enable auditing for additional security.

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

For all of the previous events, you should include in the audit log the following information at a minimum:

Session ID
Client hostname and IP address
Database server hostname and IP address
Database user
Database name
OS user
Service/instance name
Port
Application
Query
SQL command
Object
Timestamp
Error code (if applicable)

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 Logs and Project and Organization Events.
To retrieve deployment logs, use atlas deployment logs command in the Atlas CLI. To learn more, see Atlas Deployment Logs.

Automation Examples: Atlas Auditing and Logging

See Terraform examples to enforce our Staging/Prod recommendations across all pillars in one place in Github.

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.

Update Audit Configuration

Run the following Atlas CLI command to audit all authentication events for known users in your project:

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

Run the following Atlas CLI command to audit a known user via a configuration file:

atlas auditing update -f filter.json

Describe Audit Configuration

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

atlas auditing describe --output json

Create and Use Audit Filter

Create an audit filter to only audit the authenticate operations that occur against the test database. To learn more, see Configure Audit Filters.

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

To use an audit filter that you created, update the audit configuration using the atlas auditing update Atlas CLI command:

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

Retrieve Logs

To retrieve the access log, use a command similar to the following. This command returns a JSON-formatted list of all authentication requests made against the clusters named Cluster0 for the project with the ID 618d48e05277a606ed2496fe:

atlas accesslogs list --output json --projectId 618d48e05277a606ed2496fe --clusterName Cluster0

Retrieve All Log Events for Organization in a JSON File

To return all events for the specified organization, use a command similar to the following. This command returns a JSON-formatted list of events for the organization with the ID 5dd5a6b6f10fab1d71a58495:

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

Download Logs

Run the following Atlas CLI command to download a compressed file that contains the MongoDB logs for the specified host in your project.

atlas logs download atlas-lnmtkm-shard-00-00.ajlj3.mongodb.net mongodb.gz --projectId 56fd11f25f23b33ef4c2a331

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