Configure Audit Filters
On this page
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. To specify which events to record,
the audit feature includes the --auditFilter option.
Note
mongod and mongos
bind to localhost by default. If the members of your deployment are
run on different hosts or if you wish remote clients to connect to
your deployment, you must specify --bind_ip or
net.bindIp.
Before you bind to other ip addresses, consider enabling access control and other security measures listed in Security Checklist to prevent unauthorized access.
--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
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. For more information, see
Localhost Binding Compatibility Changes.
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
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. For more information, see
Localhost Binding Compatibility Changes.
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" }.
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
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. For more information, see
Localhost Binding Compatibility Changes.
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
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. For more information, see
Localhost Binding Compatibility Changes.
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
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. For more information, see
Localhost Binding Compatibility Changes.
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
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. For more information, see
Localhost Binding Compatibility Changes.
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 }
| [1] | (1, 2) You can enable auditAuthorizationSuccess
parameter without enabling --auth; however, all operations will
return success for authorization checks. |