Configure Audit Filters

Auditing in MongoDB Atlas

MongoDB Atlas supports auditing for all M10 and largerclusters. Atlas supports specifying a JSON-formatted auditfilter as documented below and using the Atlas audit filterbuilder for simplified auditing configuration. To learn more, seethe Atlas documentation forSet Up Database AuditingandConfigure a Custom Auditing Filter.

MongoDB Enterprisesupports auditing of various operations. Whenenabled, the audit facility, bydefault, records all auditable operations as detailed inAudit Event Actions, Details, and Results. To specify which events to record,the audit feature includes the —auditFilter option.

Note

Starting in MongoDB 3.6, mongod and mongosbind to localhost by default. If the members of your deployment arerun on different hosts or if you wish remote clients to connect toyour deployment, you must specify —bind_ip ornet.bindIp. For more information, seeLocalhost Binding Compatibility Changes.

Before you bind to other ip addresses, consider enablingaccess control and other security measures listedin Security Checklist to prevent unauthorizedaccess.

—auditFilter Option

The —auditFilter option takes a string representation of aquery document of the form:

  1. { <field1>: <expression1>, ... }

To specify an audit filter, enclose the filter document in singlequotes to pass the document as a string.

To specify the audit filter in a configuration file, you must use the YAML format ofthe configuration file.

Examples

Filter for Multiple Operation Types

The following example audits only the createCollectionand dropCollection actions by using the filter:

  1. { atype: { $in: [ "createCollection", "dropCollection" ] } }

To specify an audit filter, enclose the filter document in singlequotes to pass the document as a string.

  1. mongod --dbpath data/db --auditDestination file --auditFilter '{ atype: { $in: [ "createCollection", "dropCollection" ] } }' --auditFormat BSON --auditPath data/db/auditLog.bson

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

To specify the audit filter in a configuration file, you must use the YAML format ofthe configuration file.

  1. storage:
  2.    dbPath: data/db
  3. auditLog:
  4.    destination: file
  5.    format: BSON
  6.    path: data/db/auditLog.bson
  7.    filter: '{ atype: { $in: [ "createCollection", "dropCollection" ] } }'

Filter on Authentication Operations on a Single Database

The <field> can include any field in the audit message. For authentication operations (i.e.atype: "authenticate"), the audit messages include a db fieldin the param document.

The following example audits only the authenticate operationsthat occur against the test database by using the filter:

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

To specify an audit filter, enclose the filter document in singlequotes to pass the document as a string.

  1. mongod --dbpath data/db --auth --auditDestination file --auditFilter '{ atype: "authenticate", "param.db": "test" }' --auditFormat BSON --auditPath data/db/auditLog.bson

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

To specify the audit filter in a configuration file, you must use the YAML format ofthe configuration file.

  1. storage:
  2.    dbPath: data/db
  3. security:
  4.    authorization: enabled
  5. auditLog:
  6.    destination: file
  7.    format: BSON
  8.    path: data/db/auditLog.bson
  9.    filter: '{ atype: "authenticate", "param.db": "test" }'

To filter on all authenticate operations acrossdatabases, use the filter { atype: "authenticate" }.

Filter on Collection Creation and Drop Operations for a Single Database

The <field> can include any field in the audit message. For collection creation and dropoperations (i.e. atype: "createCollection" and atype:"dropCollection"), the audit messages include a namespace nsfield in the param document.

The following example audits only the createCollection anddropCollection operations that occur against the test databaseby using the filter:

Note

The regular expression requires two backslashes (\) to escapethe dot (.).

  1. { atype: { $in: [ "createCollection", "dropCollection" ] }, "param.ns": /^test\\./ } }

To specify an audit filter, enclose the filter document in singlequotes to pass the document as a string.

  1. mongod --dbpath data/db --auth --auditDestination file --auditFilter '{ atype: { $in: [ "createCollection", "dropCollection" ] }, "param.ns": /^test\\./ } }' --auditFormat BSON --auditPath data/db/auditLog.bson

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

To specify the audit filter in a configuration file, you must use the YAML format ofthe configuration file.

  1. storage:
  2.    dbPath: data/db
  3. security:
  4.    authorization: enabled
  5. auditLog:
  6.    destination: file
  7.    format: BSON
  8.    path: data/db/auditLog.bson
  9.    filter: '{ atype: { $in: [ "createCollection", "dropCollection" ] }, "param.ns": /^test\\./ } }'

Filter by Authorization Role

The following example audits operations by users withreadWrite role on the test database, including userswith roles that inherit from readWrite, by using the filter:

  1. { roles: { role: "readWrite", db: "test" } }

To specify an audit filter, enclose the filter document in singlequotes to pass the document as a string.

  1. mongod --dbpath data/db --auth --auditDestination file --auditFilter '{ roles: { role: "readWrite", db: "test" } }' --auditFormat BSON --auditPath data/db/auditLog.bson

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

To specify the audit filter in a configuration file, you must use the YAML format ofthe configuration file.

  1. storage:
  2.    dbPath: data/db
  3. security:
  4.    authorization: enabled
  5. auditLog:
  6.    destination: file
  7.    format: BSON
  8.    path: data/db/auditLog.bson
  9.    filter: '{ roles: { role: "readWrite", db: "test" } }'

Filter on Read and Write Operations

To capture read and write operations in theaudit, you must also enable the audit system to log authorizationsuccesses using the auditAuthorizationSuccess parameter.[1]

Note

Enabling auditAuthorizationSuccess degrades performancemore than logging only the authorization failures.

The following example audits the find(),insert(), remove(),update(), save(), andfindAndModify() operations by using the filter:

  1. { atype: "authCheck", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] } }

To specify an audit filter, enclose the filter document in singlequotes to pass the document as a string.

  1. mongod --dbpath data/db --auth --setParameter auditAuthorizationSuccess=true --auditDestination file --auditFilter '{ atype: "authCheck", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] } }' --auditFormat BSON --auditPath data/db/auditLog.bson

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

To specify the audit filter in a configuration file, you must use the YAML format ofthe configuration file.

  1. storage:
  2.    dbPath: data/db
  3. security:
  4.    authorization: enabled
  5. auditLog:
  6.    destination: file
  7.    format: BSON
  8.    path: data/db/auditLog.bson
  9.    filter: '{ atype: "authCheck", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] } }'
  10. setParameter: { auditAuthorizationSuccess: true }

Filter on Read and Write Operations for a Collection

To capture read and write operations in theaudit, you must also enable the audit system to log authorizationsuccesses using the auditAuthorizationSuccess parameter.[1]

Note

Enabling auditAuthorizationSuccess degrades performancemore than logging only the authorization failures.

The following example audits the find(),insert(), remove(),update(), save(), andfindAndModify() operations for the collectionorders in the database test by using the filter:

  1. { atype: "authCheck", "param.ns": "test.orders", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] } }

To specify an audit filter, enclose the filter document in singlequotes to pass the document as a string.

  1. mongod --dbpath data/db --auth --setParameter auditAuthorizationSuccess=true --auditDestination file --auditFilter '{ atype: "authCheck", "param.ns": "test.orders", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] } }' --auditFormat BSON --auditPath data/db/auditLog.bson

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

To specify the audit filter in a configuration file, you must use the YAML format ofthe configuration file.

  1. storage:
  2.    dbPath: data/db
  3. security:
  4.    authorization: enabled
  5. auditLog:
  6.    destination: file
  7.    format: BSON
  8.    path: data/db/auditLog.bson
  9.    filter: '{ atype: "authCheck", "param.ns": "test.orders", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] } }'
  10. setParameter: { auditAuthorizationSuccess: true }

See also

Configure Auditing,Auditing,System Event Audit Messages

[1](1, 2) You can enable auditAuthorizationSuccessparameter without enabling —auth; however, all operations willreturn success for authorization checks.