From f423671fd39f59909370953275fed3eaab8cef9a Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Tue, 29 Jun 2021 09:26:31 -0700 Subject: [PATCH] DOCSP-13233 Improved auditing coverage --- source/core/auditing.txt | 10 + source/includes/audit-local-remote.rst | 10 + source/includes/collection-audit-event.rst | 8 + source/reference/audit-message.txt | 250 ++++++++++++++++++--- source/release-notes/5.0-compatibility.txt | 6 + source/release-notes/5.0.txt | 32 ++- 6 files changed, 269 insertions(+), 47 deletions(-) create mode 100644 source/includes/audit-local-remote.rst create mode 100644 source/includes/collection-audit-event.rst diff --git a/source/core/auditing.txt b/source/core/auditing.txt index 973f8eba3da..c257fdd9213 100644 --- a/source/core/auditing.txt +++ b/source/core/auditing.txt @@ -26,6 +26,8 @@ file, or a BSON file. To enable auditing for MongoDB Enterprise, see For information on the audit log messages, see :doc:`/reference/audit-message`. +.. _auditing-audit-events-and-filter: + Audit Events and Filter ----------------------- @@ -36,6 +38,14 @@ Once enabled, the auditing system can record the following operations [#transact - authentication and authorization, and - CRUD operations (requires :parameter:`auditAuthorizationSuccess` set to ``true``). +.. note:: + + Starting in MongoDB 5.0, :term:`secondaries ` do not log + DDL audit events for replicated changes. DDL audit events are still + logged for DDL operations that modify the :ref:`local database + ` and the :data:`system.profile + <.system.profile>` collection. + For details on audited actions, see :ref:`audit-action-details-results`. With the auditing system, you can :ref:`set up filters ` to restrict the diff --git a/source/includes/audit-local-remote.rst b/source/includes/audit-local-remote.rst new file mode 100644 index 00000000000..8393a0f934d --- /dev/null +++ b/source/includes/audit-local-remote.rst @@ -0,0 +1,10 @@ +Starting in MongoDB 5.0, can alternatively be a document with one of +these fields: + +- ``isSystemUser`` that indicates whether the user who + caused the event was a system user. Logged for self-referential jobs + initiated by a background process that runs on the same server + instance. + +- ``unix`` that contains the MongoDB socket file path if the client + connects through a Unix domain socket. \ No newline at end of file diff --git a/source/includes/collection-audit-event.rst b/source/includes/collection-audit-event.rst new file mode 100644 index 00000000000..70da4b98d6e --- /dev/null +++ b/source/includes/collection-audit-event.rst @@ -0,0 +1,8 @@ +Starting in MongoDB 5.0, this additional information is logged for a +view: + +- ``viewOn`` field with the database and collection for the view. + +- ``pipeline`` field with the + :doc:`aggregation pipeline ` definition + for the view. \ No newline at end of file diff --git a/source/reference/audit-message.txt b/source/reference/audit-message.txt index 67cc003a2df..56784e2f75e 100644 --- a/source/reference/audit-message.txt +++ b/source/reference/audit-message.txt @@ -21,17 +21,20 @@ The :doc:`event auditing feature ` can record events in JSON format. To configure auditing output, see :doc:`/tutorial/configure-auditing`. +.. versionchanged:: 5.0 + The recorded JSON messages have the following syntax: .. code-block:: none { - atype: , - ts : { "$date": }, - local: { ip: , port: }, - remote: { ip: , port: }, - users : [ { user: , db: }, ... ], - roles: [ { role: , db: }, ... ], + atype: , + ts : { $date: }, + uuid : { $binary: , $type: }, + local: { ip: , port: || isSystemUser: || unix: }, + remote: { ip: , port: || isSystemUser: || unix: }, + users : [ { user: , db: }, ... ], + roles: [ { role: , db: }, ... ], param: , result: } @@ -64,23 +67,54 @@ The recorded JSON messages have the following syntax: - * - ``local`` + * - .. _audit-message-uuid: + + ``uuid`` - document - - Document that contains the local ``ip`` address and the ``port`` + - Document that contains a universally unique identifier (UUID) for + the audit message. The ``$type`` field specifies the BSON subtype + for the ``$binary`` field. The ``$type`` value of ``04`` + specifies that the ``$binary`` field contains a UUID. + + .. versionadded:: 5.0 + + + + * - .. _audit-message-local: + + ``local`` + + - document + + - A document that contains the ``ip`` address and the ``port`` number of the running instance. - - + + .. include:: /includes/audit-local-remote.rst + + .. note:: + + Starting in MongoDB 5.0, the ``local`` field is deprecated. + Use the ``localEndpoint`` field in the :ref:`clientMetadata + ` audit message instead. + + .. versionchanged:: 5.0 + + * - ``remote`` - document - - Document that contains the remote ``ip`` address and the ``port`` number of - the incoming connection associated with the event. - - + - A document that contains the ``ip`` address and the ``port`` + number of the incoming connection associated with the event. + + .. include:: /includes/audit-local-remote.rst + + .. versionchanged:: 5.0 + + * - ``users`` @@ -141,7 +175,10 @@ associated ``param`` details and the ``result`` values, if any. - ``result`` - * - :authaction:`authenticate` + + * - .. _audit-message-authenticate: + + :authaction:`authenticate` - .. code-block:: none :copyable: false @@ -152,12 +189,25 @@ associated ``param`` details and the ``result`` values, if any. mechanism: } + Starting in MongoDB 5.0, :authaction:`authenticate`: + + - Is logged for incomplete authentication attempts. + + - Includes the principle name and identifier in + ``mechanism`` for external authentication mechanisms such as + :ref:`x.509 ` and Amazon Web Services + Identity and Access Management (AWS-IAM) (see + :urioption:`authMechanism`). + + .. versionchanged:: 5.0 - | ``0`` - Success | ``18`` - Authentication Failed | ``334`` - Mechanism Unavailable - * - :authaction:`authCheck` + * - .. _audit-message-authCheck: + + :authaction:`authCheck` - .. code-block:: none :copyable: false @@ -171,24 +221,93 @@ associated ``param`` details and the ``result`` values, if any. | ``ns`` field is optional. | ``args`` field may be redacted. + By default, the auditing system logs only the authorization + failures. To enable the system to log authorization successes, + use the :parameter:`auditAuthorizationSuccess` parameter. + + .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst + + Starting in MongoDB 5.0, :authaction:`authCheck` is not logged + for actions that are generated internally. + + .. versionchanged:: 5.0 + - | ``0`` - Success | ``13`` - Unauthorized to perform the operation. - By default, the auditing system logs only the authorization - failures. To enable the system to log authorization successes, use - the :parameter:`auditAuthorizationSuccess` parameter. [#performance]_ + * - .. _audit-message-clientMetadata: - * - :authaction:`createCollection` + :authaction:`clientMetadata` - .. code-block:: none :copyable: false - { ns: . } + { + localEndpoint : { + ip : , + port : + } || { + unix : + }, + clientMetadata : { + driver : { + name : , + version : + }, + os : { + type : , + name : , + architecture : , + version : + }, + platform : , + application : { + name : + } + } + } + Contains the client metadata. Logged when the client runs the + :dbcommand:`hello` command. + + .. seealso:: + + :ref:`log-messages-client-data` + + .. versionadded:: 5.0 - ``0`` - Success + + * - .. _audit-message-createCollection: + + :authaction:`createCollection` + + - .. code-block:: none + :copyable: false + + { + ns: ., + viewOn: ., + pipeline: [ ] + } + + Logged when a: + + - Collection is created. + + - :ref:`View <3.4-reference-views>` is created, with the view + name logged in the ``ns`` field. + + .. include:: /includes/collection-audit-event.rst + + .. versionchanged:: 5.0 + + - ``0`` - Success + + * - :authaction:`createDatabase` - .. code-block:: none @@ -199,7 +318,10 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`createIndex` + + * - .. _audit-message-createIndex: + + :authaction:`createIndex` - .. code-block:: none :copyable: false @@ -217,6 +339,21 @@ associated ``param`` details and the ``result`` values, if any. - ``IndexBuildSucceeded`` - ``IndexBuildAborted`` + Starting in MongoDB 5.0, :authaction:`createIndex` audit events + are: + + - Logged at the start and end of index creation, and includes a + message indicating if the index was successfully created or + not. + + - Attributed to the originating user for the action that + caused the :authaction:`createIndex` audit event. + + - Logged for a :authaction:`createCollection` event if the + collection has an index. + + .. versionchanged:: 5.0 + - | ``0`` - Success | ``276`` - Index build aborted. @@ -227,6 +364,31 @@ associated ``param`` details and the ``result`` values, if any. ``IndexBuildState`` set to ``IndexBuildStarted`` or ``IndexBuildSucceeded``. + + * - .. _audit-message-directAuthMutation: + + :authaction:`directAuthMutation` + + - .. code-block:: none + :copyable: false + + { + document: { + + }, + ns: ., + operation: + } + + Logged when a database operation directly modifies the contents + of the :data:`admin.system.users` or :data:`admin.system.roles` + collections. + + .. versionadded:: 5.0 + + - ``0`` - Success + + * - :authaction:`renameCollection` - .. code-block:: none @@ -240,21 +402,34 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`dropCollection` + + * - .. _audit-message-dropCollection: + + :authaction:`dropCollection` - .. code-block:: none :copyable: false { - ns: ., + ns: ., viewOn: ., - pipeline: [] + pipeline: [ ] } - Starting in MongoDB v5.0 ``dropCollection`` adds an audit event - when a :ref:`view <3.4-reference-views>` is dropped as well as - when a :term:`collection` is dropped. The ``pipeline`` - parameter defines the ``view`` referenced in ``viewOn``. + Logged when a: + + - Collection is dropped. + + - :ref:`View <3.4-reference-views>` is dropped, with the view + name logged in the ``ns`` field. + + .. include:: /includes/collection-audit-event.rst + + In addition, starting in MongoDB 5.0, a + :authaction:`dropCollection` audit event is logged when a + :authaction:`dropDatabase` event occurs. + + .. versionchanged:: 5.0 - | ``0`` - Success | ``26`` - ``NamespaceNotFound`` @@ -682,8 +857,11 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - - * - :authaction:`logout` + + + * - .. _audit-message-logout: + + :authaction:`logout` - .. code-block:: none :copyable: false @@ -714,7 +892,10 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`startup` + + * - .. _audit-message-startup: + + :authaction:`startup` - .. code-block:: none :copyable: false @@ -728,8 +909,3 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - -.. [#performance] - - .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst - diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 00bfa069c64..9474e88b2dd 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -366,6 +366,12 @@ Deprecations *Deprecated in version 5.0:* Disconnect from the server to end your session instead. +- :ref:`local ` audit message field + + *Deprecated in version 5.0:* Use the ``localEndpoint`` field in + the :ref:`clientMetadata ` audit message + instead. + Deprecated Wire Protocol Opcodes ```````````````````````````````` diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 906246efeee..e666f5d05fb 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -173,6 +173,28 @@ MongDB 5.0 adds the ability to configure auditing filters at runtime. * - :parameter:`auditConfigPollingFrequencySecs` - Defines the polling interval for checking audit configuration +Starting in MongoDB 5.0: + +- :ref:`System event auditing ` has: + + - An additional :ref:`uuid ` field and other + :ref:`audit message ` enhancements. + + - New audit message types: :ref:`clientMetadata + `, :ref:`directAuthMutation + `, :ref:`logout + `, and :ref:`startup `. + + - Additional information and logging scenarios for these existing + audit message types: :ref:`authCheck `, + :ref:`authenticate `, + :ref:`createCollection `, + :ref:`createIndex `, and + :ref:`dropCollection `. + +- DDL operations auditing on :term:`secondaries ` has + changes. See :ref:`auditing-audit-events-and-filter`. + .. _5.0-rel-notes-change-streams: Change Streams @@ -459,16 +481,6 @@ Implicit Default Write Concern .. include:: /includes/5.0-default-wc.rst -Audit Events -~~~~~~~~~~~~ - -Starting in MongoDB 5.0, ``startup`` and ``logout`` audit action types -are available in -:doc:`System Event Audit Messages `. - -The ``dropCollection`` audit action type (``atype``) adds an audit -event when a :ref:`view <3.4-reference-views>` is dropped. - ``mongosShutdownTimeoutMillisForSignaledShutdown`` Parameter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~