AUDIT.RULES:(7) System Administration Utilities AUDIT.RULES:(7)NAMEaudit.rules - a set of rules loaded in the kernel audit system
DESCRIPTIONaudit.rules is a file containing audit rules that will be loaded by the
audit daemon's init script whenever the daemon is started. The auditctl
program is used by the initscripts to perform this operation. The syn‐
tax for the rules is essentially the same as when typing in an auditctl
command at a shell prompt except you do not need to type the auditctl
command name since that is implied. The audit rules come in 3 vari‐
eties: control, file, and syscall.
Control
Control commands generally involve configuring the audit system rather
than telling it what to watch for. These commands typically include
deleting all rules, setting the size of the kernel's backlog queue,
setting the failure mode, setting the event rate limit, or to tell
auditctl to ignore syntax errors in the rules and continue loading.
Generally, these rules are at the top of the rules file.
File System
File System rules are sometimes called watches. These rules are used to
audit access to particular files or directories that you may be inter‐
ested in. If the path given in the rule is a directory, then the rule
used is recursive to the bottom of the directory tree excluding any
directories that may be mount points. The syntax of these rules gener‐
ally follow this format:
-w path-to-file -p permissions -k keyname
where the permission are any one of the following:
r - read of the file
w - write to the file
x - execute the file
a - change in the file's attribute
System Call
The system call rules are loaded into a matching engine that intercepts
each syscall that all programs on the system makes. Therefore it is
very important to only use syscall rules when you have to since these
affect performance. The more rules, the bigger the performance hit. You
can help the performance, though, by combining syscalls into one rule
whenever possible.
The Linux kernel has 5 rule matching lists or filters as they are some‐
times called. They are: task, entry, exit, user, and exclude. The task
list is checked only during the fork or clone syscalls. It is rarely
used in practice.
The entry list is run through at each syscall entry. The exit list is
checked on syscall exit. The main difference between these two is that
some things are not available at syscall entry and cannot be checked,
like the exit value. Rules on the exit filter are much more common and
all fields are available for use at syscall exit. At some point in the
near future the entry filter will be deprecated, so it would be best to
only use the exit filter.
The user filter is used to filter some events that originate in user
space. Fields that are valid for use are: uid, auid, gid, and pid. The
exclude filter is used to exclude certain events from being emitted.
The msgtype field is used to tell the kernel which message types you do
not want to record.
Syscall rules take the general form of:
-a action,list -S syscall -F field=value -k keyname
The -a option tells the kernel's rule matching engine that we want to
append a rule and the end of the rule list. But we need to specify
which rule list it goes on and what action to take when it triggers.
Valid actions are:
always - always create an event
never - never create an event
The action and list are separated by a comma but no space in between.
Valid lists are: task, entry, exit, user, and exclude. There meaning
was explained earlier.
Next in the rule would normally be the -S option. This field can either
be the syscall name or number. For readability, the name is almost
always used. You may give more than one syscall in a rule by specifying
another -S option. When sent into the kernel, all syscall fields are
put into a mask so that one compare can determine if the syscall is of
interest. So, adding multiple syscalls in one rule is very efficient.
When you specify a syscall name, auditctl will look up the name and get
its syscall number. This leads to some problems on bi-arch machines.
The 32 and 64 bit syscall numbers sometimes, but not always, line up.
So, to solve this problem, you would generally need to break the rule
into 2 with one specifying -F arch=b32 and the other specifying -F
arch=b64. This needs to go in front of the -S option so that auditctl
looks at the right lookup table when returning the number.
After the syscall is specified, you would normally have one or more -F
options that fine tune what to match against. Rather than list all the
valid field types here, the reader should look at the auditctl man page
which has a full listing of each field and what it means. But its worth
mentioning a couple things.
The audit system considers uids to be unsigned numbers. The audit sys‐
tem uses the number -1 to indicate that a loginuid is not set. This
means that when its printed out, it looks like 4294967295. If you write
a rule that you wanted try to get the valid users of the system, you
need to look in /etc/login.defs to see where user accounts start. For
example, if UID_MIN is 500, then you would also need to take into
account that the unsigned representation of -1 is higher than 500. So
you would address this with the following piece of a rule:
-F auid>=500 -F auid!=4294967295
These individual checks are "anded" and both have to be true.
The last thing to know about syscall rules is that you can add a key
field which is a free form text string that you want inserted into the
event to help identify its meaning. This is discussed in more detail in
the NOTES section.
NOTES
The purpose of auditing is to be able to do an investigation periodi‐
cally or whenever an incident occurs. A few simple steps in planning up
front will make this job easier. The best advice is to use keys in both
the watches and system call rules to give the rule a meaning. If rules
are related or together meet a specific requirement, then give them a
common key name. You can use this during your investigation to select
only results with a specific meaning.
When doing an investigation, you would normally start off with the main
aureport output to just get an idea about what is happening on the sys‐
tem. This report mostly tells you about events that are hard coded by
the audit system such as login/out, uses of authentication, system
anomalies, how many users have been on the machine, and if SE Linux has
detected any AVCs.
aureport --start this-week
After looking at the report, you probably want to get a second view
about what rules you loaded that have been triggering. This is where
keys become important. You would generally run the key summary report
like this:
aureport --start this-week --keys --summary
This will give an ordered listing of the keys associated with rules
that have been triggering. If, for example, you had a syscall audit
rule that triggered on the failure to open files with EPERM that had a
key field of access like this:
-a always,exit -F arch=b64 -S open -F exit=-EPERM -k access
Then you can isolate these failures with ausearch and pipe the results
to aureport for display. Suppose your investigation noticed a lot of
the access denied events. If you wanted to see the files that unautho‐
rized access has been attempted, you could run the following command:
ausearch --start this-week -k access --raw | aureport --file --summary
This will give an ordered list showing which files are being accessed
with the EPERM failure. Suppose you wanted to see which users might be
having failed access, you would run the following command:
ausearch --start this-week -k access --raw | aureport --user --summary
If your investigation showed a lot of failed accesses to a particular
file, you could run the following report to see who is doing it:
ausearch --start this-week -k access -f /path-to/file --raw | aureport
--user -i
This report will give you the individual access attempts by person. If
you needed to see the actual audit event that is being reported, you
would look at the date, time, and event columns. Assuming the event was
822 and it occurred at 2:30 on 09/01/2009 and you use the en_US.utf8
locale, the command would look something like this:
ausearch --start 09/01/2009 02:30 -a 822 -i --just-one
This will select the first event from that day and time with the match‐
ing event id and interpret the numeric values into human readable val‐
ues.
The most important step in being able to do this kind of analysis is
setting up key fields when the rules were originally written. It should
also be pointed out that you can have more than one key field associ‐
ated with any given rule.
TROUBLESHOOTING
If you are not getting events on syscall rules that you think you
should, try running a test program under strace so that you can see the
syscalls. There is a chance that you might have identified the wrong
syscall.
If you get a warning from auditctl saying, "32/64 bit syscall mismatch
in line XX, you should specify an arch". This means that you specified
a syscall rule on a bi-arch system where the syscall has a different
syscall number for the 32 and 64 bit interfaces. This means that on one
of those interfaces you are likely auditing the wrong syscall. To solve
the problem, re-write the rule as two rules specifying the intended
arch for each rule. For example,
-always,exit -S open -k access
would be rewritten as
-always,exit -F arch=b32 -S open -k access
-always,exit -F arch=b64 -S open -k access
If you get a warning that says, "entry rules deprecated, changing to
exit rule". This means that you have a rule intended for the entry fil‐
ter, but that filter is not going to be available at some point in the
future. Auditctl moved your rule to the exit filter so that its not
lost. But to solve this so that you do not get the warning any more,
you need to change the offending rule from entry to exit.
EXAMPLES
The following rule shows how to audit failed access to files due per‐
mission problems. Note that it takes two rules for each arch ABI to
audit this since file access can fail with two different failure codes
indicating permission problems.
-a always,exit -F arch=b32 -S open -S openat -F exit=-EACCES -k access
-a always,exit -F arch=b32 -S open -S openat -F exit=-EPERM -k access
-a always,exit -F arch=b64 -S open -S openat -F exit=-EACCES -k access
-a always,exit -F arch=b64 -S open -S openat -F exit=-EPERM -k access
SEE ALSOauditctl(8), auditd(8).
AUTHOR
Steve Grubb
Red Hat Sep 2009 AUDIT.RULES:(7)
