1AUDITCTL(8)             System Administration Utilities            AUDITCTL(8)
2
3
4

NAME

6       auditctl - a utility to assist controlling the kernel's audit system
7

SYNOPSIS

9       auditctl [options]
10

DESCRIPTION

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

CONFIGURATION OPTIONS

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
22       --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
28       --reset_backlog_wait_time_actual
29              Reset the actual backlog wait time counter shown by  the  status
30              command.
31
32       -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
36       -D     Delete  all  rules and watches. This can take a key option (-k),
37              too.
38
39       -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
49       -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
58       -h     Help
59
60       -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
65       --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
72       -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
81       -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
86       --reset-lost
87              Reset the lost record counter shown by the status command.
88
89       -R file
90              Read rules from a file. The rules must be 1 per line and in  the
91              order  that  they  are  to be executed in. The rule file must be
92              owned by root and not readable by other users or it will be  re‐
93              jected. The rule file may have comments embedded by starting the
94              line with a '#' character. Rules that are read from a  file  are
95              identical  to  what you would type on a command line except they
96              are not preceded by auditctl (since auditctl is the one  execut‐
97              ing  the  file)  and  you would not use shell escaping since au‐
98              ditctl is reading the file instead of bash.
99
100       --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
104       -t     Trim the subtrees after a mount command.
105

STATUS OPTIONS

107       -l     List all rules 1 per line. Two more options may be given to this
108              command. You can give either a key option  (-k)  to  list  rules
109              that  match a key or a (-i) to have a0 through a3 interpreted to
110              help determine the syscall argument values are correct .
111
112       -m text
113              Send a user space message into the audit system. This  can  only
114              be  done  if  you  have CAP_AUDIT_WRITE capability (normally the
115              root user has this). The resulting event will be the USER type.
116
117       -s     Report the kernel's audit subsystem status. It will tell you the
118              in-kernel  values that can be set by -e, -f, -r, and -b options.
119              The pid value is the process number of the  audit  daemon.  Note
120              that  a pid of 0 indicates that the audit daemon is not running.
121              The lost entry will tell you how many event  records  that  have
122              been  discarded  due  to the kernel audit queue overflowing. The
123              backlog field tells how many event records are currently  queued
124              waiting  for auditd to read them. This option can be followed by
125              the -i to get a couple fields interpreted.
126
127       -v     Print the version of auditctl.
128
129

RULE OPTIONS

131       -a [list,action|action,list]
132              Append rule to the end of list  with  action.  Please  note  the
133              comma  separating the two values. Omitting it will cause errors.
134              The fields may be in either order. It could  be  list,action  or
135              action,list. The following describes the valid list names:
136
137              task        Add  a  rule to the per task list. This rule list is
138                          used only at the time a  task  is  created  --  when
139                          fork()  or  clone()  are  called by the parent task.
140                          When using this list, you  should  only  use  fields
141                          that  are  known  at task creation time, such as the
142                          uid, gid, etc.
143
144              exit        Add a rule to the syscall exit list.  This  list  is
145                          used upon exit from a system call to determine if an
146                          audit event should be created.
147
148              user        Add a rule to the user  message  filter  list.  This
149                          list  is  used by the kernel to filter events origi‐
150                          nating in user space before relaying them to the au‐
151                          dit  daemon. It should be noted that the only fields
152                          that are valid are: uid, auid, gid, pid,  subj_user,
153                          subj_role,  subj_type,  subj_sen, subj_clr, msgtype,
154                          and  executable  name.  All  other  fields  will  be
155                          treated  as  non-matching.  It  should be understood
156                          that any event originating from user  space  from  a
157                          process  that  has  CAP_AUDIT_WRITE will be recorded
158                          into the audit  trail.  This  means  that  the  most
159                          likely  use  for this filter is with rules that have
160                          an action of never since nothing has to be  done  to
161                          allow events to be recorded.
162
163              exclude     Add  a rule to the event type exclusion filter list.
164                          This list is used to filter events that you  do  not
165                          want  to see. For example, if you do not want to see
166                          any avc messages,  you  would  using  this  list  to
167                          record  that.  Events can be excluded by process ID,
168                          user ID, group ID, login user ID, message type, sub‐
169                          ject  context, or executable name. The action is ig‐
170                          nored and uses its default of "never".
171
172              filesystem  Add a rule that will be applied to a whole  filesys‐
173                          tem. The filesystem must be identified with a fstype
174                          field. Normally this filter is used to  exclude  any
175                          events for a whole filesystem such as tracefs or de‐
176                          bugfs.
177
178       The following describes the valid actions for the rule:
179
180              never       No audit records will be generated. This can be used
181                          to  suppress  event generation. In general, you want
182                          suppressions at the top of the list instead  of  the
183                          bottom.  This  is  because the event triggers on the
184                          first matching rule.
185
186              always      Allocate an audit context,  always  fill  it  in  at
187                          syscall entry time, and always write out a record at
188                          syscall exit time.
189
190       -A list,action
191              Add rule to the beginning list with action.
192
193       -C [f=f | f!=f]
194              Build an inter-field comparison rule: field,  operation,  field.
195              You may pass multiple comparisons on a single command line. Each
196              one must start with -C. Each inter-field equation is anded  with
197              each  other  as well as equations starting with -F to trigger an
198              audit record. There are 2 operators supported - equal,  and  not
199              equal. Valid fields are:
200
201              auid,  uid, euid, suid, fsuid, obj_uid; and gid, egid, sgid, fs‐
202              gid, obj_gid
203
204              The two groups of uid and gid cannot be mixed. But any  compari‐
205              son  within  the  group  can be made. The obj_uid/gid fields are
206              collected from the object of the event such as a file or  direc‐
207              tory.
208
209
210       -d list,action
211              Delete  rule  from list with action. The rule is deleted only if
212              it exactly matches syscall name(s)  and  every  field  name  and
213              value.
214
215       -F [n=v | n!=v | n<v | n>v | n<=v | n>=v | n&v | n&=v]
216              Build  a  rule field: name, operation, value. You may have up to
217              64 fields passed on a single command line. Each one  must  start
218              with  -F.  Each field equation is anded with each other (as well
219              as equations starting with -C) to trigger an audit record. There
220              are 8 operators supported - equal, not equal, less than, greater
221              than, less than or equal, and greater than or equal,  bit  mask,
222              and  bit  test  respectively. Bit test will "and" the values and
223              check that they are equal, bit  mask  just  "ands"  the  values.
224              Fields that take a user ID may instead have the user's name; the
225              program will convert the name to user ID. The same  is  true  of
226              group names. Valid fields are:
227
228              a0, a1, a2, a3
229                          Respectively,  the  first  4 arguments to a syscall.
230                          Note that string arguments are not  supported.  This
231                          is  because  the  kernel  is passed a pointer to the
232                          string. Triggering on a pointer address value is not
233                          likely to work. So, when using this, you should only
234                          use on numeric values. This is  most  likely  to  be
235                          used on platforms that multiplex socket or IPC oper‐
236                          ations.
237
238              arch        The CPU architecture of the syscall. The arch can be
239                          found  doing 'uname -m'. If you do not know the arch
240                          of your machine but you  want  to  use  the  32  bit
241                          syscall  table and your machine supports 32 bit, you
242                          can also use b32 for the arch. The same  applies  to
243                          the  64 bit syscall table, you can use b64.  In this
244                          way, you can write rules that are somewhat arch  in‐
245                          dependent  because  the family type will be auto de‐
246                          tected. However, syscalls can be arch  specific  and
247                          what is available on x86_64, may not be available on
248                          ppc. The arch directive should precede the -S option
249                          so  that  auditctl knows which internal table to use
250                          to look up the syscall numbers.
251
252              auid        The original ID the user logged in with. Its an  ab‐
253                          breviation  of  audit uid. Sometimes its referred to
254                          as loginuid. Either the user account text or  number
255                          may be used.
256
257              devmajor    Device Major Number
258
259              devminor    Device Minor Number
260
261              dir         Full  Path  of Directory to watch. This will place a
262                          recursive watch on the directory and its whole  sub‐
263                          tree. It can only be used on exit list. See "-w".
264
265              egid        Effective  Group  ID.  May  be numeric or the groups
266                          name.
267
268              euid        Effective User ID. May be numeric or  the  user  ac‐
269                          count name.
270
271              exe         Absolute  path  to  application that while executing
272                          this rule will apply to. It supports = and != opera‐
273                          tors.  Note that you can only use this once for each
274                          rule.
275
276              exit        Exit value from a syscall. If the exit  code  is  an
277                          errno, you may use the text representation, too.
278
279              fsgid       Filesystem  Group  ID.  May be numeric or the groups
280                          name.
281
282              fsuid       Filesystem User ID. May be numeric or the  user  ac‐
283                          count name.
284
285              filetype    The  target  file's  type.  Can be either file, dir,
286                          socket, link, character, block, or fifo.
287
288              gid         Group ID. May be numeric or the groups name.
289
290              inode       Inode Number
291
292              key         This is another way of setting  a  filter  key.  See
293                          discussion above for -k option.
294
295              msgtype     This  is  used  to match the event's record type. It
296                          should only be used on the exclude  or  user  filter
297                          lists.
298
299              obj_uid     Object's UID
300
301              obj_gid     Object's GID
302
303              obj_user    Resource's SE Linux User
304
305              obj_role    Resource's SE Linux Role
306
307              obj_type    Resource's SE Linux Type
308
309              obj_lev_low Resource's SE Linux Low Level
310
311              obj_lev_high
312                          Resource's SE Linux High Level
313
314              path        Full  Path  of File to watch. It can only be used on
315                          exit list.
316
317              perm        Permission filter for file operations. See "-p".  It
318                          can  only  be  used  on  exit list. You can use this
319                          without specifying a syscall and the kernel will se‐
320                          lect the syscalls that satisfy the permissions being
321                          requested.
322
323              pers        OS Personality Number
324
325              pid         Process ID
326
327              ppid        Parent's Process ID
328
329              saddr_fam   Address  family  number   as   found   in   /usr/in‐
330                          clude/bits/socket.h.  For  example,  IPv4 would be 2
331                          and IPv6 would be 10.
332
333              sessionid   User's login session ID
334
335              subj_user   Program's SE Linux User
336
337              subj_role   Program's SE Linux Role
338
339              subj_type   Program's SE Linux Type
340
341              subj_sen    Program's SE Linux Sensitivity
342
343              subj_clr    Program's SE Linux Clearance
344
345              sgid        Saved Group ID. See getresgid(2) man page.
346
347              success     If the exit value is >= 0 this is true/yes otherwise
348                          its  false/no.  When  writing  a  rule,  use a 1 for
349                          true/yes and a 0 for false/no
350
351              suid        Saved User ID. See getresuid(2) man page.
352
353              uid         User ID. May be numeric or the user account name.
354
355       -k key Set a filter key on an audit rule. The filter key  is  an  arbi‐
356              trary  string  of  text  that can be up to 31 bytes long. It can
357              uniquely identify the audit records produced by a rule.  Typical
358              use  is  for when you have several rules that together satisfy a
359              security requirement. The key value  can  be  searched  on  with
360              ausearch  so  that no matter which rule triggered the event, you
361              can find its results. The key can also be  used  on  delete  all
362              (-D)  and  list  rules (-l) to select rules with a specific key.
363              You may have more than one key on a rule if you want to be  able
364              to  search  logged events in multiple ways or if you have an au‐
365              ditd plugin that uses a key to aid its analysis.
366
367       -p [r|w|x|a]
368              Describe the permission access type that  a  file  system  watch
369              will trigger on. r=read, w=write, x=execute, a=attribute change.
370              These permissions are not the  standard  file  permissions,  but
371              rather the kind of syscall that would do this kind of thing. The
372              read & write syscalls are omitted from this set since they would
373              overwhelm  the  logs.  But  rather for reads or writes, the open
374              flags are looked at to see what permission was requested.
375
376       -S [Syscall name or number|all]
377              Any syscall name or number may be used. The word 'all' may  also
378              be  used.  If the given syscall is made by a program, then start
379              an audit record. If a field rule is  given  and  no  syscall  is
380              specified, it will default to all syscalls. You may also specify
381              multiple syscalls in the same rule by using multiple -S  options
382              in  the  same  rule.  Doing  so improves performance since fewer
383              rules need to be evaluated. Alternatively, you may pass a  comma
384              separated list of syscall names. If you are on a bi-arch system,
385              like x86_64, you should be aware that auditctl simply takes  the
386              text,  looks  it  up  for the native arch (in this case b64) and
387              sends that rule to the kernel. If there are no  additional  arch
388              directives, IT WILL APPLY TO BOTH 32 & 64 BIT SYSCALLS. This can
389              have undesirable effects since there is no  guarantee  that  any
390              syscall  has  the  same number on both 32 and 64 bit interfaces.
391              You will likely want to control this and write 2 rules, one with
392              arch equal to b32 and one with b64 to make sure the kernel finds
393              the events that you intend. See the arch  field  discussion  for
394              more info.
395
396       -w path
397              Insert  a  watch  for the file system object at path. You cannot
398              insert a watch to the top level directory. This is prohibited by
399              the kernel. Wildcards are not supported either and will generate
400              a warning. The way that watches work is by  tracking  the  inode
401              internally.  If you place a watch on a file, its the same as us‐
402              ing the -F path option on a syscall rule. If you place  a  watch
403              on  a  directory,  its  the same as using the -F dir option on a
404              syscall rule. The -w form of writing watches  is  for  backwards
405              compatibility and the syscall based form is more expressive. Un‐
406              like most syscall auditing rules, watches do not impact  perfor‐
407              mance  based on the number of rules sent to the kernel. The only
408              valid options when using a watch are the -p and -k. If you  need
409              to  do  anything  fancy  like  audit a specific user accessing a
410              file, then use the syscall auditing form with the  path  or  dir
411              fields.  See  the  EXAMPLES section for an example of converting
412              one form to another.
413
414       -W path
415              Remove a watch for the file system object at path. The rule must
416              match exactly. See -d discussion for more info.
417

PERFORMANCE TIPS

419       Syscall  rules get evaluated for each syscall for every program. If you
420       have 10 syscall rules, every program on your system will delay during a
421       syscall  while  the  audit system evaluates each rule. Too many syscall
422       rules will hurt performance. Try to combine as many as you can whenever
423       the filter, action, key, and fields are identical. For example:
424
425       auditctl -a always,exit -F arch=b64 -S openat -F success=0
426       auditctl -a always,exit -F arch=b64 -S truncate -F success=0
427
428       could be re-written as one rule:
429
430       auditctl -a always,exit -F arch=b64 -S openat -S truncate -F success=0
431
432       Also, try to use file system auditing wherever practical. This improves
433       performance. For example, if you were wanting  to  capture  all  failed
434       opens  &  truncates  like above, but were only concerned about files in
435       /etc and didn't care about /usr or /sbin,  its  possible  to  use  this
436       rule:
437
438       auditctl -a always,exit -S openat -S truncate -F dir=/etc -F success=0
439
440       This  will  be higher performance since the kernel will not evaluate it
441       each and every syscall. It will be handled by the  filesystem  auditing
442       code and only checked on filesystem related syscalls.
443

EXAMPLES

445       To see all syscalls made by a specific program:
446
447       # By pid:
448       auditctl -a always,exit -S all -F pid=1005
449       # By executable path
450       auditctl -a always,exit -S all -F exe=/usr/bin/ls
451
452       To see files opened by a specific user:
453
454       auditctl -a always,exit -S openat -F auid=510
455
456       To see unsuccessful openat calls:
457
458       auditctl -a always,exit -S openat -F success=0
459
460       To watch a file for changes (2 ways to express):
461
462       auditctl -w /etc/shadow -p wa
463       auditctl -a always,exit -F path=/etc/shadow -F perm=wa
464
465       To recursively watch a directory for changes (2 ways to express):
466
467       auditctl -w /etc/ -p wa
468       auditctl -a always,exit -F dir=/etc/ -F perm=wa
469
470       To see if an admin is accessing other user's files:
471
472       auditctl -a always,exit -F dir=/home/ -F uid=0 -C auid!=obj_uid
473
474

DISABLED BY DEFAULT

476       On  many  systems auditd is configured to install an -a never,task rule
477       by default. This rule causes every new process to skip all  audit  rule
478       processing.  This is usually done to avoid a small performance overhead
479       imposed by syscall auditing. If you want to use auditd, you need to re‐
480       move  that  rule  by deleting 10-no-audit.rules and adding 10-base-con‐
481       fig.rules to the audit rules directory.
482
483       If you have defined audit rules that are not matching when they should,
484       check auditctl -l to make sure there is no never,task rule there.
485
486

FILES

488       /etc/audit/audit.rules /etc/audit/audit-stop.rules
489
490

SEE ALSO

492       audit.rules(7), ausearch(8), aureport(8), auditd(8).
493
494

AUTHOR

496       Steve Grubb
497
498
499
500Red Hat                            July 2021                       AUDITCTL(8)
Impressum