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".

Important

The CSV handler does not sanitize messages when writing to CSV log files.

Do not open CSV logs in spreadsheets and 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<single-character string>,
      "delimiterChar": configuration expression<single-character 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>
    },
    "fileRetention": {
      "maxDiskSpaceToUse": configuration expression<number>,
      "maxNumberOfHistoryFiles": configuration expression<number>,
      "minFreeSpaceRequired": configuration expression<number>,
      "rotationRetentionCheckInterval": 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>, ... ]
    }
  }
}

The values in this configuration object can use expressions as long as they resolve to the correct types for each field. For details about expressions, see "Expressions".

Configuration

The "config" object has the following properties:

"name": configuration expression<string>, required

The name of the event handler.

"logDirectory": configuration expression<string>, required

The file system directory where log files are written.

"topics": array of configuration expression<string>, required

An array of one or more topics that this event handler intercepts. IG 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 access audit 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 IG 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, see "Recording 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<single-character string>, optional

The character used to quote CSV entries.

Default: "

"delimiterChar": configuration expression<single-character string>, optional

The character used to delimit CSV entries.

Default: ,

"endOfLineSymbols": configuration expression<string>, optional

The character or characters that separate a line.

Default: system-dependent line separator defined for the JVM

"buffering": object, optional

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:

"enabled": configuration expression<boolean>, optional

Whether log buffering is enabled.

Default: false

"autoFlush": configuration expression<boolean>, optional

Whether events are automatically flushed after being written.

Default: true

"security": configuration expression<object>, optional

Security settings for CSV log files. These settings govern tamper-evident logging, whereby messages are signed. By default tamper-evident logging is not 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. For details, see "Preparing a Keystore for Tamper-Evident Logs".

"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. For details, see "Preparing a Keystore for Tamper-Evident Logs".

"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. For details, see "Preparing a Keystore for Tamper-Evident Logs".

"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.

For information about supported formats for duration, see duration.

"fileRetention": object, optional

File retention settings for CSV log files.

The file retention object has the following fields:

"maxDiskSpaceToUse": configuration expression<number>, optional

The maximum disk space in bytes the audit logs can occupy. A setting of 0 or less indicates that the policy is disabled.

Default: 0

"maxNumberOfHistoryFiles": configuration expression<number>, optional

The maximum number of historical log files to retain. A setting of -1 disables pruning of old history files.

Default: 0

"minFreeSpaceRequired": configuration expression<number>, optional

The minimum free space in bytes that the system must contain for logs to be written. A setting of 0 or less indicates that the policy is disabled.

Default: 0

"fileRotation": object, optional

File rotation settings for log files.

The file rotation object has the following fields:

"rotationEnabled": configuration expression<boolean>, optional

Whether file rotation is enabled for 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.

For information about supported formats for duration, see duration.

"rotationTimes": array of configuration expression<duration>, optional

The durations, counting from midnight, 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.

For information about supported formats for duration, see duration.

"rotationRetentionCheckInterval": configuration expression<duration>, optional

The time interval after which to check file rotation and retention policies for updates.

Default: 5 seconds

For information about supported formats for duration, see duration.

Preparing a Keystore for Tamper-Evident Logs

Tamper-evident logging depends on a public key/private key pair and on a secret key that are stored together in a JCEKS keystore. Follow these steps to prepare the keystore:

  1. Generate a key pair in the keystore.

    The CSV event handler expects a JCEKS-type keystore with a key alias of Signature for the signing key, where the key is generated with the RSA key algorithm and the SHA256withRSA signature algorithm: 

    $ keytool \
 -genkeypair \
 -keyalg RSA \
 -sigalg SHA256withRSA \
 -alias "signature" \
 -dname "CN=openig.example.com,O=Example Corp,C=FR" \
 -keystore /path/to/audit-keystore \
 -storetype JCEKS \
 -storepass password \
 -keypass password

    Note

    Because KeyStore converts all characters in its key aliases to lower case, use only lowercase in alias definitions of a KeyStore.

  2. Generate a secret key in the keystore.

    The CSV event handler expects a JCEKS-type keystore with a key alias of Password for the symmetric key, where the key is generated with the HmacSHA256 key algorithm and 256-bit key size: 

    $ keytool \
 -genseckey \
 -keyalg HmacSHA256 \
 -keysize 256 \
 -alias "password" \
 -keystore /path/to/audit-keystore \
 -storetype JCEKS \
 -storepass password \
 -keypass password

  3. Verify the content of the keystore: 

    $ keytool \
 -list \
 -keystore /path/to/audit-keystore \
 -storetype JCEKS \
 -storepass password

Keystore type: JCEKS
Keystore provider: SunJCE

Your keystore contains 2 entries

signature, Nov 27, 2015, PrivateKeyEntry,
Certificate fingerprint (SHA1): 4D:CF:CC:29:...:8B:6E:68:D1
password, Nov 27, 2015, SecretKeyEntry,

Example

For information about how to record audit events in a CSV file, see "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/audit-keystore",
    "password": "password",
    "signatureInterval": "10 seconds"
  }
}
Read a different version of :