CsvAuditEventHandler
An audit event handler that responds to events by logging messages to files in comma-separated variable (CSV) format.
Declare the configuration in an audit service, as described in AuditService.
|
The CSV handler doesn’t sanitize messages when writing to CSV log files. Don’t open CSV logs in spreadsheets or other applications that treat data as code. |
Usage
{
"class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
"config": {
"name": configuration expression<string>,
"logDirectory": configuration expression<string>,
"topics": [ configuration expression<string>, ... ],
"enabled": configuration expression<boolean>,
"formatting": {
"quoteChar": configuration expression<string>,
"delimiterChar": configuration expression<string>,
"endOfLineSymbols": configuration expression<string>
},
"buffering": {
"enabled": configuration expression<boolean>,
"autoFlush": configuration expression<boolean>
},
"security": {
"enabled": configuration expression<boolean>,
"filename": configuration expression<string>,
"password": configuration expression<string>,
"signatureInterval": configuration expression<duration>
},
"fileRotation": {
"rotationEnabled": configuration expression<boolean>,
"maxFileSize": configuration expression<number>,
"rotationFilePrefix": configuration expression<string>,
"rotationFileSuffix": configuration expression<string>,
"rotationInterval": configuration expression<duration>,
"rotationTimes": [ configuration expression<duration>, ... ]
},
"fileRetention": {
"maxDiskSpaceToUse": configuration expression<number>,
"maxNumberOfHistoryFiles": configuration expression<number>,
"minFreeSpaceRequired": configuration expression<number>
},
"rotationRetentionCheckInterval": configuration expression<duration>
}
}The values in this configuration object can use expressions as long as they resolve to the correct types for each field. Learn more about expressions in Expressions.
Configuration
"name": configuration expression<string>, required-
The name of the event handler.
"logDirectory": configuration expression<string>, required-
The file system directory where this event handler writes log files.
When multiple AuditServices are defined in the deployment, prevent them from logging to the same audit logging file by setting different values for
logDirectory. "topics": array of configuration expression<strings>, required-
One or more topics that this event handler intercepts. PingGateway can record the following audit event topics:
-
access: Log access audit events. Access audit events occur at the system boundary, and include the arrival of the initial request and departure of the final response.To record
accessaudit events, configure AuditService inline in a route, or in the heap. -
customTopic: Log custom audit events. To create a topic for a custom audit event, include a JSON schema for the topic in your PingGateway configuration.
To record custom audit events, configure AuditService in the heap, and refer to it from the route or subroutes. For an example of how to set up custom audit events, refer to Record custom audit events.
-
"enabled": configuration expression<boolean>, optional-
Whether this event handler is active.
Default: true
"formatting": object, optional-
Formatting settings for CSV log files.
The formatting object has the following fields:
"quoteChar": configuration expression<string>, optional-
A single character to quote CSV entries.
Default:
" "delimiterChar": configuration expression<string>, optional-
A single character to delimit CSV entries.
Default:
, "endOfLineSymbols": configuration expression<string>, optional-
A character or characters to separate a line.
Default: System-dependent line separator defined for the JVM
"buffering": object, optional-
Don’t enable
bufferingwhensecurityis configured for tamper-evident logging.Buffering settings for writing CSV log files. The default is for messages to be written to the log file for each event.
The buffering object has the following fields:
"security": object, optional-
When
securityis configured for tamper-evident logging, don’t enablebuffering.Security settings for CSV log files. These settings govern tamper-evident logging, whereby messages are signed. By default tamper-evident logging isn’t enabled.
The security object has the following fields:
"enabled": configuration expression<boolean>, optional-
Whether tamper-evident logging is enabled.
Default: false
Tamper-evident logging depends on a specially prepared keystore. You can find an example in Recording Access Audit Events in CSV.
"filename": configuration expression<string>, required-
File system path to the keystore containing the private key for tamper-evident logging.
The keystore must be a keystore of type
JCEKS. You can find an example in Recording access audit events in CSV. "password": configuration expression<string>, required-
The password for the keystore for tamper-evident logging.
This password is used for the keystore and for private keys. You can find an example in Recording access audit events in CSV.
"signatureInterval": configuration expression<duration>, required-
The time interval after which to insert a signature in the CSV file. This duration must not be zero, and must not be unlimited.
"fileRotation": object, optional-
File rotation settings for log files.
"rotationEnabled": configuration expression<boolean>, optional-
A flag to enable rotation of log files.
Default: false.
"maxFileSize": configuration expression<number>, optional-
The maximum file size of an audit log file in bytes. A setting of 0 or less indicates that the policy is disabled.
Default: 0.
"rotationFilePrefix": configuration expression<string>, optional-
The prefix to add to a log file on rotation. This has an effect when time-based file rotation is enabled.
"rotationFileSuffix": configuration expression<string>, optional-
The suffix to add to a log file on rotation, possibly expressed in SimpleDateFormat.
This has an effect when time-based file rotation is enabled.
Default:
-yyyy.MM.dd-HH.mm.ss, where yyyy characters are replaced with the year, MM characters are replaced with the month, dd characters are replaced with the day, HH characters are replaced with the hour (00-23), mm characters are replaced with the minute (00-60), and ss characters are replaced with the second (00-60). "rotationInterval": configuration expression<duration>, optional-
The time interval after which to rotate log files. This duration must not be zero. This has the effect of enabling time-based file rotation.
"rotationTimes": array of configuration expression<durations>, optional-
The durations, counting from midnight UTC, after which to rotate files.
The following example schedules rotation six and twelve hours after midnight:
"rotationTimes": [ "6 hours", "12 hours" ]This has the effect of enabling time-based file rotation.
"fileRetention": object, optional-
File retention settings for log files.
"maxNumberOfHistoryFiles": configuration expression<number>, optional-
The maximum number of historical audit files that can be stored. If the number exceeds this maximum, older files are deleted. A value of
-1disables purging of old log files.Default: 0.
"maxDiskSpaceToUse": configuration expression<number>, optional-
The maximum disk space in bytes that can be used for audit files. If the audit files use more than this space, older files are deleted. A negative or zero value indicates that this policy is disabled, and historical audit files can use unlimited disk space.
Default: 0
"minFreeSpaceRequired": configuration expression<string>, optional-
The minimum free disk space in bytes required on the system that houses the audit files. If the free space drops below this minimum, older files are deleted. A negative or zero value indicates that this policy is disabled, and no minimum space requirements apply.
Default: 0
"rotationRetentionCheckInterval": configuration expression<string>, optional-
Interval at which to periodically check file rotation and retention policies. The interval must be a duration, for example, 5 seconds, 5 minutes, or 5 hours.
PingGateway checks whether to rotate the current audit file at each interval. If so, it also checks whether to retain old audit files.
Default: 5 seconds
Example
You can find more information about how to record audit events in a CSV file in Recording Access Audit Events in CSV.
The following example configures a CSV audit event handler to write a log file /path/to/audit/logs/access.csv
that is signed every 10 seconds to make it tamper-evident:
{
"name": "csv",
"topics": [
"access"
],
"logDirectory": "/path/to/audit/logs/",
"security": {
"enabled": "true",
"filename": "/path/to/secrets/audit-keystore",
"password": "password",
"signatureInterval": "10 seconds"
}
}