Audit Subsystem
The audit subsystem provides a built-in auditing capability for system administrators, application administrators, and auditors of the IoT solution.
To ensure the integrity of audit data, the logs cannot be modified. Further, the audit logs do not contain any sensitive information.
When enabled and the Auto Start option is selected, the audit subsystem starts when the ThingWorx Platform starts and stops when the instance stops. It supports the following auditing capabilities:
• Searching for audit entries (use the QueryAuditHistory service)
• Archiving audit entries to offline storage (automatically performed daily by default)
• Exporting audit data, using the language selected for the export
• Purging online audit data on the basis of the specified number of days that the audit data should remain online and on the number of rows to keep online, which are both set in the configuration of the audit subsystem.
• Auditing start, stop, and restart actions
• 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. For details, see Auditing the Switching of Security Context .
 |
By default, the audit subsystem is disabled for a new installation or an upgrade. If you are a system administrator, see Enabling the Audit Subsystem to learn how to enable the subsystem.
|
What Activities Are Audited?
Activities on ThingWorx Platform can generate events. For example, the start of a file download generates an event. You may want to subscribe to such events, using them to trigger other actions. Auditing exists for the following types of built-in events in ThingWorx:
• Thing-related events — ThingStart, FileTransfer, and RemoteSession.
• Security Monitoring events — LoginSucceeded, LoginFailed, ApplicationKeySucceeded, and ApplicationKeyFailed.
• Subsystem events — As of v.8.5.0 of ThingWorx Platform, the start, stop, and restart actions on the subsystems are audited. Note that restart actions show a restart audit message and the start/stop audit messages in the audit log.
|
|
The ApplicationKeySucceeded and ApplicationKeyFailed events are triggered only for HTTP/HTTPS REST connections.
|
Typically, these events are triggered by an operation on an entity in ThingWorx:
• Thing-related events are triggered by operations that can be performed on Things, such as starting and restarting a Thing, transferring files using the file transfer subsystem, and tunneling (RemoteSession event).
• Security monitoring events are for users accessing ThingWorx.
• Subsystem events are fired when a subsystem is started, stopped, or restarted.
|
|
Auditing of user-defined (custom) events is not supported.
|
When a subsystem is restarted, based on subsystem status, either two or three audit messages are inserted. Consider the following scenarios:
• Scenario: If the status of the subsystem is RUNNING, the Restart operation inserts three messages:
◦ System Subsystem "FederationSubsystem" restarted
◦ System Subsystem "FederationSubsystem" stopped
◦ System Subsystem "Federation Subsystem" started
• Scenario: If the current status of the subsystem is not RUNNING, the Restart operation inserts only two messages because the Stop operation is not performed:
◦ System Subsystem "FederationSubsystem" restarted
◦ System Subsystem "Federation Subsystem" started
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__.