User namespace rules

user namespaces for application developers for administrators for security researchers

A userns rule lets a confined task create a user namespace. It has one permission create and no conditionals. Every profile compiled for a feature set that lists userns_create denies the creation unless it has the rule. Unconfined tasks are not asked. A refusal is logged as operation userns_create.

On the map: rule classes

▶ Watch this deck — 9 scenes, ~6 min

Worth seeing first

Part of journeys

01 demo starts its worker in a user namespace

USER NAMESPACE RULES demo unshare(CLONE_NEWUSER) kernel = -1 EACCES the profile has no userns rule userns create, line 21 of demo's profile new user namespace demo uid 0 here still under profile demo the rule is about creating the namespace, not about what happens inside it
demo calls unshare with CLONE_NEWUSER. The profile has no userns rule and the kernel refuses with EACCES. With the rule userns create the call goes through: demo runs in a new user namespace with uid 0 there, still under profile demo. The rule is about creating the namespace, not about what happens inside it.

userns create, (or just userns,) lets a confined task create a user namespace.

Demo wants its worker in a sandbox, and the first step of most sandboxes is a new user namespace: a place where the process can be root without being root outside. Under a current profile that step is refused unless the profile says otherwise. Line twenty-one says otherwise: userns create. That's the whole rule. Demo is still confined by the same profile inside the new namespace. The rule only decides whether the namespace may be created.

Details and sources

Details

  • The LSM hook is userns_create (lsm.c:1051-1071, registered at lsm.c:1873). It is called from create_user_ns (user_namespace.c:122), which unshare(CLONE_NEWUSER) and clone(CLONE_NEWUSER) reach. It is the hook's only call site.
  • The feature file is /sys/kernel/security/apparmor/features/namespaces/mask, which reads userns_create (apparmorfs.c:2658).
  • The generic limit on user namespaces, user.max_user_namespaces, is separate from AppArmor.
  • userns create, is line 21 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.

02 One keyword, one word

GRAMMAR QUALIFIERSusernscreate, userns create, line 21 of demo's profile userns, the same rule audit deny userns, audit, allow, deny and priority= work; owner is refused userns (create), Lexer found unexpected character: '(' (0x28) in state: USERNS_MODE no parenthesised list and no conditionals in this class
The syntax diagram of a userns rule: optional qualifiers, the word userns, the optional word create, a comma. userns create and userns are the same rule. audit deny userns shows that the qualifiers work. userns (create) with parentheses is a scanner error.

[QUALIFIERS] userns [create],. No parentheses, no conditionals.

This is the shortest grammar of all the rule classes. The keyword, optionally the word create, and the comma. Create is the only permission, so writing it or not makes no difference. The usual qualifiers go in front: you can deny it, audit it, give it a priority. What you can't do is what other classes allow: put the permission in parentheses, or add a conditional. The scanner knows exactly one word after userns.

Details and sources

Details

  • The one permission is create; a rule without the word means the same.
  • Seats: audit, allow, deny, prompt and priority= are accepted (run with the tree's parser); owner and other are refused: owner userns, gives owner prefix not allowed on userns rules.
  • userns (create), gives Lexer found unexpected character: '(' (0x28) in state: USERNS_MODE (run with the tree's parser).
  • Examples in the tree: ok_userns_01.sd, ok_userns_05.sd, ok_userns_07.sd.

for AppArmor developers for security researchers

In the code

03 Without the rule, the answer is no

THE DEFAULT profile demo /usr/bin/demo { /etc/demo/** r, } no userns rule abi <abi/3.0>, feature set without userns_create demo unshare(CLONE_NEWUSER) AppArmor does not check abi <abi/4.0>, abi <abi/5.0>, feature set with userns_create demo unshare(CLONE_NEWUSER) denied changing the abi line of an old profile can make a working sandbox fail userns, allowed
One profile text with no userns rule, compiled twice. With abi 3.0, a feature set without userns_create, AppArmor does not check demo's unshare call. With abi 4.0 or abi 5.0, a feature set with userns_create, the same call is denied; adding the rule userns allows it. Changing the abi line of an old profile can make a working sandbox fail.

With a feature set that lists namespaces/mask/userns_create, every confined profile denies user namespace creation unless it has userns,.

Most rule classes are deny by default, but here it bites, because the class is newer than many profiles. Take a profile that never mentions user namespaces. Compiled for an old feature set, one that doesn't know the class, AppArmor stays out of it and the namespace is created. Compiled for a current one, the same text now denies it. Nothing in the profile changed, only the abi line, or the kernel. So when a program that sandboxes itself starts failing after a policy update, look for this, and add the rule.

Details and sources

Details

  • The feature is namespaces/mask/userns_create. The feature set is that of the profile's abi rule. A profile without an abi rule is compiled for the parser's built-in default (unless a feature set is pinned with --policy-features), which does not list the feature, so it is in the left column on every kernel (run with the tree's parser: the warning is missing feature abi, falling back to default policy feature abi). In both cases a feature the running kernel lacks is left out as well; see feature ABI.
  • In the tree, userns_create is listed by abi/4.0, abi/4.0-ip, abi/5.0 and abi/5.0-interface, and not by abi/3.0 or the kernel-5.4 files.
  • Without the feature the rule is dropped. Run with the tree's parser, abi <abi/3.0>, with userns, prints Warning from profile demo (...): userns rules not enforced; the warning class rule-not-enforced is off by default. The kernel is then told nothing about the class and does not check that profile (task.c:389-391).
  • With the feature, the class is marked in every profile the parser compiles, with or without a userns rule, and the kernel checks the create permission.
  • "Does not check" and "denied" on the slide are derived from the kernel source (task.c:374-399); they were not run on a kernel.
  • Kernel statements are read from the kernel source and were not run.

for AppArmor developers for security researchers

In the code

04 Only confined tasks are asked

WHO IS ASKED the kernel bash unconfined not asked: allowed by AppArmor demo demo: userns, allowed demo demo: userns, sandbox: no rule denied every profile of the label must allow it upstream-and-ubuntu Ubuntu kernels add a restriction for tasks without a profile the mainline kernel has no setting that makes unconfined tasks ask the ordinary kernel limits on user namespaces still apply to everyone
Three tasks call unshare with CLONE_NEWUSER. An unconfined bash is not asked and is allowed by AppArmor. demo under profile demo, which has the rule userns, is allowed. demo under a stack of two profiles, demo with the rule and sandbox without it, is denied: every profile of the label must allow it. The mainline kernel has no setting that makes unconfined tasks ask; Ubuntu kernels add one, see upstream-and-ubuntu. The ordinary kernel limits on user namespaces still apply to everyone.

The kernel checks every confined profile of the label; unconfined labels are skipped. Restricting unconfined tasks is an Ubuntu addition: see Upstream and Ubuntu.

Who gets asked? Only confined tasks. An unconfined shell creates user namespaces without AppArmor looking. A task under a profile with the rule is allowed. If the task runs under a stack of two profiles, both are asked, and one refusal is enough. You may have heard that Ubuntu stops unprivileged programs from creating user namespaces unless they have a profile. That's an addition in Ubuntu's kernels. The mainline kernel has no such switch, and the upstream and Ubuntu deck explains the difference.

Details and sources

Details

  • The whole check is guarded by if (!unconfined(label)) (lsm.c:1063). For each profile of the label, aa_profile_ns_perm skips an unconfined profile (task.c:384), returns 0 when the class is not mediated (task.c:389-391), and otherwise checks the permission.
  • The third row of the slide is derived from the loop over the profiles of the label (lsm.c:1063-1066); it was not run.
  • The sysctls kernel.apparmor_restrict_unprivileged_userns* are not in security/apparmor/ of the kernel tree read for this map. The sysctls that do exist nearby are kernel.unprivileged_userns_apparmor_policy (lsm.c:2454: whether a root user inside a user namespace may load policy) and kernel.apparmor_restrict_unprivileged_unconfined (lsm.c:2469).
  • The fixture testcase_userns_02.in (info="Userns create - transitioning profile" profile="unconfined" ... target="unprivileged_userns") is from a kernel with the Ubuntu addition.
  • Kernel statements are read from the kernel source and were not run.

05 What demo and the log see

THE DENIAL demo unshare(CLONE_NEWUSER) = -1 EACCES apparmor="DENIED" operation="userns_create" class="namespace" profile="demo"pid=1785 comm="demo" requested="userns_create" denied="userns_create" userns, the rule that would allow it deny userns, refuses it quietly: no record audit deny userns, refuses it and logs some programs treat this failure as "no sandbox available" and carry on without one
demo calls unshare with CLONE_NEWUSER and gets EACCES. The record has operation userns_create, class namespace, profile demo, requested userns_create and denied userns_create. The rule userns would allow it. deny userns refuses it quietly with no record; audit deny userns refuses it and logs. Some programs treat this failure as no sandbox available and carry on without one.

operation="userns_create" class="namespace" requested="userns_create" denied="userns_create"; the call returns EACCES.

When it's refused, unshare fails with EACCES. The log record is operation="userns_create", class namespace, and it names the profile. There's no path and no peer, because nothing else is involved. The fix is one line. If instead you want to be sure a program can't do this, deny userns says so explicitly, and it's quiet unless you add audit. One practical note: a lot of software treats this failure as no sandbox available and carries on without one, so the denial may show up as a change in behaviour instead of an error.

Details and sources

Details

  • The record on the slide is assembled from the fixture testcase_userns_01.in (apparmor="DENIED" operation="userns_create" class="namespace" profile="/usr/bin/userns_child_exec" pid=1785 comm="userns_child_ex" requested="userns_create" denied="userns_create") with demo's values, which are illustrative.
  • The fields requested= and denied= come from the audit callback of this class, which can also add execpath= (task.c:353-372). The error is EACCES (lib.c:440).
  • In complain mode the creation is allowed and logged as ALLOWED. audit userns, logs each allowed creation. audit deny userns, compiles (run with the tree's parser).
  • The last line of the slide is general knowledge about callers, not a finding from the source trees.
  • Kernel statements are read from the kernel source and were not run.

06 A permission on the class byte, and two markers for AppArmor developers for security researchers

IN THE PARSER userns create, class userns_rule \x15 class 21, AA_CLASS_NS 0x8 create priority 0 \d7 0x4 priority 1001 other classes: one marker, at the top priority here that would hide the permission, so the generic marker goes to the bottom 0x4 marker priority -1001 every profile 0x4 marker priority 0 per rule aa_profile_ns_perm() state = RULE_MEDIATES(rules, AA_CLASS_NS); if (!state) return 0; lookup perms; check AA_USERNS_CREATE the bottom marker is added before the test for unconfined and default_allow profiles
The rule userns create compiles to one byte, 15 hexadecimal, class 21, leading to one state. Three entries sit on that state: the permission 0x8 create at priority 0, a marker 0x4 at priority 0, and a marker 0x4 at priority minus 1001 that every profile gets. Other classes have one marker at the top priority; here that would hide the permission. In the kernel aa_profile_ns_perm finds the state with RULE_MEDIATES, returns 0 if there is none, and otherwise checks AA_USERNS_CREATE.

userns.cc:101-133 writes \x15 with 0x8 and a marker at the rule's priority; parser_regex.c:1392-1394 adds \d21 at the minimum priority to every profile; task.c:374-399 reads the state.

The class userns_rule writes the shortest match string there is: the class byte, twenty-one, and nothing after it. The permission, eight, sits on the state that byte leads to. That breaks the usual trick of marking a class as mediated with a top priority entry on the same state: it would wipe the permission out. So for this class the generic marker goes in at the lowest priority, and every rule adds a marker of its own at the rule's priority. The kernel finds the state and, if there is one, reads its permissions and tests the bit. The generic marker is added to every profile, even unconfined ones.

Details and sources

for AppArmor developers for security researchers

Details

  • Dumps from the tree's parser (-D rule-exprs): userns, gives \x15 with 0x8 and \x15 with 0x4 at the rule's priority, plus \d21 with 0x4 at priority -1001; priority=3 userns, puts the first two at priority 3; audit deny userns, gives a deny of 0x8 on \x15 and the marker \x15 0x4.
  • The rule: userns.cc:46-61, userns.cc:101-133. Class AA_CLASS_NS is 21 (policydb.h:45).
  • The comment that explains the scheme, and perms_onclass_mediates_priority = MIN_INTERNAL_PRIORITY: parser_regex.c:1374-1383. The generic marker is added when the feature is supported, before the mode test that exempts unconfined and default_allow profiles from the other markers (parser_regex.c:1392-1397). io_uring uses the same scheme inside that test (parser_regex.c:1450-1452).
  • Kernel: aa_profile_ns_perm (task.c:374-399).
  • Kernel statements are read from the kernel source and were not run.

for security researchers

Attack surface

  • A default_allow profile is packed as unconfined mode (profile.h:75-79), so aa_profile_ns_perm skips it (task.c:384) and its \d21 marker is not read. Read from the code, not run.

for AppArmor developers for security researchers

Read more

07 Where the default flips for security researchers

ATTACK SURFACE label unconfined? yes: allowed by AppArmor lsm.c:1063 profile mediates the class? no: allowed old abi or no feature: task.c:389 userns rule? yes: allowed no: EACCES inside the new namespace capability checks still go through the profile's capability rules the userns rule does not narrow or widen them setns(fd, CLONE_NEWUSER) joining an existing namespace does not reach this hook audit a profile set by its abi lines, not only by its userns rules
A decision path for one unshare call. Is the label unconfined? Then it is allowed by AppArmor. Does the profile mediate the class? If not, because of an old abi or a kernel without the feature, it is allowed. Is there a userns rule? Yes: allowed; no: EACCES. Inside the new namespace capability checks still go through the profile's capability rules; the userns rule does not narrow or widen them. Joining an existing namespace with setns does not reach this hook.

The check is skipped for unconfined labels and for profiles whose feature set lacks userns_create. The rule covers creation only: not setns, not what happens inside.

For a reviewer the rule itself is the small part. Two things decide the outcome before it's read. Is the task unconfined? Then AppArmor doesn't ask. Was the profile compiled for a feature set that knows the class? If not, a profile with no userns rule allows it, and so does one with a deny, because the rule was dropped. Only then does the rule count. And the rule says nothing about afterwards: inside the namespace, what the task can do with its capabilities is still filtered by the profile's capability rules. Joining an existing namespace isn't covered by this check at all.

Details and sources

for security researchers

Details

  • The early exits: an unconfined label (lsm.c:1063); an unconfined profile inside a label (task.c:384); a profile that does not mediate the class, next to the comment TODO: add flag to complain about unmediated (task.c:389-391).
  • The parser's drop of the rule for a feature set without userns_create is silent by default. Run with the tree's parser under abi <abi/3.0>,, both userns create, and deny userns, give the warning userns rules not enforced and no entry for class 21.
  • The hook has one call site in the tree read (user_namespace.c:122).
  • Every statement here is read from the code or produced with the tree's parser; none was run on a kernel.

for security researchers

Attack surface

  • Old ABI: a shipped profile pinned to abi <abi/3.0>,, or with no abi rule at all, cannot deny user namespace creation; deny userns, there compiles to nothing.
  • Unconfined: on the mainline kernel any unconfined task creates user namespaces subject only to the generic kernel limits. Whether a distribution kernel changes that is in Upstream and Ubuntu kernels.
  • Inside: the rule grants no capability. A profile with userns, and broad capability rules (or all,) gives the task those capabilities inside its own namespace, which is where much kernel attack surface for unprivileged users starts; see User namespaces and AppArmor.
  • setns into an existing user namespace is not covered by this hook.

08 Mistakes and their messages

MISTAKES userns (create), Lexer found unexpected character: '(' (0x28) in state: USERNS_MODE userns peer=foo, Lexer found unexpected character: 'p' (0x70) in state: USERNS_MODE userns create create, syntax error, unexpected TOK_CREATE, expecting TOK_CONDID or TOK_END_OF_RULE owner userns, owner prefix not allowed on userns rules abi <abi/3.0>, ... userns, accepted and dropped; --warn=rule-not-enforced prints userns rules not enforced
Five userns rules. Parentheses are a scanner error. A conditional such as peer=foo is a scanner error. create twice is a syntax error. owner is refused. A correct rule under abi 3.0 is accepted and dropped; the warning userns rules not enforced appears only with --warn=rule-not-enforced.

Only userns, and userns create, exist. Use --warn=rule-not-enforced to see a dropped rule.

There's not much to get wrong. Parentheses, which other classes with permissions accept, are a scanner error here. So is a conditional, or any word other than create. Create twice is a syntax error. Owner isn't allowed. And the one to watch for is the last: a correct rule in a profile whose abi line predates the class is dropped without a word, unless you turn the warning on.

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. All five rows were run with the tree's parser. The warning of row 5 is printed as Warning from profile demo (FILE): userns rules not enforced.
  • userns create foo=bar, also fails in the scanner, and so does any other word: userns read, gives Lexer found unexpected character: 'r' (0x72) in state: USERNS_MODE.
  • A failing example in the tree: bad_userns_01.sd.

for AppArmor developers for security researchers

In the code

  • Three messages exist in the source and cannot be produced from a profile: perms contains invalid permissions for userns, only "=" allowed in conditions of userns rules and invalid userns rule conditional "%s" (userns.cc:38-51).
  • The scanner state is described in the scanner.

09 Around the namespace

ROADS userns create, one line, and a default that depends on the feature set sec-userns why this matters upstream-and-ubuntu what Ubuntu kernels add syn-capability capabilities inside syn-abi the feature set syn-io-uring the same kind of default adm-denials the userns_create record
User namespace rules in the centre with roads to sec-userns and upstream-and-ubuntu, to syn-capability and syn-abi, and to syn-io-uring and adm-denials.

userns, allows creating a user namespace. Why it matters: User namespaces and AppArmor.

One line in the profile, and a default that depends on the feature set. If you want to know why user namespaces get this attention, the security deck on them is next. The upstream and Ubuntu deck covers the restriction Ubuntu adds for programs without a profile. And the capability deck is where you decide what the task may do once it's inside.

Details and sources

Details

  • [QUALIFIERS] userns [create],: one permission, no conditionals.
  • A confined task without the rule gets EACCES, logged as operation="userns_create", when its profile was compiled for a feature set that lists userns_create.
  • 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

USERNS RULE:  [QUALIFIERS] userns [create] ,
QUALIFIERS:   [priority=N] [audit] [allow|deny|prompt]
  • create is the only permission; userns, and userns create, are the same rule (tree).
  • What cannot be written: a parenthesised list (userns (create),), a conditional (userns peer=foo,), a second word (tree).
SeatOn a userns rule
priority=taken
audittaken
allow, deny, prompttaken: deny is not logged; prompt is in syn-prompt
owner, otherrefused: owner prefix not allowed on userns rules (tree)

Who may create a user namespace

The taskChecked by AppArmorResultSource
unconfined labelnoallowedlinux:security/apparmor/lsm.c:1063
confined, feature set without userns_createnoallowed, with or without a rule, also with deny userns,linux:security/apparmor/task.c:389-391
confined, profile without an abi rulenoallowed, with or without a rulethe built-in default lacks userns_create (tree)
confined, feature set with userns_create, no ruleyesEACCESlinux:security/apparmor/task.c:392-395
confined, with userns,yesallowedthe same
confined, with deny userns,yesEACCES, not loggedthe same
a stack of profileseach confined profileallowed only if every one allows itlinux:security/apparmor/lsm.c:1063-1066

All rows are read from the kernel source (code), except where marked.

Feature set

Feature setLists namespaces/mask/userns_create
no abi rule (built-in default)no
abi/3.0no
abi/kernel-5.4-vanilla, abi/kernel-5.4-outoftree-networkno
abi/4.0, abi/4.0-ipyes
abi/5.0, abi/5.0-interfaceyes

Without the feature the rule is dropped; --warn=rule-not-enforced prints userns rules not enforced (tree). See syn-abi and adm-features.

What the rule does not cover

  • Capabilities inside the namespace: they are still checked against the profile's capability rules; see syn-capability.
  • setns into an existing user namespace (code).
  • Other namespace types: the class has one permission.
  • The restriction of unprivileged user namespaces in Ubuntu kernels: see upstream-and-ubuntu and sec-userns.

The log record

FieldMeaning
operation="userns_create"the creation
class="namespace"always
profile=the profile that refused
requested=, denied=userns_create

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

apparmor="DENIED" operation="userns_create" class="namespace" profile="/usr/bin/userns_child_exec" pid=1785 comm="userns_child_ex" requested="userns_create" denied="userns_create"

testcase_userns_02.in in the same directory is from a kernel with the Ubuntu addition. A refused creation returns EACCES.

Errors and warnings

RuleMessage
userns (create),Lexer found unexpected character: '(' (0x28) in state: USERNS_MODE
userns read,Lexer found unexpected character: 'r' (0x72) in state: USERNS_MODE
userns peer=foo,Lexer found unexpected character: 'p' (0x70) in state: USERNS_MODE
userns create create,syntax error, unexpected TOK_CREATE, expecting TOK_CONDID or TOK_END_OF_RULE
owner userns,owner prefix not allowed on userns rules
userns, under abi <abi/3.0>,warning userns rules not enforced (class rule-not-enforced, off by default)
none (unreachable)perms contains invalid permissions for userns
none (unreachable)only "=" allowed in conditions of userns rules
none (unreachable)invalid userns rule conditional "%s"

Rows with a rule are from the tree's parser; the unreachable messages are read from the parser source (code).

for AppArmor developers for security researchers

In the parser and the kernel

  • Class AA_CLASS_NS 21 (parser/policydb.h:45); permission create 0x8 (parser/userns.h:24-25).
  • The rule writes \x15 with 0x8 and a marker \x15 0x4 at the rule's priority (parser/userns.cc:101-133). The generic marker \d21 0x4 goes to every profile at the minimum priority (parser/parser_regex.c:1374-1394), because a top-priority marker on the class state would hide the permission.
  • Kernel: apparmor_userns_create (linux:security/apparmor/lsm.c:1051-1071) calls aa_profile_ns_perm for each profile of a confined label (linux:security/apparmor/task.c:374-399); the permission is AA_USERNS_CREATE 8 (linux:security/apparmor/include/task.h:112).

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.

  • The grammar and the rule class have code for a permission list and for conditionals that the scanner never produces; the example files bad_userns_02.sd and bad_userns_03.sd fail in the scanner for that reason (code, tree).

Not run on a kernel.

Roads from here

START HERE

PREAMBLE AND REUSE

PROFILE HEAD

QUALIFIERS

RULE CLASSES

SECURITY · threat model and limits

RUNNING THE PARSER