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
- Mount rules — the mount that prepared the new root
- Rule conditionals — how a conditional such as oldroot= is written
- Named exec transitions — the arrow and profile name a rule can end with
01 demo moves the worker's root
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 issb_pivotroot(lsm.c:774-786, registered at lsm.c:1794), which callsaa_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/maskreadsmount 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 programdemoand 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 withcapability sys_admin,. Withoutcapability sys_admin,the call fails withEPERMbefore 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
[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,promptandpriority=are taken;ownerandotherare refused:owner pivot_root,givesowner prefix not allowed on mount rules(run with the tree's parser). oldrootis the only conditional name:pivot_root putold=/run/demo/old/ /run/demo/,givesinvalid 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
TOK_PIVOTROOT opt_conds opt_id opt_target TOK_END_OF_RULE: parser_yacc.y:1297-1300; the target: parser_yacc.y:1037-1041;do_pivot_rule: parser_yacc.y:1820-1838.- The keyword has no scanner state of its own: the rule is scanned in
INITIAL, and->pushesSUB_ID_WS(parser_lex.l:419-453, parser_lex.l:822). - Variable expansion of the paths and the target: mount.cc:654.
03 The rule lists the paths the other way round
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
- apparmor.d(5), Pivot Root Rules.
- Globbing, umount rules for the same trailing slash.
04 The arrow names a profile, and the profile stays the same
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 fieldtrans=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_rootin thenamespacesdirectory is a boolean with the value 0 (apparmorfs.c:2657), and booleans are printed asyesorno(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; thetrans=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
- The pivot_root branch of the generator writes two fields (mount.cc:1167-1181).
post_parse_profilehas only/* TODO: pivot_root profile transition */(mount.cc:1194-1199). The targettransis expanded and compared (mount.cc:654, mount.cc:699).
05 What demo and the log see
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 afteroperationas the newer fixtures of this class have it (testcase_umount_01.in); the pivot_root fixture itself is older than theclassfield. name=is the new root andsrcname=the old root (mount.c:626-637). The error isEACCES.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 notrans=field.- The rule is in the mount class. For a feature set without
mountthe parser drops it (warningmount 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
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 ofgen_policy_re: mount.cc:1167-1181.post_parse_profilehas 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_pivotrootcombines the per-profile labels and callsaa_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_rootchecks 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 thebogusconditional 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
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-enforcedprintsmount rules not enforce. - More cases that are accepted without a message (a second conditional, the
inoperator, a value list) are listed in the scene for security researchers.
Read more
08 After the pivot
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
EACCESand is logged asoperation="pivotroot"withname=(new root) andsrcname=(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]
oldrootis the only conditional and comes before the path (tree).- Both paths are patterns and take variables; the arrow target may be a variable (code).
| Seat | On a pivot_root 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) |
System call and rule
| pivot_root(2) argument | In the rule | In the log |
|---|---|---|
new_root, first | the path at the end | name= |
put_old, second | the value of oldroot=, before the path | srcname= |
Both are directories; the kernel's names end in / (code).
Forms
| Rule | Allows |
|---|---|
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
-> PROFILEis 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_rootreadsno(derived fromlinux: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
| Field | Meaning |
|---|---|
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
| Rule | Message |
|---|---|
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-enforced | warning 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_rulebuildsmnt_rule(NULL, oldroot, NULL, newroot, AA_MAY_PIVOTROOT)and stores the target intrans(parser/parser_yacc.y:1820-1838).transis expanded and compared (parser/mount.cc:654, 699) and never encoded:post_parse_profilehas only a TODO (parser/mount.cc:1194-1199).- Encoding: the class byte 7, new root, NUL, old root, with
AA_MAY_PIVOTROOT0x1 (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) callsaa_pivotroot(linux:security/apparmor/mount.c:663-709);build_pivotrootmatches 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 andbogusis dropped (tree). - The operator is not checked and only the first value is used:
pivot_root oldroot in (/a/) /new/,is accepted, andoldroot=(/a/ /b/)means/a/(tree). - The arrow target is accepted and ignored without a message (tree, code).
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
FILE ACCESS
- Named exec transitions — the other arrows that name a profile
RULE CLASSES
- Mount rules — the mount that becomes the new root
- Umount rules — unmounting the old root afterwards
- Remount rules — the third sibling in the mount class
- Rule conditionals — oldroot= and how conditionals are written
- change_profile rules — the rule that does change the profile
- Capability rules — sys_admin which pivot_root also needs
RUNNING THE PARSER
- Reading a denial — reading the pivotroot record