Reading a denial
what a DENIED line says for application developers for administrators
Every AppArmor decision that is logged is one record. It goes to the audit log when the audit daemon runs and to the kernel log otherwise. The first field says DENIED or ALLOWED or AUDIT or KILLED or STATUS. The others name the profile and the operation and the object and the refused permission and together they are the rule that would allow it. A plain deny rule and the rate limit of the kernel log both leave no line.
On the map: running the parser
▶ Watch this deck — 9 scenes, ~7 min
Worth seeing first
- Why AppArmor — what a profile is and a first look at a denial
- File rules — the path and the letters that a file record maps back to
Part of journeys
- New to AppArmor, step 10 of 10 · previous: How the kernel checks an access
- Hardening a privileged program, step 9 of 11 · previous: Profile mode flags · next: The limits of name-based mediation
01 Permission denied: was it AppArmor?
A refused access is one record: the profile that refused, the operation, the object and the permission. This deck reads it field by field, for administrators and application developers.
Demo tries to open a file, and gets permission denied. The file's mode looks fine, so who said no? If it was AppArmor, the kernel wrote one line about it, and that line answers three questions: which profile refused, what the program was doing, and to what. This deck teaches you to read that line. We'll find where it lands, look at its first word, go through its fields, and see when a refusal leaves no line at all. By the end you can take a record and write the one rule that would allow it. Or decide that the profile was right.
Details and sources
Details
- The command and the record are real. Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. The profile
demowas compiled by the parser of the AppArmor tree the map describes and entered withaa-exec -p demo; it allows reading/etc/demo/demo.confand has no rule for/etc/demo/secret.conf. - The full line in the kernel log:
audit: type=1400 audit(1794831779.488:174): apparmor="DENIED" operation="open" class="file" profile="demo" name="/etc/demo/secret.conf" pid=1323 comm="cat" requested_mask="r" denied_mask="r" fsuid=0 ouid=0. On the slide the prefixaudit: type=1400 audit(SECONDS:SERIAL):is left out and the record is broken over lines. comm="cat"and not "demo": the record names the command that ran under the profile. The profile is inprofile=.- A program gets
EACCES("Permission denied") from AppArmor exactly as from file modes; the record is the only thing that tells the two apart. - The first look at a denial in the map is the scene "What a denial looks like" of Why AppArmor; its line is composed for the example, the ones in this deck were logged.
for AppArmor developers for security researchers
In the code
- The fixed part of every record is written by
audit_pre()(audit.c:93-141);pid=andcomm=by the LSM audit helper (lsm_audit.c:423); the file fields byfile_audit_cb()(file.c:45-77).
02 Where the line ends up
With the audit daemon running, records are in /var/log/audit/audit.log as type=AVC. Without it they are in the kernel log (dmesg, journalctl -k) as audit: type=1400. The text after the prefix is the same.
Where's the line? AppArmor hands every record to the kernel's audit system, and from there it goes one of two ways. If the audit daemon is running, the record lands in the audit log, as a line of type AVC. If no audit daemon is running, the kernel prints the record into its own log, and you see it with dmesg, or in the journal's kernel messages. The prefix differs; the text after it is the same. So know which case you're in. We installed the audit daemon on a test machine, and from that moment the kernel log got no AppArmor lines at all. They hadn't stopped. They'd moved.
Details and sources
Details
- Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. Without auditd the records were in
dmesgand injournalctl -k:Nov 16 12:23:31 aamap kernel: audit: type=1400 audit(1794831811.744:217): apparmor="DENIED" .... - After
apt-get install auditdon the same guest:auditctl -sprintedenabled 1,rate_limit 0,backlog_limit 8192,lost 0; new records were in/var/log/audit/audit.log(type=AVC msg=audit(1794831843.332:433): apparmor="ALLOWED" operation="open" class="file" profile="demo-complain" ...) and the number ofapparmor=lines indmesgstayed 0. - The number in parentheses is the time in seconds since 1970 with milliseconds, a colon and a serial number. Two records with the same number belong to one event.
- In audit.log, file records end
fsuid=0 ouid=0FSUID="root" OUID="root": auditd appends the names it looked up after a separator character that a terminal does not show. /var/log/syslogand/var/log/kern.loghold the kernel log too on systems that run a syslog daemon. On the Debian sid image neither exists; on the Ubuntu guests both exist and had the records.- The utilities read the first file that exists of
/var/log/audit/audit.log,/var/log/syslog,/var/log/messages(logprof.conf:15). - Records of D-Bus mediation are written by the bus daemon, not by the kernel. They have type 1107 (
USER_AVC) and carry the AppArmor text insidemsg='...': see D-Bus mediation and the reference below. - In a container the kernel log is the host's: the records of a confined container process are on the host.
- The kernel log is rate limited; the audit log was not in the test. See the scene "Complain mode, and the lines that never appear".
for AppArmor developers for security researchers
In the code
aa_audit_msg()callscommon_lsm_audit()(audit.c:160-165), which starts a record of typeAUDIT_AVC(lsm_audit.c:437-460; the number 1400: audit.h:127).- With no audit daemon registered, kauditd prints the record with
pr_notice("type=%d %s\n")underprintk_ratelimit()(audit.c:582-590).
03 The first word: five kinds of record
apparmor= is DENIED (refused), ALLOWED (complain mode: would be refused), AUDIT (allowed by an audit rule), KILLED (refused and signalled) or STATUS (policy changed).
The first field tells you what kind of line you have. Denied: the profile refused, and the call failed. Allowed is the one that misleads people. It doesn't mean a rule allowed it. It means the profile is in complain mode: the access would have been refused, and went through. Audit is the opposite case: a rule did allow it, and the rule was marked audit, so you get a record. Killed: refused, and the process got a signal as well. And status isn't about a program's access at all: a profile was loaded, replaced or removed. Here it's the parser loading demo.
Details and sources
Details
- All five lines were logged in one run. Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. On the slide the middle of each record is replaced by
.... DENIED:apparmor="DENIED" operation="open" class="file" profile="demo" name="/etc/demo/secret.conf" pid=1323 comm="cat" requested_mask="r" denied_mask="r" fsuid=0 ouid=0;catprintedPermission denied.ALLOWED: the profiledemo-complainhasflags=(complain)and no rule for the file:apparmor="ALLOWED" operation="open" class="file" profile="demo-complain" name="/etc/demo/secret.conf" pid=1468 comm="cat" requested_mask="r" denied_mask="r" fsuid=0 ouid=0;catprinted the file. The record still hasdenied_mask: it says what would have been denied.AUDIT: the rule isaudit /etc/demo/audited.conf r,:apparmor="AUDIT" operation="open" class="file" profile="demo" name="/etc/demo/audited.conf" pid=1474 comm="cat" requested_mask="r" fsuid=0 ouid=0. There is nodenied_mask. A secondAUDITrecord withoperation="getattr"followed.KILLED: the profiledemo-killhasflags=(kill):apparmor="KILLED" operation="open" class="file" profile="demo-kill" name="/etc/demo/secret.conf" pid=1494 comm="cat" requested_mask="r" denied_mask="r" fsuid=0 ouid=0; the shell reportedKilledand exit status 137.STATUS:apparmor="STATUS" operation="profile_load" profile="unconfined" name="demo" pid=1292 comm="apparmor_parser". Hereprofile=is the label of the process that changed policy andname=is the profile that was changed. Loading the same profile again loggedoperation="profile_replace" info="same as current profile, skipping"; removing itoperation="profile_remove".- A load that the kernel refuses is a
STATUSrecord withinfo=anderror=: 300 random bytes written to.loadloggedapparmor="STATUS" info="invalid profile format" error=-93 profile="unconfined" pid=1317 comm="cat". - The kernel's table has three more words,
HINT,ERRORandAUTO. None was produced in the run;AUTOis replaced before a record is written. - Known discrepancy: Kernel: an
audit denyfile rule in a complain-mode profile is allowed and logged ALLOWED.
for AppArmor developers for security researchers
In the code
- The eight words: audit.c:29-38. The choice between them:
aa_audit()(audit.c:200-237) andaa_select_audit_type()(audit.c:143-152). After aKILLEDrecord the profile's signal is sent (audit.c:228-231). - The field is written only while the module parameter
audit_headerisY, its default (audit.c:97-100). - libapparmor's names for the types: aalogparse.h:44-53.
04 Who was stopped, doing what, to what
profile is the profile to edit; comm is only the command name. operation and class say what was checked and by which kind of rule; name is the object. info and error give a reason when the kernel has one.
Now the fields that every record has. Start with profile. That's the profile that made the decision, and so the one to edit. Don't take it from comm: comm is only the command name, cut to fifteen characters, and for a script it's the interpreter. The pid is the process. Operation is what the kernel was checking, here an open, and class is the kind of rule that was consulted: file. Then name: the object. For a file, that's the path, exactly as AppArmor saw it. Some records carry two more fields, info and error. That's the kernel giving its reason, when it has one beyond no rule matching.
Details and sources
Details
- Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. On the slide the prefix
audit: type=1400 audit(SECONDS:SERIAL):is left out and the record is broken over lines. - The kernel writes the common fields in this order:
apparmor,operation,class,infoanderror(only when there is a reason),namespace(only when the profile is not in the root policy namespace),profile(orlabelwhen the subject is a stack of profiles),name, thenpidandcomm, then the fields of the class. operationvalues seen in the run:open,mknod(creating a file),exec,link,chown,getattr,connect,create(a socket),capable,signal,ptrace,mount,umount,userns_create,change_onexec,profile_load,profile_replace,profile_remove. The complete list is in the reference below.classvalues seen:file,cap,net,signal,ptrace,mount,namespace.change_onexecis logged withclass="file".commis the task's command name, at most 15 characters. In the run a refused exec hadcomm="sh"(the caller) andname="/opt/demo/helper"(the program that was to run); Python scripts hadcomm="python3".nameis quoted. When it contains a space, a quote or a control character the kernel writes it as hexadecimal digits without quotes; libapparmor and the utilities decode it.nameis not always a full path. The mount command's look at a mount that is not attached yet loggedoperation="getattr" class="file" ... name="", and opening the POSIX message queue/demologgedoperation="open" class="file" ... name="demo", both withinfo="Failed name lookup - disconnected path" error=-13: the object had no path from the task's root, sonameis not a path a file rule can be written from. See The other profile flags forattach_disconnected.- The message queue record is a file record because this kernel has no message queue mediation: the queue is opened as a file on a mount that is attached nowhere. A profile with
mqueue (create, open, read, write, delete) type=posix /demo-ok,got the same refusal for/demo-ok:apparmor="DENIED" operation="open" class="file" info="Failed name lookup - disconnected path" error=-13 profile="demo-mq" name="demo-ok" pid=1455 comm="python3" requested_mask="wrc" denied_mask="wrc" fsuid=0 ouid=0. The same was logged on Debian 13. What kernels with message queue mediation log instead is in Upstream and Ubuntu kernels. - Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path.
infovalues seen:failed af match(no rule for the address family),failed mntpnt match,Failed name lookup - disconnected path,same as current profile, skipping,invalid profile format.erroris a negative errno:-13EACCES,-93EPROTONOSUPPORT.- For a
STATUSrecordprofile=is the label of the process that changed policy andname=the profile that changed. - Known discrepancy: Kernel: the audit class name table has
io_uringat index 18.
for AppArmor developers for security researchers
In the code
audit_pre(): audit.c:93-141. The operation strings: audit.h:47-110. The class names: audit.c:40-74.pid=andcomm=: lsm_audit.c:423.- The keys libapparmor's log scanner knows: scanner.l:147-214.
Read more
- Stacking for
label=, Policy namespaces fornamespace=. - How a denial is logged.
05 Which permission, and whose file
denied_mask is the refused part in rule letters; c and d are written w in a rule. fsuid is who asked and ouid who owns the file: when they differ, an owner rule does not apply.
For a file, two masks say which permission. The requested_mask is what was asked for, the denied_mask the part that was refused, in the letters you write in a rule. Two letters differ: c for create and d for delete. A rule has neither; you write w. So touch on a new file logs c, and the rule says w. Then fsuid and ouid: the user who asked, and the user who owns the file. Here they're one thousand and zero, and the rule says owner. That's the reason for this denial. A link record has one field more: target, the existing file.
Details and sources
Details
- Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. On the slide the prefix
audit: type=1400 audit(SECONDS:SERIAL):is left out and the record is broken over lines. - The first record: the profile has
owner /srv/demo/** r,;/srv/demo/root-owned.txtbelongs to root with mode 644; it was read by the usertester(uid 1000) withrunuser -u tester -- aa-exec -p demo -- cat /srv/demo/root-owned.txt. File modes would allow the read; the profile does not, because the rule applies only when the task's fsuid is the file's owner. - The letters:
rread,wwrite,aappend,xexecute,mmap executable,klock,llink, and in records alsoccreate andddelete. A check of file attributes (getattr) is logged asr;chmod,chownandsetattrare logged asw. - For a denial the kernel reduces
requested_maskto the permissions that were not allowed before it writes the record, so the two masks are normally the same. AnAUDITrecord hasrequested_maskonly. - The second record in full:
apparmor="DENIED" operation="mknod" class="file" profile="demo" name="/var/lib/demo/new" pid=1342 comm="touch" requested_mask="c" denied_mask="c" fsuid=0 ouid=0. - The link record in full:
apparmor="DENIED" operation="link" class="file" profile="demo" name="/var/lib/demo/link" pid=1355 comm="ln" requested_mask="l" denied_mask="l" fsuid=0 ouid=0 target="/etc/demo/demo.conf".nameis the new link,targetthe existing file; the rule islink /var/lib/demo/link -> /etc/demo/demo.conf,orlon the new name: see Link rules. chownon a file is refused as a file operation before any capability is asked:apparmor="DENIED" operation="chown" class="file" profile="demo" name="/etc/demo/demo.conf" pid=1361 comm="chown" requested_mask="w" denied_mask="w" fsuid=0 ouid=0. The rule it maps to is awfile rule.- A unix socket in the filesystem is a file record with both letters:
operation="connect" class="file" profile="demo" name="/run/demo.sock" ... requested_mask="wr" denied_mask="wr". fsuidandouidare numbers as seen from the initial user namespace. In audit.log the audit daemon appendsFSUID="root" OUID="root"with the names.targetis also the profile of a transition:apparmor="DENIED" operation="change_onexec" class="file" profile="demo" name="demo-complain" pid=1439 comm="aa-exec" target="demo-complain".
for AppArmor developers for security researchers
In the code
file_audit_cb(): file.c:45-77. The letter tableaa_file_perm_chrs: lib.c:253.getattrshown asr,setattr/chmod/chownasw: file.c:28-38. Only the denied permissions are reported: file.c:132-133.
Read more
06 Not a file: capabilities, sockets, signals, mounts
Other classes carry their own fields: capname; family and sock_type; signal and peer; fstype, srcname and name. Each value is a word of the rule.
When class isn't file, there's no path to look for. Each class brings fields of its own, and they still spell the rule. A capability record has capname, and that's the word for the rule. A network record has family and sock_type: inet and stream give you network inet stream. A signal record names the signal, and peer: the profile of the process on the other end. Unconfined, here. A mount record has the filesystem type and the source, and name is the mount point. The decks on each kind of rule show their record in full. The pattern is always the same: the record's values are the rule's words.
Details and sources
Details
- Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. On the slide the middle of each record is replaced by
.... The four rules were compiled by the tree's parser without a message. - Capability, in full:
apparmor="DENIED" operation="capable" class="cap" profile="demo" pid=1367 comm="chroot" capability=18 capname="sys_chroot"(fromchroot / true, which failed withOperation not permitted). The two spaces beforecapnameare in the record. - Network:
apparmor="DENIED" operation="create" class="net" info="failed af match" error=-13 profile="demo" pid=1379 comm="python3" family="inet" sock_type="stream" protocol=0 requested="create" denied="create". Network records userequestedanddeniedwith words (create,connect,send,receive,bind,listen,accept,getattr,setattr,getopt,setopt,shutdown), not the_maskfields. - Unix sockets add
addr,peer_addrandpeer:apparmor="DENIED" operation="connect" class="net" profile="demo" pid=1387 comm="python3" family="unix" sock_type="stream" protocol=0 requested="send receive connect" denied="send connect" addr=none peer_addr="@demo" peer="unconfined". The rule:unix (connect, send) type=stream peer=(addr=@demo label=unconfined),. See Unix socket rules. - Signal:
apparmor="DENIED" operation="signal" class="signal" profile="demo" pid=1394 comm="sh" requested_mask="send" denied_mask="send" signal=hup peer="unconfined". The receiving side is checked against its own profile and logs its own record withreceive. - ptrace: reading
/proc/1/environloggedapparmor="DENIED" operation="ptrace" class="ptrace" profile="demo" pid=1401 comm="cat" requested_mask="read" denied_mask="read" peer="unconfined"; the rule isptrace (read) peer=unconfined,. - Mount:
apparmor="DENIED" operation="mount" class="mount" info="failed mntpnt match" error=-13 profile="demo" name="/mnt/demo/" pid=1407 comm="mount" fstype="tmpfs" srcname="none". This record is fromLIBMOUNT_FORCE_MOUNT2=always mount -t tmpfs none /mnt/demo, which makes the mount command use the mount(2) system call. With the command's default system calls the record wasoperation="mount" class="mount" info="failed mntpnt match" error=-13 profile="demo" name="/mnt/demo/" pid=1413 comm="mount" flags="rw, move", withoutfstypeandsrcname. - Known discrepancy: Kernel: mount_setattr(2), fsconfig reconfigure and fsopen/fsmount are not checked as remounts or new mounts.
- Unmount:
apparmor="DENIED" operation="umount" class="mount" profile="demo" name="/mnt/demo/" pid=1420 comm="umount"; the rule isumount /mnt/demo/,. - User namespace:
apparmor="DENIED" operation="userns_create" class="namespace" profile="demo" pid=1427 comm="unshare" requested="userns_create" denied="userns_create" execpath="/usr/bin/unshare"; the rule isuserns,. - Records that were not produced in the run (
setrlimit, io_uring,pivotroot) are in the decks of their rules.
for AppArmor developers for security researchers
In the code
- The callbacks: capability capability.c:47-53 (
capability=itself: lsm_audit.c:194), network net.c:118-166, signal ipc.c:52-76, ptrace task.c:233-250, mount mount.c:92-118, user namespace task.c:353-372.
07 Complain mode, and the lines that never appear
Complain mode logs ALLOWED and lets the access through. No line is written for a plain deny, for a capability refused again within a second, or for records beyond the kernel log's rate limit: 11 lines for 201 denials in the test.
The demo-complain profile is in complain mode. The same read goes through, and the line says allowed, with the same fields. That's how you learn what a program needs without breaking it. Now the lines that never appear. A plain deny rule refuses quietly: no record. A capability refused twice within a second is logged once. When no audit daemon runs, the kernel log has a rate limit. We ran two hundred and one denials, and eleven lines came out, with a note that the rest was suppressed. With the audit daemon running, every one was there. So if you're building a profile from the log, run the audit daemon.
Details and sources
Details
- Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes.
- Complain mode: the profile
demo-complainhasflags=(complain);cat /etc/demo/secret.confunder it printed the file and loggedapparmor="ALLOWED" operation="open" class="file" profile="demo-complain" name="/etc/demo/secret.conf" pid=1468 comm="cat" requested_mask="r" denied_mask="r" fsuid=0 ouid=0. A plaindenyrule still refuses in complain mode: see Profile mode flags. - Known discrepancy: Kernel: an
audit denyfile rule in a complain-mode profile is allowed and logged ALLOWED. - Plain deny: with
deny /etc/demo/quiet.conf r,in the profile,catprintedPermission deniedand the kernel log got no line.audit denykeeps the record: see The audit qualifier. - The module's audit mode can bring quieted records back: after
echo -n noquiet > /sys/module/apparmor/parameters/auditthe same read loggedapparmor="DENIED" operation="open" class="file" profile="demo" name="/etc/demo/quiet.conf" pid=1487 comm="cat" requested_mask="r" denied_mask="r" fsuid=0 ouid=0. The values arenormal(the default),quiet_denied,quiet.allowed,quiet,noquietandall;quiet_deniedandquietremove denials, andquiet.allowedremoves theALLOWEDrecords of complain mode (onlynoquietwas tried; the rest is from the source). A value other thannormaloverrides every profile's own audit flag. - Capabilities: a Python process called
chroot("/")20 times; all 20 failed and one record was logged (capname="sys_chroot"). The duplicate filter is per capability and lasts one second. File operations have no such filter (from the source; the recorded run refused onechownand logged one record). - The rate limit:
kernel.printk_ratelimit = 5andkernel.printk_ratelimit_burst = 10are the guest's defaults. A shell loop ran 200 refused reads, and one more 7 seconds later.dmesgthen had 11DENIEDlines and the linekauditd_printk_skb: 339 callbacks suppressed. Why the counter says 339 for 190 missing lines was not determined. - With auditd installed and running (
auditctl -s:rate_limit 0,backlog_limit 8192), the same loop of 200 added 200 lines to/var/log/audit/audit.log, andloststayed 0. sysctl -w kernel.printk_ratelimit=0switches the kernel log's limit off; the run did that for every other test.- The audit daemon has limits of its own (
auditctl -rfor a rate limit, the backlog limit); they were at their defaults here.
for AppArmor developers for security researchers
In the code
- Quieted permissions are removed from the record: file.c:142-149, lib.c:425. The module's audit mode overrides the profile's: policy.h:459-465; its names: audit.c:20-27.
- The capability filter: capability.c:67-110. The kernel log's limit: audit.c:582-590.
08 From the record to one new rule
profile names the profile to edit; name and denied_mask are the rule. Reload with apparmor_parser -r, run again, and expect the next denial.
So, from the record to a rule. First ask whether demo should have this file at all; a denial can be the profile doing its job. Say it should. The profile field says which profile to edit. The name and the denied_mask are the rule: the path, and r. Keep the path as narrow as the program needs. Then reload the profile with the parser's -r option; a status record confirms the replacement. Run demo again. It works, and there's no new record. Expect more rounds: a program usually stops at its first denial. The aa-logprof tool does this loop for you, and aa-notify shows denials as they arrive.
Details and sources
Details
- Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. The profile with the added line is the one of the run with
/etc/demo/secret.conf r,after the rule fordemo.conf.apparmor_parser -rexited with status 0;aa-exec -p demo -- cat /etc/demo/secret.confprintedsecret; the kernel log got no new line. - In the guest the profile was a file in a scratch directory and was loaded by its path. The slide writes
/etc/apparmor.d/demo, where a profile normally lives; theSTATUSline on the slide is shortened with.... The run did not keep the kernel log of this reload. The reloads it did keep replaced a profile with an identical one and loggedapparmor="STATUS" operation="profile_replace" info="same as current profile, skipping" profile="unconfined" name="demo" pid=1299 comm="apparmor_parser"; for a profile that changed, the kernel writes the same record withoutinfo(from the source, not run). - The steps, with the field that feeds each:
profileis the profile to edit (aa-statuslists what is loaded; the file is usually under/etc/apparmor.d/).classandoperationsay which kind of rule.nameanddenied_mask, or the class's own fields, are the rule's words.fsuidandouidsay whetherownerfits. - Write
canddasw. Generalise the path with care:/etc/demo/*.conf r,covers the directory's configuration files;/etc/demo/** rw,would give away much more than the record asked for. -rreplaces a loaded profile. Running processes keep the profile and get the new rules at once.- Where the profile includes a site file (
include if exists <local/NAME>), put a local addition there instead of editing the shipped file: see include if exists and the Denials quick guide. - A record with
info="Failed name lookup - disconnected path"is the exception to "name and denied_mask are the rule": itsnameis empty or has no leading slash, so it is not a path that a file rule can name. The scene "Who was stopped, doing what, to what" has two such records. Whetherattach_disconnectedand a file rule make such an access work was not tried. - Not every record should become a rule. A program that probes for things it does not need works without them; a
denyrule for such a path also silences its record. - aa-logprof and aa-notify read the same records. Neither was installed on the guest's image; they are separate packages.
09 From the log to the tools and the rules
First word, then who, what and to what, then the permission. Roads: the tools that read the log, the qualifiers and flags that decide whether a line is written, and the kernel side.
That's a denial, from left to right. The first word says the kind of record. Profile, operation and name say who was stopped, doing what, to what. The masks, or the class's own fields, give the rule's words. Silence proves nothing: a plain deny, a repeated capability or the rate limit leave no line. From here: the tools that go through the log, aa-logprof and aa-notify. The decks on audit, deny and the mode flags explain why a line is or isn't there. The deck on kernel features covers rules that load and aren't enforced. And the kernel's side of the record is in how a denial is logged.
Details and sources
Read more
- aa-logprof, aa-notify, aa-status and aa-enabled.
- The audit qualifier, allow and deny, Profile mode flags.
- File access modes, The owner qualifier.
- How a denial is logged, Kernel features and the policy ABI, Upstream and Ubuntu kernels, D-Bus mediation.
- apparmor.net: Troubleshooting, apparmor.net: Denials quick guide, apparmor.net: Audit the system, apparmor(7) ERRORS.
Read more
Basis of the statements on this page: "logged" means the line was written by a running kernel, a Debian sid guest with kernel 7.3.4 (a distribution kernel without Ubuntu's AppArmor patches), under profiles compiled by the parser of the AppArmor commit 836052d21. "source" means the kernel source the map describes was read and the record was not produced. Records are quoted without the prefix audit: type=1400 audit(SECONDS:SERIAL):. What other kernels add to these records is in Upstream and Ubuntu kernels.
Where records are
| Situation | Where | Line starts | Commands |
|---|---|---|---|
| the audit daemon (auditd) is running | /var/log/audit/audit.log | type=AVC msg=audit(1794831843.332:433): | grep apparmor= /var/log/audit/audit.log |
| no audit daemon | the kernel log | audit: type=1400 audit(1794831779.488:174): | dmesg, journalctl -k |
| a syslog daemon is installed | also /var/log/syslog, /var/log/kern.log | the kernel log's line with a time stamp | grep apparmor= /var/log/kern.log |
| D-Bus mediation | the same two places | type=1107 in the kernel log (USER_AVC), the AppArmor text inside msg='...' |
Logged: both forms, on one guest before and after installing auditd; after it, dmesg received no AppArmor line. The utilities read the first existing file of /var/log/audit/audit.log, /var/log/syslog, /var/log/messages (logprof.conf:15).
Record types
apparmor= | Meaning | Call result | Basis |
|---|---|---|---|
DENIED | the profile refused the access | fails, usually EACCES | logged |
ALLOWED | complain mode: the access would be refused | succeeds | logged |
AUDIT | a rule with audit (or the audit mode all) allowed the access | succeeds | logged |
KILLED | kill mode or a kill rule: refused | fails, and the profile's signal is sent (the test process was killed, exit status 137) | logged |
STATUS | a profile was loaded, replaced or removed, or a load failed | logged | |
HINT, ERROR | in the kernel's table | source | |
AUTO | internal; replaced before a record is written | source |
Common fields
In the order the kernel writes them.
| Field | Value | Says | Becomes |
|---|---|---|---|
apparmor | one of the words above | the kind of record | |
operation | a word | what was checked | with class, the kind of rule |
class | file, cap, net, rlimits, domain, mount, ptrace, signal, namespace, io_uring, dbus, ... | the rule class consulted | the rule's keyword |
info | text | a reason | |
error | negative errno, only with info | ||
namespace | name, only outside the root policy namespace | where the profile lives | |
profile | name | the profile that decided; in STATUS the label of the process changing policy | the profile to edit |
label | label, instead of profile for a stack | ||
name | quoted, or hexadecimal without quotes when it has a space, a quote or a control character | the object: a path, a mount point, a target profile; in STATUS the profile changed | the path of the rule |
pid | number | the process | |
comm | at most 15 characters | the command name |
Operations in the source: open, exec, mknod, mkdir, rmdir, unlink, truncate, link, symlink, rename_src, rename_dest, chmod, chown, getattr, file_receive, file_perm, file_lock, file_mmap, file_mprotect, file_inherit; mount, umount, pivotroot; create, post_create, bind, connect, listen, accept, sendmsg, recvmsg, getsockname, getpeername, getsockopt, setsockopt, socket_shutdown; ptrace, signal; capable, sysctl; change_hat, change_profile, change_onexec, stack, stack_onexec; setprocattr, setrlimit; userns_create; uring_override, uring_sqpoll; profile_load, profile_replace, profile_remove.
Fields by class
| Class | Fields | Rule | Logged example |
|---|---|---|---|
| file | requested_mask, denied_mask, fsuid, ouid, target | NAME LETTERS, (c, d as w); owner when the uids match; link NAME -> TARGET, | operation="open" class="file" profile="demo" name="/srv/demo/root-owned.txt" pid=1336 comm="cat" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0 |
| cap | capability, capname | capability CAPNAME, | operation="capable" class="cap" profile="demo" pid=1367 comm="chroot" capability=18 capname="sys_chroot" |
| net | family, sock_type, protocol, requested, denied | network FAMILY SOCK_TYPE, | operation="create" class="net" info="failed af match" error=-13 profile="demo" pid=1379 comm="python3" family="inet" sock_type="stream" protocol=0 requested="create" denied="create" |
| net, unix sockets | also addr, peer_addr, peer | unix (DENIED) type=SOCK_TYPE peer=(addr=PEER_ADDR label=PEER), | operation="connect" class="net" profile="demo" pid=1387 comm="python3" family="unix" sock_type="stream" protocol=0 requested="send receive connect" denied="send connect" addr=none peer_addr="@demo" peer="unconfined" |
| signal | requested_mask, denied_mask, signal, peer | signal (DENIED) set=(SIGNAL) peer=PEER, | operation="signal" class="signal" profile="demo" pid=1394 comm="sh" requested_mask="send" denied_mask="send" signal=hup peer="unconfined" |
| ptrace | requested_mask, denied_mask, peer | ptrace (DENIED) peer=PEER, | operation="ptrace" class="ptrace" profile="demo" pid=1401 comm="cat" requested_mask="read" denied_mask="read" peer="unconfined" |
| mount | fstype, srcname, trans, flags, options | mount fstype=FSTYPE options=(FLAGS) SRCNAME -> NAME,; umount NAME, | operation="mount" class="mount" info="failed mntpnt match" error=-13 profile="demo" name="/mnt/demo/" pid=1407 comm="mount" fstype="tmpfs" srcname="none" |
| namespace | requested, denied, execpath | userns, | operation="userns_create" class="namespace" profile="demo" pid=1427 comm="unshare" requested="userns_create" denied="userns_create" execpath="/usr/bin/unshare" |
| rlimits | rlimit, value, peer | set rlimit RLIMIT <= VALUE, | source |
| io_uring | requested, denied, tcontext | io_uring (...) label=TCONTEXT, | source |
| transitions | target | change_profile -> TARGET,, an exec rule | operation="change_onexec" class="file" profile="demo" name="demo-complain" pid=1439 comm="aa-exec" target="demo-complain" |
| policy load errors | ns, name, offset | apparmor="STATUS" info="invalid profile format" error=-93 profile="unconfined" pid=1317 comm="cat" | |
| D-Bus (bus daemon) | bus, path, interface, member, mask, name, label, peer_label | dbus (MASK) bus=BUS path=PATH interface=INTERFACE member=MEMBER peer=(label=PEER_LABEL), | type=1107 ... msg='apparmor="DENIED" operation="dbus_method_call" bus="system" path="/" interface="org.freedesktop.DBus" member="ListNames" mask="send" name="org.freedesktop.DBus" pid=1505 label="demo-dbus" peer_label="unconfined" |
The mount row is the record of the mount(2) system call. The mount command's default system calls logged flags="rw, move" without fstype and srcname. Known discrepancies: Kernel: mount_setattr(2), fsconfig reconfigure and fsopen/fsmount are not checked as remounts or new mounts; Kernel: mount audit records have no word for lazytime, and MS_REC shows only with bind or a propagation flag; Kernel: signal=unknown(%d) is logged without a leading space; Kernel: changeprofile &name is audited as operation="change_profile".
Mask letters
| Letter | Permission | In a rule |
|---|---|---|
r | read; also getattr | r |
w | write; also chmod, chown, setattr | w |
a | append | a |
c | create | w |
d | delete | w |
x | execute | an exec mode such as ix or Px |
m | map executable | m |
k | lock | k |
l | link | l |
info values
Logged: failed af match, failed mntpnt match, Failed name lookup - disconnected path, same as current profile, skipping, invalid profile format. From the source, among others: failed type match, failed protocol match, profile transition not found, label not found, no new privs, ix fallback, ux fallback, target restricted, link not subset of target, hat not found, conflicting profile attachments.
A record with info="Failed name lookup - disconnected path" has a name that is empty or relative, and a file rule cannot be written from it. Logged: name="" for the mount command's look at a detached mount, and name="demo", requested_mask="wrc" for opening the POSIX message queue /demo, also under a profile that has an mqueue rule for the queue. Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path.
What is not logged
| Cause | Effect | Basis |
|---|---|---|
a plain deny rule | refused, no record; audit deny logs | logged |
/sys/module/apparmor/parameters/audit | normal (default), quiet_denied and quiet remove denials, quiet.allowed removes the ALLOWED records of complain mode, noquiet logs quieted denials, all logs every access; a value other than normal overrides the profiles' own flag | noquiet logged; the rest source |
| the capability filter | the same capability for the same credentials: one record per second | logged: 20 calls, 1 record |
| the kernel log's rate limit (no audit daemon) | kernel.printk_ratelimit 5 seconds, burst 10 | logged: 201 denials, 11 lines |
| the audit daemon's own limits | auditctl -s shows rate_limit, backlog_limit, lost | logged with defaults: 200 of 200 |
From a record to a rule
1. Decide whether the access is wanted. 2. profile: the profile to edit. 3. class and operation: the kind of rule. 4. name and denied_mask, or the fields of the class: the words of the rule. 5. fsuid and ouid: whether owner fits. 6. apparmor_parser -r FILE; a STATUS record with operation="profile_replace" follows. 7. Run the program again and read the next record.
for AppArmor developers for security researchers
In the code
- Common fields:
audit_pre(), audit.c:93-141. Type selection: audit.c:143-152, audit.c:200-237. Complain mode clearsEPERMandEACCES: audit.h:206-211. - Callbacks: file file.c:45-77, capability capability.c:47-53, network net.c:118-166, signal ipc.c:52-76, ptrace task.c:233-250, user namespace task.c:353-372, mount mount.c:92-118, rlimit resource.c:30-41, io_uring lsm.c:607-623, policy load policy_unpack.c:36-51.
- The record type number and
pid,comm: lsm_audit.c:423, lsm_audit.c:437-460. Printing to the kernel log: audit.c:582-590. - libapparmor's log scanner knows 68 keys (scanner.l:147-214), more than the kernel source the map describes writes:
laddr,faddr,lport,fport,saddr,daddr,src,dest,peer_profile,peer_pid,name2,parent,magic_tokenand others come from older kernels, other kernels and user-space daemons. Its test suite has 679 files of real lines (test_multi).
Roads from here
START HERE
- Upstream and Ubuntu kernels — records that only other kernels write
- Why AppArmor — the first denial of the map
FILE ACCESS
- File access modes — the letters of the masks
PROFILE HEAD
- Profile mode flags — complain and kill mode and what they log
QUALIFIERS
- The audit qualifier — the qualifier that makes AUDIT records
- allow and deny — why a plain deny leaves no record
- The owner qualifier — what fsuid and ouid decide
RUNNING THE PARSER
- Kernel features and the policy ABI — rules that load and are not enforced
TOOLS · utils/
- aa-logprof — the tool that reads these records and proposes rules
- aa-notify (no slides yet) — the tool that shows denials as they happen
LIBAPPARMOR
- D-Bus mediation — the records the bus daemon writes
IN THE KERNEL
- How a denial is logged (no slides yet) — how the kernel builds the record