Audit kernel metricsetedit

The kernel metricset receives audit events from the Linux Audit Framework that is a part of the Linux kernel.

This metricset is available only for Linux.

How it worksedit

This metricset establishes a subscription to the kernel to receive the events as they occur. So unlike most other metricsets, the period configuration option is unused because it is not implemented using polling.

The Linux kernel only supports a single subscriber to the audit events so this metricset cannot be used simultaneously with a service like auditd. auditd should be disabled if this metricset is being used. If you wish to continue to use auditd instead of this metricset to receive audit messages from the kernel then consider using Filebeat to collect the daemon’s log files.

The Linux Audit Framework can send multiple messages for a single auditable event. For example, a rename syscall causes the kernel to send eight separate messages. Each message describes a different aspect of the activity that is occurring (the syscall itself, file paths, current working directory, process title). This metricset will combine all of the data from each of the messages into a single event.

Messages for one event can be interleaved with messages from another event. This metricset will buffer the messages in order to combine related messages into a single event even if they arrive interleaved or out of order.

Configuration optionsedit

This metricset has some configuration options for tuning its behavior. The following example shows all configuration options with their default values.

- module: audit
  metricsets: ["kernel"]
  kernel.resolve_ids: true
  kernel.failure_mode: silent
  kernel.backlog_limit: 8196
  kernel.rate_limit: 0
  kernel.include_raw_message: false
  kernel.include_warnings: false
kernel.resolve_ids
This boolean setting enables the resolution of UIDs and GIDs to their associated names. The default value is true.
kernel.failure_mode
This determines the kernel’s behavior on critical failures such as errors sending events to Auditbeat, the backlog limit was exceeded, the kernel ran out of memory, or the rate limit was exceeded. The options are silent, log, or panic. silent basically makes the kernel ignore the errors, log makes the kernel write the audit messages using printk so they show up in system’s syslog, and panic causes the kernel to panic to prevent use of the machine. Auditbeat’s default is silent.
kernel.backlog_limit
This controls the maximum number of audit messages that will be buffered by the kernel.
kernel.rate_limit
This sets a rate limit on the number of messages/sec delivered by the kernel. The default is 0, which disables rate limiting. Changing this value to anything other than zero can cause messages to be lost. The preferred approach to reduce the messaging rate is be more selective in the audit ruleset.
kernel.include_raw_message
This boolean setting causes Auditbeat to include each of the raw messages that contributed to the event in the document as a field called messages. The default value is false. This setting is primarily used for development and debugging purposes.
kernel.include_warnings
This boolean setting causes Auditbeat to include as warnings any issues that were encountered while parsing the raw messages. The default value is false. When this setting is enabled the raw messages will be included in the event regardless of the kernel.include_raw_message config setting. This setting is primarily used for development and debugging purposes.
kernel.audit_rules
A string containing the audit rules that should be installed to the kernel. There should be one rule per line. Comments can be embedded in the string using # as a prefix. The format for rules is the same used by the Linux auditctl utility. Auditbeat supports adding file watches (-w) and syscall rules (-a or -A).

Audit rulesedit

The audit rules are where you configure the activities that are audited. These rules are configured as either syscalls or files that should be monitored. For example you can track all connect syscalls or file system writes to /etc/passwd.

Auditing a large number of syscalls can place a heavy load on the system so consider carefully the rules you define and try to apply filters in the rules themselves to be as selective as possible.

The kernel evaluates the rules in the order in which they were defined so place the most active rules first in order to speed up evaluation.

You can assign keys to each rule for better identification of the rule that triggered an event and easier filtering later in Elasticsearch.

Defining any audit rules in the config causes Auditbeat to purge all existing audit rules prior to adding the rules specified in the config. Therefore it is unnecessary and unsupported to include a -D (delete all) rule.

auditbeat.modules:
- module: audit
  metricsets: ["kernel"]
  kernel.audit_rules: |
    # Things that affect identity.
    -w /etc/group -p wa -k identity
    -w /etc/passwd -p wa -k identity
    -w /etc/gshadow -p wa -k identity
    -w /etc/shadow -p wa -k identity

    # Unauthorized access attempts to files (unsuccessful).
    -a always,exit -F arch=b32 -S open,creat,truncate,ftruncate,openat,open_by_handle_at -F exit=-EACCES -F auid>=1000 -F auid!=4294967295 -F key=access
    -a always,exit -F arch=b32 -S open,creat,truncate,ftruncate,openat,open_by_handle_at -F exit=-EPERM -F auid>=1000 -F auid!=4294967295 -F key=access
    -a always,exit -F arch=b64 -S open,truncate,ftruncate,creat,openat,open_by_handle_at -F exit=-EACCES -F auid>=1000 -F auid!=4294967295 -F key=access
    -a always,exit -F arch=b64 -S open,truncate,ftruncate,creat,openat,open_by_handle_at -F exit=-EPERM -F auid>=1000 -F auid!=4294967295 -F key=access

Fieldsedit

For a description of each field in the metricset, see the exported fields section.

Here is an example document generated by this metricset:

{
    "@timestamp": "2017-04-22T21:25:01.818Z",
    "audit": {
        "kernel": {
            "action": "logged-in",
            "actor": {
                "attrs": {
                    "auid": "unset",
                    "uid": "root"
                },
                "primary": "unset",
                "secondary": "(invalid user)"
            },
            "category": "user-login",
            "data": {
                "acct": "(invalid user)",
                "addr": "179.38.151.221",
                "exe": "/usr/sbin/sshd",
                "op": "login",
                "pid": "12635",
                "terminal": "sshd"
            },
            "how": "/usr/sbin/sshd",
            "record_type": "user_login",
            "result": "fail",
            "sequence": 19955,
            "session": "unset",
            "thing": {
                "primary": "sshd",
                "secondary": "179.38.151.221",
                "what": "user-session"
            }
        }
    },
    "beat": {
        "hostname": "host.example.com",
        "name": "host.example.com"
    },
    "metricset": {
        "module": "audit",
        "name": "kernel",
        "rtt": 115
    },
    "type": "metricsets"
}