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 RULES mount fstype=tmpfs options=(rw, nosuid) tmpfs -> /run/demo/, demo's profile so far demo /run/demo/ tmpfs mounted umount("/run/demo") kernel = -1 EACCES the mount rule does not cover it umount /run/demo/, line 16 of demo's profile with the rule: unmounted the mount point; nothing else is compared the call also needs:capability sys_admin,
demo's profile has a mount rule for /run/demo/, where a tmpfs is mounted. demo calls umount on it and the kernel refuses with EACCES: the mount rule does not cover unmounting. With the rule umount /run/demo/ the call goes through. The rule names the mount point and nothing else is compared. The call also needs capability sys_admin.

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/mask reads mount 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 with EPERM before 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 program demo and its profile are invented for the map.
  • Kernel statements are read from the kernel source and were not run.

for AppArmor developers for security researchers

In the code

  • The permission is AA_MAY_UMOUNT (0x4), separate from AA_MAY_MOUNT (0x2) (mount.h:21-22).

02 A keyword and a mount point

GRAMMAR QUALIFIERSumount MOUNTPOINT,unmount umount /run/demo/, line 16 of demo's profile unmount /run/demo/, the same rule umount, any mount point audit deny umount /boot/, qualifiers as for other rules; owner is refused umount /run/demo/ -> /mnt/, syntax error, unexpected TOK_ARROW, expecting TOK_END_OF_RULE
The syntax diagram of an umount rule: optional qualifiers, the word umount or unmount, an optional mount point, a comma. Examples: umount /run/demo/; unmount /run/demo/, the same rule; umount alone for any mount point; audit deny umount /boot/; and umount with an arrow, which is a syntax error.

[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, umount and unmount, are one keyword.
  • The path takes globbing, quoting and variables: umount "/", (ok_quoted_1.sd), umount @{HOME}/**/, (fusermount3:28). The plain form is umount /foo, (ok_23.sd).
  • Seats: audit, allow, deny, prompt and priority= are taken; owner and other are refused with owner prefix not allowed on mount rules (run with the tree's parser). audit deny umount /boot/, and unmount /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= and options= are accepted; see the scene "Only the path is compared".

for AppArmor developers for security researchers

In the code

03 The mount point is a directory, so it ends in a slash

THE NAME demo umount("/run/demo") kernel /run/demo/ the name the kernel compares umount /run/demo, no match umount /run/demo/, match umount /run/demo/{,**/}, match, and every directory below it the log shows the name with its slash:name="/run/demo/"
demo calls umount on /run/demo. The name the kernel compares is /run/demo/ with a slash at the end. The rule umount /run/demo does not match; umount /run/demo/ matches; umount /run/demo/{,**/} matches the directory and every directory below it. The log shows the name with its 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

04 Only the path is compared

WHAT IS NOT COMPARED umount("/run/demo") umount2("/run/demo", MNT_DETACH) umount2("/run/demo", MNT_FORCE) kernel /run/demo/ the same question for all three umount /run/demo/, allows all three not compared: lazy or forced filesystem type mount flags fstype= and options= are accepted in an umount rule and change nothing deny umount /boot/, a deny with the path protects a mount point
Three calls, umount, umount2 with MNT_DETACH and umount2 with MNT_FORCE, reach the kernel, which asks the same question for all three: the name /run/demo/. The rule umount /run/demo/ allows all three. Whether the unmount is lazy or forced, the filesystem type and the mount flags are not compared. fstype= and options= are accepted in an umount rule and change nothing. A deny rule with the path protects a mount point.

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_umount receives the umount flags (MNT_FORCE, MNT_DETACH, MNT_EXPIRE, UMOUNT_NOFOLLOW) and does not use them (mount.c:578-599). profile_umount matches the name of the mount point and checks AA_MAY_UMOUNT (mount.c:544-576).
  • Known discrepancy, on the bug list as "umount accepts options= and fstype= and ignores them": umount options=ro fstype=ext4 /a, compiles to the same rule as umount /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, gives invalid mount conditional foo, then bad 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.

05 What demo and the log see

THE DENIAL demo umount("/run/demo") kernel = -1 EACCES apparmor="DENIED" operation="umount" class="mount"profile="demo" name="/run/demo/" pid=26697 comm="demo" umount /run/demo/, the rule that would allow it: the name, as logged profile demo mount ... -> /run/demo/, mount, remount, umount, pivot_root: one class where the kernel has it, each needs a rule a plain deny umount is not logged
demo calls umount on /run/demo and gets EACCES. The log record has operation umount, class mount, profile demo and name /run/demo/. The name, as logged, is what the rule umount /run/demo/ must contain. A profile with only a mount rule still refuses the unmount, because mount, remount, umount and pivot_root are one class and each needs a rule. A plain deny umount is not logged.

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, srcname or flags field because none of those is compared. The error is EACCES (lib.c:440).
  • A profile compiled for a feature set without mount does not mediate the class, and AppArmor does not check unmounts for it. The parser then drops the rule; its warning mount rules not enforce is in the class rule-not-enforced, which is off by default.
  • A plain deny umount refuses without a log record; audit deny logs. In complain mode the record is ALLOWED.
  • Kernel statements are read from the kernel source and were not run.

for AppArmor developers for security researchers

In the code

06 One field and the bit 0x4 for AppArmor developers for security researchers

IN THE PARSER umount /run/demo/, class mnt_rule, permission umount \x07 /run/demo/ class 7 mount point perms 0x4 AA_MAY_UMOUNT no NUL, no source, no type, no flags profile_umount() aa_dfa_match(start[AA_CLASS_MOUNT], name), then perms & AA_MAY_UMOUNT \x07/run/demo/ \x00 tmpfs \x00 (tmpfs) \x00 \x02 perms 0x2 the mount rule: the same class, a longer string mount -> /a/, + umount /a/, one object, perms 0x6 rules of this class that differ only in keyword are merged
The rule umount /run/demo/ as a match string: the class byte 07 and the mount point /run/demo/, with permission 0x4; no NUL, no source, no type, no flags. For comparison the longer string of the mount rule with permission 0x2. In the kernel profile_umount matches the name from the start state of the mount class and tests AA_MAY_UMOUNT. A mount rule and an umount rule with the same path merge into one object with permissions 0x6.

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 test perms & 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 \d7 is 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

MISTAKES umount /run/demo, accepted; does not match the directory write /run/demo/ 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 umount /run/demo/**, accepted; covers what is below, not /run/demo/ itself
Five umount rules. umount /run/demo without the slash is accepted and does not match the directory. umount with an arrow is a syntax error. owner umount is refused. An unknown conditional foo=bar is refused. umount /run/demo/** is accepted and covers what is below the directory, not the directory itself.

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 by bad 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, gives conflicting flag values = 1, 1, then conflicting flags in the rule, and umount options=bogus /a, gives unsupported 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.

08 The other mount rules

ROADS umount /run/demo/, one path, with its slash syn-mount put it there syn-remount change it syn-pivot-root pivot into it syn-globbing a tree of mount points syn-capability sys_admin adm-denials the umount record
Umount rules in the centre with roads to syn-mount, syn-remount and syn-pivot-root, to syn-globbing and syn-capability, and to adm-denials.

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],; unmount is 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]
  • umount and unmount are 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).
SeatOn an umount rule
priority=taken
audittaken
allow, deny, prompttaken: deny is not logged; prompt is in syn-prompt
owner, otherrefused: owner prefix not allowed on mount rules (tree)

Rule and what it covers

RuleCovers
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

ComparedNot 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

FieldMeaning
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

RuleMessage
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-enforcedwarning 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_RULE calls do_mnt_rule($2, NULL, NULL, $3, AA_MAY_UMOUNT) (parser/parser_yacc.y:1292-1295). The class is mnt_rule, shared with mount, remount and pivot_root.
  • Encoding: the class byte 7 and the mount point, with AA_MAY_UMOUNT 0x4 (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) calls aa_umount, which calls profile_umount for each profile of the label (linux:security/apparmor/mount.c:544-599): build the name, match it from start[AA_CLASS_MOUNT], test AA_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 as umount /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

FILE ACCESS

QUALIFIERS

RULE CLASSES

RUNNING THE PARSER