Docs Menu
Docs Home
/
MongoDB Manual
/ / /

Configure Audit Filters on Self-Managed Deployments

On this page

  • Audit Filter Syntax
  • Filter Configuration at Runtime
  • Filter Configuration at System Startup
  • Examples
  • Learn More

Note

Auditing in MongoDB Atlas

MongoDB Atlas supports auditing for all M10 and larger clusters. Atlas supports specifying a JSON-formatted audit filter as documented below and using the Atlas audit filter builder for simplified auditing configuration. To learn more, see the Atlas documentation for Set Up Database Auditing and Configure a Custom Auditing Filter.

MongoDB Enterprise supports auditing of various operations. When enabled, the audit facility, by default, records all auditable operations as detailed in Audit Event Actions, Details, and Results. You can specify event filters to limit which events are recorded.

You can configure audit filters at startup or you can configure MongoDB to allow filter configuration at runtime.

Audit filters have the same form as query predicate documents specified to find commands. To see example audit filters, see Examples.

Starting in MongoDB 5.0, audit configurations for mongod and mongos nodes can be configured at runtime. A group of these nodes can take part in a distributed audit configuration.

To include a node in a distributed audit configuration, update the node's configuration file as follows and restart the server.

Parameter
Value
true
Unset
Unset

The server logs an error and fails to start if:

To modify audit filters and the auditAuthorizationSuccess parameter at runtime, see auditConfig.

Audit filters can be specified on the command line or else in the configuration file used to start the mongod or mongos instance.

Filters can be specified in YAML under the auditLog session of the configuration file. See the examples below for sample configurations.

Note

If runtimeConfiguration is enabled, then the configuration file cannot be used to specify audit filters.

To record all auditable events, do not specify an audit filter. By default, the audit facility records all auditable operations.

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

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

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

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. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

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

storage:
dbPath: data/db
auditLog:
destination: file
format: BSON
path: data/db/auditLog.bson
filter: '{ atype: { $in: [ "createCollection", "dropCollection" ] } }'

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

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

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

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

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. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

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

storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: BSON
path: data/db/auditLog.bson
filter: '{ atype: "authenticate", "param.db": "test" }'

To filter on all authenticate operations across databases, omit "param.db": "test" and use the filter { atype: "authenticate" }.

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

The following example audits only the createCollection and dropCollection operations that occur against the test database by using the filter:

Note

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

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

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

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. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

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

storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: BSON
path: data/db/auditLog.bson
filter: '{ atype: { $in: [ "createCollection", "dropCollection" ] }, "param.ns": /^test\\./ }'

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

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

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

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. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

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

storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: BSON
path: data/db/auditLog.bson
filter: '{ roles: { role: "readWrite", db: "test" } }'

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

Note

Enabling auditAuthorizationSuccess degrades performance more than logging only the authorization failures.

This filter audits multiple read and write operations:

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

The audited operations include:

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

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. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

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

storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: BSON
path: data/db/auditLog.bson
filter: '{ atype: "authCheck", "param.command": { $in: [ "find", "insert", "delete", "update", "findAndModify" ] } }'
setParameter: { auditAuthorizationSuccess: true }

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

Note

Enabling auditAuthorizationSuccess degrades performance more than logging only the authorization failures.

This filter audits multiple read and write operations on the orders collection in the test database:

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

The audited operations include:

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

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. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

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

storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: BSON
path: data/db/auditLog.bson
filter: '{ atype: "authCheck", "param.ns": "test.orders", "param.command": { $in: [ "find", "insert", "delete", "update", "findAndModify" ] } }'
setParameter: { auditAuthorizationSuccess: true }

Starting in MongoDB 8.0, MongoDB can write log messages in OCSF format. The OCSF schema contains different fields than the default mongo schema.

The following audit filter captures Network Activity actions that are recorded in the OCSF schema:

{ category_uid: 4 }

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

mongod --dbpath data/db --auth --setParameter auditAuthorizationSuccess=true --auditDestination file --auditFilter '{ category_uid: 4 }' --auditFormat JSON --auditSchema OCSF --auditPath data/db/auditLog.json

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

storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: JSON
path: data/db/auditLog.json
filter: '{ category_uid: 4 }'
schema: OCSF
setParameter: { auditAuthorizationSuccess: true }

For more information on OCSF log messages, see OCSF Schema Audit Messages.

To filter on multiple audit message fields, you can specify a top-level query operator like $or. For example, the following filter captures operations where either atype is authenticate or the operation was performed by a user with the readWrite role:

{
$or: [
{ atype: "authenticate" },
{ "roles.role": "readWrite" }
]
}

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

mongod --dbpath data/db --auth --setParameter auditAuthorizationSuccess=true --auditDestination file --auditFilter '{ $or: [ { atype: "authenticate" }, { "roles.role": "readWrite" } ] }' --auditFormat BSON --auditPath data/db/auditLog.bson

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

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

storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: BSON
path: data/db/auditLog.bson
filter: '{ $or: [ { atype: "authenticate" }, { "roles.role": "readWrite" } ] }'
[1](1, 2) You can enable auditAuthorizationSuccess parameter without enabling --auth; however, all operations will return success for authorization checks.

Back

Configure