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
13       auditing, to see status of the configuration, and to load discretionary
14       audit rules.
15

CONFIGURATION OPTIONS

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
22       -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
26       -D     Delete  all  rules and watches. This can take a key option (-k),
27              too.
28
29       -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
39       -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
48       -h     Help
49
50       -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
55       --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
62       -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
71       -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
76       --reset-lost
77              Reset the lost record counter shown by the status command.
78
79       -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
90       -t     Trim the subtrees after a mount command.
91

STATUS OPTIONS

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
98       -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
103       -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
113       -v     Print the version of auditctl.
114
115

RULE OPTIONS

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
123              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
130              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
134              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
149              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
158       The following describes the valid actions for the rule:
159
160              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
166              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
170       -A list,action
171              Add rule to the beginning list with action.
172
173       -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
181              auid, uid, euid, suid, fsuid,  obj_uid;  and  gid,  egid,  sgid,
182              fsgid, obj_gid
183
184              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
189
190       -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
195       -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
208              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
218              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
232              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
237              devmajor    Device Major Number
238
239              devminor    Device Minor Number
240
241              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
245              egid        Effective Group ID. May be  numeric  or  the  groups
246                          name.
247
248              euid        Effective  User  ID.  May  be  numeric  or  the user
249                          account name.
250
251              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
255              exit        Exit value from a syscall. If the exit  code  is  an
256                          errno, you may use the text representation, too.
257
258              fsgid       Filesystem  Group  ID.  May be numeric or the groups
259                          name.
260
261              fsuid       Filesystem User ID.  May  be  numeric  or  the  user
262                          account name.
263
264              filetype    The  target  file's  type.  Can be either file, dir,
265                          socket, link, character, block, or fifo.
266
267              gid         Group ID. May be numeric or the groups name.
268
269              inode       Inode Number
270
271              key         This is another way of setting  a  filter  key.  See
272                          discussion above for -k option.
273
274              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
278              obj_uid     Object's UID
279
280              obj_gid     Object's GID
281
282              obj_user    Resource's SE Linux User
283
284              obj_role    Resource's SE Linux Role
285
286              obj_type    Resource's SE Linux Type
287
288              obj_lev_low Resource's SE Linux Low Level
289
290              obj_lev_high
291                          Resource's SE Linux High Level
292
293              path        Full  Path  of File to watch. It can only be used on
294                          exit list.
295
296              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
302              pers        OS Personality Number
303
304              pid         Process ID
305
306              ppid        Parent's Process ID
307
308              sessionid   User's login session ID
309
310              subj_user   Program's SE Linux User
311
312              subj_role   Program's SE Linux Role
313
314              subj_type   Program's SE Linux Type
315
316              subj_sen    Program's SE Linux Sensitivity
317
318              subj_clr    Program's SE Linux Clearance
319
320              sgid        Saved Group ID. See getresgid(2) man page.
321
322              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
326              suid        Saved User ID. See getresuid(2) man page.
327
328              uid         User ID. May be numeric or the user account name.
329
330       -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
342       -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
351       -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
371       -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
389       -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

PERFORMANCE TIPS

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
400       auditctl -a always,exit -S openat -F success=0
401       auditctl -a always,exit -S truncate -F success=0
402
403       could be re-written as one rule:
404
405       auditctl -a always,exit -S openat -S truncate -F success=0
406
407       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
413       auditctl -a always,exit -S openat -S truncate -F dir=/etc -F success=0
414
415       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

EXAMPLES

420       To see all syscalls made by a specific program:
421
422       auditctl -a always,exit -S all -F pid=1005
423
424       To see files opened by a specific user:
425
426       auditctl -a always,exit -S openat -F auid=510
427
428       To see unsuccessful openat calls:
429
430       auditctl -a always,exit -S openat -F success=0
431
432       To watch a file for changes (2 ways to express):
433
434       auditctl -w /etc/shadow -p wa
435       auditctl -a always,exit -F path=/etc/shadow -F perm=wa
436
437       To recursively watch a directory for changes (2 ways to express):
438
439       auditctl -w /etc/ -p wa
440       auditctl -a always,exit -F dir=/etc/ -F perm=wa
441
442       To see if an admin is accessing other user's files:
443
444       auditctl -a always,exit -F dir=/home/ -F uid=0 -C auid!=obj_uid
445
446

FILES

448       /etc/audit/audit.rules
449
450

SEE ALSO

452       audit.rules(7), auditd(8).
453
454

AUTHOR

456       Steve Grubb
457
458
459
460Red Hat                            Jan 2017                       AUDITCTL:(8)
Impressum