Audit Log

The following article exclusively pertains to a Graylog Enterprise feature or functionality. To learn more about obtaining an Enterprise license, please contact the Graylog Sales team.

The audit log provides a detailed, immutable history of all system activities, crucial for monitoring system use, troubleshooting issues, and verifying compliance with regulations. It plays a key role in maintaining transparency and accountability in the system.

This article will review how to enable and configure the audit log and view, search, or export logs as needed.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

• You must be a Graylog administrator to enable and configure the audit log.

Highlights

The following highlights provide a summary of the key takeaways from this article:

• The audit log be enabled and configured in the Graylog Server configuration file, including settings for message signing.

• Audit logs can be viewed, searched, filtered, and exported via the Graylog interface or REST API.

• Graylog administrator privileges are required to enable, configure, and manage audit logging.

Enable Audit Logging

The audit log is disabled by default. To enable audit logging:

1. Set the following property in the Graylog configuration file to true: 

   Copy

   auditlog_message_signing_enabled = true

2. Configure audit log entries to be signed with any non-null string value of your choosing:

   Copy

   auditlog_message_signing_key = <key>

When signing is enabled, an HMAC signature is included along with each log entry. This is a cryptographic code that verifies the authenticity and integrity of a message.

Configure the Audit Log

To view your current configuration settings for the audit log in the Graylog interface, navigate to Enterprise > Audit Log and select the Configuration tab. Here you can view current settings applied for both the MongoDB Audit Log and the Log4j 2 Audit Log.

The following sections describe specific configuration properties applicable to the audit log when enabled.

Configure the MongoDB Audit Log

The default MongoDB audit log has a few configuration options:

auditlog_mongodb_keep_entries

This configures the interval at which old audit log entries in the MongoDB database are deleted. Use values like 90d (90 days) to configure the interval. The default value for this is 365d.

For example:

auditlog_mongodb_keep_entries = 365d

auditlog_mongodb_cleanup_interval

This configures the interval of the background job that periodically deletes old audit log entries from the MongoDB database. Use values like 1h (1 hour) to configure the interval. The default value is 1h. For example:

auditlog_mongodb_cleanup_interval = 1h

auditlog_mongodb_collection

This configures the name of the MongoDB collection where audit log entries will be stored.

The default value for this is audit_log. For example:

auditlog_mongodb_collection = audit_log

Configure the Log4j 2 Audit Log

The optional log4j2 audit log appender has a few configuration options.

auditlog_log4j_enabled

The log4j2 audit log appender is disabled by default, so the default value for this is false.To enable it, set this option to true. For example:

auditlog_log4j_enabled = true

auditlog_log4j_logger_name

This configures the log4j2 logger name of the audit log. The default value for this is gl-org.graylog.plugins.auditlog. For example:

auditlog_log4j_logger_name = graylog-auditlog

auditlog_log4j_marker_name

This configures the log4j2 marker name for the audit log. The default value for this is AUDIT_LOG. For example:

auditlog_log4j_marker_name = AUDIT_LOG

Configure the Log4j2 Appender

To write audit log entries into a file, enable the log4j2 appender in your Graylog configuration file and add configurations to the log4j2.xml file that is used by your server process. The log4j2.xml file location depends on your deployment method. Please check the default file locations page to confirm file location.

An existing log4j2.xml configuration file needs another <Logger/> statement in the <Loggers/> section and an additional appender in the <Appenders/> section of the file.

Review the following example with the log4j2.xml file with audit log enabled. Note that the file on your system may look different than the example. Only add the audit log-related snippets to your configuration, and do not remove anything else.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration packages="org.graylog2.log4j" shutdownHook="disable">
    <Appenders>
        <!-- Graylog server log file appender -->
        <RollingFile name="rolling-file" fileName="/var/log/graylog-server/server.log" filePattern="/var/log/graylog-server/server.log.%i.gz">
            <PatternLayout pattern="%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX} %-5p [%c{1}] %m%n"/>
            <Policies>
                <SizeBasedTriggeringPolicy size="50MB"/>
            </Policies>
            <DefaultRolloverStrategy max="10" fileIndex="min"/>
        </RollingFile>

        <!-- ##################################################### -->
        <!-- Rotate audit logs daily -->
        <RollingFile name="AUDITLOG" fileName="/var/log/graylog-server/audit.log" filePattern="/var/log/graylog-server/audit-%d{yyyy-MM-dd}.log.gz">
            <PatternLayout>
                <Pattern>%d - %m - %X%n</Pattern>
            </PatternLayout>
            <Policies>
                <TimeBasedTriggeringPolicy />
            </Policies>
        </RollingFile>
        <!-- ##################################################### -->
    </Appenders>
    <Loggers>
        <Logger name="org.graylog2" level="info"/>

        <!-- ##################################################### -->
        <!-- Graylog Audit Log.  The logger name has to match the "auditlog_log4j_logger_name" setting in the Graylog configuration file -->
        <Logger name="graylog-auditlog" level="info" additivity="false">
            <AppenderRef ref="AUDITLOG"/>
        </Logger>
        <!-- ##################################################### -->

        <Root level="warn">
            <AppenderRef ref="rolling-file"/>
        </Root>
    </Loggers>
</Configuration>

The configuration snippets between the <!-- ######### --> tags have been added to the existing log4j2.xml file. Check that the name in the <Logger/> tag matches the configured auditlog_log4j_logger_name in your Graylog server configuration. Otherwise, you will not see any log entries in the log file.

View Audit Log Entries

Audit log entries may be viewed via Enterprise > Audit Log in the web interface. You can view and export existing audit log entries in the database and search and filter for audit events you are interested in with a simple search form.

Expand Event Details

Every row in the audit event entry table is clickable and reveals the details of the audit event when clicked.

All audit events have static fields, like actor,object, etc. In addition, every event has event-specific fields. The fields on the left side, in the details, are the static fields for every event. The fields on the right side are the event-specific fields.

Search and Filter Audit Logs

To make it easier to get to the audit log entries you need, the interface provides a simple query language to search and filter the audit log entries.

Search for Text in the Message

If you want to find specific text in the audit event message, enter the word you are looking for into the search bar.

Search for Specific Fields

You can also filter the entries for specific fields, like the actor.

Or, for example, if you want to filter for all events triggered by the user jane, enter actor:jane into the search bar.

To filter for events for more than one actor, use actor:jane,john or actor:jane actor:john.

To find all audit events that have not been triggered by a user, add a - in front of the field name to negate the condition. To show all events except those created by user jane, add-actor:jane to the search field.

Mix and match several field queries to find the entries you need. Here are more examples.

• actor:jane,john -namespace:server: Retrieves all events by users jane and john that are not in the server namespace.
• index action:create: Retrieves all events which have the word index in the event message and where the action is create.
• message:index action:create: Same as above but with an explicit field selector for the message field.

Export Audit Log Entries

You can also export the results of your query as JSON or CSV for further processing.

Select the Export Results button next to the search bar allows you to export.

Export via REST API

If you want to back up the audit log entries or make them available to another system, use the Graylog REST API. For example:

# Export 20,000 audit log entries in JSON format
curl -u admin:<admin-password> http://127.0.0.1:9000/api/plugins/org.graylog.plugins.auditlog/entries/export/json?limit=20000

# Export 5,000 audit log entries with actor "jane" in CSV format
curl -u admin:<admin-password> http://127.0.0.1:9000/api/plugins/org.graylog.plugins.auditlog/entries/export/csv?limit=5000&query=actor:jane

Further Reading

Explore the following additional resources and recommended readings to expand your knowledge on related topics:

• Permission Management

• Secure Your Graylog Environment

• User Authentication