Umount rules
unmounting for application developers for administrators for security researchers
An umount rule allows unmounting the mount points its path matches. umount and unmount are the same keyword. Only the mount point is compared and a directory is named with a slash at the end. A refusal is logged as operation umount.
On the map: rule classes
▶ Watch this deck — 8 scenes, ~5 min
Worth seeing first
- Mount rules — the mount rule that created what this rule removes
01 demo takes its scratch area down
umount MOUNTPOINT, allows unmounting. A mount rule for the same path does not.
Demo is shutting down and wants to remove the scratch area it mounted. Its profile has a mount rule for that directory, and that isn't enough: unmounting is its own permission. The call fails with EACCES until the profile has an umount rule, which is line sixteen of demo's profile. The rule is short: the keyword and the mount point. As with mounting, the sys_admin capability is needed too.
Details and sources
Details
- The LSM hook is
sb_umount(lsm.c:760-772, registered at lsm.c:1793), called for umount(2) and umount2(2). - The check applies to confined profiles that mediate the mount class (mount.c:544-576). The feature file
/sys/kernel/security/apparmor/features/mount/maskreadsmount umount pivot_root. - Unmounting is a permission of its own in the mount class; a mount rule does not give it.
- Without
capability sys_admin,the call fails withEPERMbefore AppArmor's check of the rule is reached (namespace.c:2082). umount /run/demo/,is line 16 of demo's profile; it compiles with no warning (run with the tree's parser). The programdemoand its profile are invented for the map.- Kernel statements are read from the kernel source and were not run.
Read more
for AppArmor developers for security researchers
In the code
- The permission is
AA_MAY_UMOUNT(0x4), separate fromAA_MAY_MOUNT(0x2) (mount.h:21-22).
02 A keyword and a mount point
[QUALIFIERS] umount [MOUNTPOINT],. unmount is the same keyword. No arrow.
This is one of the smallest rules in the language. The keyword, which you can spell umount or unmount, and one path: the mount point. Leave the path out and the rule covers every mount point. The usual qualifiers go in front, so you can deny or audit unmounting a particular place. There's no arrow and no source, because an unmount has only one path.
Details and sources
Details
- Both spellings,
umountandunmount, are one keyword. - The path takes globbing, quoting and variables:
umount "/",(ok_quoted_1.sd),umount @{HOME}/**/,(fusermount3:28). The plain form isumount /foo,(ok_23.sd). - Seats:
audit,allow,deny,promptandpriority=are taken;ownerandotherare refused withowner prefix not allowed on mount rules(run with the tree's parser).audit deny umount /boot/,andunmount /run/demo/,are accepted (run with the tree's parser). - The arrow gives
syntax error, unexpected TOK_ARROW, expecting TOK_END_OF_RULE(run with the tree's parser). - The rule shares its conditional slot with mount rules, so
fstype=andoptions=are accepted; see the scene "Only the path is compared".
Read more
for AppArmor developers for security researchers
In the code
TOK_UMOUNT opt_conds opt_id TOK_END_OF_RULEcallsdo_mnt_rule($2, NULL, NULL, $3, AA_MAY_UMOUNT)(parser_yacc.y:1292-1295). The keyword table: parser_misc.c:111-112. The scanner stateMOUNT_MODE: parser_lex.l:876-879.
03 The mount point is a directory, so it ends in a slash
Write the mount point with a trailing /. umount /mnt/{,**/}, covers /mnt/ and every directory below it.
One detail decides whether an umount rule works: the slash at the end. Demo passes the path without it, but the kernel compares its own name for the mount point, and for a directory that name ends in a slash. So the rule has to end in a slash too. If demo also mounts things below the scratch area, a pattern with an empty alternative and **/ covers the directory itself and every directory under it. When in doubt, copy the name from the log.
Details and sources
Details
- The kernel builds the path of the mount's root and marks it as a directory when it is one, which gives the trailing
/(mount.c:214-221, mount.c:544-576). A mount on a regular file (a bind mount of a file) is named without the slash. - "No match" for the rule without the slash is derived from that naming and from the fixture record, whose name is
name="/mnt/a/"(testcase_umount_01.in); it was not run. umount,compiles to "any name" (run with the tree's parser).- The mount point in the rule is a pattern in the globbing syntax, so
/run/demo/**does not match/run/demo/itself.umount /mnt/{,**/},is used in the tree (fusermount3:29). - Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), Mount Rules.
- Globbing, mount rules for the same naming of mount points.
04 Only the path is compared
An umount rule matches the mount point only. Lazy and forced unmounts, the filesystem type and the mount flags are not compared.
For an unmount the kernel compares exactly one thing: the mount point. It doesn't matter whether the program asked for a normal, a lazy or a forced unmount. The rule can't tell them apart. It also can't say only if it's a tmpfs, or only if it's read-only. You may see fstype or options written in an umount rule, and the parser accepts them, but they don't change what the rule allows. If you need to protect a mount point, a deny with the path is the tool.
Details and sources
Details
aa_umountreceives the umount flags (MNT_FORCE,MNT_DETACH,MNT_EXPIRE,UMOUNT_NOFOLLOW) and does not use them (mount.c:578-599).profile_umountmatches the name of the mount point and checksAA_MAY_UMOUNT(mount.c:544-576).- Known discrepancy, on the bug list as "
umountacceptsoptions=andfstype=and ignores them":umount options=ro fstype=ext4 /a,compiles to the same rule asumount /a,(run with the tree's parser). The grammar summary of apparmor.d(5) lists mount conditions for umount (apparmor.d.pod:252). - An unknown conditional name is still an error:
umount foo=bar /a,givesinvalid mount conditional foo, thenbad mount rule. - Kernel statements are read from the kernel source and were not run.
for security researchers
Attack surface
- A rule that reads as restricted (
umount fstype=tmpfs /run/**/,) allows unmounting anything mounted on a matching path. - Reasoned from name-based matching, not a finding: unmounting uncovers the directory underneath, which file rules then match by the same path.
- A lazy unmount cannot be denied separately from a normal one.
Read more
05 What demo and the log see
operation="umount" class="mount" name="/run/demo/". The name is the mount point as the rule must write it.
When no rule matches, the unmount fails with EACCES. The record is short: operation="umount", the profile, and name, which is the mount point exactly as the kernel compared it, slash included. That's the string to put in the rule. Why was it refused in a profile that says nothing about unmounting? Because mount, remount, umount and pivot_root are one class. Once the profile is compiled for a kernel that supports that class, every one of those operations needs a rule.
Details and sources
Details
- The record on the slide is assembled from the fixture testcase_umount_01.in (
apparmor="DENIED" operation="umount" class="mount" profile="/home/user/test/testmount" name="/mnt/a/" pid=26697 comm="testmount") with demo's values, which are illustrative. - The record has no
info,fstype,srcnameorflagsfield because none of those is compared. The error isEACCES(lib.c:440). - A profile compiled for a feature set without
mountdoes not mediate the class, and AppArmor does not check unmounts for it. The parser then drops the rule; its warningmount rules not enforceis in the classrule-not-enforced, which is off by default. - A plain
deny umountrefuses without a log record;audit denylogs. In complain mode the record isALLOWED. - Kernel statements are read from the kernel source and were not run.
Read more
for AppArmor developers for security researchers
In the code
- The warning for a feature set without
mount: mount.cc:782. The check:profile_umount, mount.c:544-576.
06 One field and the bit 0x4 for AppArmor developers for security researchers
mount.cc:1155-1166 writes \x07 + mount point with AA_MAY_UMOUNT (0x4); profile_umount (mount.c:544-576) reads the permission after the name.
An umount rule goes through the same class as mount, mnt_rule, with the umount permission. None of the generators for the five kinds of mount run, because each of them tests for the mount permission. What's left writes one field: the class byte and the mount point. The kernel matches the name from the start state of the mount class and tests the umount bit right there, where a mount rule would continue with a NUL and the source. One curiosity: a mount rule and an umount rule with the same paths compare equal, so they merge into one object with both bits.
Details and sources
for AppArmor developers for security researchers
Details
- Dumps from the tree's parser (
-D rule-exprs):umount /run/demo/,gives\x07/run/demo/with 0x4;umount /a,gives\x07/a;umount,gives\x07[^\000]*;umount /run/demo/{,**/},gives\x07/run/demo/(|[^\x00]*/). - The umount branch of
gen_policy_re: mount.cc:1155-1166. The generators for the kinds of mount call all testperms & AA_MAY_MOUNT(mount.cc:1089-1123). profile_umount: mount.c:544-576.- The merge leaves the permission out of the comparison and ORs it (rule.h:540-554, mount.cc:688-714).
all,shows the merged value 0x7 on the mount, umount and pivot_root strings; its separate remount string has 0x2 (run with the tree's parser). - The class marker
\d7is added at priority 1001 (parser_regex.c:1403-1405). - Kernel statements are read from the kernel source and were not run.
for security researchers
Attack surface
- After a merge the strings of the mount rule carry the umount bit, and the reverse. The kernel reads the umount permission at the end of the mount point, the mount permission after the flags and the pivot_root permission after the second path, so each operation reads its bit at a different state. No cross-grant was found by reading. Not run on a kernel.
for AppArmor developers for security researchers
Read more
07 Mistakes and their messages
End the mount point with /. No arrow, no owner.
The mistake you'll actually make isn't reported: leaving off the slash. The parser accepts it, and the rule matches nothing you meant. The real errors are simple: an arrow, which umount doesn't have; owner, which the whole mount class refuses; and an unknown conditional. And remember that ** after the slash covers what's below the directory, and not the directory itself.
Details and sources
Details
- The parser prints an error as
AppArmor parser error for FILE in profile FILE at line N: MESSAGE; the slide shows MESSAGE. Rows 2, 3 and 4 were run with the tree's parser; row 4 is followed bybad mount rule. - Rows 1 and 5 are accepted by the parser. That they do not match the directory is derived from the kernel's naming of mount points and from the globbing rules; it was not run on a kernel.
- The messages say "mount" because the class is shared with mount rules.
umount options=(rw, ro) /a,givesconflicting flag values = 1, 1, thenconflicting flags in the rule, andumount options=bogus /a,givesunsupported mount option value 'bogus': the conditionals are checked although an umount rule does not use them.- No warning exists for a mount point without a trailing slash.
Read more
08 The other mount rules
Umount rules name mount points. Mount, remount and pivot_root rules are the same class.
That's umount: one path, with its slash. The rule that mounted the scratch area is in the mount deck, and remount and pivot_root are its siblings. The globbing deck explains the pattern for a directory and everything under it. And the denials deck shows where to find the name the kernel compared.
Details and sources
Details
[QUALIFIERS] umount [MOUNTPOINT],;unmountis the same keyword. Without a path the rule covers every mount point.- Only the mount point is compared; a directory is named with a trailing
/. - Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2) and the kernel tree named on the page. The kernel behaviour was read from the source, not observed on a running kernel.
Read more
Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the line (-Q -K --skip-kernel-load --warn=all, -D rule-exprs for compiled forms), with nothing loaded into a kernel; "code" means the parser source or the kernel source was read, not run. Nothing here was observed on a running kernel.
Grammar
UMOUNT RULE: [QUALIFIERS] ( umount | unmount ) [MOUNTPOINT] , QUALIFIERS: [priority=N] [audit] [allow|deny|prompt]
umountandunmountare one keyword (code).- The mount point is a pattern in the globbing syntax and takes quoting and variables (tree).
- There is no arrow and no source (tree).
| Seat | On an umount rule |
|---|---|
priority= | taken |
audit | taken |
allow, deny, prompt | taken: deny is not logged; prompt is in syn-prompt |
owner, other | refused: owner prefix not allowed on mount rules (tree) |
Rule and what it covers
| Rule | Covers |
|---|---|
umount, | every mount point (tree) |
umount /a/, | a mount on the directory /a |
umount /a/{,**/}, | /a/ and every directory below it |
umount /a/**, | what is below /a/, not /a/ itself |
umount /a, | a mount on a regular file /a; not a directory |
The last four rows follow from the kernel's naming of mount points (linux:security/apparmor/mount.c:214-221) and the globbing rules (code); they were not run on a kernel.
What is compared
| Compared | Not compared |
|---|---|
the name of the mount point; a directory ends in / | the umount2 flags (MNT_FORCE, MNT_DETACH, MNT_EXPIRE, UMOUNT_NOFOLLOW) |
| the filesystem type | |
| the mount flags | |
| what is mounted (the source) |
Read from linux:security/apparmor/mount.c:544-599 (code).
The log record
| Field | Meaning |
|---|---|
operation="umount" | the unmount |
class="mount" | always |
profile= | the profile that refused |
name= | the mount point as compared, with its trailing / |
A record from the tree (libraries/libapparmor/testsuite/test_multi/testcase_umount_01.in):
apparmor="DENIED" operation="umount" class="mount" profile="/home/user/test/testmount" name="/mnt/a/" pid=26697 comm="testmount"
A refused unmount returns EACCES.
Errors and warnings
| Rule | Message |
|---|---|
umount /run/demo/ -> /mnt/, | syntax error, unexpected TOK_ARROW, expecting TOK_END_OF_RULE |
owner umount /run/demo/, | owner prefix not allowed on mount rules |
umount foo=bar /run/demo/, | invalid mount conditional foo then bad mount rule |
umount options=(rw, ro) /a, | conflicting flag values = 1, 1 then conflicting flags in the rule |
umount options=bogus /a, | unsupported mount option value 'bogus' |
umount /run/demo, | none; the rule does not match a directory |
any umount rule, no mount in the feature set, --warn=rule-not-enforced | warning mount rules not enforce |
Rows with an error message are from the tree's parser.
for AppArmor developers for security researchers
In the parser and the kernel
- Grammar action:
TOK_UMOUNT opt_conds opt_id TOK_END_OF_RULEcallsdo_mnt_rule($2, NULL, NULL, $3, AA_MAY_UMOUNT)(parser/parser_yacc.y:1292-1295). The class ismnt_rule, shared withmount,remountandpivot_root. - Encoding: the class byte 7 and the mount point, with
AA_MAY_UMOUNT0x4 (parser/mount.cc:1155-1166).umount /run/demo/,is\x07/run/demo/(tree). - Rules of the mount class that differ only in keyword are merged and their permissions ORed (
parser/rule.h:540-554,parser/mount.cc:688-714). - Kernel:
sb_umount(linux:security/apparmor/lsm.c:760-772) callsaa_umount, which callsprofile_umountfor each profile of the label (linux:security/apparmor/mount.c:544-599): build the name, match it fromstart[AA_CLASS_MOUNT], testAA_MAY_UMOUNT.
for AppArmor developers for security researchers
Known discrepancies
None of these is taught as intended behaviour. All are on the bug list as confirmed; see Known bugs.
umount options=ro fstype=ext4 /a,compiles to the same rule asumount /a,: the conditionals are accepted and not used, while apparmor.d(5) lists them in the grammar of umount (tree).- A mount rule and an umount rule with the same paths are merged into one object with both permission bits; no cross-grant was found by reading the kernel (code). Not run on a kernel.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
FILE ACCESS
- Globbing (AARE) — patterns that cover a mount point and what is below it
QUALIFIERS
- allow and deny — deny and audit on umount rules
RULE CLASSES
- Mount rules — the rule that put the mount there
- Remount rules — changing a mount instead of removing it
- pivot_root rules — the fourth rule of the mount class
- Capability rules — sys_admin which unmounting also needs
RUNNING THE PARSER
- Reading a denial — reading the umount record