1AUDIT.RULES:(7)         System Administration Utilities        AUDIT.RULES:(7)
2
3
4

NAME

6       audit.rules - a set of rules loaded in the kernel audit system
7

DESCRIPTION

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
17
18   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
26
27   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
35       -w path-to-file -p permissions -k keyname
36
37       where the permission are any one of the following:
38
39
40              r - read of the file
41
42              w - write to the file
43
44              x - execute the file
45
46              a - change in the file's attribute
47
48       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
56
57   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
65       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
70       The  exit  filter  is the place where all syscall and file system audit
71       requests are evaluated.
72
73       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
79       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
87       Syscall rules take the general form of:
88
89       -a action,list -S syscall -F field=value -k keyname
90
91       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
96
97              always - always create an event
98
99              never  - never create an event
100
101       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
105       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
119       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
125       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. But when
128       you write rules, you can use either "unset" which is easy to  remember,
129       or -1, or 4294967295. They are all equivalent. If you write a rule that
130       you wanted try to get the valid users of the system, you need  to  look
131       in  /etc/login.defs  to  see where user accounts start. For example, if
132       UID_MIN is 1000, then you would also need to take into account that the
133       unsigned  representation of -1 is higher than 500. So you would address
134       this with the following piece of a rule:
135
136       -F auid>=1000 -F auid!=unset
137
138       These individual checks are "anded" and both have to be true.
139
140       The last thing to know about syscall rules is that you can  add  a  key
141       field  which is a free form text string that you want inserted into the
142       event to help identify its meaning. This is discussed in more detail in
143       the NOTES section.
144
145

NOTES

147       The  purpose  of auditing is to be able to do an investigation periodi‐
148       cally or whenever an incident occurs. A few simple steps in planning up
149       front will make this job easier. The best advice is to use keys in both
150       the watches and system call rules to give the rule a meaning. If  rules
151       are  related  or together meet a specific requirement, then give them a
152       common key name. You can use this during your investigation  to  select
153       only results with a specific meaning.
154
155       When doing an investigation, you would normally start off with the main
156       aureport output to just get an idea about what is happening on the sys‐
157       tem.  This  report mostly tells you about events that are hard coded by
158       the audit system such as  login/out,  uses  of  authentication,  system
159       anomalies, how many users have been on the machine, and if SE Linux has
160       detected any AVCs.
161
162       aureport --start this-week
163
164       After looking at the report, you probably want to  get  a  second  view
165       about  what  rules  you loaded that have been triggering. This is where
166       keys become important. You would generally run the key  summary  report
167       like this:
168
169       aureport --start this-week --key --summary
170
171       This  will  give  an  ordered listing of the keys associated with rules
172       that have been triggering. If, for example, you  had  a  syscall  audit
173       rule  that triggered on the failure to open files with EPERM that had a
174       key field of access like this:
175
176       -a always,exit -F arch=b64 -S open -S openat -F exit=-EPERM -k access
177
178       Then you can isolate these failures with ausearch and pipe the  results
179       to  aureport  for  display. Suppose your investigation noticed a lot of
180       the access denied events. If you wanted to see the files that  unautho‐
181       rized access has been attempted, you could run the following command:
182
183       ausearch --start this-week -k access --raw | aureport --file --summary
184
185       This  will  give an ordered list showing which files are being accessed
186       with the EPERM failure. Suppose you wanted to see which users might  be
187       having failed access, you would run the following command:
188
189       ausearch --start this-week -k access --raw | aureport --user --summary
190
191       If  your  investigation showed a lot of failed accesses to a particular
192       file, you could run the following report to see who is doing it:
193
194       ausearch --start this-week -k access -f /path-to/file --raw |  aureport
195       --user -i
196
197       This  report will give you the individual access attempts by person. If
198       you needed to see the actual audit event that is  being  reported,  you
199       would look at the date, time, and event columns. Assuming the event was
200       822 and it occurred at 2:30 on 09/01/2009 and you  use  the  en_US.utf8
201       locale, the command would look something like this:
202
203       ausearch --start 09/01/2009 02:30 -a 822 -i --just-one
204
205       This will select the first event from that day and time with the match‐
206       ing event id and interpret the numeric values into human readable  val‐
207       ues.
208
209       The  most  important  step in being able to do this kind of analysis is
210       setting up key fields when the rules were originally written. It should
211       also  be  pointed out that you can have more than one key field associ‐
212       ated with any given rule.
213
214

TROUBLESHOOTING

216       If you are not getting events on  syscall  rules  that  you  think  you
217       should, try running a test program under strace so that you can see the
218       syscalls. There is a chance that you might have  identified  the  wrong
219       syscall.
220
221       If  you get a warning from auditctl saying, "32/64 bit syscall mismatch
222       in line XX, you should specify an arch". This means that you  specified
223       a  syscall  rule  on a bi-arch system where the syscall has a different
224       syscall number for the 32 and 64 bit interfaces. This means that on one
225       of those interfaces you are likely auditing the wrong syscall. To solve
226       the problem, re-write the rule as two  rules  specifying  the  intended
227       arch for each rule. For example,
228
229       -a always,exit -S openat -k access
230
231       would be rewritten as
232
233       -a always,exit -F arch=b32 -S openat -k access
234       -a always,exit -F arch=b64 -S openat -k access
235
236       If  you  get  a warning that says, "entry rules deprecated, changing to
237       exit rule". This means that you have a rule intended for the entry fil‐
238       ter,  but  that filter is no longer available. Auditctl moved your rule
239       to the exit filter so that it's not lost. But to solve this so that you
240       do  not get the warning any more, you need to change the offending rule
241       from entry to exit.
242
243

EXAMPLES

245       The following rule shows how to audit failed access  to  files  due  to
246       permission  problems. Note that it takes two rules for each arch ABI to
247       audit this since file access can fail with two different failure  codes
248       indicating permission problems.
249
250       -a always,exit -F arch=b32 -S open -S openat -F exit=-EACCES -k access
251       -a always,exit -F arch=b32 -S open -S openat -F exit=-EPERM -k access
252       -a always,exit -F arch=b64 -S open -S openat -F exit=-EACCES -k access
253       -a always,exit -F arch=b64 -S open -S openat -F exit=-EPERM -k access
254
255

HARD WIRED EVENTS

257       If  auditing  is enabled, then you can get any event that is not caused
258       by syscall or file watch  rules  (because  you  don't  have  any  rules
259       loaded). So, that means, any event from 1100-1299, 1326, 1328, 1331 and
260       higher can be emitted. The reason that there are  a  number  of  events
261       that  are  hardwired is because they are required by regulatory compli‐
262       ance and  are  sent  automatically  as  a  convenience.  (For  example,
263       logon/logoff  is  a  mandatory  event in all security guidance.) If you
264       don't want this, you can use the exclude filter to drop events that you
265       do not want.
266
267       -a always,exclude -F msgtype=CRED_REFR
268
269

SEE ALSO

271       auditctl(8), auditd(8).
272
273

AUTHOR

275       Steve Grubb
276
277
278
279Red Hat                            Jan 2019                    AUDIT.RULES:(7)
Impressum