1AUDIT.RULES:(7) System Administration Utilities AUDIT.RULES:(7)
2
6 audit.rules - a set of rules loaded in the kernel audit system
7
9 audit.rules is a file containing audit rules that will be loaded by the
10 audit daemon's init script whenever the daemon is started. The auditctl
11 program is used by the initscripts to perform this operation. The syn‐
12 tax for the rules is essentially the same as when typing in an auditctl
13 command at a shell prompt except you do not need to type the auditctl
14 command name since that is implied. The audit rules come in 3 vari‐
15 eties: control, file, and syscall.
16 Control
19 Control commands generally involve configuring the audit system rather
20 than telling it what to watch for. These commands typically include
21 deleting all rules, setting the size of the kernel's backlog queue,
22 setting the failure mode, setting the event rate limit, or to tell
23 auditctl to ignore syntax errors in the rules and continue loading.
24 Generally, these rules are at the top of the rules file.
25 File System
28 File System rules are sometimes called watches. These rules are used to
29 audit access to particular files or directories that you may be inter‐
30 ested in. If the path given in a watch rule is a directory, then the
31 rule used is recursive to the bottom of the directory tree excluding
32 any directories that may be mount points. The syntax of these watch
33 rules generally follow this format:
34 -w path-to-file -p permissions -k keyname
36 where the permission are any one of the following:
38 r - read of the file
41 w - write to the file
43 x - execute the file
45 a - change in the file's attribute
47 Watches can also be created using the syscall format described below
49 which allow for greater flexibility and options. Using syscall rules
50 you can choose between path and dir which is against a specific inode
51 or directory tree respectively. It should also be noted that the recur‐
52 sive directory watch will stop if there is a mount point below the par‐
53 ent directory. There is an option to make the mounted subdirectory
54 equivalent by using a -q rule.
55 System Call
58 The system call rules are loaded into a matching engine that intercepts
59 each syscall that all programs on the system makes. Therefore it is
60 very important to only use syscall rules when you have to since these
61 affect performance. The more rules, the bigger the performance hit. You
62 can help the performance, though, by combining syscalls into one rule
63 whenever possible.
64 The Linux kernel has 4 rule matching lists or filters as they are some‐
66 times called. They are: task, exit, user, and exclude. The task list is
67 checked only during the fork or clone syscalls. It is rarely used in
68 practice.
69 The exit filter is the place where all syscall and file system audit
71 requests are evaluated.
72 The user filter is used to filter (remove) some events that originate
74 in user space. By default, any event originating in user space is
75 allowed. So, if there are some events that you do not want to see, then
76 this is a place where some can be removed. See auditctl(8) for fields
77 that are valid.
78 The exclude filter is used to exclude certain events from being emit‐
80 ted. The msgtype and a number of subject attribute fields can be used
81 to tell the kernel which message types you do not want to record. This
82 filter can remove the event as a whole and is not selective about any
83 other attribute. The user and exit filters are better suited to selec‐
84 tively auditing events. The action is ignored for this filter,
85 defaulting to "never".
86 Syscall rules take the general form of:
88 -a action,list -S syscall -F field=value -k keyname
90 The -a option tells the kernel's rule matching engine that we want to
92 append a rule at the end of the rule list. But we need to specify which
93 rule list it goes on and what action to take when it triggers. Valid
94 actions are:
95 always - always create an event
98 never - never create an event
100 The action and list are separated by a comma but no space in between.
102 Valid lists are: task, exit, user, and exclude. Their meaning was
103 explained earlier.
104 Next in the rule would normally be the -S option. This field can either
106 be the syscall name or number. For readability, the name is almost
107 always used. You may give more than one syscall in a rule by specifying
108 another -S option. When sent into the kernel, all syscall fields are
109 put into a mask so that one compare can determine if the syscall is of
110 interest. So, adding multiple syscalls in one rule is very efficient.
111 When you specify a syscall name, auditctl will look up the name and get
112 its syscall number. This leads to some problems on bi-arch machines.
113 The 32 and 64 bit syscall numbers sometimes, but not always, line up.
114 So, to solve this problem, you would generally need to break the rule
115 into 2 with one specifying -F arch=b32 and the other specifying -F
116 arch=b64. This needs to go in front of the -S option so that auditctl
117 looks at the right lookup table when returning the number.
118 After the syscall is specified, you would normally have one or more -F
120 options that fine tune what to match against. Rather than list all the
121 valid field types here, the reader should look at the auditctl man page
122 which has a full listing of each field and what it means. But it's
123 worth mentioning a couple things.
124 The audit system considers uids to be unsigned numbers. The audit sys‐
126 tem uses the number -1 to indicate that a loginuid is not set. This
127 means that when it's printed out, it looks like 4294967295. If you
128 write a rule that you wanted try to get the valid users of the system,
129 you need to look in /etc/login.defs to see where user accounts start.
130 For example, if UID_MIN is 500, then you would also need to take into
131 account that the unsigned representation of -1 is higher than 500. So
132 you would address this with the following piece of a rule:
133 -F auid>=500 -F auid!=4294967295
135 These individual checks are "anded" and both have to be true.
137 The last thing to know about syscall rules is that you can add a key
139 field which is a free form text string that you want inserted into the
140 event to help identify its meaning. This is discussed in more detail in
141 the NOTES section.
142
145 The purpose of auditing is to be able to do an investigation periodi‐
146 cally or whenever an incident occurs. A few simple steps in planning up
147 front will make this job easier. The best advice is to use keys in both
148 the watches and system call rules to give the rule a meaning. If rules
149 are related or together meet a specific requirement, then give them a
150 common key name. You can use this during your investigation to select
151 only results with a specific meaning.
152 When doing an investigation, you would normally start off with the main
154 aureport output to just get an idea about what is happening on the sys‐
155 tem. This report mostly tells you about events that are hard coded by
156 the audit system such as login/out, uses of authentication, system
157 anomalies, how many users have been on the machine, and if SE Linux has
158 detected any AVCs.
159 aureport --start this-week
161 After looking at the report, you probably want to get a second view
163 about what rules you loaded that have been triggering. This is where
164 keys become important. You would generally run the key summary report
165 like this:
166 aureport --start this-week --key --summary
168 This will give an ordered listing of the keys associated with rules
170 that have been triggering. If, for example, you had a syscall audit
171 rule that triggered on the failure to open files with EPERM that had a
172 key field of access like this:
173 -a always,exit -F arch=b64 -S open -S openat -F exit=-EPERM -k access
175 Then you can isolate these failures with ausearch and pipe the results
177 to aureport for display. Suppose your investigation noticed a lot of
178 the access denied events. If you wanted to see the files that unautho‐
179 rized access has been attempted, you could run the following command:
180 ausearch --start this-week -k access --raw | aureport --file --summary
182 This will give an ordered list showing which files are being accessed
184 with the EPERM failure. Suppose you wanted to see which users might be
185 having failed access, you would run the following command:
186 ausearch --start this-week -k access --raw | aureport --user --summary
188 If your investigation showed a lot of failed accesses to a particular
190 file, you could run the following report to see who is doing it:
191 ausearch --start this-week -k access -f /path-to/file --raw | aureport
193 --user -i
194 This report will give you the individual access attempts by person. If
196 you needed to see the actual audit event that is being reported, you
197 would look at the date, time, and event columns. Assuming the event was
198 822 and it occurred at 2:30 on 09/01/2009 and you use the en_US.utf8
199 locale, the command would look something like this:
200 ausearch --start 09/01/2009 02:30 -a 822 -i --just-one
202 This will select the first event from that day and time with the match‐
204 ing event id and interpret the numeric values into human readable val‐
205 ues.
206 The most important step in being able to do this kind of analysis is
208 setting up key fields when the rules were originally written. It should
209 also be pointed out that you can have more than one key field associ‐
210 ated with any given rule.
211
214 If you are not getting events on syscall rules that you think you
215 should, try running a test program under strace so that you can see the
216 syscalls. There is a chance that you might have identified the wrong
217 syscall.
218 If you get a warning from auditctl saying, "32/64 bit syscall mismatch
220 in line XX, you should specify an arch". This means that you specified
221 a syscall rule on a bi-arch system where the syscall has a different
222 syscall number for the 32 and 64 bit interfaces. This means that on one
223 of those interfaces you are likely auditing the wrong syscall. To solve
224 the problem, re-write the rule as two rules specifying the intended
225 arch for each rule. For example,
226 -always,exit -S openat -k access
228 would be rewritten as
230 -always,exit -F arch=b32 -S openat -k access
232 -always,exit -F arch=b64 -S openat -k access
233 If you get a warning that says, "entry rules deprecated, changing to
235 exit rule". This means that you have a rule intended for the entry fil‐
236 ter, but that filter is no longer available. Auditctl moved your rule
237 to the exit filter so that it's not lost. But to solve this so that you
238 do not get the warning any more, you need to change the offending rule
239 from entry to exit.
240
243 The following rule shows how to audit failed access to files due to
244 permission problems. Note that it takes two rules for each arch ABI to
245 audit this since file access can fail with two different failure codes
246 indicating permission problems.
247 -a always,exit -F arch=b32 -S open -S openat -F exit=-EACCES -k access
249 -a always,exit -F arch=b32 -S open -S openat -F exit=-EPERM -k access
250 -a always,exit -F arch=b64 -S open -S openat -F exit=-EACCES -k access
251 -a always,exit -F arch=b64 -S open -S openat -F exit=-EPERM -k access
252
255 auditctl(8), auditd(8).
256
259 Steve Grubb
260Red Hat Aug 2014 AUDIT.RULES:(7)