Navigation

This version of the documentation is archived and no longer supported.

Security >
Auditing >
Configure Audit Filters

Configure Audit Filters¶

On this page

--auditFilter Option
Examples

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. To specify which events to record, the audit feature includes the --auditFilter option.

`--auditFilter` Option¶

The --auditFilter option takes a string representation of a query document of the form:

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

The <field> can be any field in the audit message, including fields returned in the param document.
The <expression> is a query condition expression.

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

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

Examples¶

Filter for Multiple Operation Types¶

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

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" ] } }'

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 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

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, 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 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

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\\./ } }'

Filter by Authorization Role¶

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

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" } }'

Filter on Read and Write Operations¶

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.

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

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

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

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 }

Filter on Read and Write Operations for a Collection¶

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.

The following example audits the find(), insert(), remove(), update(), save(), and findAndModify() operations for the collection orders in the database test by using the filter:

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

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

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 }

See also

Configure Auditing, Auditing, System Event Audit Messages

[1]	(1, 2) You can enable `auditAuthorizationSuccess` parameter without enabling `--auth`; however, all operations will return success for authorization checks.

← Configure Auditing Security Hardening →