Audit Subsystem
The audit subsystem provides a built-in auditing capability for system administrators, application administrators, and auditors of an organization's IoT solution. By default the audit subsystem is disabled on platform start. You must enable it.
The audit subsystem is intended to provide the information you need to answer the following questions:
• Do we meet compliance requirements?
• What has a rogue employee done in the system?
• Who made what changes and when?
 |
It is important to remember that the Audit Log is not intended to be another debug log. The Audit Log provides information about who made what changes when and any other information that may need to be captured for compliance reasons.
|
The initial release of the Audit Subsystem was part of ThingWorx Platform v.8.2.0. That version is referred to as the Data Table implementation. As of ThingWorx Platform, v.9.0.0, another implementation, referred to as the Direct Persistence implementation, is also available for the Audit Subsystem. The Direct Persistence implementation is a completely new implementation that provides a more robust and performant auditing tool. For backwards compatibility, the Data Table implementation is the default implementation used when you enable the Audit Subsystem. You can switch to the Direct Persistence implementation when configuring the Audit Subsystem.
|
|
PTC strongly encourages you to use the Direct Persistence implementation because the Data Table implementation will be deprecated in a future release of ThingWorx Platform. In addition, the QueryAuditHistory service will be deprecated in favor of the QueryAuditHistoryWithQueryCriteria service.
|
If you previously used the Data Table implementation, your data is preserved when you perform an upgrade. After upgrading, it is recommended that you archive any online audit data before switching to the Direct Persistence implementation.
The following sections provide details about activities that are audited as well as the features of the Audit Subsystem for the two implementations. Click the title of a section to display its content. To hide the content, click the title again.
Audit Subsystem Features, Data Table Implementation
The Data Table implementation supports the following auditing capabilities:
• Searching for audit entries
• Archiving online audit entries to offline storage
• Exporting online and offline audit data using the language selected for the export
• Purging online audit data and cleanup of archived (offline) audit data
When the Audit Subsystem is enabled and the Auto Start option is selected, the subsystem starts when the ThingWorx Platform starts and stops when the platform stops.
As of v.8.5 of ThingWorx Platform, the 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, refer to Auditing
the Switching of Security Context .
 | For organizations that must collect and retain large amounts of audit data, the Direct Persistence implementation is strongly recommended for best performance and additional features. By default, the subsystem is disabled for a new installation or an upgrade. In addition, the Data Table implementation is enabled and the Direct Persistence implementation is disabled. If you are a system administrator and have enabled the audit subsystem, you can change the configuration of the audit subsystem to switch from the Data Table implementation to the Direct Persistence implementation. Refer to Configuration of Audit Subsystem. |
Audit Subsystem in ThingWorx Platform, Direct Persistence
The Direct Persistence implementation provides all of the auditing capabilities of the Data Table implementation and more. With the addition of this implementation in ThingWorx Platform v.9.0.0, the Audit Subsystem has significant changes that provide the following improvements in performance and scalability:
• Persistence of audit data uses the Persistence Provider of the ThingWorx Platform. This implementation can be used with PostgreSQL or MSSQL databases used as Persistence Providers for ThingWorx Platform instances.
 | It is not possible to change the configuration of the platform Persistence Provider through the Configuration page of the Audit Subsystem |
• Querying is more performant.
• Querying is configurable to adapt to the needs and use cases of different organizations. The query services accept localization tokens for the category parameter of a query.
The use of a database in the Direct Persistence implementation enhances the querying capability. In addition to filtering and sorting that are available in the Data Table implementation, you can specify pagination properties when using the QueryAuditHistory and QueryAuditDataWithQueryCriteria services with the Direct Persistence implementation.
| | The QueryAuditHistory and QueryAuditHistoryWithQueryCriteria services do not perform any visibility checks. Everything is visible to the users who have permissions to execute this service. You can run a query service directly from the Services page of the audit subsystem. You can also run a query indirectly by using the Audit Log, which is available through Monitoring in the ThingWorx Composer UI. Users with appropriate access can run the service manually from ThingWorx Composer. Developers can use the ThingWorx REST APIs to run the service programmatically. |
• Another QueryAuditHistory service is available from the Thing level. This service restricts queried data to the current Thing and current user only. If the user that executes this service is in the Auditors group, the user can see actions of all other users but only for that Thing.
| | The Auditors user group is available, starting with ThingWorx Platform v.9.0.0. |
• In addition to the ExportAuditData service, the Direct Persistence implementation provides the ExportOnlineAuditData service. For details about this service, refer to Exporting Online Audit Data.
• The Direct Persistence implementation also provides a less expensive storage option than the Data Table implementation with the ArchiveAuditHistoryDirectPersistence[DATETIME[) service. This service copies the audit entries from the ThingWorx database into a file within the configured file repository for Audit data, under the AuditArchiveDirectPersistence folder.
• The Audit Subsystem can support customers with large and small audit data needs. Guidance is provided on how to configure the subsystem, based on specific data retention needs. Refer to Configuration of the Audit Subsystem.
• A category to track the execution of the services of the Audit Subsystem is provided, called AUDIT.
• The subsystem has additional audit messages for the categories. For more information about audit messages for the Direct Persistence implementation, refer to ThingWorx Audit Messages.
• If the set of Audit categories provided in the subsystem does not meet all of your organization’s requirements, developers can create custom audit categories and messages. Refer to Custom Audit Categories .
• BETA ONLY: The Direct Persistence implementation also improves the usability of the Audit Subsystem by providing a new user interface within ThingWorx Composer for querying audit data. Available as a tab in the Monitoring section of Composer, this new UI provides filtering options for queries as well as pagination options for query results.
Audit logs may contain sensitive data. To ensure the integrity of audit data, make sure that you limit access using ThingWorx permissions capabilities. For details, refer to Security for Audit Activities.
What Activities Are Audited?
Both implementations monitor the ThingWorx Platform for events generated by various components and extensions. Activities such as transferring files using the File Subsystem of the platform can generate events. 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 — FileTransfer and RemoteSession
| | The ThingStart event is disabled by default as of v.9.0.0 of the ThingWorx Platform. To enable it, edit the configuration file, platform-settings.json. If enabled, the event is audited. |
• Security Monitoring events — LoginSucceeded, LoginFailed, ApplicationKeySucceeded, and ApplicationKeyFailed. In addition, switching of security context is audited.
| | The ApplicationKeySucceeded and ApplicationKeyFailed events are triggered only for HTTP/HTTPS REST connections. |
• Subsystem events — Updates to the configuration of a subsystem are audited. In addition, calls to audit services such as archive, export, clean-up, and purge, are audited in the category, AUDIT.
| | Start, stop, and restart actions on the subsystems are not audited. |
Typically, the following 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 transferring files using the file transfer subsystem and tunneling (RemoteSession event).
• Security monitoring events are for users accessing ThingWorx.
Customizing the Audit Functionality
The custom audit feature has the following components:
• Custom Audit Category
• Custom Audit Message
• Custom Audit Event
There are two ways to create a custom audit category and a custom audit message token:
• By creating a new back end Java extension for the platform, using the ThingWorx Java SDK. Refer to Creating Custom Audit Categories Using an Extension. The extension should include a Localization Table so that, when the extension is imported into the ThingWorx Platform, the Localization Table with the added Audit Category Token and Audit Message Token are imported.
• For a Custom Audit Category, by modifying the ThingWorx Localization table through ThingWorx Composer. Refer to Custom Audit Categories .
Custom Audit Events must be defined in the code for your extension because two aspects are required. These aspects are not exposed in the Composer user interface, which means that you cannot add a custom event from Composer. These aspects tell the platform that the event should be audited. The following figure highlights these two aspects:
