Audit log

Audit log documentation

The Audit Log gives administrators the ability to see all actions made by a user during a selected period and all configurations and settings made on the system during a selected time period.

It can be used for audit and compliance purposes.

All configuration changes in SAFEQ Cloud are logged.
All higher-level operations are logged to audit log.
So it should be possible to see what has been done where, when and by whom.

Audit event log configuration

The configuration of the event log happens in application.conf config file.

CODE

  event-log {
    file {
      is-enabled = false
      basename = "audit"
      directory = ${app.home}"/logs"
      retention-days = 30
    }
  }

The sub-node(s) under event-log are the output writers. Currently there is only a file writer. So the settings under file only apply to the file writer, or generally to the node under which they are present.

Most settings are self-explanatory.

is-enabled switches the audit log file writing on/off. Changing this setting requires re-start of SAFEQ Cloud.
basename is the base name of the audit log file. A date is automatically appended to the basename.
directory is the directory where the log files are created in. ${app.home} is a variable that points to the root folder of SAFEQ Cloud.
retention-days is unused

Audit log writing

File writer

The audit log file is only written on primary servers. The log file name is simply: ‘audit-YYYY-MMM-DD.log’. Every day a new log file is created with events that occured on that day. The ‘audit’ part is the basename of the configuration above.

Events from secondary/gateway servers

Under normal circumstances (secondary is online/connected to primary) entity events are not logged at all on secondary servers. Because entities are not modified on secondary servers.

Action events and config update events are being raised on secondary servers, i.e. if a user authentication happens on an Authentication Service. So those kinds of events are being forwarded to primary servers and logged there.

Log synchronization from offline secondary servers

In case a secondary server looses connection to the primary and the offline-cache is enabled it will record any entity, action and config events locally and synchronize them to the primary when the connection is established again. The original event-context and event-detail of the event is maintained with original timestamps of when those operations did occur on the secondary server while offline.

For this to work a temporary audit log file is written on the secondary where the audit entries are written to in an encoded format.

The log structure

An audit log entry current has the following structure. It is embedded into starting { and ending } as the first character of a line. For example:

CODE

{
    event-context:{type:EventContext,source:test,traceId:"fabb825a-6fb6-4d25-96c2-f6482972319d",serverId:"f4911326-eb36-41e7-8fc5-bee01ca07ae5",datetime:"2020-05-11T15:37:24.627+02:00",request:{type:UnauthenticatedRequest,requesting-user:{type:RequestingUser,user-id:user-not-defined},requesting-domain:}},
    event-detail:{type:DeleteEntityEvent,entity-type:Account,entity-to-delete:{type:Account,account-type:Container,id:1,name:Foo,domains:[]},result:{type:Account,account-type:Container,id:1,name:Foo,domains:[]}},datetime:"2020-05-11T15:37:24.630+02:00"}
}

There are two major parts of a log entry.
The first one is event-context. The event-context transports the when, where and who. The same event-context may be part of multiple log entries. This happens when an operation triggered at a system boundary (i.e. API) or in the UI and consists of multiple configuration changes. Each configuration change is separately logged with the same event-context as they all group one operation. This is easily visible as the traceId value is static to multiple audit log entries.

The event-context has the following parameters:

source: the source of where the event occurred. This can be i.e.: “web”, or “api”.
traceId: The trace ID combines multiple events into a single action. For example, an API request to upload a document may result in multiple audit log events that change some data but are all part of this higher-level operation. The value is generated as a UUID by default. If the OpenTelemetry (OTEL) feature is enabled, the value is generated by OpenTelemetry—32 hexadecimal characters without any dash or so.
serverId: the server ID where this event originated.
datetime: the date and time when the event first hit an SAFEQ Cloud boundary system or was initiated otherwise.
request: distinguishes between an authenticated request and an unauthenticated request. An authenticated request contains an account-id and user details. This is used when a user could be identified as part of an API request or an UI operation. An unauthenticated request is used when a user could not be identified, for example because the API uses an ApiKey. In this case the unauthenticated request contains at least the domain that is the target of the request and any ApiKey, or email address that was additionally available.

The second part is the event-detail. The event-detail is the what.

There are the following different types of what:

Domain model/entity based configuration changes

The following operations on domain model/entities are recorded:

adding data, AddEntityEvent
updating data, UpdateEntityEvent
deleting data, DeleteEntityEvent
deleting all of something, DeleteAllEntityEvent
some custom operation on entities that cannot be easily catigorized on the above, CustomEntityEvent

All of the above events record changes to entities.

entity-type logs the name/type of entity.
result log the operation result.

Additionally each operation has special fields. I.e. UpdateEntityEvent logs a previous/old value and the new value as result.

The result field can also contain an error like so:
result:{type:Error,error-code:9999,error-msg:Foo,cause:none}

The following entities may get recorded:

CODE

Account, ApiKey, AuthProvider, AuthRole, Document, EncryptionKey, Group, 
InputPort, KeystoreData, LicenseAllocation, Location, MessagingConfig, 
MobilePrintConfig, MobilePrintWideArea, ObjectNode, OutputPort, 
Server, Service, Storage, TagGroup, TemplateConfig, TerminalConfig, Trigger, User, UserDetail

Other configuration changes

Log type: ConfigUpdateEvent

Config updates are raised and written to log when configuration is changed that is stored in application.conf file.

Here is an example of how this looks for a change to the log-level:

CODE

{
    event-context:{type:EventContext,source:web,traceId:"19d09e6c-8d10-4390-9256-1dbb7d9002ba",serverId:"1e786aa7-d46a-473b-98e8-5c8cccb39fb5",datetime:"2020-05-26T15:06:31.055+02:00",request:{type:AuthenticatedRequest,executing-user:...,account-id:1}},
    event-detail:{type:ConfigUpdateEvent,configType:app.logging,configData:{"loglevel":"DEBUG"}},datetime:"2020-05-26T15:06:31.066+02:00"}
}

Action based operations

Log type: IntentActionEvent

The IntentActionEvent events mark high-level operations. Those include things like user authentication, document upload, push or pull-print, etc.

Those operations usually involve changes to multiple entities. To get those together the IntentActionEvents mark a start and end block where multiple entity events may occur.

The opening block event is usually marked with an intent similar like this:
event-detail:{type:IntentActionEvent,intent:{type:AddDocumentIntent...

Where the closing block is marked with an intent-result similar like this:
event-detail:{type:IntentActionEvent,intent-result:{type:AddDocumentIntentResult...

All events within this block have the same event-context and hence the same traceId.

So the traceId can be used to filter for higher-level operations that contains multiple entity operations.

Common to all is the datetime when events happened.

The following intent types may get logged:

CODE

AuthUserIntent, FindUsersIntent, FindGroupsIntent, TestAuthProviderIntent, PrintInputIntent, MobilePrintInputIntent, PrintOutputIntent, PrintAllIntent, CreateOutputPortIntent, UpdateOutputPortIntent, DeleteOutputPortIntent, DefaultConvertDocumentIntent, InternalConvertDocumentIntent, ScheduledConvertDocumentIntent, MoveStorageIntent, AddDocumentIntent, UpdateDocumentIntent, RetrieveDocumentIntent, UploadDocumentIntent, DownloadDocumentIntent, DeleteDocumentIntent, DeleteTemporaryDocumentIntent, GetDocumentUriIntent, AddDocumentFromServerIntent, UpdateDocumentFromServerIntent, ConfigureTerminalIntent, DeployTerminalIntent, UndeployTerminalIntent, LicenseCheckIntent, EmailMessageSendIntent, TestEmailMessageSendIntent