Applies to openSUSE Leap 42.2

32 Setting Up the Linux Audit Framework

This chapter shows how to set up a simple audit scenario. Every step involved in configuring and enabling audit is explained in detail. After you have learned to set up audit, consider a real-world example scenario in Chapter 33, Introducing an Audit Rule Set.

To set up audit on openSUSE Leap, you need to complete the following steps:

Procedure 32.1: Setting Up the Linux Audit Framework
  1. Make sure that all required packages are installed: audit, audit-libs, and optionally audit-libs-python. To use the log visualization as described in Section 32.6, “Configuring Log Visualization”, install gnuplot and graphviz from the openSUSE Leap media.

  2. Determine the components to audit. Refer to Section 32.1, “Determining the Components to Audit” for details.

  3. Check or modify the basic audit daemon configuration. Refer to Section 32.2, “Configuring the Audit Daemon” for details.

  4. Enable auditing for system calls. Refer to Section 32.3, “Enabling Audit for System Calls” for details.

  5. Compose audit rules to suit your scenario. Refer to Section 32.4, “Setting Up Audit Rules” for details.

  6. Generate logs and configure tailor-made reports. Refer to Section 32.5, “Configuring Audit Reports” for details.

  7. Configure optional log visualization. Refer to Section 32.6, “Configuring Log Visualization” for details.

Important: Controlling the Audit Daemon

Before configuring any of the components of the audit system, make sure that the audit daemon is not running by entering systemctl status auditd as root. On a default openSUSE Leap system, audit is started on boot, so you need to turn it off by entering systemctl stop auditd. Start the daemon after configuring it with systemctl start auditd.

32.1 Determining the Components to Audit

Before starting to create your own audit configuration, determine to which degree you want to use it. Check the following general rules to determine which use case best applies to you and your requirements:

32.2 Configuring the Audit Daemon

The basic setup of the audit daemon is done by editing /etc/audit/auditd.conf. You may also use YaST to configure the basic settings by calling YaST › Security and Users › Linux Audit Framework (LAF). Use the tabs Log File and Disk Space for configuration.

log_file = /var/log/audit/audit.log
log_format = RAW
log_group = root
priority_boost = 4
freq = 20
num_logs = 5
disp_qos = lossy
dispatcher = /sbin/audispd
name_format = NONE
##name = mydomain
max_log_file = 6
max_log_file_action = ROTATE
space_left = 75
space_left_action = SYSLOG
action_mail_acct = root
admin_space_left = 50
admin_space_left_action = SUSPEND
disk_full_action = SUSPEND
disk_error_action = SUSPEND
##tcp_listen_port =
tcp_listen_queue = 5
tcp_max_per_addr = 1
##tcp_client_ports = 1024-65535
tcp_client_max_idle = 0
cp_client_max_idle = 0

The default settings work reasonably well for many setups. Some values, such as num_logs, max_log_file, space_left, and admin_space_left depend on the size of your deployment. If disk space is limited, you should reduce the number of log files to keep if they are rotated and you should get an earlier warning if disk space is running out. For a CAPP-compliant setup, adjust the values for log_file, flush, max_log_file, max_log_file_action, space_left, space_left_action, admin_space_left, admin_space_left_action, disk_full_action, and disk_error_action, as described in Section 31.2, “Configuring the Audit Daemon”. An example CAPP-compliant configuration looks like this:

log_file = path_to_separate_partition/audit.log
log_format = RAW
priority_boost = 4
flush = SYNC                       ### or DATA
freq = 20
num_logs = 4
dispatcher = /sbin/audispd
disp_qos = lossy
max_log_file = 5
max_log_file_action = KEEP_LOGS
space_left = 75
space_left_action = EMAIL
action_mail_acct = root
admin_space_left = 50
admin_space_left_action = SINGLE   ### or HALT
disk_full_action = SUSPEND         ### or HALT
disk_error_action = SUSPEND        ### or HALT

The ### precedes comments where you can choose from several options. Do not add the comments to your actual configuration files.

Tip: For More Information

Refer to Section 31.2, “Configuring the Audit Daemon” for detailed background information about the auditd.conf configuration parameters.

32.3 Enabling Audit for System Calls

If the audit framework is not installed, install the audit package. A standard openSUSE Leap system does not have auditd running by default. Enable it with:

systemctl enable auditd

There are different levels of auditing activity available:

Basic Logging

Out of the box (without any further configuration) auditd logs only events concerning its own configuration changes to /var/log/audit/audit.log. No events (file access, system call, etc.) are generated by the kernel audit component until requested by auditctl. However, other kernel components and modules may log audit events outside of the control of auditctl and these appear in the audit log. By default, the only module that generates audit events is AppArmor.

Advanced Logging with System Call Auditing

To audit system calls and get meaningful file watches, you need to enable audit contexts for system calls.

As you need system call auditing capabilities even when you are configuring plain file or directory watches, you need to enable audit contexts for system calls. To enable audit contexts for the duration of the current session only, execute auditctl -e 1 as root. To disable this feature, execute auditctl -e 0 as root.

The audit contexts are enabled by default. To turn this feature off temporarily, use auditctl -e 0.

32.4 Setting Up Audit Rules

Using audit rules, determine which aspects of the system should be analyzed by audit. Normally this includes important databases and security-relevant configuration files. You may also analyze various system calls in detail if a broad analysis of your system is required. A very detailed example configuration that includes most of the rules that are needed in a CAPP compliant environment is available in Chapter 33, Introducing an Audit Rule Set.

Audit rules can be passed to the audit daemon on the auditctl command line and by composing a rule set in /etc/audit/audit.rules which is processed whenever the audit daemon is started. To customize /etc/audit/audit.rules either edit it directly, or use YaST: Security and Users › Linux Audit Framework (LAF) › Rules for 'auditctl'. Rules passed on the command line are not persistent and need to be re-entered when the audit daemon is restarted.

A simple rule set for very basic auditing on a few important files and directories could look like this:

# basic audit system parameters
-b 8192
-f 1
-e 1

# some file and directory watches with keys
-w /var/log/audit/ -k LOG_audit
-w /etc/audit/auditd.conf -k CFG_audit_conf -p rxwa
-w /etc/audit/audit.rules -k CFG_audit_rules -p rxwa

-w /etc/passwd -k CFG_passwd -p rwxa
-w /etc/sysconfig/ -k CFG_sysconfig  

# an example system call rule
-a entry,always -S umask

### add your own rules

When configuring the basic audit system parameters (such as the backlog parameter -b) test these settings with your intended audit rule set to determine whether the backlog size is appropriate for the level of logging activity caused by your audit rule set. If your chosen backlog size is too small, your system might not be able to handle the audit load and consult the failure flag (-f) when the backlog limit is exceeded.

Important: Choosing the Failure Flag

When choosing the failure flag, note that -f 2 tells your system to perform an immediate shutdown without flushing any pending data to disk when the limits of your audit system are exceeded. Because this shutdown is not a clean shutdown, restrict the use of -f 2 to only the most security-conscious environments and use -f 1 (system continues to run, issues a warning and audit stops) for any other setup to avoid loss of data or data corruption.

Directory watches produce less verbose output than separate file watches for the files under these directories. To get detailed logging for your system configuration in /etc/sysconfig, for example, add watches for each file. Audit does not support globbing, which means you cannot create a rule that says -w /etc/* and watches all files and directories below /etc.

For better identification in the log file, a key has been added to each of the file and directory watches. Using the key, it is easier to comb the logs for events related to a certain rule. When creating keys, distinguish between mere log file watches and configuration file watches by using an appropriate prefix with the key, in this case LOG for a log file watch and CFG for a configuration file watch. Using the file name as part of the key also makes it easier for you to identify events of this type in the log file.

Another thing to bear in mind when creating file and directory watches is that audit cannot deal with files that do not exist when the rules are created. Any file that is added to your system while audit is already running is not watched unless you extend the rule set to watch this new file.

For more information about creating custom rules, refer to Section 31.4, “Passing Parameters to the Audit System”.

Important: Changing Audit Rules

After you change audit rules, always restart the audit daemon with systemctl restart auditd to reread the changed rules.

32.5 Configuring Audit Reports

To avoid having to dig through the raw audit logs to get an impression of what your system is currently doing, run custom audit reports at certain intervals. Custom audit reports enable you to focus on areas of interest and get meaningful statistics on the nature and frequency of the events you are monitoring. To analyze individual events in detail, use the ausearch tool.

Before setting up audit reporting, consider the following:

  • What types of events do you want to monitor by generating regular reports? Select the appropriate aureport command lines as described in Section 31.5.2, “Generating Custom Audit Reports”.

  • What do you want to do with the audit reports? Decide whether to create graphical charts from the data accumulated or whether it should be transferred into any sort of spreadsheet or database. Set up the aureport command line and further processing similar to the examples shown in Section 32.6, “Configuring Log Visualization” if you want to visualize your reports.

  • When and at which intervals should the reports run? Set up appropriate automated reporting using cron.

For this example, assume that you are interested in finding out about any attempts to access your audit, PAM, and system configuration. Proceed as follows to find out about file events on your system:

  1. Generate a full summary report of all events and check for any anomalies in the summary report, for example, have a look at the failed syscalls record, because these might have failed because of insufficient permissions to access a file or a file not being there:

    Summary Report
    Range of time in logs: 03/02/09 14:13:38.225 - 17/02/09 16:30:10.352
    Selected time for report: 03/02/09 14:13:38 - 17/02/09 16:30:10.352
    Number of changes in configuration: 24
    Number of changes to accounts, groups, or roles: 0
    Number of logins: 9
    Number of failed logins: 15
    Number of authentications: 19
    Number of failed authentications: 578
    Number of users: 3
    Number of terminals: 15
    Number of host names: 4
    Number of executables: 20
    Number of files: 279
    Number of AVC's: 0
    Number of MAC events: 0
    Number of failed syscalls: 994
    Number of anomaly events: 0
    Number of responses to anomaly events: 0
    Number of crypto events: 0
    Number of keys: 2
    Number of process IDs: 1238
    Number of events: 5435
  2. Run a summary report for failed events and check the files record for the number of failed file access events:

    aureport --failed
    Failed Summary Report
    Range of time in logs: 03/02/09 14:13:38.225 - 17/02/09 16:30:10.352
    Selected time for report: 03/02/09 14:13:38 - 17/02/09 16:30:10.352
    Number of changes in configuration: 0
    Number of changes to accounts, groups, or roles: 0
    Number of logins: 0
    Number of failed logins: 15
    Number of authentications: 0
    Number of failed authentications: 578
    Number of users: 1
    Number of terminals: 7
    Number of host names: 4
    Number of executables: 12
    Number of files: 77
    Number of AVC's: 0
    Number of MAC events: 0
    Number of failed syscalls: 994
    Number of anomaly events: 0
    Number of responses to anomaly events: 0
    Number of crypto events: 0
    Number of keys: 2
    Number of process IDs: 713
    Number of events: 1589
  3. To list the files that could not be accessed, run a summary report of failed file events:

    aureport -f -i --failed --summary
    Failed File Summary Report
    total  file                
    80  /var                   
    80  spool                  
    80  cron                   
    80  lastrun                
    46  /usr/lib/locale/en_GB.UTF-8/LC_CTYPE
    45  /usr/lib/locale/locale-archive      
    38  /usr/lib/locale/en_GB.UTF-8/LC_IDENTIFICATION
    38  /usr/lib/locale/en_GB.UTF-8/LC_MEASUREMENT   
    38  /usr/lib/locale/en_GB.UTF-8/LC_TELEPHONE     
    38  /usr/lib/locale/en_GB.UTF-8/LC_ADDRESS       
    38  /usr/lib/locale/en_GB.UTF-8/LC_NAME          
    38  /usr/lib/locale/en_GB.UTF-8/LC_PAPER         
    38  /usr/lib/locale/en_GB.UTF-8/LC_MESSAGES      
    38  /usr/lib/locale/en_GB.UTF-8/LC_MONETARY      
    38  /usr/lib/locale/en_GB.UTF-8/LC_COLLATE       
    38  /usr/lib/locale/en_GB.UTF-8/LC_TIME          
    38  /usr/lib/locale/en_GB.UTF-8/LC_NUMERIC       
    8  /etc/magic.mgc                           

    To focus this summary report on a few files or directories of interest only, such as /etc/audit/auditd.conf, /etc/pam.d, and /etc/sysconfig, use a command similar to the following:

    aureport -f -i --failed --summary |grep -e "/etc/audit/auditd.conf" -e "/etc/pam.d/" -e "/etc/sysconfig"
    1  /etc/sysconfig/displaymanager
  4. From the summary report, then proceed to isolate these items of interest from the log and find out their event IDs for further analysis:

    aureport -f -i --failed |grep -e "/etc/audit/auditd.conf" -e "/etc/pam.d/" -e "/etc/sysconfig"
    993. 17/02/09 16:47:34 /etc/sysconfig/displaymanager readlink no /bin/vim-normal root 7887
    994. 17/02/09 16:48:23 /etc/sysconfig/displaymanager getxattr no /bin/vim-normal root 7889
  5. Use the event ID to get a detailed record for each item of interest:

    ausearch -a 7887 -i
    time->Tue Feb 17 16:48:23 2009
    type=PATH msg=audit(1234885703.090:7889): item=0 name="/etc/sysconfig/displaymanager" inode=369282 dev=08:06 mode=0100644 ouid=0 ogid=0 rdev=00:00
    type=CWD msg=audit(1234885703.090:7889):  cwd="/root"
    type=SYSCALL msg=audit(1234885703.090:7889): arch=c000003e syscall=191 success=no exit=-61 a0=7e1e20 a1=7f90e4cf9187 a2=7fffed5b57d0 a3=84 items=1 ppid=25548 pid=23045 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts2 ses=1166 comm="vim" exe="/bin/vim-normal" key=(null)
Tip: Focusing on a Certain Time Frame

If you are interested in events during a particular period of time, trim down the reports by using start and end dates and times with your aureport commands (-ts and -te). For more information, refer to Section 31.5.2, “Generating Custom Audit Reports”.

All steps (except for the last one) can be run automatically and would easily be scriptable and configured as cron jobs. Any of the --failed --summary reports could be transformed easily into a bar chart that plots files versus failed access attempts. For more information about visualizing audit report data, refer to Section 32.6, “Configuring Log Visualization”.

32.6 Configuring Log Visualization

Using the scripts mkbar and mkgraph you can illustrate your audit statistics with various graphs and charts. As with any other aureport command, the plotting commands are scriptable and can easily be configured to run as cron jobs.

mkbar and mkgraph were created by Steve Grubb at Red Hat. They are available from Because the current version of audit in openSUSE Leap does not ship with these scripts, proceed as follows to make them available on your system:

Warning: Downloaded Content Is Dangerous

Use mkbar and mkgraph at your own risk. Any content downloaded from the Web is potentially dangerous to your system, even more so when run with root privileges.

  1. Download the scripts to root's ~/bin directory:

    wget -O ~/bin/mkbar
    wget -O ~/bin/mkgraph
  2. Adjust the file permissions to read, write, and execute for root:

    chmod 744 ~/bin/mk{bar,graph}

To plot summary reports, such as the ones discussed in Section 32.5, “Configuring Audit Reports”, use the script mkbar. Some example commands could look like the following:

Create a Summary of Events
aureport -e -i --summary | mkbar events
Create a Summary of File Events
aureport -f -i --summary | mkbar files
Create a Summary of Login Events
aureport -l -i --summary | mkbar login
Create a Summary of User Events
aureport -u -i --summary | mkbar users
Create a Summary of System Call Events
aureport -s -i --summary | mkbar syscalls

To create a summary chart of failed events of any of the above event types, add the --failed option to the respective aureport command. To cover a certain period of time only, use the -ts and -te options on aureport. Any of these commands can be tweaked further by narrowing down its scope using grep or egrep and regular expressions. See the comments in the mkbar script for an example. Any of the above commands produces a PNG file containing a bar chart of the requested data.

To illustrate the relationship between different kinds of audit objects, such as users and system calls, use the script mkgraph. Some example commands could look like the following:

Users versus Executables
LC_ALL=C aureport -u -i | awk '/^[0-9]/ { print $4" "$7 }' | sort | uniq | mkgraph users_vs_exec
Users versus Files
LC_ALL=C aureport -f -i | awk '/^[0-9]/ { print $8" "$4 }' | sort | uniq | mkgraph users_vs_files
System Calls versus Commands
LC_ALL=C aureport -s -i | awk '/^[0-9]/ { print $4" "$6 }' | sort | uniq | mkgraph syscall_vs_com
System Calls versus Files
LC_ALL=C aureport -s -i | awk '/^[0-9]/ { print $5" "$4 }' | sort | uniq | mkgraph | syscall_vs_file

Graphs can also be combined to illustrate complex relationships. See the comments in the mkgraph script for further information and an example. The graphs produced by this script are created in PostScript format by default, but you can change the output format by changing the EXT variable in the script from ps to png or jpg.

Print this page