Capability rules
POSIX capabilities for application developers for administrators for security researchers
A capability rule lists the Linux capabilities a confined task may use. It filters what the task already holds and grants nothing. Names are the kernel's names in lower case without CAP_. A bare capability rule means all of them. Denials are logged as operation capable with capname.
On the map: rule classes
▶ Watch this deck — 9 scenes, ~6 min
Worth seeing first
- allow and deny — deny wins and stays quiet, as it does for capabilities
Part of journeys
- Network, IPC and privileges, step 2 of 14 · previous: The abi rule and the abi files · next: Network rules
- Hardening a privileged program, step 6 of 11 · previous: Child profiles · next: The audit qualifier
01 demo wants a privileged port
A confined task may use a capability only if it holds it and its profile lists it. capability net_bind_service, lists one.
Demo runs as root and wants to listen on port eighty. Ports below ten twenty-four need a Linux capability, net_bind_service. Root holds it, so the kernel's own check passes. But demo is confined, and AppArmor adds a second question: does demo's profile list that capability? It doesn't, so the bind fails with EACCES, exactly as it would for a user who isn't root. One line fixes that: the word capability, then the name in lower case. That's line ten of demo's profile. With it, this check passes. Two checks, then, and both have to say yes.
Details and sources
Details
- The LSM hook is
capable; AppArmor registersapparmor_capablefor it (lsm.c:199-211, registered at lsm.c:1789). - It runs after the kernel's own capability check, for every capability test of a task whose label is not unconfined. For a capability the profile does not list the hook returns
EPERM(capability.c:150-154) and the kernel's capability test fails. The system call then returns what it returns for a missing capability:EACCESfor bind to a low port (af_inet.c:516-520). - The slide shows the capability check only. Listening on the port also needs a
networkrule; see Network rules. - "Runs as root" is the illustration. What counts is whether the task holds the capability.
- Feature file:
/sys/kernel/security/apparmor/features/caps/masklists the capability names the kernel knows (capability.c:28-32, apparmorfs.c:2694). capability net_bind_service,is line 10 of demo's profile. The programdemoand its profile are invented for the map.- Kernel statements are read from the kernel source and were not run.
02 capability and a list of names
[QUALIFIERS] capability [NAME ...],. Names are lower case without CAP_, separated by blanks. capability, means all.
This is the shortest grammar in the language. The word capability, then names, then the comma. Several names go on one rule with blanks between them, not commas, because the comma ends the rule. No name at all means every capability, so be careful with that one. The names are the kernel's own, in lower case and without the CAP_ prefix. There are forty-one, and they're all listed under this deck. And there's nothing else: no permissions, no conditionals, no quotes, no variables.
Details and sources
Details
- The list of names may continue on the next line. Naming a capability twice is fine (capability/ok1.sd).
capability,with no name allows every capability. The ruleall,includes every capability too (all_rule.cc:144).- The 41 names, by number:
chown,dac_override,dac_read_search,fowner,fsetid,kill,setgid,setuid,setpcap,linux_immutable,net_bind_service,net_broadcast,net_admin,net_raw,ipc_lock,ipc_owner,sys_module,sys_rawio,sys_chroot,sys_ptrace,sys_pacct,sys_admin,sys_boot,sys_nice,sys_resource,sys_time,sys_tty_config,mknod,lease,audit_write,audit_control,setfcap,mac_override,mac_admin,syslog,wake_alarm,block_suspend,audit_read,perfmon,bpf,checkpoint_restore(base_cap_names.h:1-81). - The kernel's highest capability is
checkpoint_restore, number 40 (capability.h:421-423).
Read more
for AppArmor developers for security researchers
In the code
capability: TOK_CAPABILITY caps TOK_END_OF_RULEreturns a 64-bit mask (parser_yacc.y:1694-1716); with no name every bit is set (parser_yacc.y:1696-1698).- Names are ordinary words scanned in the initial state (parser_lex.l:855-866); the keyword is in the table at parser_misc.c:86.
03 The rule filters; it does not give
A capability rule lets a task use a capability it already holds. It grants none, and it does not replace the network or file rule for the same operation.
Two things people expect from this rule that it doesn't do. First, it doesn't give demo anything. If demo runs as an ordinary user with no capabilities, listing net_bind_service in the profile changes nothing. A profile can only narrow what the task holds. Second, it isn't a substitute for the other rules. The capability lets demo use a low port, but the socket itself still needs a network rule. Without one, the socket call is refused before bind is even reached. Think of capability rules as a filter on privilege, next to the rules about objects.
Details and sources
Details
- A capability rule is tested after the kernel's own check: a task that does not hold the capability is refused before AppArmor is asked.
- A profile with no
networkrule refuses every socket; the caller seesEACCES. See Network rules. - With a stack of profiles, every confined profile of the label must list the capability (capability.c:188-189).
capget(2)is filtered too: the effective and permitted sets a confined task reads are intersected with what its profiles allow (hookcapget, lsm.c:167-197; capability.c:194-223). A profile in complain mode reports the full set.- Kernel statements are read from the kernel source and were not run.
for security researchers
Attack surface
- The rule is a mask over the task's own capabilities, tested per profile of the label. It has no object:
capability dac_override,is all-or-nothing for every file. - Checks that the kernel makes without auditing return the answer in enforce mode and leave no record (capability.c:156-163).
- Capabilities inside user namespaces are in User namespaces and security.
04 deny, audit and the seats that do nothing here
deny capability X, always wins and is not logged; audit deny logs it. audit capability X, logs uses. priority= has no effect; owner is an error.
Capability rules take the usual qualifiers, with a twist or two. Rules add up, so the bare rule gives everything. A deny takes one away again, and deny wins wherever it's written. Like every deny it's quiet: a refused sys_admin leaves no trace in the log, unless you write audit deny. Audit on an allow rule logs each use. Priority is accepted, so that blocks keep working, but for capabilities it changes nothing. And owner makes no sense here, so the parser refuses it.
Details and sources
Details
- Capability rules take three of the four qualifier seats:
priority=(accepted, no effect),audit, andallow/deny/prompt. The seat ofownerandotheris refused:owner conditional not allowed on capability rules. - The parser, not the kernel, resolves
deny. What it sends is "allowed and not denied", "allowed and audited" and "denied and quiet" (parser_interface.c:549-559). No priority can therefore let an allow beat a deny here (block_rules.cc:135-138). prompt capability chown,is accepted and stored as allow (block_rules.cc:148-152); see prompt.- In a block:
owner { capability chown, }givesowner prefix not allowed on capability rules(block_rules.h:69). Block example: capability/ok_block1.sd. deny audit capability ...is a syntax error:auditsits beforedeny.- The parser results were produced with the parser built from the AppArmor tree. What is logged is read from the kernel source and was not run.
05 What demo and the log see
A refused capability fails the call as a missing capability would (EACCES for setpriority and bind, EPERM for most calls) and is logged as operation="capable" capability=N capname="name", one record per second per capability. Plain deny rules log nothing.
When the profile doesn't list a capability, demo's call fails, with the same error the kernel gives when the task lacks the capability altogether. For setpriority that's EACCES. The log tells you which it was: operation="capable", the capability number, and its name. The name is exactly the word to put in the rule. One thing to know when you read logs: the kernel doesn't repeat itself. The same capability refused again within a second isn't logged again. And a capability refused by a plain deny rule isn't logged at all. So silence isn't proof that it was allowed.
Details and sources
Details
- The record on the slide is assembled from the layout of testcase_dmesg_capability.in (
apparmor="DENIED" operation="capable" parent=... profile=... pid=7292 comm=... capability=23 capname="sys_nice", with two blanks beforecapname). The profile and command names are demo's; the values are illustrative. capability=Ncomes from the common LSM audit code (lsm_audit.c:194);capname=is added by AppArmor (capability.c:47-53); the operation name iscapable(audit.h:48).- The error demo sees is the system call's own, not the hook's
EPERM:setpriorityreturnsEACCESwhen the nice test fails (sys.c:243-245). - The repeat filter is per CPU: it remembers one set of credentials and, per capability, an expiry one second ahead. A different task on that CPU resets it (capability.c:34-40, capability.c:94-107).
- Not logged at all: capabilities refused by a plain
denyrule, unless the profile's audit mode isnoquietorall(capability.c:84-92); and checks the kernel makes without auditing, in enforce mode. - In complain mode the use is allowed and logged as
ALLOWED. A profile in kill mode logs the typeKILL. - Kernel statements are read from the kernel source and were not run.
06 Four masks, not rules for AppArmor developers for security researchers
block_rules.cc:133-154 builds caps.allow/audit/deny/quiet; parser_interface.c:547-559 writes them; capability.c:149-165 tests the bit.
Capability rules don't go through the regular expression compiler at all. Each rule returns a sixty-four bit mask, and add_capabilities ORs it into one of four masks, depending on the qualifiers. When the profile is written out, the deny is subtracted, and three words per half are stored: allowed, audited, and quietly denied. The kernel unpacks them, and profile_capable tests a single bit. The kernel does have a policydb path for capabilities, but this parser doesn't emit that class, so the bitmask branch is the one that runs.
Details and sources
Details
- Parser: the four masks are built at block_rules.cc:133-154 and written at parser_interface.c:547-559.
- Kernel unpack: four low words go into
caps.allow,caps.audit,caps.quietand a discarded one; then the optionalcaps64with the upper halves; then the optionalcapsxintocaps.extended(policy_unpack.c:1254-1288).struct aa_caps: capability.h:29-36. - Load errors:
failed to unpack profile capabilities,failed to unpack upper profile capabilities,failed to unpack extended profile capabilities. - The kernel exports
caps/extendedand the tree's abi/5.0 lists it (abi/5.0:3); no parser code reads it. - The policydb branch (
AA_CLASS_CAP, class 3): one bytecap >> 5, then bitcap & 0x1f(capability.c:128-147). It is not reachable with this parser. The bit test: capability.c:149-165. - Observed with the tree's parser: the blobs of
capability chown,andcapability audit_control,differ in bytes 61 and 64. - Kernel statements are read from the kernel source and were not run.
for security researchers
Attack surface
- Known discrepancy (latent, not reachable with this parser): the policydb branch of
aa_profile_capgetloops overCAP_LAST_CAP >> 5chunks, which is one, and shifts byi * 5(capability.c:204-214). With policy that mediates the class in the policydb,capget(2)would not report capabilities 32 to 40. Found by reading; not run.
07 When the kernel does not know the name for AppArmor developers for security researchers
With a kernel feature set that lacks them, perfmon, bpf and checkpoint_restore compile as sys_admin (parser_yacc.y:1710-1714). No warning is printed.
Three capabilities were split out of sys_admin in newer kernels: perfmon, BPF and checkpoint_restore. A kernel from before the split checks sys_admin for those operations. So when the kernel's feature set doesn't list the new name, the parser compiles the rule as sys_admin instead. That keeps the program working. It also means a profile that asks for perfmon gets the whole of sys_admin on such a kernel. The same swap applies to a deny. There is no message either way; the source has a to-do for the warning.
Details and sources
for security researchers for AppArmor developers
Details
- The test is: the name has a back-map and the kernel feature set does not list it (parser_yacc.y:1710-1714). The three names with a back-map are
perfmon,bpfandcheckpoint_restore, all tosys_admin(base_cap_names.h:9, base_cap_names.h:11, base_cap_names.h:47). - The kernel feature set is what
--kernel-featuresnames, or the running kernel's/sys/kernel/security/apparmor/features/caps/mask. The policy ABI of anabirule is not consulted for this. - The bare
capability,andall,set every bit regardless. sys_adminis capability 21 (capability.h:281),perfmon38 (capability.h:383).- The two outputs were compared with the tree's parser, using abi/5.0 without the three names as the kernel feature set. Nothing was loaded into a kernel.
- The name table: 41 built-in rows, checked when the parser is built against the build host's
linux/capability.h(Makefile:404-415), plus names fromcaps/maskof the kernel feature set and of the policy ABI at run time, numbered by position (parser_misc.c:407-436).
for security researchers for AppArmor developers
Attack surface
- On such a kernel the grant is wider than the text of the profile, the whole of
sys_admin, and adenyis wider too. A reviewer has to know thecaps/maskof the target kernel. - Known discrepancy: when a feature set names a capability the parser build does not know, adding it moves the table, and the name
audit_controlthen compiles to a bit that differs between runs, with exit status 0 (parser_misc.c:234-257, parser_misc.c:339-356). Reproduced with the tree's parser. - Known discrepancy: a capability known only from the policy ABI and not from the kernel feature set compiles as
chown: new rows get back-map 0 (parser_misc.c:347) where "no back-map" is 0xff (capability.h:25). Reproduced with the tree's parser. - Both are confirmed; see Known bugs.
Read more
for AppArmor developers for security researchers
In the code
capability_backmapandcapability_in_kernel: parser_misc.c:298-314. The comment/* TODO: special backmap warning */is at parser_yacc.y:1712.add_cap_feature_mask(parser_misc.c:407-436) is called at parser_main.c:1841 and parser_yacc.y:365-367.
08 Mistakes and their messages
Lower-case names without CAP_; blanks between names; no parentheses, quotes or variables.
The classic mistake is writing the name the way C does, with CAP_, in capitals. The parser wants lower case and no prefix. Next, a comma between names. The comma ends the rule, so the second name starts a new one, which the parser takes for a file rule with no permissions. Hence the odd message about a mode. Parentheses and variables aren't part of this grammar. And the seats are fixed: audit goes before deny.
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, produced by the tree's parser. The message of the last row continues with the tokens the parser expected. - More of the same kind:
capability cap_chown,givesInvalid capability cap_chown.;capability "chown",givesLexer found unexpected character: '"' (0x22) in state: INITIAL;capability all,givessyntax error, unexpected TOK_ALL;capability set=hup,givessyntax error, unexpected TOK_CONDID. - A missing comma before
}givessyntax error, unexpected TOK_CLOSE, expecting TOK_ID or TOK_END_OF_RULE. capability ptrace trace,fails:ptraceis not a capability name (ptrace/bad_05.sd). Another failing example: capability/bad_1.sd.- One warning, on by default:
feature capability 'NAME:N' does not equal expected M. Ignoring ..., when a feature set lists a known name at another position (parser_misc.c:331).
Read more
- apparmor.d(5), Capabilities.
- Rule conditionals: there are none here.
- allow and deny.
09 Privilege is one half
Capabilities filter privilege. Sockets, files and other objects have their own rules.
That's the capability rule: a list of names that filters what a task may use. Next door are the rules for the objects themselves, starting with network rules for demo's socket. Ptrace and rlimit rules each lean on a capability in one corner case. The qualifier decks cover deny and audit in full. And the practice deck shows how the shipped profiles of privileged programs use these lines.
Details and sources
Details
[QUALIFIERS] capability [NAME ...],: the task may use the named capabilities if it holds them.capability,names all of them.- A refused capability fails the call like a missing one and is logged with
operation="capable", at most once a second per capability; plaindenyis not logged. - 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), 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
CAPABILITY RULE: [QUALIFIERS] capability [NAME ...] , QUALIFIERS: [priority=N] [audit] [allow|deny|prompt]
- Names are separated by blanks and may continue on the next line. The comma ends the rule (tree).
capability,with no name means every capability (code).- Not allowed: permissions, conditionals, parentheses, quotes, variables, and the word
allas a name (tree). - The rule
all,includes every capability; see syn-all.
Capability names
The name is the kernel's constant in lower case without CAP_. "Back-map" is the capability the parser uses instead when the kernel feature set does not list the name (code; confirmed by a run of the tree's parser).
| Number | Name | Kernel constant | Back-map |
|---|---|---|---|
| 0 | chown | CAP_CHOWN | |
| 1 | dac_override | CAP_DAC_OVERRIDE | |
| 2 | dac_read_search | CAP_DAC_READ_SEARCH | |
| 3 | fowner | CAP_FOWNER | |
| 4 | fsetid | CAP_FSETID | |
| 5 | kill | CAP_KILL | |
| 6 | setgid | CAP_SETGID | |
| 7 | setuid | CAP_SETUID | |
| 8 | setpcap | CAP_SETPCAP | |
| 9 | linux_immutable | CAP_LINUX_IMMUTABLE | |
| 10 | net_bind_service | CAP_NET_BIND_SERVICE | |
| 11 | net_broadcast | CAP_NET_BROADCAST | |
| 12 | net_admin | CAP_NET_ADMIN | |
| 13 | net_raw | CAP_NET_RAW | |
| 14 | ipc_lock | CAP_IPC_LOCK | |
| 15 | ipc_owner | CAP_IPC_OWNER | |
| 16 | sys_module | CAP_SYS_MODULE | |
| 17 | sys_rawio | CAP_SYS_RAWIO | |
| 18 | sys_chroot | CAP_SYS_CHROOT | |
| 19 | sys_ptrace | CAP_SYS_PTRACE | |
| 20 | sys_pacct | CAP_SYS_PACCT | |
| 21 | sys_admin | CAP_SYS_ADMIN | |
| 22 | sys_boot | CAP_SYS_BOOT | |
| 23 | sys_nice | CAP_SYS_NICE | |
| 24 | sys_resource | CAP_SYS_RESOURCE | |
| 25 | sys_time | CAP_SYS_TIME | |
| 26 | sys_tty_config | CAP_SYS_TTY_CONFIG | |
| 27 | mknod | CAP_MKNOD | |
| 28 | lease | CAP_LEASE | |
| 29 | audit_write | CAP_AUDIT_WRITE | |
| 30 | audit_control | CAP_AUDIT_CONTROL | |
| 31 | setfcap | CAP_SETFCAP | |
| 32 | mac_override | CAP_MAC_OVERRIDE | |
| 33 | mac_admin | CAP_MAC_ADMIN | |
| 34 | syslog | CAP_SYSLOG | |
| 35 | wake_alarm | CAP_WAKE_ALARM | |
| 36 | block_suspend | CAP_BLOCK_SUSPEND | |
| 37 | audit_read | CAP_AUDIT_READ | |
| 38 | perfmon | CAP_PERFMON | sys_admin |
| 39 | bpf | CAP_BPF | sys_admin |
| 40 | checkpoint_restore | CAP_CHECKPOINT_RESTORE | sys_admin |
Qualifiers on capability rules
| Seat | On a capability rule |
|---|---|
priority= | taken, without effect: deny is subtracted by the parser whatever the priorities (code) |
audit | taken: each use of an allowed capability is logged; with deny, the refusal is logged |
allow, deny, prompt | taken: allow is the default; deny removes the capability whatever else allows it and its refusals are not logged; prompt is stored as allow (code), see syn-prompt |
owner, other | refused: owner conditional not allowed on capability rules (tree) |
- In a block the same holds:
audit { capability chown, }works;owner { capability chown, }givesowner prefix not allowed on capability rules(tree).
What the kernel does
All statements in this section are from the kernel source (linux:security/apparmor/capability.c, linux:security/apparmor/lsm.c:167-211), not from a run.
1. The kernel's own capability check comes first. A task that does not hold the capability is refused there. 2. For a task whose label is not unconfined, AppArmor then tests the capability against each confined profile of the label. All of them must list it. 3. A capability that is not listed is refused: the hook returns EPERM and the system call returns its usual error for a missing capability. In complain mode it is allowed and logged.
capget(2)is filtered: the effective and permitted sets a confined task reads are intersected with what its profiles allow.- Checks that the kernel makes without auditing are answered in enforce mode without a record.
- A capability rule grants nothing, and it does not replace the
network, file or other rule for the same operation.
The log record
apparmor="DENIED" operation="capable" ... profile="demo" pid=7292 comm="demo" capability=23 capname="sys_nice"
- Layout from
libraries/libapparmor/testsuite/test_multi/testcase_dmesg_capability.in; the profile and command names are illustrative. - A refused capability is logged at most once a second per capability; the filter is per CPU and is reset by a different task (code).
- A capability refused by a plain
denyrule is not logged, unless the profile's audit mode isnoquietorall(code).
Errors and warnings
| Rule | Message |
|---|---|
capability CAP_NET_BIND_SERVICE, | Invalid capability CAP_NET_BIND_SERVICE. |
capability cap_chown, | Invalid capability cap_chown. |
capability net_bind_service, net_admin, | syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE |
capability (chown), | syntax error, unexpected TOK_OPENPAREN, expecting TOK_ID or TOK_END_OF_RULE |
capability @{caps}, | syntax error, unexpected TOK_SET_VAR, expecting TOK_ID or TOK_END_OF_RULE |
capability "chown", | Lexer found unexpected character: '"' (0x22) in state: INITIAL |
capability all, | syntax error, unexpected TOK_ALL, expecting TOK_ID or TOK_END_OF_RULE |
capability set=hup, | syntax error, unexpected TOK_CONDID, expecting TOK_ID or TOK_END_OF_RULE |
capability chown before } | syntax error, unexpected TOK_CLOSE, expecting TOK_ID or TOK_END_OF_RULE |
deny audit capability net_admin, | syntax error, unexpected TOK_AUDIT, expecting TOK_ID or TOK_MODE or TOK_SET_VAR |
owner capability chown, | owner conditional not allowed on capability rules |
owner { capability chown, } | owner prefix not allowed on capability rules |
| a feature set lists a known name at another position | warning feature capability 'NAME:N' does not equal expected M. Ignoring ... (code) |
All rows are from the tree's parser unless marked.
for AppArmor developers
Encoding
- Capability rules are not in the policydb. Each rule is a 64-bit mask;
block_rules::add_capabilitiesORs it intocaps.allow,caps.audit,caps.denyorcaps.quiet(parser/block_rules.cc:133-154). - Written per half (
parser/parser_interface.c:547-559):allow & ~deny,allowed & audit,deny & quiet, and a zero word; the upper halves follow incaps64. - The kernel unpacks them into
caps.allow,caps.audit,caps.quiet, with optionalcaps64andcapsx(linux:security/apparmor/policy_unpack.c:1254-1288);profile_capabletests one bit (linux:security/apparmor/capability.c:149-165). The policydb branch forAA_CLASS_CAP(capability.c:128-147) is not reachable with this parser. - Name table: 41 built-in rows (
parser/base_cap_names.h), checked at build time against the build host'slinux/capability.h(parser/Makefile:404-415); names fromcaps/maskof the kernel feature set and of the policy ABI are added at run time (parser/parser_misc.c:407-436). - Back-mapping:
parser/parser_yacc.y:1710-1714,parser/parser_misc.c:298-314.
for security researchers
Known discrepancies
None of these is taught as intended behaviour; the verdicts come from the review (sec-bugs).
- A feature set that names a capability unknown to the parser build moves the name table;
capability audit_control,then compiles to a bit that differs between runs, with exit status 0 (tree). - A capability known only from the policy ABI, not from the kernel feature set, compiles as
chown(tree). - The policydb branch of
aa_profile_capgetcovers only capabilities 0 to 31; it is not reachable with this parser (code, not run).
Roads from here
START HERE
- 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 names the capabilities
QUALIFIERS
- allow and deny — deny and why it is quiet
- The audit qualifier — audit on a capability and the one second repeat filter
- Qualifier blocks — one qualifier for several capability rules
- Rule priority — priority is accepted here and has no effect
RULE CLASSES
- Network rules — the socket rule a privileged port also needs
- Ptrace rules — sys_ptrace as the fallback when ptrace rules are not mediated
- rlimit rules — sys_resource and other tasks' limits
- The all rule — the rule that includes every capability
IN PRACTICE · security-sensitive programs
- Profiles for security-sensitive programs — capabilities in shipped profiles of privileged programs
RUNNING THE PARSER
- Reading a denial — reading the capable record
IN THE KERNEL
- How a denial is logged (no slides yet) — how the kernel builds the record