Auditd Module

« ModulesFile Integrity Module »

Elastic Docs›Auditbeat Reference [8.15]›Modules

edit

edit

The auditd module receives audit events from the Linux Audit Framework thatis a part of the Linux kernel.

This module is available only for Linux.

How it works

edit

This module establishes a subscription to the kernel to receive the eventsas they occur. So unlike most other modules, the period configurationoption is unused because it is not implemented using polling.

Useful commands

edit

When running Auditbeat with the auditd module enabled, you might findthat other monitoring tools interfere with Auditbeat.

For example, you might encounter errors if another process, such as auditd, isregistered to receive data from the Linux Audit Framework. You can use thesecommands to see if the auditd service is running and stop it:

See if auditd is running:
```
service auditd status
```
Stop the auditd service:
```
service auditd stop
```
Disable auditd from starting on boot:
```
chkconfig auditd off
```

To save CPU usage and disk space, you can use this command to stop journaldfrom listening to audit messages:

systemctl mask systemd-journald-audit.socket

Inspect the kernel audit system status

edit

Auditbeat provides useful commands to query the state of the audit systemin the Linux kernel.

See the list of installed audit rules:

auditbeat show auditd-rules

Prints the list of loaded rules, similar to auditctl -l:

-a never,exit -S all -F pid=26253-a always,exit -F arch=b32 -S all -F key=32bit-abi-a always,exit -F arch=b64 -S execve,execveat -F key=exec-a always,exit -F arch=b64 -S connect,accept,bind -F key=external-access-w /etc/group -p wa -k identity-w /etc/passwd -p wa -k identity-w /etc/gshadow -p wa -k identity-a always,exit -F arch=b64 -S open,truncate,ftruncate,creat,openat,open_by_handle_at -F exit=-EACCES -F key=access-a always,exit -F arch=b64 -S open,truncate,ftruncate,creat,openat,open_by_handle_at -F exit=-EPERM -F key=access

See the status of the audit system:
```
auditbeat show auditd-status
```
See Also
How to Modify auditd Rules in Immutable Mode and Resolve...
Prints the status of the kernel audit system, similar to auditctl -s:
```
enabled 1failure 0pid 0rate_limit 0backlog_limit 8192lost 14407backlog 0backlog_wait_time 0features 0xf
```

Configuration options

edit

This module has some configuration options for tuning its behavior. Thefollowing example shows all configuration options with their default values.

- module: auditd resolve_ids: true failure_mode: silent backlog_limit: 8192 rate_limit: 0 include_raw_message: false include_warnings: false backpressure_strategy: auto immutable: false

This module also supports thestandard configuration optionsdescribed later.

socket_type

This optional setting controls the type ofsocket that Auditbeat uses to receive events from the kernel. The twooptions are unicast and multicast.

unicast should be used when Auditbeat is the primary userspace daemon forreceiving audit events and managing the rules. Only a single process can receiveaudit events through the "unicast" connection so any other daemons should bestopped (e.g. stop auditd).

multicast can be used in kernel versions 3.16 and newer. By using multicastAuditbeat will receive an audit event broadcast that is not exclusive to aa single process. This is ideal for situations where auditd is running andmanaging the rules.

By default Auditbeat will use multicast if the kernel version is 3.16 ornewer and no rules have been defined. Otherwise unicast will be used.

immutable

This boolean setting sets the audit config as immutable (-e 2).This option can only be used with the socket_type: unicast since Auditbeatneeds to manage the rules to be able to set it.

It is important to note that with this setting enabled, if Auditbeat isstopped and resumed events will continue to be processed but theconfiguration won’t be updated until the system is restarted entirely.

resolve_ids

This boolean setting enables the resolution of UIDs andGIDs to their associated names. The default value is true.

failure_mode

This determines the kernel’s behavior on criticalfailures such as errors sending events to Auditbeat, the backlog limit wasexceeded, the kernel ran out of memory, or the rate limit was exceeded. Theoptions are silent, log, or panic. silent basically makes the kernelignore the errors, log makes the kernel write the audit messages usingprintk so they show up in system’s syslog, and panic causes the kernel topanic to prevent use of the machine. Auditbeat’s default is silent.

backlog_limit

This controls the maximum number of audit messagesthat will be buffered by the kernel.

rate_limit

This sets a rate limit on the number of messages/secdelivered 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 theaudit ruleset.

include_raw_message

This boolean setting causes Auditbeat toinclude each of the raw messages that contributed to the event in the documentas a field called event.original. The default value is false. This setting isprimarily used for development and debugging purposes.

include_warnings

This boolean setting causes Auditbeat toinclude as warnings any issues that were encountered while parsing the rawmessages. The messages are written to the error.message field. The defaultvalue is false. When this setting is enabled the raw messages will be includedin the event regardless of the include_raw_message config setting. Thissetting is primarily used for development and debugging purposes.

audit_rules

A string containing the audit rules that should beinstalled to the kernel. There should be one rule per line. Comments can beembedded in the string using # as a prefix. The format for rules is the sameused by the Linux auditctl utility. Auditbeat supports adding file watches(-w) and syscall rules (-a or -A). For more information, seeAudit rules.

audit_rule_files

A list of files to load audit rules from. This files areloaded after the rules declared in audit_rules are loaded. Wildcards aresupported and will expand in lexicographical order. The format is the same asthat of the audit_rules field.

ignore_errors

This setting allows errors during rule loading and parsingto be ignored, but logged as warnings.

backpressure_strategy

Specifies the strategy that Auditbeat uses toprevent backpressure from propagating to the kernel and impacting auditedprocesses.

The possible values are:

auto (default): Auditbeat uses the kernel strategy, if supported, orfalls back to the userspace strategy.
kernel: Auditbeat sets the backlog_wait_time in the kernel’saudit framework to 0. This causes events to be discarded in the kernel ifthe audit backlog queue fills to capacity. Requires a 3.14 kernel ornewer.
userspace: Auditbeat drops events when there is backpressurefrom the publishing pipeline. If no rate_limit is set, Auditbeat sets a ratelimit of 5000. Users should test their setup and adjust the rate_limitoption accordingly.
both: Auditbeat uses the kernel and userspace strategies at the sametime.
none: No backpressure mitigation measures are enabled.

Standard configuration options

edit

You can specify the following options for any Auditbeat module.

module

The name of the module to run.

enabled

A Boolean value that specifies whether the module is enabled.

fields

A dictionary of fields that will be sent with the dataset event. This settingis optional.

tags

A list of tags that will be sent with the dataset event. This setting isoptional.

processors

A list of processors to apply to the data generated by the dataset.

See Processors for information about specifyingprocessors in your config.

index

If present, this formatted string overrides the index for events from thismodule (for elasticsearch outputs), or sets the raw_index field of the event’smetadata (for other outputs). This string can only refer to the agent name andversion and the event timestamp; for access to dynamic fields, useoutput.elasticsearch.index or a processor.

Example value: "%{[agent.name]}-myindex-%{+yyyy.MM.dd}" mightexpand to "auditbeat-myindex-2019.12.13".

keep_null

If this option is set to true, fields with null values will be published inthe output document. By default, keep_null is set to false.

service.name

A name given by the user to the service the data is collected from. It can beused for example to identify information collected from nodes of differentclusters with the same service.type.

Audit rules

edit

The audit rules are where you configure the activities that are audited. Theserules are configured as either syscalls or files that should be monitored. Forexample 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 soconsider carefully the rules you define and try to apply filters in the rulesthemselves to be as selective as possible.

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

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

Defining any audit rules in the config causes Auditbeat to purge allexisting 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: auditd 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

Example configuration

edit

The Auditd module supports the common configuration options that aredescribed under configuring Auditbeat. Hereis an example configuration:

auditbeat.modules:- module: auditd # Load audit rules from separate files. Same format as audit.rules(7). audit_rule_files: [ '${path.config}/audit.rules.d/*.conf' ] audit_rules: | ## Define audit rules here. ## Create file watches (-w) or syscall audits (-a or -A). Uncomment these ## examples or add your own rules. ## If you are on a 64 bit platform, everything should be running ## in 64 bit mode. This rule will detect any use of the 32 bit syscalls ## because this might be a sign of someone exploiting a hole in the 32 ## bit API. #-a always,exit -F arch=b32 -S all -F key=32bit-abi ## Executions. #-a always,exit -F arch=b64 -S execve,execveat -k exec ## External access (warning: these can be expensive to audit). #-a always,exit -F arch=b64 -S accept,bind,connect -F key=external-access ## Identity changes. #-w /etc/group -p wa -k identity #-w /etc/passwd -p wa -k identity #-w /etc/gshadow -p wa -k identity ## Unauthorized access attempts. #-a always,exit -F arch=b64 -S open,creat,truncate,ftruncate,openat,open_by_handle_at -F exit=-EACCES -k access #-a always,exit -F arch=b64 -S open,creat,truncate,ftruncate,openat,open_by_handle_at -F exit=-EPERM -k access

« ModulesFile Integrity Module »