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 au‐
13 diting, to see status of the configuration, and to load discretionary
14 audit rules.
15
17 -b backlog
18 Set max number (limit) of outstanding audit buffers allowed
19 (Kernel Default=64) If all buffers are full, the failure flag is
20 consulted by the kernel for action.
21 --backlog_wait_time wait_time
23 Set the time for the kernel to wait (Kernel Default 60*HZ) when
24 the backlog limit is reached before queuing more audit events to
25 be transferred to auditd. The number must be greater than or
26 equal to zero and less than 10 times the default value.
27 --reset_backlog_wait_time_actual
29 Reset the actual backlog wait time counter shown by the status
30 command.
31 -c Continue loading rules in spite of an error. This summarizes the
33 results of loading the rules. The exit code will not be success
34 if any rule fails to load.
35 -D Delete all rules and watches. This can take a key option (-k),
37 too.
38 -e [0..2]
40 Set enabled flag. When 0 is passed, this can be used to tempo‐
41 rarily disable auditing. When 1 is passed as an argument, it
42 will enable auditing. To lock the audit configuration so that it
43 can't be changed, pass a 2 as the argument. Locking the configu‐
44 ration is intended to be the last command in audit.rules for
45 anyone wishing this feature to be active. Any attempt to change
46 the configuration in this mode will be audited and denied. The
47 configuration can only be changed by rebooting the machine.
48 -f [0..2]
50 Set failure mode 0=silent 1=printk 2=panic. This option lets you
51 determine how you want the kernel to handle critical errors. Ex‐
52 ample conditions where this mode may have an effect includes:
53 transmission errors to userspace audit daemon, backlog limit ex‐
54 ceeded, out of kernel memory, and rate limit exceeded. The de‐
55 fault value is 1. Secure environments will probably want to set
56 this to 2.
57 -h Help
59 -i When given by itself, ignore errors when reading rules from a
61 file. This causes auditctl to always return a success exit code.
62 If passed as an argument to -s then it gives an interpretation
63 of the numbers to human readable words if possible.
64 --loginuid-immutable
66 This option tells the kernel to make loginuids unchangeable once
67 they are set. Changing loginuids requires CAP_AUDIT_CONTROL. So,
68 its not something that can be done by unprivileged users. Set‐
69 ting this makes loginuid tamper-proof, but can cause some prob‐
70 lems in certain kinds of containers.
71 -q mount-point,subtree
73 If you have an existing directory watch and bind or move mount
74 another subtree in the watched subtree, you need to tell the
75 kernel to make the subtree being mounted equivalent to the di‐
76 rectory being watched. If the subtree is already mounted at the
77 time the directory watch is issued, the subtree is automatically
78 tagged for watching. Please note the comma separating the two
79 values. Omitting it will cause errors.
80 -r rate
82 Set limit in messages/sec (0=none). If this rate is non-zero and
83 is exceeded, the failure flag is consulted by the kernel for ac‐
84 tion. The default value is 0.
85 --reset-lost
87 Reset the lost record counter shown by the status command.
88 -R file
90 Read and execute auditctl commands from a file. The commands are
91 executed line-by-line, in the order that they appear in the
92 file. The file must be owned by root and not readable by other
93 users, or else it will be rejected. Empty lines are skipped.
94 Lines starting with the '#' character are treated as comment
95 lines. Each line is executed as if it was provided to auditctl
96 as command line arguments. Since auditctl is the one reading the
97 file and not a shell such as bash, do not escape special shell
98 characters. See the EXAMPLES section for an example.
99 --signal signal
101 Send a signal to the audit daemon. You must have privileges to
102 do this. Supported signals are TERM, HUP, USR1, USR2, CONT
103 and user friendly versions stop, reload, rotate, resume, state.
104 -t Trim the subtrees after a mount command.
106
108 -l List all rules 1 per line. Two more options may be given to this
109 command. You can give either a key option (-k) to list rules
110 that match a key or a (-i) to have a0 through a3 interpreted to
111 help determine the syscall argument values are correct .
112 -m text
114 Send a user space message into the audit system. This can only
115 be done if you have CAP_AUDIT_WRITE capability (normally the
116 root user has this). The resulting event will be the USER type.
117 -s Report the kernel's audit subsystem status. It will tell you the
119 in-kernel values that can be set by -e, -f, -r, and -b options.
120 The pid value is the process number of the audit daemon. Note
121 that a pid of 0 indicates that the audit daemon is not running.
122 The lost entry will tell you how many event records that have
123 been discarded due to the kernel audit queue overflowing. The
124 backlog field tells how many event records are currently queued
125 waiting for auditd to read them. This option can be followed by
126 the -i to get a couple fields interpreted.
127 -v Print the version of auditctl.
129
132 -a [list,action|action,list]
133 Append rule to the end of list with action. Please note the
134 comma separating the two values. Omitting it will cause errors.
135 The fields may be in either order. It could be list,action or
136 action,list. The following describes the valid list names:
137 task Add a rule to the per task list. This rule list is
139 used only at the time a task is created -- when
140 fork() or clone() are called by the parent task.
141 When using this list, you should only use fields
142 that are known at task creation time, such as the
143 uid, gid, etc.
144 exit Add a rule to the syscall exit list. This list is
146 used upon exit from a system call to determine if an
147 audit event should be created.
148 user Add a rule to the user message filter list. This
150 list is used by the kernel to filter events origi‐
151 nating in user space before relaying them to the au‐
152 dit daemon. It should be noted that the only fields
153 that are valid are: uid, auid, gid, pid, subj_user,
154 subj_role, subj_type, subj_sen, subj_clr, msgtype,
155 and executable name. All other fields will be
156 treated as non-matching. It should be understood
157 that any event originating from user space from a
158 process that has CAP_AUDIT_WRITE will be recorded
159 into the audit trail. This means that the most
160 likely use for this filter is with rules that have
161 an action of never since nothing has to be done to
162 allow events to be recorded.
163 exclude Add a rule to the event type exclusion filter list.
165 This list is used to filter events that you do not
166 want to see. For example, if you do not want to see
167 any avc messages, you would using this list to
168 record that. Events can be excluded by process ID,
169 user ID, group ID, login user ID, message type, sub‐
170 ject context, or executable name. The action is ig‐
171 nored and uses its default of "never".
172 filesystem Add a rule that will be applied to a whole filesys‐
174 tem. The filesystem must be identified with a fstype
175 field. Normally this filter is used to exclude any
176 events for a whole filesystem such as tracefs or de‐
177 bugfs.
178 io_uring Add a rule to the io_uring syscall filter. Rules
180 against this filter specify the syscall operation
181 using the -S syscall notion explained below. You can
182 add a key field to the rule so that it may be
183 grouped with other rules watching the same underly‐
184 ing syscall.
185 The following describes the valid actions for the rule:
187 never No audit records will be generated. This can be used
189 to suppress event generation. In general, you want
190 suppressions at the top of the list instead of the
191 bottom. This is because the event triggers on the
192 first matching rule.
193 always Allocate an audit context, always fill it in at
195 syscall entry time, and always write out a record at
196 syscall exit time.
197 -A list,action
199 Add rule to the beginning list with action.
200 -C [f=f | f!=f]
202 Build an inter-field comparison rule: field, operation, field.
203 You may pass multiple comparisons on a single command line. Each
204 one must start with -C. Each inter-field equation is anded with
205 each other as well as equations starting with -F to trigger an
206 audit record. There are 2 operators supported - equal, and not
207 equal. Valid fields are:
208 auid, uid, euid, suid, fsuid, obj_uid; and gid, egid, sgid, fs‐
210 gid, obj_gid
211 The two groups of uid and gid cannot be mixed. But any compari‐
213 son within the group can be made. The obj_uid/gid fields are
214 collected from the object of the event such as a file or direc‐
215 tory.
216 -d list,action
219 Delete rule from list with action. The rule is deleted only if
220 it exactly matches syscall name(s) and every field name and
221 value.
222 -F [n=v | n!=v | n<v | n>v | n<=v | n>=v | n&v | n&=v]
224 Build a rule field: name, operation, value. You may have up to
225 64 fields passed on a single command line. Each one must start
226 with -F. Each field equation is anded with each other (as well
227 as equations starting with -C) to trigger an audit record. There
228 are 8 operators supported - equal, not equal, less than, greater
229 than, less than or equal, and greater than or equal, bit mask,
230 and bit test respectively. Bit test will "and" the values and
231 check that they are equal, bit mask just "ands" the values.
232 Fields that take a user ID may instead have the user's name; the
233 program will convert the name to user ID. The same is true of
234 group names. Valid fields are:
235 a0, a1, a2, a3
237 Respectively, the first 4 arguments to a syscall.
238 Note that string arguments are not supported. This
239 is because the kernel is passed a pointer to the
240 string. Triggering on a pointer address value is not
241 likely to work. So, when using this, you should only
242 use on numeric values. This is most likely to be
243 used on platforms that multiplex socket or IPC oper‐
244 ations.
245 arch The CPU architecture of the syscall. The arch can be
247 found doing 'uname -m'. If you do not know the arch
248 of your machine but you want to use the 32 bit
249 syscall table and your machine supports 32 bit, you
250 can also use b32 for the arch. The same applies to
251 the 64 bit syscall table, you can use b64. In this
252 way, you can write rules that are somewhat arch in‐
253 dependent because the family type will be auto de‐
254 tected. However, syscalls can be arch specific and
255 what is available on x86_64, may not be available on
256 ppc. The arch directive should precede the -S option
257 so that auditctl knows which internal table to use
258 to look up the syscall numbers.
259 auid The original ID the user logged in with. Its an ab‐
261 breviation of audit uid. Sometimes its referred to
262 as loginuid. Either the user account text or number
263 may be used.
264 devmajor Device Major Number
266 devminor Device Minor Number
268 dir Full Path of Directory to watch. This will place a
270 recursive watch on the directory and its whole sub‐
271 tree. It can only be used on exit list. See "-w".
272 egid Effective Group ID. May be numeric or the groups
274 name.
275 euid Effective User ID. May be numeric or the user ac‐
277 count name.
278 exe Absolute path to application that while executing
280 this rule will apply to. It supports = and != opera‐
281 tors. Note that you can only use this once for each
282 rule.
283 exit Exit value from a syscall. If the exit code is an
285 errno, you may use the text representation, too.
286 fsgid Filesystem Group ID. May be numeric or the groups
288 name.
289 fstype File system type. This is used with the filesystem
291 rule list. The only values supported are debugfs and
292 tracefs.
293 fsuid Filesystem User ID. May be numeric or the user ac‐
295 count name.
296 filetype The target file's type. Can be either file, dir,
298 socket, link, character, block, or fifo.
299 gid Group ID. May be numeric or the groups name.
301 inode Inode Number
303 key This is another way of setting a filter key. See
305 discussion above for -k option.
306 msgtype This is used to match the event's record type. It
308 should only be used on the exclude or user filter
309 lists.
310 obj_uid Object's UID
312 obj_gid Object's GID
314 obj_user Resource's SE Linux User
316 obj_role Resource's SE Linux Role
318 obj_type Resource's SE Linux Type
320 obj_lev_low Resource's SE Linux Low Level
322 obj_lev_high
324 Resource's SE Linux High Level
325 path Full Path of File to watch. It can only be used on
327 exit list.
328 perm Permission filter for file operations. See "-p". It
330 can only be used on exit list. You can use this
331 without specifying a syscall and the kernel will se‐
332 lect the syscalls that satisfy the permissions being
333 requested.
334 pers OS Personality Number
336 pid Process ID
338 ppid Parent's Process ID
340 saddr_fam Address family number as found in /usr/in‐
342 clude/bits/socket.h. For example, IPv4 would be 2
343 and IPv6 would be 10.
344 sessionid User's login session ID
346 subj_user Program's SE Linux User
348 subj_role Program's SE Linux Role
350 subj_type Program's SE Linux Type
352 subj_sen Program's SE Linux Sensitivity
354 subj_clr Program's SE Linux Clearance
356 sgid Saved Group ID. See getresgid(2) man page.
358 success If the exit value is >= 0 this is true/yes otherwise
360 its false/no. When writing a rule, use a 1 for
361 true/yes and a 0 for false/no
362 suid Saved User ID. See getresuid(2) man page.
364 uid User ID. May be numeric or the user account name.
366 -k key Set a filter key on an audit rule. The filter key is an arbi‐
368 trary string of text that can be up to 31 bytes long. It can
369 uniquely identify the audit records produced by a rule. Typical
370 use is for when you have several rules that together satisfy a
371 security requirement. The key value can be searched on with
372 ausearch so that no matter which rule triggered the event, you
373 can find its results. The key can also be used on delete all
374 (-D) and list rules (-l) to select rules with a specific key.
375 You may have more than one key on a rule if you want to be able
376 to search logged events in multiple ways or if you have an au‐
377 ditd plugin that uses a key to aid its analysis.
378 -p [r|w|x|a]
380 Describe the permission access type that a file system watch
381 will trigger on. r=read, w=write, x=execute, a=attribute change.
382 These permissions are not the standard file permissions, but
383 rather the kind of syscall that would do this kind of thing. The
384 read & write syscalls are omitted from this set since they would
385 overwhelm the logs. But rather for reads or writes, the open
386 flags are looked at to see what permission was requested.
387 -S [Syscall name or number|all]
389 Any syscall name or number may be used. The word 'all' may also
390 be used. If the given syscall is made by a program, then start
391 an audit record. If a field rule is given and no syscall is
392 specified, it will default to all syscalls. You may also specify
393 multiple syscalls in the same rule by using multiple -S options
394 in the same rule. Doing so improves performance since fewer
395 rules need to be evaluated. Alternatively, you may pass a comma
396 separated list of syscall names. If you are on a bi-arch system,
397 like x86_64, you should be aware that auditctl simply takes the
398 text, looks it up for the native arch (in this case b64) and
399 sends that rule to the kernel. If there are no additional arch
400 directives, IT WILL APPLY TO BOTH 32 & 64 BIT SYSCALLS. This can
401 have undesirable effects since there is no guarantee that any
402 syscall has the same number on both 32 and 64 bit interfaces.
403 You will likely want to control this and write 2 rules, one with
404 arch equal to b32 and one with b64 to make sure the kernel finds
405 the events that you intend. See the arch field discussion for
406 more info.
407 -w path
409 Insert a watch for the file system object at path. You cannot
410 insert a watch to the top level directory. This is prohibited by
411 the kernel. Wildcards are not supported either and will generate
412 a warning. The way that watches work is by tracking the inode
413 internally. If you place a watch on a file, its the same as us‐
414 ing the -F path option on a syscall rule. If you place a watch
415 on a directory, its the same as using the -F dir option on a
416 syscall rule. The -w form of writing watches is for backwards
417 compatibility and the syscall based form is more expressive. Un‐
418 like most syscall auditing rules, watches do not impact perfor‐
419 mance based on the number of rules sent to the kernel. The only
420 valid options when using a watch are the -p and -k. If you need
421 to do anything fancy like audit a specific user accessing a
422 file, then use the syscall auditing form with the path or dir
423 fields. See the EXAMPLES section for an example of converting
424 one form to another.
425 -W path
427 Remove a watch for the file system object at path. The rule must
428 match exactly. See -d discussion for more info.
429
431 Syscall rules get evaluated for each syscall for every program. If you
432 have 10 syscall rules, every program on your system will delay during a
433 syscall while the audit system evaluates each rule. Too many syscall
434 rules will hurt performance. Try to combine as many as you can whenever
435 the filter, action, key, and fields are identical. For example:
436 auditctl -a always,exit -F arch=b64 -S openat -F success=0
438 auditctl -a always,exit -F arch=b64 -S truncate -F success=0
439 could be re-written as one rule:
441 auditctl -a always,exit -F arch=b64 -S openat -S truncate -F success=0
443 Also, try to use file system auditing wherever practical. This improves
445 performance. For example, if you were wanting to capture all failed
446 opens & truncates like above, but were only concerned about files in
447 /etc and didn't care about /usr or /sbin, its possible to use this
448 rule:
449 auditctl -a always,exit -S openat -S truncate -F dir=/etc -F success=0
451 This will be higher performance since the kernel will not evaluate it
453 each and every syscall. It will be handled by the filesystem auditing
454 code and only checked on filesystem related syscalls.
455
457 To see all syscalls made by a specific program:
458 # By pid:
460 auditctl -a always,exit -S all -F pid=1005
461 # By executable path
462 auditctl -a always,exit -S all -F exe=/usr/bin/ls
463 To see files opened by a specific user:
465 auditctl -a always,exit -S openat -F auid=510
467 To see unsuccessful openat calls:
469 auditctl -a always,exit -S openat -F success=0
471 To watch a file for changes (2 ways to express):
473 auditctl -w /etc/shadow -p wa
475 auditctl -a always,exit -F path=/etc/shadow -F perm=wa
476 To recursively watch a directory for changes (2 ways to express):
478 auditctl -w /etc/ -p wa
480 auditctl -a always,exit -F dir=/etc/ -F perm=wa
481 To see if an admin is accessing other user's files:
483 auditctl -a always,exit -F dir=/home/ -F uid=0 -C auid!=obj_uid
485 This is an example rules file:
487 # Remove all existing rules
489 -D
490 # Never record sudo invocations
491 -A exclude,always -F exe=/usr/bin/sudo
492
495 On many systems auditd is configured to install an -a never,task rule
496 by default. This rule causes every new process to skip all audit rule
497 processing. This is usually done to avoid a small performance overhead
498 imposed by syscall auditing. If you want to use auditd, you need to re‐
499 move that rule by deleting 10-no-audit.rules and adding 10-base-con‐
500 fig.rules to the audit rules directory.
501 If you have defined audit rules that are not matching when they should,
503 check auditctl -l to make sure there is no never,task rule there.
504
507 /etc/audit/audit.rules /etc/audit/audit-stop.rules
508
511 audit.rules(7), ausearch(8), aureport(8), auditd(8).
512
515 Steve Grubb
516Red Hat Feb 2023 AUDITCTL(8)