Extended Audits

Extended Audits lets the user query occurrences in the audit logs and quickly relate them to whom executed said changes.

Extended Audits provides information for Users, Roles and Groups only. It allows searching for specific types of objects, object keys, actions, the period of occurrence, the user that executed the action, and any relevant content that exists inside of the changed artifact.

User interface at a glance

The Extended Audits’ Tree Table always appears with the first level visible. This image has all the entries collapsed, so the folders for the artifacts can be visible in the same screen.
extended audits interface at a glance

The Extended Audits user interface consists of the following elements:

Artifact’s Tree Table Update Button

The “Update” button, updates the content of the Artifact’s Tree Table at any time.

Search Audit Log Button

By pressing the button a new pop-up appears. This new window allows the user to search for audit log and user activity entries in the Artifact’s Tree Table.

Artifact’s Tree Table

All the Users, Roles, and Groups are included on this tree table. The results on the Tree Table can be filtered by using the "Expand/Collapse" buttons or through the Filter section.

Expand/Collapse Buttons

From left to right, the buttons are respectively Collapse, Expand/Collapse to the first level, and Expand all. Collapse will show the artifacts’ folders. Expand/Collapse to the first level will always show the first level of artifacts regardless of the previous state (if collapsed or fully/partially expanded). The Expand all button will expand all entries.

Filter section

This section will filter the results in the Artifacts’ Tree Table based on the following rules:

  • If the “Search” field is filled in, then it filters based on text than may be contained in the “ID/Username” and the “Description” columns – it will only display those hits, excluding children.

  • If the “Package” field contains tokens, then all artifacts that belong to at least one of the listed packages will appear – it will also show its children.

  • The “Visible Folder” buttons allow to focus on first level artifacts of a specific type – keep in mind that their children will still be visible.

  • The “Visible User Status” buttons, will show entries that only contain Active, Inactive or Locked users respectively.

Artifacts

An artifact can be a User, a Role, or a Group. All artifacts can navigate to its application through hash navigation (more ahead), and each artifact has an icon representing their type.

Inside the Tree Table, initially all artifacts are included in their own group, i.e. all groups are inside the “Groups” folder, all roles are inside of the “Roles” folder and all users inside of the "Users” folder.

Additionally, every first level artifact will have as children their immediate relationship, and some second level will also have children based on context and relationship.

The following diagram represents that relationship.

extended audits artifact relationship

The following screenshot is an example of an expanded tree. We can also see that the Tree Table’s contents were filtered by package.

extended audits package selection

Hash navigation

Any artifact can open its corresponding management app, by clicking on the “Navigate to” button extended audits navigate to.

For example, clicking on the “Navigate to" button of the group “FieldWorkers” opens this same artifact in the “Security Group”.

extended audits security group management tool fieldWorkers

Type icons

Every artifact has an icon that matches its type.

Icon Artifact type

extended audits group

Group

extended audits role

Role

extended audits user

User

History

By clicking on an artifact (not the hash-navigation), it is possible to get more information about it. The History tab will open next to the Artifact’s Tree Table showing the artifact history.

extended audits history

The History tab displays the artifact changes logged in the Audit Log. If the artifact is a user, it also displays user activity entries together with the audit log information.

It contains two sections:

  • The current data for the selected artifact

  • The change history that exists in the audit log. If the artifact is a user, then it also displays its user activity information from the database.

If the audit log is cleaned periodically, then the change information displayed will be reduced.

The information displayed on the changes section has a tabular format and displays the most recent entry first. Relations are cross-referenced to know the exact point at which (and by whom) a relation was added or removed. Such information is only possible if the Audit Log is preserved, see audit log cleanup in Housekeeping.

Current data

The current data of the artifact has the following format:

Current data for artifact NAME (TYPE)
    PROPERTY: VALUE

  • NAME is the name of the artifact.

  • TYPE is either Group, Role, or User.

  • PROPERTY is the name of a property that is part of the artifact.

  • VALUE is its current value.

  • The line PROPERTY: VALUE has multiple occurrences.

Activity and change history

All artifact types have a change history. The type User additionally has an activity history. The activity history is related to a user’s login/logout history in the system.

For the user activity logging, user logins are always logged but user logouts are only logged when the user intentionally logs out of the system. Session timeouts are not logged. When accessing a resource, the system detects that the session is expired and issues another login request.

The header of group artifacts or role artifacts is displayed in the following format:

Artifact change history:

The header of user artifacts is displayed in the following format:

Artifact activity & change history:

The section has the following format:

[DATE-FROM TIME-FROM -> DATE-TO TIME-TO] USER
    PROPERTY INFORMATION
    RELATION INFORMATION
[DATE TIME] USER
    user activity: ACTION (RESULT) with data DATA
[DATE TIME] USER
    PROPERTY INFORMATION
    RELATION INFORMATION

  • DATE TIME is the timestamp of either a user activity entry or the artifact’s first entry in the audit log, which corresponds to the artifact creation if the entry is still in the audit log, see Housekeeping.

  • DATE TIME for an artifact change always corresponds to an audit log entry.

  • DATE-FROM TIME-FROM belongs to a period and it is the timestamp of the last analyzed entry/period.

  • DATE-TO TIME-TO belongs to a period and it is the timestamp of the entry found that’s currently being analyzed.

  • [DATE-FROM TIME-FROM → DATE-TO TIME-TO] is an analysis period:

    • It states the changes that were executed since the last analyzed entry/period until the DATE-TO TIME-TO timestamp.

    • DATE-TO TIME-TO corresponds to an audit log entry.

  • USER is the username who made the changes in the last entry of the period, who triggered the user activity, or who executed the single entry change.

  • ACTION is the user activity action, which can either be Login or Logout.

  • RESULT is the result of the action, which can be the following:

    • Locked

    • Expired

    • WrongPassword

    • InvalidToken

    • Success

    • Redirect

    • Error

  • DATA is the relative path of the resource being accessed at the time of the user activity entry.

  • PROPERTY INFORMATION displays the value or change that was applied to a property. This entry is not guaranteed, but when it exists it can occur multiple times in the following format:

    PROPERTY: (added VALUE|from VALUE1; to VALUE2)

    • PROPERTY is the property name.

    • VALUE, VALUE1, and VALUE2 represent the value of the property.

      • VALUE is used when the property is added.

      • VALUE1 and VALUE2 are used when the property is modified. VALUE1 and VALUE2 are the old and the new values respectively.

    • The value syntax shown is mutually exclusive for the same property. It can either be an addition or a modification, but not both.

  • RELATION INFORMATION displays which relations changed.This entry is not guaranteed, but if shown it can only occur once per relation type. If a change occurred to that relation, it occurs in the following format:

    (groups|roles|users) (added|removed):
    name: NAME; id: GUID
            ([DATE TIME] (added|removed) by USER)?

    • NAME is the name of the relation artifact being added|removed.

      If the relation change exists, then this line will occur at least once, but it can occur multiple times.

    • GUID is its guid.

    • DATE TIME is the timestamp at which the relation artifact was added/removed.

      If this entry exists, then it means that the change occurred in the relation artifact’s management tool, when NAME was saved by USER at the specified DATE TIME. Otherwise, it means that either the change occurred in the parent artifact or the audit log entry related to it was already removed, see Housekeeping.

    • USER is who added/removed the artifact.

Special cases where DATE-TO TIME-TO corresponds to the current time

When an artifact exists, but no entry exists in the audit log, a period is generated from the date of its creation DATE-FROM TIME-FROM to the current time DATE-TO TIME-TO with the USER “Unknown user”. In this case, DATE-FROM TIME-FROM and DATE-TO TIME-TO do not correspond to any audit log entry.

If an artifact is saved, but its data or relations are changed due to some other artifact modification, then the DATE-TO TIME-TO will correspond to the current time. For example, a Role is added/removed to/from a Security Group. The Role artifact was not directly modified. So, no audit log entry exists, but its relation to the Security Group changed due to the Security Group artifact modification. While displaying the role history, a change is detected between the last audit log entry and the current artifact state, which triggers a period from the last audit log entry until the current time to analyze the changes in the period. There are cross-references.

Example

This example uses a Security Group, a Role, and a User. All of them are newly created. Their names are “App Developers Group”, “App Developers Role”, and “John Eric Levick” respectively.

extended audits history user
Screenshot example: User history for "John Eric Levick"
extended audits history role
Screenshot example: Role history for "App Developers Role"
extended audits history group
Screenshot example: Group history for "App Developers Group"

The group was the first to be created at 13:43:31 (see line 27 in the screenshot example: Group history for "App Developers Group"), then the role at 13:43:56 (see line 20 in the screenshot example:Role history for "App Developers Role") and the user at 13:44:56 (see line 46 in the screenshot example: User history for "John Eric Levick"). Their format complies with the format for audit log single entry described in the artifact activity & change history section. In all these entries we can see that it was the user paulo that created the artifacts.

Now, let’s focus on the screenshot example: User history for "John Eric Levick" to analyze the changes.

Its next entry is a period entry, where the name was changed (see line 44 in the screenshot example: User history for "John Eric Levick"). It is still related to changes in the artifact itself and reflects all changes taking place between its creation (last analyzed entry) and the next audit log entry. Its format complies with the format for audit log period entry described in the artifact’s activity & change history section.

The user mentioned in the time gap is related to the audit log entry found in DATE-TO TIME-TO. There may be changes in between that are not executed by that specific user. We will see one of these cases ahead, in this case connected with cross-referencing.

Next, we have user activity entries where John Eric Levick tried to login for the first time, where he successfully introduced the initial password (see line 42 in the screenshot example: User history for "John Eric Levick"), that triggered a password change, and then completed the password change and logged into the system (see line 40 the screenshot example: User history for "John Eric Levick"). He later logged out of the system (see line 38 in the screenshot example: User history for "John Eric Levick"). Their format complies with the format for user activity entries described in the artifact activity & change history section.

The user activity line is shown only once, per activity entry.

The user’s last entry is a period entry (see line 34 in the screenshot example: User history for "John Eric Levick") and its DATE-FROM TIME-FROM matches the DATE-TO TIME-TO of the previous period entry (see line 44 in the screenshot example: User history for "John Eric Levick").

“App Developers Group” was added through the Security Group management tool at 13:47:35, which changed the group relation (see line 35 in the screenshot example: User history for "John Eric Levick").

Resulting cross-references in the example:

  • Group and Role

    Role added to Group: The date in line 19 in the screenshot example: Role history for "App Developers Role" is equal to the DATE-TO TIME-TO in line 22 in the screenshot example: Group history for "App Developers Group".

  • Group and User

    User added to Group: The date in line 37 in the the screenshot example: User history for "John Eric Levick" is equal to the DATE-TO TIME-TO in line 22 in the screenshot example: Group history for "App Developers Group".

Both cases match their action (relation added) and their timing.

Audit Logs Search

By pressing the “Search Audit Log” button, the following pop-up window appears.

extended audits audit logs search search options

By pressing the “Esc” or the “Close” button, this dialog is closed. By pressing the “Search” button, the audit logs and the user activity are searched. The results are presented in a new table, below the selection options.

extended audits audit logs search results example

The selection options work as follows:

  • One row of type, key, action, period, changed by, and content combine themselves to restrict the search to those selection values.

  • Multiple rows of the selection options will join the hits of each row without duplicates.

For example, if there are two selection rows and one produces lines A and B and the other produces lines B and C, then the final result is A, B and C. Line B will only be displayed once.

A, B, and C are abstract data results that symbolize the same data.

The possible values for the selection options are the following:

extended audits audit logs search search options
Type

Group, Role, and User

Key

“New” and any single Group, Role, or User artifact

Action

Activity, Save, Create, and Delete

Period

A start and end date

Changed by

The username who executed an action

Content

Text contained inside the changed artifact

Actions

Deletes the selection line (it clears the data if it’s the only one). Inserts below a new empty selection line. Inserts below a line with the same data as the desired line.

Some old audit log entries related to the creation of an artifact still use the old mode, where the “Action” and “Key” fields have “Save” and “New” respectively. To look for these created artifacts, set the “Key” field to “New” and the “Action” field to “Save”. For all entries created after the latest patch, just select the “Action” “Create”.

Type and key selection

These two fields have a tight integration. Since artifacts of different types can have the same name, it becomes difficult to filter the correct keys if no integration is implemented.

Pressing the value help icon extended audits audit logs search value help icon in any of these fields will open a pop-up dialog that handles the integration.

extended audits audit logs search types and keys

Pressing “Close” or the “Esc” key will close the dialog and ignore any selections. Pressing “Select” will confirm everything.

Having no type selected is equivalent to having all of them selected.

extended audits audit logs search all types off
Screenshot example: No type selected
extended audits audit logs search all types on
Screenshot example: All types selected

As long as one type is selected, the keys of unselected types will become disabled:

extended audits audit logs search type off keys disabled

The search field is bound to the columns type and name. Writing “role” will filter all roles and entries which have “role” in their name. Writing “new” will filter all entries that contain “new” in their names:

extended audits audit logs search type role on keys of role enabled

Pressing select with the following options will affect the corresponding inputs in the selection options:

extended audits audit logs search type role on keys of role enabled selected
Example selection before pressing select
extended audits audit logs search search options type and key filled
Resulting selection after pressing select

Deleting a token from the “Type” input will also call the integration pop-up dialog. If the change affects the key selection, a warning message is displayed.

extended audits audit logs search search options type role delete
Example of role deletion from "Type" input field
extended audits audit logs search search options type role delete warning delete keys
Resulting key selection from previous role deletion
Pressing the “Close” button or the “Esc” will return to the previous values in the input fields. Pressing the "Select” button will confirm the changes.

Confirming the changes in the example above will produce the following result:

extended audits audit logs search search options type user only

User activity and virtual entries

The user activity is displayed as an Audit Log result, but the fact is that it is data that comes from a different table. That’s the user activity table.

To display the entry in the same format as the other audit log entries, then a virtual entry is generated in runtime before display.

This is the same idea as using a view to display data from several tables.

Let’s use the previously created user John Eric Levick. It’s a local user with the username “johnlevick”.

extended audits user john levick

In the Audit Log Search, let’s set “Action” to “Create”, and “Content” to “johnlevick”. Pressing search, this is the result we obtain:

extended audits audit logs search john levick create result

This was a real audit log entry, by the way. The virtual entry comes next.

Now let’s see a user activity triggered by this user. For the new search, we change the “Key” to “johnlevick” (the username), the “Action” to “Activity” and the “Content” to “Logout AND Success”.

The “Content” selection field accepts arbitrary text inside the artifact’s content. If the “AND” keyword in uppercase is used, then it’s possible to combine two keywords that must exist at the same time.
extended audits audit logs search john levick activity logout success result

If you notice, the result’s “Id” starts with an asterisk (*). That’s because it is not a real audit log entry. The UUID after the asterisk is the UUID of the user activity entry and can be seen by pressing the information button in the far right of the entry.

extended audits audit logs search john levick activity logout success result content json

Combining several selection options

As we said before, it is possible to combine several selection options to provide refined results. Let’s use the previous example and obtain those two lines in one go.

extended audits audit logs search john levick combined results

The results are displayed in descending order of the “Updated At” field.

Filtering and acting on the report

It is possible to filter the report by the fields “Type”, “Action”, “Object Name”, and “Changed By”. If any of them contain the text written on the “Search” input, then they’ll be visible.

By selecting an entry, and pressing the “Go to” button, then the pop-up closes, and the artifact is filtered and pin-pointed in the Artifacts’ Tree Table.

Pressing the “JSON” button downloads the whole result list as a JSON file. It is not as easy to compare data as if it was downloaded as a Microsoft Excel file, but it contains the whole data. Let us not forget that each audit log entry contains the whole data of the artifact that was changed, and that its structure is different depending on its type (Group, Role, User, and User Activity).

Setting Up

There is a supplied role, Cockpit tile and Cockpit tile group together with the packaged bundle.

It is recommended to integrate the Cockpit tile into your own set of Cockpit tile groups, but if you want to use the out-of-the-box build, then apply the role dxp_extended_audits to a user or group. Then whichever user is eligible will see the following tile in the Cockpit:

extended audits tile

These are the relevant artifacts included in the package neptunesoftware-dxp-abb-extendedaudits:

Type Name Description

Role

dxp_extended_audits

Role for the Extended Audits app

Tile (Cockpit Tile)

dxp_extended_audits

View reports for system configurations

Tile Group (Cockpit Tile Group)

dxp_extended_audits