Audit log filtering

Stronghold supports enabling audit devices with the filter option, which limits which records are written to a specific audit log. Filters are defined when the device is enabled and cannot be changed afterward. To change a filter, you must disable and re-enable the device.

When an audit device is enabled with a filter, each audit record is matched against a predicate expression. Only matching records are written to the log. The behavior of existing devices and new devices without a filter does not change.

Fallback devices

Filtering makes auditing more flexible, but it also creates a risk of losing records. For example, if one device is configured for operation == "read" and another for operation == "write", then records with operation == "update" will not reach either of them.

A fallback device stores all records that were not accepted by any filtered device. This helps preserve the security model in which all requests and responses should be logged before secret data is returned to the client.

Installations that rely only on filtered devices should always configure a fallback device.

Limitations

• A filter cannot be added to an already enabled device. It can only be set at enable time.
• Filtering is supported for all audit device types: file, socket, and syslog.
• You cannot specify both filter and fallback=true. These options are mutually exclusive.
• Only one fallback device is allowed.
• A fallback device can be the only audit backend, in which case it receives all records.

Filtering and test messages

When an audit device is enabled, Stronghold sends a test message. If the filter does not match the properties of that test message, the message will not appear in the device log. The enable operation is still considered successful.

Default test message properties:

Available properties for filtering

Filters can reference only the following audit record properties:

Filters use bexpr syntax and support:

• comparison operators == and !=;
• the matches operator for regular expressions;
• compound expressions with and, or, and not.

Fallback metrics

Stronghold publishes telemetry metrics related to fallback auditing:

• audit.fallback.success increments when a fallback device successfully writes an audit event that was not successfully written by any non-fallback device;
• audit.fallback.miss increments when an event was not written by any filtered device and no fallback device is configured.

The audit.fallback.miss metric is especially useful for detecting audit event loss in configurations that use filtered devices only.

Practical example

Assume you already have an audit file named stronghold-audit.log and want to route key/value (kv) events to a separate kv-audit.log file.

1. Enable a file audit device filtered by mount_type:

   stronghold audit enable                \
     -path kv-only                        \
     file                                 \
     filter='mount_type == "kv"'          \
     file_path=/logs/kv-audit.log

2. Enable a fallback device:

   stronghold audit enable                \
     -path=my-fallback                    \
     -description="fallback device"       \
     file                                 \
     fallback=true                        \
     file_path=/tmp/kv-audit.fallback.log

3. Verify that the devices are enabled:

   stronghold audit list --detailed

4. Enable the KV secrets engine:

   stronghold secrets enable -path my-kv kv-v2

5. Write a secret:

   stronghold kv put -mount=my-kv my_secret the_value=always_angry

After that, kv-audit.log will contain records for operations on my-kv, while the fallback device will capture records that do not match the filter.