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
- Capability rules — capabilities, which decide what the task may do inside
- The abi rule and the abi files — why the declared ABI decides whether userns is mediated
Part of journeys
- Network, IPC and privileges, step 10 of 14 · previous: Ptrace rules · next: Mount rules
01 demo starts its worker in a user namespace
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 fromcreate_user_ns(user_namespace.c:122), whichunshare(CLONE_NEWUSER)andclone(CLONE_NEWUSER)reach. It is the hook's only call site. - The feature file is
/sys/kernel/security/apparmor/features/namespaces/mask, which readsuserns_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 programdemoand its profile are invented for the map.- Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), User Namespace Rules, kernel documentation: /proc/sys/user/ for
max_user_namespaces. - User namespaces and AppArmor.
02 One keyword, one word
[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,promptandpriority=are accepted (run with the tree's parser);ownerandotherare refused:owner userns,givesowner prefix not allowed on userns rules. userns (create),givesLexer 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.
Read more
- apparmor.d(5), User Namespace Rules, apparmor.d(5), Rule Qualifiers.
- Rule conditionals: this class has none.
for AppArmor developers for security researchers
In the code
- The
userns_ruleproductions: parser_yacc.y:1527-1539. The permissioncreateis 0x8 (userns.h:24-25); no word means the same (userns.cc:54-56); theownerrefusal: userns.h:35-41. - The scanner state
USERNS_MODE(parser_lex.l:896-897) is not in the state lists that produce(,TOK_CONDIDorTOK_ID(parser_lex.l:419, parser_lex.l:669, parser_lex.l:690); its one word iscreate(parser_lex.l:636-638). - Known discrepancy, on the bug list as "
usernscannot take a permission list or a conditional; the grammar and checks for them are unreachable": the grammar and the rule class have code for a parenthesised permission list and for conditionals (parser_yacc.y:1515-1535, userns.cc:31-44), but the scanner state for this keyword produces neither, souserns (create),anduserns peer=foo,end in a scanner error. The example filesbad_userns_02.sdandbad_userns_03.sdfail for that reason.
03 Without the rule, the answer is no
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'sabirule. A profile without anabirule 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 ismissing 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_createis listed byabi/4.0,abi/4.0-ip,abi/5.0andabi/5.0-interface, and not byabi/3.0or thekernel-5.4files. - Without the feature the rule is dropped. Run with the tree's parser,
abi <abi/3.0>,withuserns,printsWarning from profile demo (...): userns rules not enforced; the warning classrule-not-enforcedis 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
createpermission. - "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.
Read more
for AppArmor developers for security researchers
In the code
- The feature set of a profile without an
abirule: parser_yacc.y:353-361. The kernel's permission isAA_USERNS_CREATE(8, task.h:112). - The feature test: parser_main.c:1099-1101. The drop and its warning: userns.cc:98, userns.cc:106-109. The marker added to every profile: parser_regex.c:1383, parser_regex.c:1392-1394.
04 Only confined tasks are asked
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_permskips 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 insecurity/apparmor/of the kernel tree read for this map. The sysctls that do exist nearby arekernel.unprivileged_userns_apparmor_policy(lsm.c:2454: whether a root user inside a user namespace may load policy) andkernel.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
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=anddenied=come from the audit callback of this class, which can also addexecpath=(task.c:353-372). The error isEACCES(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
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\x15with 0x8 and\x15with 0x4 at the rule's priority, plus\d21with 0x4 at priority -1001;priority=3 userns,puts the first two at priority 3;audit deny userns,gives a deny of 0x8 on\x15and the marker\x150x4. - The rule: userns.cc:46-61, userns.cc:101-133. Class
AA_CLASS_NSis 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 exemptsunconfinedanddefault_allowprofiles 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_allowprofile is packed as unconfined mode (profile.h:75-79), soaa_profile_ns_permskips it (task.c:384) and its\d21marker 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
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_createis silent by default. Run with the tree's parser underabi <abi/3.0>,, bothuserns create,anddeny userns,give the warninguserns rules not enforcedand 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 noabirule 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 (orall,) 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. setnsinto an existing user namespace is not covered by this hook.
for security researchers
Read more
08 Mistakes and their messages
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 asWarning 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,givesLexer found unexpected character: 'r' (0x72) in state: USERNS_MODE.- A failing example in the tree: bad_userns_01.sd.
Read more
- apparmor.d(5), User Namespace Rules.
- Running the parser for
--warn=.
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 rulesandinvalid userns rule conditional "%s"(userns.cc:38-51). - The scanner state is described in the scanner.
09 Around the namespace
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 asoperation="userns_create", when its profile was compiled for a feature set that listsuserns_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]
createis the only permission;userns,anduserns create,are the same rule (tree).- What cannot be written: a parenthesised list (
userns (create),), a conditional (userns peer=foo,), a second word (tree).
| Seat | On a userns 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 userns rules (tree) |
Who may create a user namespace
| The task | Checked by AppArmor | Result | Source |
|---|---|---|---|
| unconfined label | no | allowed | linux:security/apparmor/lsm.c:1063 |
confined, feature set without userns_create | no | allowed, with or without a rule, also with deny userns, | linux:security/apparmor/task.c:389-391 |
confined, profile without an abi rule | no | allowed, with or without a rule | the built-in default lacks userns_create (tree) |
confined, feature set with userns_create, no rule | yes | EACCES | linux:security/apparmor/task.c:392-395 |
confined, with userns, | yes | allowed | the same |
confined, with deny userns, | yes | EACCES, not logged | the same |
| a stack of profiles | each confined profile | allowed only if every one allows it | linux:security/apparmor/lsm.c:1063-1066 |
All rows are read from the kernel source (code), except where marked.
Feature set
| Feature set | Lists namespaces/mask/userns_create |
|---|---|
no abi rule (built-in default) | no |
abi/3.0 | no |
abi/kernel-5.4-vanilla, abi/kernel-5.4-outoftree-network | no |
abi/4.0, abi/4.0-ip | yes |
abi/5.0, abi/5.0-interface | yes |
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.
setnsinto 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
| Field | Meaning |
|---|---|
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
| Rule | Message |
|---|---|
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_NS21 (parser/policydb.h:45); permissioncreate0x8 (parser/userns.h:24-25). - The rule writes
\x15with 0x8 and a marker\x150x4 at the rule's priority (parser/userns.cc:101-133). The generic marker\d210x4 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) callsaa_profile_ns_permfor each profile of a confined label (linux:security/apparmor/task.c:374-399); the permission isAA_USERNS_CREATE8 (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.sdandbad_userns_03.sdfail in the scanner for that reason (code, tree).
Not run on a kernel.
Roads from here
START HERE
- Upstream and Ubuntu kernels — the restriction of unprivileged user namespaces in Ubuntu kernels
- The profile language at a glance — every kind of line on one page
PREAMBLE AND REUSE
- The abi rule and the abi files — the feature set that turns the default deny on
PROFILE HEAD
- Profile mode flags — unconfined and default_allow profiles
QUALIFIERS
- allow and deny — deny and audit on a userns rule
RULE CLASSES
- Capability rules — capabilities inside the new namespace are still filtered
- io_uring rules — the other class with a default deny of this kind
- The all rule — the rule that includes userns
SECURITY · threat model and limits
- User namespaces and AppArmor (no slides yet) — why user namespaces are attack surface and what Ubuntu restricts
RUNNING THE PARSER
- Reading a denial — reading the userns_create record