3.27. Audit
 |
The Audit section of the Remote Config properties configures the DataHub Audit feature. . |
The DataHub Audit capability supports several operational needs, including compliance, security forensics, change accountability and operational visibility. Addressing these can be critical for organizations that need to satisfy regulatory and governance requirements. For more discussion about reasons for using this feature, see Using Audit.
The audit capability can be used to monitor security events, configuration changes, connection activity, and other significant actions for compliance, forensic analysis, and operational oversight. In this kind of restricted and controlled environment, the server is often locked down and DataHub software runs as a service (without access to the native DataHub UI). Instead, the DataHub administrator is expected to work with Remote Config. By restricting access to the server, even the administrator would not have routine access to the file system and would be unable to compromise DataHub audit capabilities.
The Audit configuration is organized into three tabs: Audit, Local Storage, and Git.
Audit Tab
The Audit tab contains the master enable switch, locking controls, event selection, and data point auditing.
General Settings
- Enable audit information
Activates the audit subsystem. When enabled, DataHub records audit events as data points in the audit domain and dispatches them to any configured storage backends (e.g., local database). When the configuration is locked, this checkbox cannot be cleared.
- Domain name
The DataHub domain used for audit data points. The default value is
Audit. The name must start with a letter and contain only letters, digits, or underscores (pattern:^\p{L}\w*$). Audit events are published as data points underDomainName:Category.CategoryPath.EventName
Locking
The Locking group controls whether the audit configuration can be narrowed or disabled. Locking is designed for environments where audit integrity must be protected from tampering.
- Lock configuration
When checked, the audit configuration is locked. A locked configuration enforces the following restrictions:
Auditing cannot be disabled.
Local storage cannot be disabled.
Retention days cannot be shortened (but can be set to
0to extend to infinite retention).The domain name cannot be changed.
Previously enabled audit events cannot be disabled.
Previously selected data points cannot be removed.
Git tracking cannot be disabled.
New events, data points, and features can still be added. The configuration can be expanded but not narrowed.
When permanent lock is not enabled, the Lock configuration checkbox can be cleared to unlock the configuration. Until the Permanent Lock is enabled, locking can be enabled, disabled and re-enabled. This gives the administrator an opportunity to experiment and confirm locking behavior before committing to permanenting locking the audit configuration.
Enables permanent, automatic locking. When permanent lock is active, the configuration will be automatically locked as soon as the audit trail is enabled.
![[Warning]](images/warning_2116355759.png)
Once permanent lock is enabled, it cannot be disabled through the user interface — this is a permanent, irreversible action. The only way to reverse permanent lock is to manually edit the configuration XML file on the server filesystem.
Enable Audit Events
The Enable Audit Events group provides two views for selecting which audit events to record: By Category and By Source.
- By Category
Displays audit events organized by category in a hierarchical tree. Categories group events by what they record — for example,
Security.Authenticationgroups all authentication events regardless of which component emits them. This is the recommended view for most configuration tasks.Each item in the tree has a checkbox. Categories use tri-state checkboxes: checked means all descendant events are enabled, unchecked means all are disabled, and indeterminate (filled square) means some events are enabled and some are disabled.
When all events under a category are enabled, the DataHub instance stores a category-level enable directive. Any new events registered under that category in the future (for example, by a plugin update or a newly loaded component) are automatically enabled.
For more information about specific categories, please see Selecting Audit Events in the Using Audit chapter
- By Source
Displays audit events organized by the component that emits them. Each source appears as a top-level node with its associated events listed beneath it. This view is useful for enabling or disabling all events from a specific component. Each source has a tri-state checkbox that reflects the aggregate state of its events.
When the configuration is locked, enabled events cannot be unchecked. New events can still be enabled.
Audit Data Points
The Audit data points group displays a tree view of DataHub domains and data points with checkboxes. Selecting a data point causes value changes on that point to be recorded as audit events.
The audit domain itself (the domain specified in the Domain name field) is excluded from the tree to prevent circular monitoring — audit events writing to audit data points that trigger further audit events.
When the configuration is locked, previously selected data points cannot be removed, but new data points can be added.
Local Storage Tab
The Local Storage tab configures persistent storage of audit events in a local SQLite database.
- Enable local storage
When checked, audit events are written to a local SQLite database file (
Audit.sqlite) in the plugin's configuration directory. The database file is created automatically when local storage is first enabled. When the configuration is locked, this checkbox cannot be cleared.- Retention (days)
The number of days to retain audit records. Records older than this value are automatically purged every 6 hours. A value of
0means records are retained indefinitely. When the configuration is locked, the retention period cannot be shortened but can be extended or set to0.
Report
The Report tool provides a convenient mechanism to export and then inspect the stored audit data. This is necessary because the actual database is stored on the local file system and, in a restricted and controlled environment, is not accessible to an administrator or auditor. The data can be exported as a CSV file, which can be loaded into another tool for analysis. This group is available only when a local database exists.
- Start date / End date
Date pickers that define the range of audit records to include in a CSV export.
Exports audit records within the selected date range to a CSV file. The CSV contains the following columns:
Column Description IdUnique record identifier. EventThe event name. CategoryThe full category path. SourceThe component that emitted the event. SeverityThe severity level. MessageA human-readable description of what happened. UsernameThe user involved, if applicable. AddressThe IP address or endpoint involved, if applicable. TimestampThe date and time of the event. DetailsAdditional structured information about the event. Updates the displayed database size and record count for the selected date range.
Git Tab
The Git tab configures Git-based tracking of configuration changes. When enabled, the DataHub instance maintains a local Git repository of its configuration files. Changes are committed automatically, providing a detailed version history of all configuration modifications.
- Use Git for configuration change tracking
Enables local Git-based configuration tracking.
Committer Identity
The committer identity fields are located in the Local Git repository group. Changes can only be committed to Git when associated with a name and email address. However, neither name nor email address are validated or used by the DataHub instance (or Git).
- Your name
The full name used in Git commits. This field remains editable even when the configuration is locked.
- Your email
The email address used in Git commits. This field remains editable even when the configuration is locked.
Local Git Repository Status
The Status sub-group within Local Git repository displays the current state of local version tracking.
- Status indicator and state
Displays the current state of the local Git repository with an icon (green check mark for initialized, red cancel icon for not initialized) and the current working tree state (such as
Local Git repository existsor a descriptive error).- Last commit details
Displays a detailed, grayed-out italic summary of the most recent local Git commit (including the count and names of files that were added, modified, or deleted). This summary is updated automatically after every configuration change is saved.