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

01 demo wants a privileged port

CAPABILITY RULES demo runs as root bind(fd, port 80) the kernel does the task hold CAP_NET_BIND_SERVICE? yes does profile demo list net_bind_service? no bind() = -1 EACCES capability net_bind_service, line 10 of demo's profile with the rule: does profile demo list it? yes this check passes two checks, and both have to say yes
demo, running as root, calls bind for port 80. The kernel asks two questions: does the task hold CAP_NET_BIND_SERVICE, yes; does profile demo list net_bind_service, no, so bind fails with EACCES. With the rule capability net_bind_service in the profile the second answer is yes.

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 registers apparmor_capable for 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: EACCES for bind to a low port (af_inet.c:516-520).
  • The slide shows the capability check only. Listening on the port also needs a network rule; 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/mask lists 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 program demo and 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

GRAMMAR QUALIFIERScapabilityNAMENAME ..., capability net_bind_service,capability setuid setgid,capability, blanks between names, not commas no name: every capability names CAP_NET_BIND_SERVICE net_bind_service the kernel's name, lower case, without CAP_ 41 names, in the reference
The syntax diagram: optional qualifiers, the word capability, zero or more names, a comma. Three examples: one name, two names separated by a blank, and no name, which means every capability. A panel shows CAP_NET_BIND_SERVICE written as net_bind_service.

[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 rule all, 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).

for AppArmor developers for security researchers

In the code

03 The rule filters; it does not give

WHAT THE RULE DOES demo runs as user demo, holds no capabilities capability net_bind_service, bind(port 80) does the task hold it? no = -1 EACCES the profile cannot hand it out demo runs as root capability net_bind_service, network inet stream, not in the profile socket(AF_INET, SOCK_STREAM) = -1 EACCES the capability is not a network rule capability may use a privilege it holds network, file, ... may touch the object
Two experiments. Left: demo runs as an ordinary user without capabilities; the profile lists net_bind_service, but the task does not hold it and bind fails. Right: demo runs as root with the capability rule but no network rule; socket fails with EACCES. Capability rules cover privilege, other rules cover objects.

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 network rule refuses every socket; the caller sees EACCES. 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 (hook capget, 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

QUALIFIERS capability, demo may use all 41 deny capability sys_admin, all but sys_admin refused silently audit capability net_bind_service, net_bind_service: allowed, and logged when used audit deny capability sys_module, sys_module: refused, and the refusal is logged priority=1 capability chown, accepted; the priority is ignored owner capability chown, owner conditional not allowed on capability rules
Four capability rules and their effect: capability alone allows all 41; deny capability sys_admin removes one silently; audit capability net_bind_service logs each use; audit deny capability sys_module refuses and logs. Below, priority=1 is accepted and ignored, and owner is refused by the parser.

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, and allow / deny / prompt. The seat of owner and other is 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, } gives owner prefix not allowed on capability rules (block_rules.h:69). Block example: capability/ok_block1.sd.
  • deny audit capability ... is a syntax error: audit sits before deny.
  • 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

THE DENIAL demo setpriority(...) the kernel = -1 EACCES apparmor="DENIED" operation="capable" ... profile="demo"pid=7292 comm="demo" capability=23 capname="sys_nice" the word to put in the rule capability sys_nice, the rule that would allow it demo retries ten times in one second one record repeats within a second are not logged again no record does not mean allowed: a plain deny is quiet too
demo calls setpriority and gets EACCES. The log record has operation capable, capability 23 and capname sys_nice; the name is the word for the rule capability sys_nice. Ten retries in one second give one record. No record does not mean allowed.

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 before capname). The profile and command names are demo's; the values are illustrative.
  • capability=N comes from the common LSM audit code (lsm_audit.c:194); capname= is added by AppArmor (capability.c:47-53); the operation name is capable (audit.h:48).
  • The error demo sees is the system call's own, not the hook's EPERM: setpriority returns EACCES when 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 deny rule, unless the profile's audit mode is noquiet or all (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 type KILL.
  • Kernel statements are read from the kernel source and were not run.

06 Four masks, not rules for AppArmor developers for security researchers

IN THE PARSER capability chown kill,audit capability kill,deny capability sys_admin, block_rules::add_capabilities allow chown kill audit kill deny sys_admin quiet sys_admin serialised profile u32 allow & ~deny u32 allowed & audit u32 deny & quiet u32 0 caps64 { bits 32-63 } profile_capable() policydb mediates AA_CLASS_CAP? no: this parser does not emit it cap in caps.allow && !caps.denied ? 0 : -EPERM caps.denied and caps.kill are never assigned; deny was already subtracted by the parser
Three capability rules are ORed by block_rules::add_capabilities into four masks: allow, audit, deny, quiet. The serialised profile holds allow without deny, allowed and audited, deny and quiet, and a zero word, twice. In the kernel profile_capable finds that the policydb does not mediate the class and tests one bit.

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.quiet and a discarded one; then the optional caps64 with the upper halves; then the optional capsx into caps.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/extended and 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 byte cap >> 5, then bit cap & 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, and capability 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_capget loops over CAP_LAST_CAP >> 5 chunks, which is one, and shifts by i * 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

BACK-MAPPING capability perfmon, feature set lists perfmon caps/mask: ... perfmon bpf checkpoint_restore bit 38: perfmon feature set without perfmon caps/mask: ... sys_admin ... bit 21: sys_admin no warning capability perfmon, == capability sys_admin, byte-identical output deny capability perfmon, denies sys_admin three names have a back-map, all to sys_admin; the comparison uses the kernel's feature set, not the abi rule
The rule capability perfmon compiled for two kernels. Where the feature set lists perfmon it becomes bit 38, perfmon. Where it does not, it becomes bit 21, sys_admin, with no warning, byte-identical to capability sys_admin. A deny of perfmon then denies sys_admin.

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, bpf and checkpoint_restore, all to sys_admin (base_cap_names.h:9, base_cap_names.h:11, base_cap_names.h:47).
  • The kernel feature set is what --kernel-features names, or the running kernel's /sys/kernel/security/apparmor/features/caps/mask. The policy ABI of an abi rule is not consulted for this.
  • The bare capability, and all, set every bit regardless.
  • sys_admin is capability 21 (capability.h:281), perfmon 38 (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 from caps/mask of 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 a deny is wider too. A reviewer has to know the caps/mask of 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_control then 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.

for AppArmor developers for security researchers

In the code

08 Mistakes and their messages

MISTAKES capability CAP_NET_BIND_SERVICE, Invalid capability CAP_NET_BIND_SERVICE. capability net_bind_service, net_admin, syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE after the comma, net_admin is read as the start of a file rule 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 no variables deny audit capability net_admin, syntax error, unexpected TOK_AUDIT, expecting TOK_ID or TOK_MODE or TOK_SET_VAR audit sits before deny capability all, is an error too: write capability, with no name
Five refused capability rules with the message of the parser: the name written as CAP_NET_BIND_SERVICE; a comma between two names; parentheses; a variable; deny written before audit. A footnote: capability all is an error too.

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, gives Invalid capability cap_chown.; capability "chown", gives Lexer found unexpected character: '"' (0x22) in state: INITIAL; capability all, gives syntax error, unexpected TOK_ALL; capability set=hup, gives syntax error, unexpected TOK_CONDID.
  • A missing comma before } gives syntax error, unexpected TOK_CLOSE, expecting TOK_ID or TOK_END_OF_RULE.
  • capability ptrace trace, fails: ptrace is 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).

09 Privilege is one half

ROADS capability net_bind_service, a filter on privilege; objects have their own rules syn-allow-deny deny is quiet syn-audit logging uses syn-network the socket syn-ptrace falls back on sys_ptrace syn-rlimit sys_resource prac-privileged shipped profiles adm-denials the capable record syn-abi names the kernel knows
Capability rules in the centre with roads to syn-allow-deny and syn-audit, to syn-network, syn-ptrace and syn-rlimit, and to prac-privileged, adm-denials and syn-abi.

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; plain deny is 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 all as 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).

NumberNameKernel constantBack-map
0chownCAP_CHOWN
1dac_overrideCAP_DAC_OVERRIDE
2dac_read_searchCAP_DAC_READ_SEARCH
3fownerCAP_FOWNER
4fsetidCAP_FSETID
5killCAP_KILL
6setgidCAP_SETGID
7setuidCAP_SETUID
8setpcapCAP_SETPCAP
9linux_immutableCAP_LINUX_IMMUTABLE
10net_bind_serviceCAP_NET_BIND_SERVICE
11net_broadcastCAP_NET_BROADCAST
12net_adminCAP_NET_ADMIN
13net_rawCAP_NET_RAW
14ipc_lockCAP_IPC_LOCK
15ipc_ownerCAP_IPC_OWNER
16sys_moduleCAP_SYS_MODULE
17sys_rawioCAP_SYS_RAWIO
18sys_chrootCAP_SYS_CHROOT
19sys_ptraceCAP_SYS_PTRACE
20sys_pacctCAP_SYS_PACCT
21sys_adminCAP_SYS_ADMIN
22sys_bootCAP_SYS_BOOT
23sys_niceCAP_SYS_NICE
24sys_resourceCAP_SYS_RESOURCE
25sys_timeCAP_SYS_TIME
26sys_tty_configCAP_SYS_TTY_CONFIG
27mknodCAP_MKNOD
28leaseCAP_LEASE
29audit_writeCAP_AUDIT_WRITE
30audit_controlCAP_AUDIT_CONTROL
31setfcapCAP_SETFCAP
32mac_overrideCAP_MAC_OVERRIDE
33mac_adminCAP_MAC_ADMIN
34syslogCAP_SYSLOG
35wake_alarmCAP_WAKE_ALARM
36block_suspendCAP_BLOCK_SUSPEND
37audit_readCAP_AUDIT_READ
38perfmonCAP_PERFMONsys_admin
39bpfCAP_BPFsys_admin
40checkpoint_restoreCAP_CHECKPOINT_RESTOREsys_admin

Qualifiers on capability rules

SeatOn a capability rule
priority=taken, without effect: deny is subtracted by the parser whatever the priorities (code)
audittaken: each use of an allowed capability is logged; with deny, the refusal is logged
allow, deny, prompttaken: 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, otherrefused: owner conditional not allowed on capability rules (tree)
  • In a block the same holds: audit { capability chown, } works; owner { capability chown, } gives owner 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 deny rule is not logged, unless the profile's audit mode is noquiet or all (code).

Errors and warnings

RuleMessage
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 positionwarning 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_capabilities ORs it into caps.allow, caps.audit, caps.deny or caps.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 in caps64.
  • The kernel unpacks them into caps.allow, caps.audit, caps.quiet, with optional caps64 and capsx (linux:security/apparmor/policy_unpack.c:1254-1288); profile_capable tests one bit (linux:security/apparmor/capability.c:149-165). The policydb branch for AA_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's linux/capability.h (parser/Makefile:404-415); names from caps/mask of 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_capget covers only capabilities 0 to 31; it is not reachable with this parser (code, not run).

Roads from here

START HERE

PREAMBLE AND REUSE

QUALIFIERS

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

RUNNING THE PARSER

IN THE KERNEL