pivot_root rules

changing the root for application developers for administrators for security researchers

A pivot_root rule allows the pivot_root system call for a new root and optionally for the place where the old root is put. The rule lists them in the reverse order of the system call. Both are directories and end in a slash. The rule may name a profile after an arrow. The parser stores that name and the kernel keeps the current profile.

On the map: rule classes

▶ Watch this deck — 8 scenes, ~5 min

Worth seeing first

01 demo moves the worker's root

PIVOT_ROOT RULES / /run/demo/ tmpfs, read-only /run/demo/old/ empty directory demo kernel pivot_root("/run/demo", "/run/demo/old") = -1 EACCESwithout a rule pivot_root oldroot=/run/demo/old/ /run/demo/, line 17 of demo's profile / was /run/demo/ /old/ the former root the call also needs:capability sys_admin,
A tree: the root, below it /run/demo/ with a read-only tmpfs, below that the empty directory /run/demo/old/. demo calls pivot_root with /run/demo and /run/demo/old and gets EACCES. With the rule pivot_root oldroot=/run/demo/old/ /run/demo/ the call is allowed: /run/demo/ becomes the root and the former root hangs below it as /old/. The call also needs capability sys_admin.

pivot_root oldroot=OLD NEW, allows pivot_root(2) with NEW as the new root and OLD as the place for the old one.

Demo's scratch area is ready, and the worker should see it as its whole filesystem. The system call for that is pivot_root: it makes one mount the new root and parks the old root in a directory inside it. Container tools do this all the time. Under a profile the call fails with EACCES until there's a pivot_root rule, which is line seventeen of demo's profile. The rule names the two directories, and as with mounting, the sys_admin capability is needed too.

Details and sources

Details

  • The system call is pivot_root(new_root, put_old). The LSM hook is sb_pivotroot (lsm.c:774-786, registered at lsm.c:1794), which calls aa_pivotroot (mount.c:663-709).
  • pivot_root is a permission of its own in the mount class. Unconfined profiles and profiles that do not mediate the mount class are not checked (mount.c:605-661). The feature file /sys/kernel/security/apparmor/features/mount/mask reads mount umount pivot_root.
  • pivot_root oldroot=/run/demo/old/ /run/demo/, is line 17 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.
  • There is no example file for this rule under parser/tst/simple_tests/; the examples are those of apparmor.d(5) (apparmor.d.pod:2051-2067).
  • pivot_root(2) needs CAP_SYS_ADMIN, which a confined task has only with capability sys_admin,. Without capability sys_admin, the call fails with EPERM before AppArmor's check of the rule is reached (namespace.c:4850-4853).
  • 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_PIVOTROOT (0x1) (mount.h:20).

02 oldroot=, the new root, an arrow

GRAMMAR QUALIFIERSpivot_rootoldroot=OLDROOTNEWROOT-> PROFILE, pivot_root oldroot=/run/demo/old/ /run/demo/, line 17 of demo's profile pivot_root, any new root, any old root pivot_root /run/demo/, this new root, old root anywhere oldroot= comes before the path; owner is refused pivot_root oldroot=/run/demo/old/ /run/demo/ -> demo//worker, with an arrow target: see "The arrow"
The syntax diagram of a pivot_root rule: optional qualifiers, the word pivot_root, an optional oldroot conditional, an optional new root, an optional arrow and profile name, a comma. Examples: demo's line; pivot_root alone for any new root and any old root; pivot_root /run/demo/ for that new root with the old root anywhere; and a rule with an arrow target. oldroot= comes before the path and owner is refused.

[QUALIFIERS] pivot_root [oldroot=OLDROOT] [NEWROOT] [-> PROFILE],.

The keyword is written with an underscore, like the system call. Then one conditional, oldroot= a path. Then the new root. All of it is optional: the bare keyword allows any pivot. The conditional has to come before the path, as conditionals always do. And at the very end there may be an arrow and a profile name, which has a slide to itself, because it doesn't do what you'd expect.

Details and sources

Details

  • Both paths are patterns and take variables. The arrow target may be a variable.
  • Seats: audit, allow, deny, prompt and priority= are taken; owner and other are refused: owner pivot_root, gives owner prefix not allowed on mount rules (run with the tree's parser).
  • oldroot is the only conditional name: pivot_root putold=/run/demo/old/ /run/demo/, gives invalid pivotroot conditional 'putold' (run with the tree's parser).
  • The three forms on the slide and the bare keyword are accepted (run with the tree's parser). The examples of apparmor.d(5): apparmor.d.pod:2051-2067.

for AppArmor developers for security researchers

In the code

03 The rule lists the paths the other way round

TWO DIRECTORIES new_root put_old pivot_root( "/run/demo" , "/run/demo/old" ) the system call pivot_root oldroot= /run/demo/old/ /run/demo/ , the rule new root "/run/demo/" then old root "/run/demo/old/" the kernel's names: directories, so each ends in a slash a part you leave out matches anything
The system call pivot_root takes the new root /run/demo first and the place for the old root /run/demo/old second. The rule writes oldroot=/run/demo/old/ first and the new root /run/demo/ last: the two cross over. The kernel compares the new root and then the old root as directory names, each ending in a slash. A part left out matches anything.

System call: new root, old root. Rule: oldroot=OLD first, new root last. Both end in /.

Mind the order. The system call wants the new root first and the place for the old root second. The rule is the other way round: oldroot= comes first, because it's a conditional, and the new root is the path at the end. The kernel compares its own names for the two directories, and directory names end in a slash, so write both with a trailing slash. If you leave oldroot out, any place for the old root is accepted, and the same goes for the new root.

Details and sources

Details

  • apparmor.d(5) describes the order of the rule against the order of the system call (apparmor.d.pod:2034-2039) and asks for the trailing slash on both paths (apparmor.d.pod:2046-2047).
  • The kernel resolves both paths to names with the directory mark, which gives the trailing / (mount.c:214-221, mount.c:626-637), and matches the new root, then the old root (mount.c:639-643).
  • The parser does not check the slash or that the paths are absolute: pivot_root new, is accepted and matches no directory. pivot_root, compiles to "any new root, any old root" (run with the tree's parser).
  • Kernel statements are read from the kernel source and were not run.

Read more

04 The arrow names a profile, and the profile stays the same

THE ARROW pivot_root oldroot=/run/demo/old/ /run/demo/ -> demo//worker, demo demo pivot_root(...) kernel accepted, with no warning; not compiled allowed demo demo demo//worker no transition $ cat /sys/kernel/security/apparmor/features/namespaces/pivot_rootno the kernel does not support the transition a new profile after the pivot:change_profile
A pivot_root rule ending in an arrow and the profile name demo//worker. demo, confined by profile demo, calls pivot_root and the kernel allows it. After the call demo is still confined by profile demo; there is no transition to demo//worker. The parser accepts the arrow target with no warning. The kernel's feature file features/namespaces/pivot_root reads no. A new profile after the pivot needs change_profile.

pivot_root ... -> PROFILE, is accepted and has no effect: no warning from the parser, no transition in the kernel (features/namespaces/pivot_root reads no).

The grammar lets you end the rule with an arrow and a profile name, and it looks like the arrows you know from exec rules: do the pivot, then continue under that profile. That's the idea, and the manual says no kernel supports it. The parser accepts the name without a warning and doesn't put it into the compiled policy. The kernel allows the pivot and keeps the profile the task already has. You can ask the kernel: its feature file for this reads no. If you need a new profile after the pivot, that's what change_profile is for.

Details and sources

Details

  • With or without the arrow target the compiled rule is the same: pivot_root oldroot=/run/demo/old/ /run/demo/ -> demo//worker, and the same line without the arrow give identical output (run with the tree's parser). No warning is printed.
  • Two rules that differ only in their target stay separate rules in the parser, because the target takes part in comparing rules.
  • The kernel returns the profile's own label from the per-profile step, next to the comment todo: allow pivotroot to specify a transition other than profile (mount.c:645-655), and installs the combined, unchanged label (mount.c:682-687). The audit field trans= is set to the profile's own name (mount.c:646).
  • The command and its output on the slide are derived from the kernel's table: the entry pivot_root in the namespaces directory is a boolean with the value 0 (apparmorfs.c:2657), and booleans are printed as yes or no (apparmorfs.c:1266-1268). The file was not read on a running kernel.
  • apparmor.d(5) says the feature "is not supported by any kernel" (apparmor.d.pod:2041-2044).
  • Kernel statements are read from the kernel source and were not run.

for security researchers

Attack surface

  • A profile that reads pivot_root ... -> confined-init, suggests the task is more confined after the pivot. It is not, and nothing in the parser's output says so; the trans= field of the kernel's record carries the profile's own name.
  • Reasoned from name-based matching, not a finding: after the pivot the same profile's path rules are matched against names in the new tree.

for AppArmor developers for security researchers

In the code

05 What demo and the log see

THE DENIAL demo pivot_root("/run/demo", "/run/demo/old") = -1 EACCES apparmor="DENIED" operation="pivotroot" class="mount" profile="demo"name="/run/demo/" pid=21162 comm="demo" srcname="/run/demo/old/" trans="demo" operation is "pivotroot", without the underscore new root old root pivot_root oldroot=/run/demo/old/ /run/demo/, the rule, written from the record needed as soon as the profile is compiled for a kernel that has the mount class
demo calls pivot_root and gets EACCES. The record has operation pivotroot, without the underscore, class mount, profile demo, name /run/demo/ which is the new root, srcname /run/demo/old/ which is the old root, and trans demo, the profile's own name. In the rule, srcname is the value of oldroot= and name is the path at the end. The rule is needed as soon as the profile is compiled for a kernel that has the mount class.

operation="pivotroot" name="NEWROOT/" srcname="OLDROOT/". srcname is the value for oldroot=.

No matching rule, and the call fails with EACCES. The record's operation is pivotroot, one word, no underscore. Name is the new root and srcname is the old root, both with their slashes. So the rule writes itself from the record: srcname goes after oldroot=, name goes at the end. Like the other mount rules, this one is needed as soon as the profile is compiled for a kernel that supports the mount class.

Details and sources

Details

  • The record on the slide is assembled from the fixture testcase_pivotroot_01.in (apparmor="DENIED" operation="pivotroot" profile=... name="/tmp/.../new_root/" pid=21162 comm="pivot_root" srcname="/tmp/.../new_root/put_old/") with demo's values, which are illustrative. class="mount" is placed after operation as the newer fixtures of this class have it (testcase_umount_01.in); the pivot_root fixture itself is older than the class field.
  • name= is the new root and srcname= the old root (mount.c:626-637). The error is EACCES.
  • trans="demo" is the profile's own name; the kernel sets it before the check (mount.c:646) and it does not mean a transition. The fixture has no trans= field.
  • The rule is in the mount class. For a feature set without mount the parser drops it (warning mount rules not enforce, off by default) and AppArmor does not check pivot_root. When the class is mediated and no rule matches, pivot_root is refused.
  • Kernel statements are read from the kernel source and were not run.

06 Two fields and the bit 0x1 for AppArmor developers for security researchers

IN THE PARSER pivot_root oldroot=/run/demo/old/ /run/demo/ -> demo//worker, do_pivot_rule() mnt_rule(NULL, "/run/demo/old/", NULL, "/run/demo/", AA_MAY_PIVOTROOT) trans = "demo//worker" \x07 /run/demo/ \x00 /run/demo/old/ class 7 new root old root perms 0x1 AA_MAY_PIVOTROOT trans not encoded build_pivotroot() match new_name, NUL, match old_name, perms & AA_MAY_PIVOTROOT, return the profile's own label do_pivot_rule reads the head of the conditional list only: the conditional written last
do_pivot_rule builds a mnt_rule with the old root in the source position, the new root as mount point and the permission AA_MAY_PIVOTROOT, and stores the arrow target in trans. The match string is the class byte 07, the new root /run/demo/, a NUL and the old root /run/demo/old/, with permission 0x1; trans is not encoded. In the kernel build_pivotroot matches the new name, a NUL and the old name, tests AA_MAY_PIVOTROOT and returns the profile's own label.

parser_yacc.y:1820-1838 -> mnt_rule with AA_MAY_PIVOTROOT; mount.cc:1167-1181 writes new root NUL old root; mount.c:605-661 matches and keeps the label.

The pivot_root rule reuses the mount class once more. The function do_pivot_rule takes the oldroot value and builds a mnt_rule with it in the source position and the new root as the mount point, with the pivot_root permission. The generator writes two fields: new root, NUL, old root. The arrow target sits in a member called trans, gets its variables expanded, and is then never written. The kernel matches the two names, tests the bit, and returns the label the profile already has. A comment there says the transition is still to do.

Details and sources

for AppArmor developers for security researchers

Details

  • do_pivot_rule: parser_yacc.y:1820-1838. The pivot_root branch of gen_policy_re: mount.cc:1167-1181. post_parse_profile has only the TODO for the transition (mount.cc:1194-1199).
  • Dumps from the tree's parser: demo's line, with or without -> demo//worker, gives \x07/run/demo/\x00/run/demo/old/ with 0x1; pivot_root, gives \x07[^\000]*\x00[^\000]*.
  • In all, the pivot_root object merges with mount and umount into the permissions 0x7 (run with the tree's parser).
  • Kernel: build_pivotroot (mount.c:605-661); aa_pivotroot combines the per-profile labels and calls aa_replace_current_label (mount.c:663-709).
  • Kernel statements are read from the kernel source and were not run.

for security researchers

Attack surface

  • Known discrepancy, on the bug list as "pivot_root checks only its last conditional and ignores the others": only the conditional nearest to the path is examined (parser_yacc.y:1820-1831). pivot_root bogus=/b oldroot=/a/ /new/, is accepted and the bogus conditional is dropped; the same content in the other order is an error.
  • Known discrepancy, part of the same entry: the operator of that conditional is not checked (pivot_root oldroot in (/a/) /new/, is accepted) and only its first value is used (oldroot=(/a/ /b/) means /a/). A rule that reads as two old roots allows one.
  • The arrow target is ignored without a message; see the scene "The arrow names a profile, and the profile stays the same".

for AppArmor developers for security researchers

Read more

07 Mistakes and their messages

MISTAKES pivot_root /run/demo/ oldroot=/run/demo/old/, syntax error, unexpected TOK_CONDID, expecting TOK_END_OF_RULE oldroot= goes first pivot_root putold=/run/demo/old/ /run/demo/, invalid pivotroot conditional 'putold' owner pivot_root, owner prefix not allowed on mount rules pivot_root oldroot=/run/demo/old /run/demo, accepted; matches no directory end both paths with / pivot_root /run/demo/ -> demo//worker, accepted; the profile does not change
Five pivot_root rules. oldroot= after the path is a syntax error. A conditional named putold is refused. owner is refused. Paths without their trailing slashes are accepted and match no directory. An arrow target is accepted and the profile does not change.

oldroot= first, both paths with a trailing /, and do not rely on -> PROFILE.

Put oldroot after the path and you get a syntax error. Misname the conditional and the parser tells you so. Owner isn't allowed. Then the two quiet ones: paths without their trailing slashes are accepted and never match, and an arrow target is accepted and never used. For those the parser gives you nothing, so check them by eye.

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 1 to 3 were run with the tree's parser; rows 4 and 5 are accepted by it.
  • The message of row 2 says pivotroot, without an underscore.
  • "Matches no directory" in row 4 is derived from the kernel's naming of directories and was not run.
  • When the feature set lacks mount, the rule is dropped; --warn=rule-not-enforced prints mount rules not enforce.
  • More cases that are accepted without a message (a second conditional, the in operator, a value list) are listed in the scene for security researchers.

08 After the pivot

ROADS pivot_root oldroot=... /run/demo/, the worker's root is in place syn-mount the mount that is the root syn-umount unmount the old root syn-change-profile a new profile, for real syn-named-transitions arrows that do work syn-rule-conditionals how oldroot= is written adm-denials the pivotroot record
pivot_root rules in the centre with roads to syn-mount and syn-umount, to syn-change-profile and syn-named-transitions, and to syn-rule-conditionals and adm-denials.

pivot_root rules name two directories. A profile change needs change_profile.

The worker's root is in place. The old root is usually unmounted next, which is the umount deck. And if the worker should run under its own profile from here on, the rule for that is change_profile, the next step in demo's story. The conditionals deck covers how oldroot is written, and the denials deck the record.

Details and sources

Details

  • [QUALIFIERS] pivot_root [oldroot=OLDROOT] [NEWROOT] [-> PROFILE],: a part left out matches anything; the arrow target has no effect.
  • A refused pivot returns EACCES and is logged as operation="pivotroot" with name= (new root) and srcname= (old root).
  • 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

PIVOT ROOT RULE:  [QUALIFIERS] pivot_root [oldroot=OLDROOT] [NEWROOT] [-> PROFILE] ,
QUALIFIERS:       [priority=N] [audit] [allow|deny|prompt]
  • oldroot is the only conditional and comes before the path (tree).
  • Both paths are patterns and take variables; the arrow target may be a variable (code).
SeatOn a pivot_root 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)

System call and rule

pivot_root(2) argumentIn the ruleIn the log
new_root, firstthe path at the endname=
put_old, secondthe value of oldroot=, before the pathsrcname=

Both are directories; the kernel's names end in / (code).

Forms

RuleAllows
pivot_root,any new root, any old root
pivot_root /run/demo/,this new root, the old root anywhere
pivot_root oldroot=/run/demo/old/,any new root with this place for the old root
pivot_root oldroot=/run/demo/old/ /run/demo/,this new root with this place for the old root
pivot_root oldroot=/run/demo/old/ /run/demo/ -> demo//worker,the same as the line above

All five are accepted; the last two compile to the same rule (tree).

The arrow target

  • -> PROFILE is accepted, with no warning, stored, and not written into the compiled policy (tree, code).
  • The kernel keeps the task's current profile after the pivot (linux:security/apparmor/mount.c:645-655, code).
  • The feature file /sys/kernel/security/apparmor/features/namespaces/pivot_root reads no (derived from linux:security/apparmor/apparmorfs.c:2657; not read on a running kernel).
  • apparmor.d(5): the feature "is not supported by any kernel".
  • A profile change is requested with change_profile.

The log record

FieldMeaning
operation="pivotroot"one word, no underscore
class="mount"on current kernels; the fixture below is older
profile=the profile that refused
name=the new root, with its trailing /
srcname=the old root, with its trailing /
trans=the profile's own name; no transition happens

A record from the tree (libraries/libapparmor/testsuite/test_multi/testcase_pivotroot_01.in):

apparmor="DENIED" operation="pivotroot" profile="/home/ubuntu/bzr/apparmor/tests/regression/apparmor/pivot_root" name="/tmp/sdtest.21082-7446-EeefO6/new_root/" pid=21162 comm="pivot_root" srcname="/tmp/sdtest.21082-7446-EeefO6/new_root/put_old/"

A refused pivot returns EACCES.

Errors and warnings

RuleMessage
pivot_root /run/demo/ oldroot=/run/demo/old/,syntax error, unexpected TOK_CONDID, expecting TOK_END_OF_RULE
pivot_root putold=/run/demo/old/ /run/demo/,invalid pivotroot conditional 'putold'
owner pivot_root,owner prefix not allowed on mount rules
pivot_root oldroot=/run/demo/old /run/demo,none; the rule matches no directory
pivot_root /run/demo/ -> demo//worker,none; the profile does not change
any pivot_root rule, no mount in the feature set, --warn=rule-not-enforcedwarning mount rules not enforce

Rows with a rule are from the tree's parser.

for AppArmor developers for security researchers

In the parser and the kernel

  • do_pivot_rule builds mnt_rule(NULL, oldroot, NULL, newroot, AA_MAY_PIVOTROOT) and stores the target in trans (parser/parser_yacc.y:1820-1838).
  • trans is expanded and compared (parser/mount.cc:654, 699) and never encoded: post_parse_profile has only a TODO (parser/mount.cc:1194-1199).
  • Encoding: the class byte 7, new root, NUL, old root, with AA_MAY_PIVOTROOT 0x1 (parser/mount.cc:1167-1181). Demo's line is \x07/run/demo/\x00/run/demo/old/ (tree).
  • Kernel: sb_pivotroot (linux:security/apparmor/lsm.c:774-786) calls aa_pivotroot (linux:security/apparmor/mount.c:663-709); build_pivotroot matches the two names, tests the bit and returns the profile's own label (linux:security/apparmor/mount.c:605-661).

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.

  • Only the conditional nearest to the path is examined: pivot_root bogus=/b oldroot=/a/ /new/, is accepted and bogus is dropped (tree).
  • The operator is not checked and only the first value is used: pivot_root oldroot in (/a/) /new/, is accepted, and oldroot=(/a/ /b/) means /a/ (tree).
  • The arrow target is accepted and ignored without a message (tree, code).

Roads from here

START HERE

FILE ACCESS

RULE CLASSES

RUNNING THE PARSER