1AUDITCTL:(8) System Administration Utilities AUDITCTL:(8)
2
6 auditctl - a utility to assist controlling the kernel's audit system
7
9 auditctl [options]
10
12 The auditctl program is used to configure kernel options related to
13 auditing, to see status of the configuration, and to load discretionary
14 audit rules.
15
17 -b backlog
18 Set max number of outstanding audit buffers allowed (Kernel
19 Default=64) If all buffers are full, the failure flag is con‐
20 sulted by the kernel for action.
21 -c Continue loading rules in spite of an error. This summarizes the
23 results of loading the rules. The exit code will not be success
24 if any rule fails to load.
25 -D Delete all rules and watches. This can take a key option (-k),
27 too.
28 -e [0..2]
30 Set enabled flag. When 0 is passed, this can be used to tempo‐
31 rarily disable auditing. When 1 is passed as an argument, it
32 will enable auditing. To lock the audit configuration so that it
33 can't be changed, pass a 2 as the argument. Locking the configu‐
34 ration is intended to be the last command in audit.rules for
35 anyone wishing this feature to be active. Any attempt to change
36 the configuration in this mode will be audited and denied. The
37 configuration can only be changed by rebooting the machine.
38 -f [0..2]
40 Set failure mode 0=silent 1=printk 2=panic. This option lets you
41 determine how you want the kernel to handle critical errors.
42 Example conditions where this mode may have an effect includes:
43 transmission errors to userspace audit daemon, backlog limit
44 exceeded, out of kernel memory, and rate limit exceeded. The
45 default value is 1. Secure environments will probably want to
46 set this to 2.
47 -h Help
49 -i When given by itself, ignore errors when reading rules from a
51 file. This causes auditctl to always return a success exit code.
52 If passed as an argument to -s then it gives an interpretation
53 of the numbers to human readable words if possible.
54 --loginuid-immutable
56 This option tells the kernel to make loginuids unchangeable once
57 they are set. Changing loginuids requires CAP_AUDIT_CONTROL. So,
58 its not something that can be done by unprivileged users. Set‐
59 ting this makes loginuid tamper-proof, but can cause some prob‐
60 lems in certain kinds of containers.
61 -q mount-point,subtree
63 If you have an existing directory watch and bind or move mount
64 another subtree in the watched subtree, you need to tell the
65 kernel to make the subtree being mounted equivalent to the
66 directory being watched. If the subtree is already mounted at
67 the time the directory watch is issued, the subtree is automati‐
68 cally tagged for watching. Please note the comma separating the
69 two values. Omitting it will cause errors.
70 -r rate
72 Set limit in messages/sec (0=none). If this rate is non-zero and
73 is exceeded, the failure flag is consulted by the kernel for
74 action. The default value is 0.
75 --reset-lost
77 Reset the lost record counter shown by the status command.
78 -R file
80 Read rules from a file. The rules must be 1 per line and in the
81 order that they are to be executed in. The rule file must be
82 owned by root and not readable by other users or it will be
83 rejected. The rule file may have comments embedded by starting
84 the line with a '#' character. Rules that are read from a file
85 are identical to what you would type on a command line except
86 they are not preceded by auditctl (since auditctl is the one
87 executing the file) and you would not use shell escaping since
88 auditctl is reading the file instead of bash.
89 -t Trim the subtrees after a mount command.
91
93 -l List all rules 1 per line. Two more options may be given to this
94 command. You can give either a key option (-k) to list rules
95 that match a key or a (-i) to have a0 through a3 interpreted to
96 help determine the syscall argument values are correct .
97 -m text
99 Send a user space message into the audit system. This can only
100 be done if you have CAP_AUDIT_WRITE capability (normally the
101 root user has this). The resulting event will be the USER type.
102 -s Report the kernel's audit subsystem status. It will tell you the
104 in-kernel values that can be set by -e, -f, -r, and -b options.
105 The pid value is the process number of the audit daemon. Note
106 that a pid of 0 indicates that the audit daemon is not running.
107 The lost entry will tell you how many event records that have
108 been discarded due to the kernel audit queue overflowing. The
109 backlog field tells how many event records are currently queued
110 waiting for auditd to read them. This option can be followed by
111 the -i to get a couple fields interpreted.
112 -v Print the version of auditctl.
114
117 -a [list,action|action,list]
118 Append rule to the end of list with action. Please note the
119 comma separating the two values. Omitting it will cause errors.
120 The fields may be in either order. It could be list,action or
121 action,list. The following describes the valid list names:
122 task Add a rule to the per task list. This rule list is
124 used only at the time a task is created -- when
125 fork() or clone() are called by the parent task.
126 When using this list, you should only use fields
127 that are known at task creation time, such as the
128 uid, gid, etc.
129 exit Add a rule to the syscall exit list. This list is
131 used upon exit from a system call to determine if an
132 audit event should be created.
133 user Add a rule to the user message filter list. This
135 list is used by the kernel to filter events origi‐
136 nating in user space before relaying them to the
137 audit daemon. It should be noted that the only
138 fields that are valid are: uid, auid, gid, pid,
139 subj_user, subj_role, subj_type, subj_sen, subj_clr,
140 and msgtype. All other fields will be treated as
141 non-matching. It should be understood that any event
142 originating from user space from a process that has
143 CAP_AUDIT_WRITE will be recorded into the audit
144 trail. This means that the most likely use for this
145 filter is with rules that have an action of never
146 since nothing has to be done to allow events to be
147 recorded.
148 exclude Add a rule to the event type exclusion filter list.
150 This list is used to filter events that you do not
151 want to see. For example, if you do not want to see
152 any avc messages, you would using this list to
153 record that. Events can be excluded by process ID,
154 user ID, group ID, login user ID, message type or
155 subject context. The action is ignored and uses its
156 default of "never".
157 The following describes the valid actions for the rule:
159 never No audit records will be generated. This can be used
161 to suppress event generation. In general, you want
162 suppressions at the top of the list instead of the
163 bottom. This is because the event triggers on the
164 first matching rule.
165 always Allocate an audit context, always fill it in at
167 syscall entry time, and always write out a record at
168 syscall exit time.
169 -A list,action
171 Add rule to the beginning list with action.
172 -C [f=f | f!=f]
174 Build an inter-field comparison rule: field, operation, field.
175 You may pass multiple comparisons on a single command line. Each
176 one must start with -C. Each inter-field equation is anded with
177 each other as well as equations starting with -F to trigger an
178 audit record. There are 2 operators supported - equal, and not
179 equal. Valid fields are:
180 auid, uid, euid, suid, fsuid, obj_uid; and gid, egid, sgid,
182 fsgid, obj_gid
183 The two groups of uid and gid cannot be mixed. But any compari‐
185 son within the group can be made. The obj_uid/gid fields are
186 collected from the object of the event such as a file or direc‐
187 tory.
188 -d list,action
191 Delete rule from list with action. The rule is deleted only if
192 it exactly matches syscall name(s) and every field name and
193 value.
194 -F [n=v | n!=v | n<v | n>v | n<=v | n>=v | n&v | n&=v]
196 Build a rule field: name, operation, value. You may have up to
197 64 fields passed on a single command line. Each one must start
198 with -F. Each field equation is anded with each other (as well
199 as equations starting with -C) to trigger an audit record. There
200 are 8 operators supported - equal, not equal, less than, greater
201 than, less than or equal, and greater than or equal, bit mask,
202 and bit test respectively. Bit test will "and" the values and
203 check that they are equal, bit mask just "ands" the values.
204 Fields that take a user ID may instead have the user's name; the
205 program will convert the name to user ID. The same is true of
206 group names. Valid fields are:
207 a0, a1, a2, a3
209 Respectively, the first 4 arguments to a syscall.
210 Note that string arguments are not supported. This
211 is because the kernel is passed a pointer to the
212 string. Triggering on a pointer address value is not
213 likely to work. So, when using this, you should only
214 use on numeric values. This is most likely to be
215 used on platforms that multiplex socket or IPC oper‐
216 ations.
217 arch The CPU architecture of the syscall. The arch can be
219 found doing 'uname -m'. If you do not know the arch
220 of your machine but you want to use the 32 bit
221 syscall table and your machine supports 32 bit, you
222 can also use b32 for the arch. The same applies to
223 the 64 bit syscall table, you can use b64. In this
224 way, you can write rules that are somewhat arch
225 independent because the family type will be auto
226 detected. However, syscalls can be arch specific and
227 what is available on x86_64, may not be available on
228 ppc. The arch directive should precede the -S option
229 so that auditctl knows which internal table to use
230 to look up the syscall numbers.
231 auid The original ID the user logged in with. Its an
233 abbreviation of audit uid. Sometimes its referred to
234 as loginuid. Either the user account text or number
235 may be used.
236 devmajor Device Major Number
238 devminor Device Minor Number
240 dir Full Path of Directory to watch. This will place a
242 recursive watch on the directory and its whole sub‐
243 tree. It can only be used on exit list. See "-w".
244 egid Effective Group ID. May be numeric or the groups
246 name.
247 euid Effective User ID. May be numeric or the user
249 account name.
250 exe Absolute path to application that while executing
252 this rule will apply to. This can only be used on
253 the exit list.
254 exit Exit value from a syscall. If the exit code is an
256 errno, you may use the text representation, too.
257 fsgid Filesystem Group ID. May be numeric or the groups
259 name.
260 fsuid Filesystem User ID. May be numeric or the user
262 account name.
263 filetype The target file's type. Can be either file, dir,
265 socket, link, character, block, or fifo.
266 gid Group ID. May be numeric or the groups name.
268 inode Inode Number
270 key This is another way of setting a filter key. See
272 discussion above for -k option.
273 msgtype This is used to match the event's record type. It
275 should only be used on the exclude or user filter
276 lists.
277 obj_uid Object's UID
279 obj_gid Object's GID
281 obj_user Resource's SE Linux User
283 obj_role Resource's SE Linux Role
285 obj_type Resource's SE Linux Type
287 obj_lev_low Resource's SE Linux Low Level
289 obj_lev_high
291 Resource's SE Linux High Level
292 path Full Path of File to watch. It can only be used on
294 exit list.
295 perm Permission filter for file operations. See "-p". It
297 can only be used on exit list. You can use this
298 without specifying a syscall and the kernel will
299 select the syscalls that satisfy the permissions
300 being requested.
301 pers OS Personality Number
303 pid Process ID
305 ppid Parent's Process ID
307 sessionid User's login session ID
309 subj_user Program's SE Linux User
311 subj_role Program's SE Linux Role
313 subj_type Program's SE Linux Type
315 subj_sen Program's SE Linux Sensitivity
317 subj_clr Program's SE Linux Clearance
319 sgid Saved Group ID. See getresgid(2) man page.
321 success If the exit value is >= 0 this is true/yes otherwise
323 its false/no. When writing a rule, use a 1 for
324 true/yes and a 0 for false/no
325 suid Saved User ID. See getresuid(2) man page.
327 uid User ID. May be numeric or the user account name.
329 -k key Set a filter key on an audit rule. The filter key is an arbi‐
331 trary string of text that can be up to 31 bytes long. It can
332 uniquely identify the audit records produced by a rule. Typical
333 use is for when you have several rules that together satisfy a
334 security requirement. The key value can be searched on with
335 ausearch so that no matter which rule triggered the event, you
336 can find its results. The key can also be used on delete all
337 (-D) and list rules (-l) to select rules with a specific key.
338 You may have more than one key on a rule if you want to be able
339 to search logged events in multiple ways or if you have an aud‐
340 ispd plugin that uses a key to aid its analysis.
341 -p [r|w|x|a]
343 Describe the permission access type that a file system watch
344 will trigger on. r=read, w=write, x=execute, a=attribute change.
345 These permissions are not the standard file permissions, but
346 rather the kind of syscall that would do this kind of thing. The
347 read & write syscalls are omitted from this set since they would
348 overwhelm the logs. But rather for reads or writes, the open
349 flags are looked at to see what permission was requested.
350 -S [Syscall name or number|all]
352 Any syscall name or number may be used. The word 'all' may also
353 be used. If the given syscall is made by a program, then start
354 an audit record. If a field rule is given and no syscall is
355 specified, it will default to all syscalls. You may also specify
356 multiple syscalls in the same rule by using multiple -S options
357 in the same rule. Doing so improves performance since fewer
358 rules need to be evaluated. Alternatively, you may pass a comma
359 separated list of syscall names. If you are on a bi-arch system,
360 like x86_64, you should be aware that auditctl simply takes the
361 text, looks it up for the native arch (in this case b64) and
362 sends that rule to the kernel. If there are no additional arch
363 directives, IT WILL APPLY TO BOTH 32 & 64 BIT SYSCALLS. This can
364 have undesirable effects since there is no guarantee that any
365 syscall has the same number on both 32 and 64 bit interfaces.
366 You will likely want to control this and write 2 rules, one with
367 arch equal to b32 and one with b64 to make sure the kernel finds
368 the events that you intend. See the arch field discussion for
369 more info.
370 -w path
372 Insert a watch for the file system object at path. You cannot
373 insert a watch to the top level directory. This is prohibited by
374 the kernel. Wildcards are not supported either and will generate
375 a warning. The way that watches work is by tracking the inode
376 internally. If you place a watch on a file, its the same as
377 using the -F path option on a syscall rule. If you place a watch
378 on a directory, its the same as using the -F dir option on a
379 syscall rule. The -w form of writing watches is for backwards
380 compatibility and the syscall based form is more expressive.
381 Unlike most syscall auditing rules, watches do not impact per‐
382 formance based on the number of rules sent to the kernel. The
383 only valid options when using a watch are the -p and -k. If you
384 need to anything fancy like audit a specific user accessing a
385 file, then use the syscall auditing form with the path or dir
386 fields. See the EXAMPLES section for an example of converting
387 one form to another.
388 -W path
390 Remove a watch for the file system object at path. The rule must
391 match exactly. See -d discussion for more info.
392
394 Syscall rules get evaluated for each syscall for every program. If you
395 have 10 syscall rules, every program on your system will delay during a
396 syscall while the audit system evaluates each rule. Too many syscall
397 rules will hurt performance. Try to combine as many as you can whenever
398 the filter, action, key, and fields are identical. For example:
399 auditctl -a always,exit -S openat -F success=0
401 auditctl -a always,exit -S truncate -F success=0
402 could be re-written as one rule:
404 auditctl -a always,exit -S openat -S truncate -F success=0
406 Also, try to use file system auditing wherever practical. This improves
408 performance. For example, if you were wanting to capture all failed
409 opens & truncates like above, but were only concerned about files in
410 /etc and didn't care about /usr or /sbin, its possible to use this
411 rule:
412 auditctl -a always,exit -S openat -S truncate -F dir=/etc -F success=0
414 This will be higher performance since the kernel will not evaluate it
416 each and every syscall. It will be handled by the filesystem auditing
417 code and only checked on filesystem related syscalls.
418
420 To see all syscalls made by a specific program:
421 auditctl -a always,exit -S all -F pid=1005
423 To see files opened by a specific user:
425 auditctl -a always,exit -S openat -F auid=510
427 To see unsuccessful openat calls:
429 auditctl -a always,exit -S openat -F success=0
431 To watch a file for changes (2 ways to express):
433 auditctl -w /etc/shadow -p wa
435 auditctl -a always,exit -F path=/etc/shadow -F perm=wa
436 To recursively watch a directory for changes (2 ways to express):
438 auditctl -w /etc/ -p wa
440 auditctl -a always,exit -F dir=/etc/ -F perm=wa
441 To see if an admin is accessing other user's files:
443 auditctl -a always,exit -F dir=/home/ -F uid=0 -C auid!=obj_uid
445
448 /etc/audit/audit.rules
449
452 audit.rules(7), auditd(8).
453
456 Steve Grubb
457Red Hat Jan 2017 AUDITCTL:(8)