Audit

Audit logs are specific kind of logs that used to keep trace of users interactions only . They are stored onto a specific collection into MongoDB using module osp-collections.

Capabilities

Capability	Support	Comment
Managing audit collection access rights		By default the rights are restricted, and not editable by any users. But is is possible to manage rights as same as any collections.
Display audit on frontend (widget)		The audit log is a collection, so a :ref:collections widget <feature-collection-table> allows displaying it with the same customization capabilities.
Storage rolling management (size or time)		The logs are preserved in the same way as a collection, meaning the Create a TTL index to remove inactive collection entries also applies.
Edit audit table from frontend		Editing an audit record entry in the collection is not allowed by default. But depending on the collection access right, user may be allowed to edit logs. See rights collections.
Enrich audit entry		Scripts can add additional entries to enrich the audit log, with a dedicated audit controller available for this purpose.
Add custom column to audit collection		Every audit entries has to correspond to default schema. But addition information can be added to enrich all entries.
Trigger a callback on new audit entry		See Track the changes of a collection entry with a value.
Send audit log to external storage		Scripts can be used to transfer audit entries external. However, it depend on protocols available from script api.
Adding custom log entries		It is possible to add customs log entries depending of rights. See Examples.
Data anonymization		This feature is currently not supported. In case of interest please contact us at info@sdn.ch

Dependencies

This feature use osp-collections to store every audit messages. This imply a necessary dependency to the module Collection.

Concept

Audit logs are gathered from any interactions between users and internal data. The following table contains the list of every interactions that create an Audit log entry into the specific collection:

Interaction logged	Description
Configuration validation request	Any git push that triggers a configuration validation generate an audit log.
Apply new configuration	A git push followed by a successful validation create an audit log.
Configuration Change	Any configuration change triggered by a git push and validated successfully is logged.
Web API of osp-web	Any HTTP/S request to the web API is logged into the audit collection.
WebSocket Interactions	Any data request over WebSocket create an audit log entry.
Authentication	Any authentication attempt.
Command line	Any authentication, and all requests from command line.

The following list represent all modules that can generate audit logs:

• osp-configuration-dispatcher

• osp-keycloak

• osp-cli

• osp-web

Getting Started

Before starting to implement this feature, make sure that the module osp-collections is present in your configuration.

First, configure osp-collections to be able to receive logs from modules through his messaging queue. To do this, start by checking out the corresponding branch of the feature into branch edit.

git checkout edit
git checkout origin/feature-audit-log .

This create the least minimum collection schema of type “AUDIT” and declare it as a collection named audit. Then declare into osp-collection module (modules/collections/collections-1/module.collections) that the feature is activated and it has to store logs the collections we just declared:

{
  ...
  "useCollectionsRights": false,
  "useCollectionsProfilesRights": false,
  "useCollectionsServicesRights": false,
+ "useAuditLog": true
}

Now, the module osp-collections is ready to receive logs, the next step is to activate audit message generation from all modules.

This is done by editing (or creating) the configuration file stack.cfg and enabling the audit log creation. Be aware that the stack.cfg file contains the list of moduleId that will read it, if the moduleId is not present the module will not read the stack.cfg. Therefore, check the the list of modules audited.

Hint

If the file doesn’t exist it can be created anywhere in the root directory hierarchy

{
    "moduleId": [
+       "modules.configuration-dispatcher.main",
+       "modules.web.web-1",
+       "modules.keycloak.keycloak-1",
+       "modules.cli.cli-1"
    ],
    "hostname": "mara.sdnroot.net",
+   "enableAuditLog": true
}

Then update the running configuration :

git push

Audit log automatically start and store all log. To view logs, add a collection table into a dashboard. Do not forget to se the schema item id pointing to the collection. For more information about visualization, consult CollationTable widget documentation.

{
    "configuration": [
        {
            "type": "CollectionTable",
            "id": "XDoTd60x",
            "title": "Fiche de suivi",
            "collectionTableWidgetSettings": {
                "defaultSchemas": [
                    "root.audit-log"
                ],
                "defaultView": "default",
                "includeViews": [
                    "default"
                ]
            }
        }
    ],
    "layout": {
        "lg": [
            {
                "w": 12,
                "h": 6,
                "x": 0,
                "y": 0,
                "i": "XDoTd60x"
            }
        ]
    }
  }
}

Examples

• How to insert audit-log manually

Audit logs access right

By default all users has full access right to this collection. However this is possible to change this behavior by settings specific right to a collections. See rights collections for more information.

On top of that it is possible to manage right to this collection in general by settings specifics rights to the schema. See chapter Authorization.

Storage

All generated logs are stored into Collection module