{
    "mode": "man",
    "parameter": "audit.rules",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/audit.rules/7/json",
    "generated": "2026-11-21T20:23:05Z",
    "sections": {
        "NAME": {
            "content": "audit.rules - a set of rules loaded in the kernel audit system\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "audit.rules  is  a file containing audit rules that will be loaded by the audit daemon's init\nscript whenever the daemon is started. The auditctl program is used  by  the  initscripts  to\nperform this operation. The syntax for the rules is essentially the same as when typing in an\nauditctl  command  at a shell prompt except you do not need to type the auditctl command name\nsince that is implied. The audit rules come in 3 varieties: control, file, and syscall.\n\n",
            "subsections": [
                {
                    "name": "Control",
                    "content": "Control commands generally involve configuring the audit system rather than telling  it  what\nto  watch  for.  These commands typically include deleting all rules, setting the size of the\nkernel's backlog queue, setting the failure mode, setting the event rate limit,  or  to  tell\nauditctl  to  ignore  syntax errors in the rules and continue loading. Generally, these rules\nare at the top of the rules file.\n\n"
                },
                {
                    "name": "File System",
                    "content": "File System rules are sometimes called watches. These rules are used to audit access to  par‐\nticular files or directories that you may be interested in. If the path given in a watch rule\nis a directory, then the rule used is recursive to the bottom of the directory tree excluding\nany  directories  that  may be mount points. The syntax of these watch rules generally follow\nthis format:\n"
                },
                {
                    "name": "-w path-to-file -p permissions -k keyname",
                    "content": "where the permission are any one of the following:\n\n\nr - read of the file\n\nw - write to the file\n\nx - execute the file\n\na - change in the file's attribute\n\nWatches can also be created using the syscall format described below which allow for  greater\nflexibility  and  options.  Using  syscall rules you can choose between path and dir which is\nagainst a specific inode or directory tree respectively. It should also be noted that the re‐\ncursive directory watch will stop if there is a mount point below the parent directory. There\nis an option to make the mounted subdirectory equivalent by using a -q rule.\n\n",
                    "flag": "-k"
                },
                {
                    "name": "System Call",
                    "content": "The system call rules are loaded into a matching engine that intercepts each syscall that all\nprograms on the system makes. Therefore it is very important to only use syscall  rules  when\nyou  have  to since these affect performance. The more rules, the bigger the performance hit.\nYou can help the performance, though, by combining syscalls into one rule whenever possible.\n\nThe Linux kernel has 6 rule matching lists or filters as they are sometimes called. They are:\ntask, exit, user, exclude, filesystem, and iouring. The task list is checked only during the\nfork or clone syscalls. It is rarely used in practice.\n\nThe exit filter is the place where all syscall and file system audit requests are evaluated.\n\nThe user filter is used to filter (remove) some events that originate in user space.  By  de‐\nfault,  any event originating in user space is allowed. So, if there are some events that you\ndo not want to see, then this is a place where some  can  be  removed.  See  auditctl(8)  for\nfields that are valid.\n\nThe  exclude  filter  is used to exclude certain events from being emitted. The msgtype and a\nnumber of subject attribute fields can be used to tell the kernel which message types you  do\nnot  want  to  record. This filter can remove the event as a whole and is not selective about\nany other attribute. The user and exit filters are  better  suited  to  selectively  auditing\nevents.  The action is ignored for this filter, defaulting to \"never\".\n\nThe iouring filter is used to watch underlying syscalls performed by iouring operations.\n\nSyscall rules take the general form of:\n"
                },
                {
                    "name": "-a action,list -S syscall -F field=value -k keyname",
                    "content": "The  -a  option  tells the kernel's rule matching engine that we want to append a rule at the\nend of the rule list. But we need to specify which rule list it goes on and  what  action  to\ntake when it triggers. Valid actions are:\n\n\nalways - always create an event\n\nnever  - never create an event\n\nThe  action and list are separated by a comma but no space in between. Valid lists are: task,\nexit, user, exclude, filesystem, and iouring. Their meaning was explained earlier.\n\nNext in the rule would normally be the -S option. This field can either be the  syscall  name\nor  number.  For  readability,  the  name  is  almost always used. You may give more than one\nsyscall in a rule by specifying another -S option. When sent into  the  kernel,  all  syscall\nfields  are  put into a mask so that one compare can determine if the syscall is of interest.\nSo, adding multiple syscalls in one rule is very efficient. When you specify a syscall  name,\nauditctl will look up the name and get its syscall number. This leads to some problems on bi-\narch  machines.  The 32 and 64 bit syscall numbers sometimes, but not always, line up. So, to\nsolve this problem, you would generally need to break the rule into 2 with one specifying  -F\narch=b32  and the other specifying -F arch=b64. This needs to go in front of the -S option so\nthat auditctl looks at the right lookup table when returning the number.\n\nAfter the syscall is specified, you would normally have one or more -F options that fine tune\nwhat to match against. Rather than list all the valid field types  here,  the  reader  should\nlook  at  the auditctl man page which has a full listing of each field and what it means. But\nit's worth mentioning a couple things.\n\nThe audit system considers uids to be unsigned numbers. The audit system uses the  number  -1\nto  indicate that a loginuid is not set. This means that when it's printed out, it looks like\n4294967295. But when you write rules, you can use either \"unset\" which is easy  to  remember,\nor -1, or 4294967295. They are all equivalent. If you write a rule that you wanted try to get\nthe valid users of the system, you need to look in /etc/login.defs to see where user accounts\nstart.  For  example,  if UIDMIN is 1000, then you would also need to take into account that\nthe unsigned representation of -1 is higher than 500. So you would address this with the fol‐\nlowing piece of a rule:\n\n-F auid>=1000 -F auid!=unset\n\nThese individual checks are \"anded\" and both have to be true.\n\nThe last thing to know about syscall rules is that you can add a key field which  is  a  free\nform  text string that you want inserted into the event to help identify its meaning. This is\ndiscussed in more detail in the NOTES section.\n\n",
                    "flag": "-k"
                }
            ]
        },
        "NOTES": {
            "content": "The purpose of auditing is to be able to do an investigation periodically or whenever an  in‐\ncident  occurs.  A  few simple steps in planning up front will make this job easier. The best\nadvice is to use keys in both the watches and system call rules to give the rule  a  meaning.\nIf  rules  are  related  or together meet a specific requirement, then give them a common key\nname. You can use this during your investigation to select only results with a specific mean‐\ning.\n\nWhen doing an investigation, you would normally start off with the main  aureport  output  to\njust  get  an  idea about what is happening on the system. This report mostly tells you about\nevents that are hard coded by the audit system such as  login/out,  uses  of  authentication,\nsystem  anomalies,  how many users have been on the machine, and if SE Linux has detected any\nAVCs.\n\naureport --start this-week\n\nAfter looking at the report, you probably want to get a second  view  about  what  rules  you\nloaded  that  have  been triggering. This is where keys become important. You would generally\nrun the key summary report like this:\n\naureport --start this-week --key --summary\n\nThis will give an ordered listing of the keys associated with rules that have  been  trigger‐\ning.  If,  for  example,  you  had a syscall audit rule that triggered on the failure to open\nfiles with EPERM that had a key field of access like this:\n\n-a always,exit -F arch=b64 -S open -S openat -S openat2 -F exit=-EPERM -k access\n\nThen you can isolate these failures with ausearch and pipe the results to aureport  for  dis‐\nplay.  Suppose your investigation noticed a lot of the access denied events. If you wanted to\nsee the files that unauthorized access has been attempted, you could run the  following  com‐\nmand:\n\nausearch --start this-week -k access --raw | aureport --file --summary\n\nThis will give an ordered list showing which files are being accessed with the EPERM failure.\nSuppose  you  wanted to see which users might be having failed access, you would run the fol‐\nlowing command:\n\nausearch --start this-week -k access --raw | aureport --user --summary\n\nIf your investigation showed a lot of failed accesses to a particular file, you could run the\nfollowing report to see who is doing it:\n\nausearch --start this-week -k access -f /path-to/file --raw | aureport --user -i\n\nThis report will give you the individual access attempts by person. If you needed to see  the\nactual  audit  event  that  is  being  reported,  you would look at the date, time, and event\ncolumns. Assuming the event was 822 and it occurred at 2:30 on 09/01/2009  and  you  use  the\nenUS.utf8 locale, the command would look something like this:\n\nausearch --start 09/01/2009 02:30 -a 822 -i --just-one\n\nThis will select the first event from that day and time with the matching event id and inter‐\npret the numeric values into human readable values.\n\nThe  most  important  step in being able to do this kind of analysis is setting up key fields\nwhen the rules were originally written. It should also be pointed out that you can have  more\nthan one key field associated with any given rule.\n\n",
            "subsections": []
        },
        "TROUBLESHOOTING": {
            "content": "If  you are not getting events on syscall rules that you think you should, try running a test\nprogram under strace so that you can see the syscalls. There is a chance that you might  have\nidentified the wrong syscall.\n\nIf you get a warning from auditctl saying, \"32/64 bit syscall mismatch in line XX, you should\nspecify  an arch\". This means that you specified a syscall rule on a bi-arch system where the\nsyscall has a different syscall number for the 32 and 64 bit interfaces. This means  that  on\none  of those interfaces you are likely auditing the wrong syscall. To solve the problem, re-\nwrite the rule as two rules specifying the intended arch for each rule. For example,\n\n-a always,exit -S openat -k access\n\nwould be rewritten as\n\n-a always,exit -F arch=b32 -S openat -k access\n-a always,exit -F arch=b64 -S openat -k access\n\nIf you get a warning that says, \"entry rules deprecated, changing to exit rule\".  This  means\nthat  you  have a rule intended for the entry filter, but that filter is no longer available.\nAuditctl moved your rule to the exit filter so that it's not lost. But to solve this so  that\nyou  do  not  get  the  warning any more, you need to change the offending rule from entry to\nexit.\n\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "The following rule shows how to audit failed access to files due to permission problems. Note\nthat it takes two rules for each arch ABI to audit this since file access can fail  with  two\ndifferent failure codes indicating permission problems.\n",
            "subsections": [
                {
                    "name": "-a always,exit -F arch=b32 -S open -S openat -S openat2 -F exit=-EACCES -k access",
                    "content": "",
                    "flag": "-k"
                },
                {
                    "name": "-a always,exit -F arch=b32 -S open -S openat -S openat2 -F exit=-EPERM -k access",
                    "content": "",
                    "flag": "-k"
                },
                {
                    "name": "-a always,exit -F arch=b64 -S open -S openat -S openat2 -F exit=-EACCES -k access",
                    "content": "",
                    "flag": "-k"
                },
                {
                    "name": "-a always,exit -F arch=b64 -S open -S openat -S openat2 -F exit=-EPERM -k access",
                    "content": "",
                    "flag": "-k"
                }
            ]
        },
        "IOURING RULES": {
            "content": "Iouring  rules do not take an arch field. It is implicit in the specification of the filter.\nThe following example rule watches for file opens through the iouring subsystem:\n",
            "subsections": [
                {
                    "name": "-a always,io_uring -S openat -S openat2 -F key=access",
                    "content": "",
                    "flag": "-F"
                }
            ]
        },
        "HARD WIRED EVENTS": {
            "content": "If auditing is enabled, then you can get any event that is not  caused  by  syscall  or  file\nwatch  rules  (because  you  don't  have  any  rules  loaded). So, that means, any event from\n1100-1299, 1326, 1328, 1331 and higher can be emitted. The reason that there are a number  of\nevents  that are hardwired is because they are required by regulatory compliance and are sent\nautomatically as a convenience. (For example, logon/logoff is a mandatory event in all  secu‐\nrity  guidance.)  If  you don't want this, you can use the exclude filter to drop events that\nyou do not want.\n",
            "subsections": [
                {
                    "name": "-a always,exclude -F msgtype=CRED_REFR",
                    "content": "",
                    "flag": "-F"
                }
            ]
        },
        "SEE ALSO": {
            "content": "auditctl(8), auditd(8).\n\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Steve Grubb\n\nRed Hat                                       Feb 2023                                AUDIT.RULES(7)",
            "subsections": []
        }
    },
    "summary": "audit.rules - a set of rules loaded in the kernel audit system",
    "flags": [
        {
            "flag": "-k",
            "long": null,
            "arg": null,
            "description": "where the permission are any one of the following: r - read of the file w - write to the file x - execute the file a - change in the file's attribute Watches can also be created using the syscall format described below which allow for greater flexibility and options. Using syscall rules you can choose between path and dir which is against a specific inode or directory tree respectively. It should also be noted that the re‐ cursive directory watch will stop if there is a mount point below the parent directory. There is an option to make the mounted subdirectory equivalent by using a -q rule."
        },
        {
            "flag": "-k",
            "long": null,
            "arg": null,
            "description": "The -a option tells the kernel's rule matching engine that we want to append a rule at the end of the rule list. But we need to specify which rule list it goes on and what action to take when it triggers. Valid actions are: always - always create an event never - never create an event The action and list are separated by a comma but no space in between. Valid lists are: task, exit, user, exclude, filesystem, and iouring. Their meaning was explained earlier. Next in the rule would normally be the -S option. This field can either be the syscall name or number. For readability, the name is almost always used. You may give more than one syscall in a rule by specifying another -S option. When sent into the kernel, all syscall fields are put into a mask so that one compare can determine if the syscall is of interest. So, adding multiple syscalls in one rule is very efficient. When you specify a syscall name, auditctl will look up the name and get its syscall number. This leads to some problems on bi- arch machines. The 32 and 64 bit syscall numbers sometimes, but not always, line up. So, to solve this problem, you would generally need to break the rule into 2 with one specifying -F arch=b32 and the other specifying -F arch=b64. This needs to go in front of the -S option so that auditctl looks at the right lookup table when returning the number. After the syscall is specified, you would normally have one or more -F options that fine tune what to match against. Rather than list all the valid field types here, the reader should look at the auditctl man page which has a full listing of each field and what it means. But it's worth mentioning a couple things. The audit system considers uids to be unsigned numbers. The audit system uses the number -1 to indicate that a loginuid is not set. This means that when it's printed out, it looks like 4294967295. But when you write rules, you can use either \"unset\" which is easy to remember, or -1, or 4294967295. They are all equivalent. If you write a rule that you wanted try to get the valid users of the system, you need to look in /etc/login.defs to see where user accounts start. For example, if UIDMIN is 1000, then you would also need to take into account that the unsigned representation of -1 is higher than 500. So you would address this with the fol‐ lowing piece of a rule: -F auid>=1000 -F auid!=unset These individual checks are \"anded\" and both have to be true. The last thing to know about syscall rules is that you can add a key field which is a free form text string that you want inserted into the event to help identify its meaning. This is discussed in more detail in the NOTES section."
        }
    ],
    "examples": [
        "The following rule shows how to audit failed access to files due to permission problems. Note",
        "that it takes two rules for each arch ABI to audit this since file access can fail  with  two",
        "different failure codes indicating permission problems."
    ],
    "see_also": [
        {
            "name": "auditctl",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/auditctl/8/json"
        },
        {
            "name": "auditd",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/auditd/8/json"
        }
    ]
}