ThingWorx Audit Messages
This topic provides details about the content of ThingWorx audit messages in the following sections. Click the title of a section to display the content. Click the title again to hide the content.
Types of Audit Messages
The Audit Subsystem generates messages for different activities in the ThingWorx Platform. The messages fall into the following general types:
• Changes to an Object — Auditing of changes such as creation, deletion, or modification of an entity. The entity may be a Thing or a non-Thing, such as a subsystem or organization.
• Changes to Users — Auditing of changes such as creation or modification of a user or application key. Refer to the next section to learn about auditing of a switch in security context.
• Operations on an Object — Auditing of operations on an entity. Examples include remote session activity (tunneling) on a Thing.
• Operations on the System — Audits where no target object exists for the message, such as user login and import/export operations.
• Audit operations — Invocations of audit services trigger audit messages and adds messages to the audit log.
Audit messages contain audit entries, which provide the information about the activity.
Auditing the Switching of Security Context
As of v.8.5 of ThingWorx Platform, the audit subsystem audits the switching of security context from one user to another as well as the elevation of security context to super user. One example of a security context switch occurs at the invocation of the SecurityContext.createUserContext(User anotherUser) method of the ThingWorx Extension API. This method allows an extension or a script to switch to another user's security context. The SecurityContext.createSuperUserContext() method of the ThingWorx Extension API makes it possible for an extension or a script to switch to the security context of the super user of the system, allowing the extension code to access all entities that a super user can access.
The change of security context often happens internally in ThingWorx Platform to enable different features to access services and entities that may not be visible to standard users. For this reason, not all security context changes will be audited. Only deliberate security context changes that may indicate a security breach will be audited.
The category for these messages is SECURITY_CONFIGURATION.The audit messages for switching security context follow:
audit.securityContext.SuperUser
User _currentUser__switched context to SuperUser within the Entity Context of __thingName__.
audit.SecurityContext.Changed
User __currentUser__ switched context to __username__within the Entity Context of __thingName__.
User _currentUser__switched context to SuperUser within the Entity Context of __thingName__.
audit.SecurityContext.Changed
User __currentUser__ switched context to __username__within the Entity Context of __thingName__.
Audit Entries
Each audit entry is comprised of two components, an Audit Category Key and an Audit Message Key:
• The Audit Category Key is a localization token that specifies the functional area, or category, with which the audit message is associated. This key is a STRING. For a list of categories, see .Audit Categories
• The Audit Message Key is a localization token that points to the text of the audit message. This key is a STRING.
The value for each component is pulled from the corresponding, built-in event definition or instance.
Audit Message Arguments
The audit message provides arguments that are used to generate a localized text message and the name of the entity that performed the operation. A ValueCollection of substitution name/value pairs is used to generate the localized text message. This information is retrieved from the eventData fields of the event instance. A ThingWorx entity, such as a Thing or a user, is associated with an audit message, including who or what performed the operation that is the subject of the audit message.
Audit Categories
All audit entries are associated with an audit category. Audit categories make it very easy to filter audit data and look at a trend of activities for a certain category of operations.
Each audit entry has a single category, which is stored as a string with the audit entry. The displayed audit category string is localized. Based on the user's preferred locale, the audit category is displayed in the appropriate language.
In the Localization Tokens table in ThingWorx Composer, each category has a localization token and each message has a localization token. These tokens are also referred to as CategoryKey and MessageKey when enabling/disabling the categories and messages.
Here is an example of the Localization table, showing the localization token names and values for audit categories and messages:
The following table briefly describes and provides examples of audited actions for each category. It also provides the localization tokens (or "keys") for categories and messages.
Category | Description | Examples | Category Keys and Message Keys | ||
|---|---|---|---|---|---|
ANALYTICS | Actions related to analytics entities. Operations performed by ThingWorx Analytics. | Create, edit, delete operations on data analysis definitions. Other actions within ThingWorx Analytics. | Category Key: audit.AuditCategory.Analytics | ||
AUDIT | For internal audit subsystem use. | Enabled by default. Enables the tracking of Audit service executions because they potentially may contain sensitive data. The audit message returns the USERNAME that executed the service. The services that are audited by default follow: • ArchiveAuditHistory • ArchiveAuditHistoryDirectPersistence • PurgeAuditData • ExportAuditData • ExportOnlineAuditData • CleanUpOfflineAudit The following services are not audited by default: • QueryAuditHistory • QueryAuditHistoryWithQueryCriteria • QueryAuditHistoryContextConstrained • GetAuditEntryCount | Category Key: audit.AuditCategory.Audit Message Keys: • audit.Audit.ExecutedService.ArchiveAuditHistory • audit.Audit.ExecutedService.ArchiveAuditHistoryDirectPersistence • audit.Audit.ExecutedService.PurgeAuditData • audit.Audit.ExecutedService.ExportAuditData • audit.Audit.ExecutedService.ExportOnlineAuditData • audit.Audit.ExecutedService.CleanUpOfflineAudit • audit.Audit.ExecutedService.Query AuditHistory • audit.Audit.ExecutedService.GetAuditEntryCount | ||
AUTHENTICATION | Actions related to authentication. | • Successful and unsuccessful user login, user logout, and errors related to using application keys. For example: Login successful for user: Administrator. • The Logout entry enables tracking of User logout actions. This entry is generated for user-initiated logout from ThingWorx Composer. The user name is included in the audit message. • The LoginSucceeded entry enables tracking of successful User login actions. The user name is included in the audit message. • The LoginFailed entry enables tracking of failed User Login actions. The user name is included in the audit message. • The ApplicationKeySucceeded entry enables tracking of successful authentication with an application key. The user name is included in the audit message. • The ApplicationKeyFailed entry enables the tracking of failed authentication with an application key. The user name is included in the audit message. | Category Key: audit.AuditCategory.Authentication Message Keys • com.thingworx.things.security.SecurityMonitorThing.Logout.Audit • com.thingworx.things.security.SecurityMonitorThing.LoginSucceeded.Audit • com.thingworx.things.security.SecurityMonitorThing.LoginFailed.Audit • com.thingworx.things.security.SecurityMonitorThing.ApplicationKeySucceeded.Audit • com.thingworx.things.security.SecurityMonitorThing.ApplicationKeyFailed.Audit | ||
COLLABORATION | Actions related to collaboration entities. | Create, edit, and delete operations on blogs and wikis. | Category Key: audit.AuditCategory.Collaboration | ||
DATA_MANAGEMENT | Actions related to managing or using data. | Delete operations on data. | Category Key: audit.AuditCategory.DataManagement | ||
DATA_STORAGE | Actions related to data storage entities and related subsystems. | Create, edit, and delete operations on data tables, streams, and other data storage entities. | Category Key: audit.AuditCategory.DataStorage | ||
DEVICE_COMMUNICATION | Action related to communication with edge devices. | The CloseWebSocketSessions service of the WSCommunicationSubsystem is audited. For details about the service, refer to the "Services" section of the topic, WebSocketCommunications Subsystem.
| Category Key: audit.AuditCategory.DeviceCommunication | ||
FILE_TRANSFER | Actions and events related to file uploads and downloads. | For file transfers, successful completion of a transfer, cancellation of a transfer, and generation of errors during a transfer. | Category Key: audit.AuditCategory.FileTransfer | ||
IMPORT_EXPORT | Actions related to import and export of data to and from ThingWorx. | Model and data import/export operations. Import of an extension. | Category Key: audit.AuditCategory.ImportExport | ||
LIFECYCLE | Actions related to a Thing-specific event, such as ThingEnable | Events such as ThingEnable and ThingDisable are generated when corresponding services are called on a Thing. Auditing of ThingStart events is disabled by default due to load during ThingWorx Platform startup and restarts. | Category Key: audit.AuditCategory.Lifecycle Message Keys: • com.thingworx.things.Thing.ThingStart.Audit • audit.EntityLifecycle.Enable • audit.EntityLifecycle.Disable | ||
Create and delete operations related to all entities, including Thing Groups | The audited operations and messages follow: • User X created new Thing Group Y — audit message is "Created type "name".. • User X deleted Thing Group Y — audit message is "Deleted type "name". • User X deleted all child members of Thing Group Y — audit message is "Deleted all child members of typename. | Category Key: audit.LifeCycle Message Keys: • audit.LifeCycle.Created • audit.LifeCycle.Deleted • audit.LifeCycle.DeletedAll | |||
THINGGROUPMEMBERSHIPS | Add operations related to Thing Group memberships | The audited operations and audit messages follow: • User X added Thing 123 as child member of Thing Group Y — audit message is "Added Thing thingName as child member of Thing Group thingGroupName • User X added Thing Group ABC as child member of Thing Group Y— audit message is "Added Thing Group thingGroupName1 as child member of Thing Group thingGroupName2 | Category Key: audit.ThingGroupMemberships Message Keys: • com.thingworx.thinggroups.ThingGroup.AddedThingAsChildMember • com.thingworx.thinggroups.ThingGroup.AddedThingGroupAsChildMember | ||
Delete operations related to Thing Group memberships | The audited operations and audit messages follow: • User X deleted Thing 123 as child member of Thing Group Y — audit message is "Deleted Thing thingName as child member of Thing Group thingGroupName" • User X deleted Thing Group ABC as child member of Thing Group Y — audit message is "Deleted Thing Group thingGroupName1 as child member of Thing Group thingGroupName2" • User X deleted all child members (Things and/or ThingGroups) of Thing Group Y— audit message is "Deleted all child members of Thing Group thingGroupName" | Category Key:audit.ThingGroupMemberships Message Keys: • com.thingworx.thinggroups.ThingGroup.DeletedThingAsChildMember • com.thingworx.thinggroups.ThingGroup.DeletedThingGroupAsChildMember • com.thingworx.thinggroups.ThingGroup.DeletedAllChildMembers | |||
MODELING | Actions related to Modeling entities. When an entity is created, the system generates an audit message that includes the Owner assigned to the new entity. Note that the Owner of an entity is set automatically to the user name that created the entity. The system generates the audit message when any of the ways to create an entity is used: • Through PUTcall in Composer • Through a call to a Create API, a Clone API, or to the SetOwnerAPI Any user who is authorized to view the Audit subsystem can view reports regarding changes in ownership. | Create, edit, delete operations on Things, Thing Templates, Thing Shapes, Data Shapes, networks, projects, models, tags. The format of the audit message is: "Created <Source Type> <Source> with owner <username of owner>." Where: • Source Type is the kind of entity created. For example, a Thing. • Source is the name of the new entity. • The owner shows the username of the user performing the create action. | Category Key: audit.AuditCategory.Modeling Message key is: audit.EntityLifecycle.Create. | ||
REMOTE_ACCESS | Actions related to remote access (tunneling). | • User session start — The audit message includes the user id and start time of the session. • User session stop — The audit message includes the user id, end time, and total time of the session. | Category Key: audit.AuditCategory.RemoteAccess | ||
SCM (Software Content Management) | Actions related to packages, deployments, and configuration changes. | Create, edit, publish, and delete packages. Create, start, transition, and delete deployments. Includes test and actual deployments, assets specified for a test deployment, and the success or failure of package installation. Configuration changes for automatic purging and for concurrent deployments. Information for package deployments Includes the user id when the deployment is initiated directly by a user. When a deployment is initiated by the platform, SYSTEM is listed as the entity deploying the package . | Category Key: audit.AuditCategory.SoftwareManagement | ||
SECURITY_CONFIGURATION | Actions related to security entities and permissions, including users, user groups, Thing Groups, organizations, application keys, directory services, and authenticators. Whenever the ownership changes for an entity, an audit message is generated. An Owner can be changed through Composer, through an API call, or through an import of an entities XML file An ownership audit message is not generated in the following cases: • The Audit subsystem is disabled. • The entity has been updated without ownership changes. • The SetOwner API call set the same owner that was already the owner of the entity. | Create, edit, and delete operations on users, user groups, Thing Groups, organizations, application keys, directory services, and authenticators. Enables tracking of UserGroup changes. The audit.Groups.Added entry is generated whenever a User or UserGoup is added as a member of another User Group. The audit.Groups.Removed entity is generated whenever a User or User Group is removed from a User Group. Entity permission changes (all entity types). Refer to the section above, Auditing the Switching of Security Context.. The general format of the ownership change audit message follows: "Owner for <Source Type> <Source> changed from <original owner username> to <new owner username>." Where: • Source Type is the kind of entity whose owner has changed. For example, a Thing. • Source is the name of the entity whose owner has changed. • The original owner username shows the username of the user performing the change action. • The new owner username is the username of the new owner. | Category Key: audit.AuditCategory.SecurityConfiguration Message Keys: • audit.Groups.Added • audit.Groups.Removed • audit.entity.ownership.change | ||
Administrator enabling and disabling Thing Group visibility permission delegation in User Management Subsystem | The audited operations and audit messages follow: • Administrator enabled Thing Group visibility permission delegation in User Management Subsystem — audit message is "Thing Group visibility permission delegation enabled." • Administrator disabled Thing Group visibility permission delegation in User Management Subsystem — audit message is "Thing Group visibility permission delegation disabled." | Category Key: audit.AuditCategory.SecurityConfiguration Message Keys: • com.thingworx.thinggroups.ThingGroup.VisibilityPermissionDelegationEnabled • com.thingworx.thinggroups.ThingGroup.VisibilityPermissionDelegationDisabled | |||
SYSTEM | Actions related to system entities. | Create, edit, and delete operations on localization tables, resources, subsystems, and logs. Subsystem configuration changes and actions, including start, stop, and restart. All subsystem-related entries are in this category and will not appear at all in other categories.
| Category Key: audit.AuditCategory.System | ||
VISUALIZATION | Actions related to Visualization entities. | Create, edit, and delete operations on mashups, masters, gadgets, dashboards, menus, media entities, style definitions, and state definitions. | Category Key: audit.AuditCategory.Visualization |
Enabling and Disabling Audit Events
When the ThingWorx Platform is restarted, all Things trigger the ThingStart event. Auditing all these events causes a long startup time for the platform. To avoid that situation, the ThingStart event in the LIFECYCLE category is disabled by default. The following table shows other audit messages that are disabled by default:
Audit Category | Audit Message Key |
|---|---|
AUDIT | • audit.Audit.ExecutedService.QueryAuditHistory • audit.Audit.ExecutedService.QueryAuditHistoryWithQueryCriteria • QueryAuditHistoryContextConstrained • audit.Audit.ExecutedService.GetAuditEntryCount |
THINGGROUPMEMBERSHIPS | • com.thingworx.thinggroups.ThingGroup.AddedThingAsChildMember • com.thingworx.thinggroups.ThingGroup.DeletedThingAsChildMember • com.thingworx.thinggroups.ThingGroup.AddedThingGroupAsChildMember • com.thingworx.thinggroups.ThingGroup.DeletedThingGroupAsChildMember • com.thingworx.thinggroups.ThingGroup.DeletededAllChildMembers |
LIFECYCLE | audit.Lifecycle.ThingStart |
If you still want to audit any of the operations listed in the table above, you can enable the messages by editing the platform configuration file, platform-settings.json. In addition, if you want to disable categories and event messages that you do not use, you can do so by editing this configuration file.
 | You cannot enable or disable individual events in the LIFECYCLE category. You must enable or disable all of them, using the notation, "MessageKeys" : ["ALL"]. |
To check which categories are disabled, go to ThingWorx Composer and in the left navigation panel, go to > and search for disabled audit categories.
 | Making changes to the platform-settings.json file for audit categories and event messages requires a restart of the ThingWorx Platform instance. This type of change should be made as infrequently as possible. |
The platform-settings.json file does not contain a section for Audit. To enable or disable categories and messages, you need to add a JSON structure to the file. For the ThingWorx Platform instance for which you want audit messages, you need a user that has permissions to locate and edit the platform-settins.json file and add the appropriate configuration.
| | The Audit section must be added as a sibling node to the JSON entry of PlatformSettingsConfig. It can be located before or after the PlatformSettingsConfig node, but it must be at the same node level. |
To enable or disable the auditing of specific events:
1. Navigate to the ThingWorxPlatform directory and open the platform-settings.json file in a text editor.
2. At the end of the file, create a new group, called "Audit", and add the groups and keys for categories and event messages, following these patterns:
◦ Each category must have its own "CategoryKey" entry in the "Enabled" group or the "Disabled" group.
◦ Each category key must be followed by a "MessageKeys" entry. To enable or disable the entire category, you must have both the category key and a message key similar to the following example:
"CategoryKey" : "audit.AuditCategory.Audit"
"MessageKeys" : ["ALL"]
◦ The "CategoryKey" accepts the key string for the category shown in the table, Table 120. For example, audit.AuditCategory.Lifecycle.
◦ The "CategoryKey" value is always delimited by double quotation marks. The line always ends with a comma.
◦ A "MessageKeys" entry always uses square brackets around the value, whether there is just one message key or there are multiple message keys. If there are multiple message keys, use a comma at the end of each key, except for the last one.
◦ The "MessageKeys" accept the literal string ["ALL"] as well as the message keys shown in the table, Table 120.
◦ Make sure that you use the proper brackets for each group, as shown in the example below.
"PlatformSettingsConfig:: {
"BasicSettings":( . . .
}
}
"Audit": {
"Disabled": [{
"CategoryKey": "audit.AuditCategory.Collaboration",
"MessageKeys": ["ALL"]
}, {
"CategoryKey": "audit.AuditCategory.Authentication",
"MessageKeys": [
"com.thingworx.things.security.SecurityMonitorThing.LoginSucceeded.Audit",
"com.thingworx.things.security.SecurityMonitorThing.ApplicationKeySucceeded.Audit"
]
}],
"Enabled": [{
"CategoryKey": "audit.AuditCategory.Lifecycle",
"MessageKeys": ["ALL"]
}, {
"CategoryKey": "audit.AuditCategory.Authentication",
"MessageKeys": [
"com.thingworx.things.security.SecurityMonitorThing.LoginFailed.Audit"
]
}, {
"CategoryKey": "audit.AuditCategory.ThingGroupMemberships",
"MessageKeys": [
"com.thingworx.thinggroups.ThingGroup.DeletdThingAsChildMember"
"com.thingworx.thinggroups.ThingGroup.DeletedThingGroupAsChildMember"
"com.thingworx.thinggroups.ThingGroup.DeletedAllChildMembers"
]
}, {
"CategoryKey": "audit.AuditCategory.Authentication",
"MessageKeys": [
"com.thingworx.things.security.SecurityMonitorThing.LoginFailed.Audit"
]
}]
}
3. Save and close the file.
4. As with any change to the platform-settings.json file, you need to stop and restart the ThingWorx Platform.
For more information, refer to the section,"Adding an Audited Event Section to platform-settings.json", in the topic, platform-settings.json Configuration Details.