Rule priority
rule precedence for application developers
priority=N ranks a rule from -1000 to 1000 with 0 as the default. For each permission the rule with the highest priority decides and at equal priority deny beats allow. Priorities are resolved by the parser and are not part of the compiled policy.
On the map: qualifiers
▶ Watch this deck — 8 scenes, ~6 min
Worth seeing first
- allow and deny — deny beats allow, the default that priority overrides
Part of journeys
- File access in depth, step 11 of 12 · previous: allow and deny · next: The limits of name-based mediation
- How a rule becomes a permission, step 8 of 12 · previous: The audit qualifier · next: Permissions in the DFA
01 Deny the directory, allow one file in it
priority=N in front of a rule makes it outrank rules with a lower number. A higher-priority allow overrides a deny.
Suppose an abstraction you include denies reading everything under demo's configuration directory, and demo needs one file from it, override.conf. So you add an allow rule for that file. And nothing changes. When an allow and a deny meet on the same file, the deny wins. That's a good default, and right now it's in your way. Priority is the way out. Write priority=10 in front of the allow, and for that one file the allow decides. Everything else in the directory stays denied. It's the shape of line 28 in the example profile.
Details and sources
Details
- Syntax:
priority=Nin front of a rule, as inpriority=10 allow /etc/demo/override.conf r,. A rule without it has priority 0. - Without a priority, both rules on the slide have priority 0, and at equal priority a deny beats an allow for the same permission: see allow and deny.
- The pair
deny /etc/demo/** r,andpriority=10 allow /etc/demo/override.conf r,was run through the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all -D rule-exprs -D dfa-states-initial, nothing loaded into a kernel). The state reached by/etc/demo/override.confis(0x 10004/0//0/0/0): read allowed, nothing denied, nothing quieted. Every other name under/etc/demo/reaches(0x 0/10004//0/0/10004): read denied and quiet. - The tuples read
(allow/deny//prompt/audit/quiet);0x10004isrfor the owner half and the other half together. - The allow wins only for
override.confand only forr, the permission it names. The deny keeps deciding every other file in the directory. - The line is line 28 of the map's example profile. In that profile it sits next to
/etc/demo/** r,on line 25; the deny on this slide stands for one that arrives through an included abstraction. - The program
demo, its files and its profile are invented for the map. Nothing on this slide was observed on a running kernel.
Read more
- apparmor.d(5), priority.
- allow and deny: the default order that priority overrides.
- Globbing: the overlapping patterns that make two rules meet on one file.
for AppArmor developers for security researchers
In the code
- The grammar reads the value and checks the range at parser_yacc.y:677-691.
- The deny is outranked in
pri_update_perm: its score for the read bit,0*4 + 3 = 3, is lower than the allow's10*4 + 1 = 41, so the deny node is skipped for that bit (hfa.cc:1536-1560).
02 priority=N, the first seat
priority=N RULE, with N from -1000 to 1000; the default is 0. priority is the first qualifier.
Priority takes the first seat, in front of audit and the access type. You write the word priority, an equals sign and a whole number, anywhere from -1000 to 1000. A rule without it has priority zero, so there's room on both sides: raise the rule that should win, or lower the one that should lose. The numbers mean nothing by themselves. Only their order counts. A plus or minus sign is fine, and so are spaces around the equals sign. And whatever else the rule carries, priority goes first.
Details and sources
Details
- Form:
priority=N RULE,where N is an optional+or-followed by digits. - Range: -1000 to 1000 inclusive. Default: 0.
- Position: first of the four qualifier seats, in the fixed order
priority=N,audit,allow | deny | prompt,owner | other. Each seat is optional. - White space around
=is allowed.priority = -5 /a r,andpriority=+5 /b r,were accepted by the parser built from the AppArmor tree at 836052d21. prioritymust be followed by=; white space in between is allowed. Without the=it is still the keyword:priority /a r,givessyntax error, unexpected TOK_ID, expecting TOK_EQUALS(run with the tree's parser).- Only the order of the numbers matters:
priority=1against 0 behaves likepriority=1000against 0. - The two examples on the number line are the rules of the scenes before and after this one.
Read more
- apparmor.d(5), priority and apparmor.d(5), Rule Qualifiers.
- allow and deny, audit, prompt, owner, other: the other three seats.
- The syntax map.
for AppArmor developers for security researchers
In the code
opt_priority: empty gives 0; otherwiseTOK_PRIORITY TOK_EQUALS TOK_VALUE, converted withstrtoland checked against the bounds (parser_yacc.y:677-691).opt_prefix: opt_priority opt_audit_flag opt_rule_mode opt_owner_flagfixes the order (parser_yacc.y:705-711).- The scanner rule is
priority/{WS}*=, with trailing context, and it pushes the stateINTEGER_MODE(parser_lex.l:428-432). That state accepts=and anINTEGER, defined as[+-]?{NUMBER}(parser_lex.l:292, parser_lex.l:697-704). MIN_POLICY_PRIORITYis -1000 andMAX_POLICY_PRIORITYis 1000 (immunix.h:198-199).
03 A broad deny that gives way
A deny with a negative priority loses to every default-priority allow and still applies where no allow matches.
Priorities go down as well as up. A negative priority makes a rule weaker than every ordinary rule. Here's a catch-all: deny writing anywhere, at priority minus one. It's a plain deny, so its refusals are marked quiet, and that's the reason to write it. And because it sits below zero, any ordinary allow rule beats it. Demo's state directory stays writable. Where no allow matches, the password file for one, the deny is the only rule and it applies. Take the priority away, and the same deny overrides the state rule: demo couldn't write its own state.
Details and sources
Details
- A negative priority puts a rule below every rule that has no
priority=, because those have priority 0. - Run with the parser built from the AppArmor tree at 836052d21:
/a* rw,withpriority=-1 deny /** w,. Names matching/a*reach the state(0x 3800e/0//0/0/0): read and write allowed. Other names reach(0x 0/2800a//0/0/2800a): write and append denied, and quiet. - The slide uses the same shape with demo's paths (
/var/lib/demo/** rw,in place of/a* rw,). That pair gives the same two states with the same parser. win a file rule carries the append permission with it, which is why the deny mask is0x2800aand not only the write bit.- Without
priority=-1the two rules have equal priority and the deny wins the write permission everywhere it matches, including under/var/lib/demo/. This is the equal-priority case of allow and deny (with the parser built from the tree,/a rw, deny /a w,gives(0x 10004/2800a//0/0/2800a)). - "Quietly": a plain
denymarks its permissions quiet in the compiled policy. In the kernel a refused request whose denied permissions are all quiet returns the error without a log record (file.c:95-154, read and not run).priority=-1 audit deny /** w,would log the refusals. - The parser's own tests use the shape:
priority=-1 deny /usr/bin/foo r,(ok_deny_2.sd). Another test states thataudit deny /[^a]* rwxlk, /a r,andpriority=-1 audit deny /* rwxlk, /a r,compile to the same binary policy (equality.sh:1926-1928): the lowered deny replaces a hand-written carve-out pattern. /etc/passwdstands for any file no allow rule matches.
Read more
- apparmor.d(5), priority and apparmor.d(5), deny.
- allow and deny: why a plain deny is quiet.
- audit:
audit denybrings the record back. - Globbing: writing the carve-out as a pattern instead.
04 Priority works one permission at a time
priority=1 /f r, with /f w, allows rw: a higher-priority rule overrides lower rules only for the permissions it names.
It's tempting to think the highest priority rule replaces every other rule for a file. It doesn't. The contest is held separately for each permission. Here a priority one rule grants read on demo's state file, and an ordinary rule grants write on it. Read is decided by the first rule. That rule says nothing about write, so the second rule decides write. The result is read and write. The manual says higher priority rules completely override lower ones where they overlap. In the code, overlap means the same permission on the same name. Against a deny for read and write, a priority one read wins back only read.
Details and sources
Details
- The comparison is made per permission and per name. A rule takes part only for the permissions it names.
- Run with the parser built from the AppArmor tree at 836052d21:
priority=1 /a r,with/a w,gives the state(0x 3800e/0//0/0/0)for/a: read, write and append allowed. The slide shows the same pair on/var/lib/demo/state, which gives the same state. - Run the same way:
priority=1 /x r,withdeny /x rw,gives(0x 10004/2800a//0/0/2800a)for/x: read allowed; write and append denied and quiet. - Format
(allow/deny//prompt/audit/quiet). Per halfx 0x1, w 0x2, r 0x4, a 0x8; the other half is shifted left by 14, soris0x10004,wwith its implied append is0x2800aandrwis0x3800e. - The manual page, apparmor.d(5), says: "Rules with higher priority are given preferences and will completely override permissions of lower priority rules where they overlap" (apparmor.d.pod:2540-2548). What the code does is narrower than a reader may take from "completely": the override applies to a permission the higher rule names, on a name both rules match. This deck teaches what the code does.
- The same holds for audit: with the parser built from the tree,
priority=1 /a r, audit /a rw,allows read and write and audits only write and append. See audit.
Read more
- apparmor.d(5), priority: the wording on rules that overlap partly.
- AppArmor wiki: rule prefixes and modes.
- Access modes: the permission letters.
- audit: a priority rule taking the audit away for one permission.
for AppArmor developers for security researchers
In the code
- Only the bits in a node's
perms | auditare visited when a state's permissions are built (hfa.cc:1680-1694), so a node cannot affect a bit it does not carry. - Per bit: a lower score is skipped, a higher one clears the bit and then applies the node (hfa.cc:1556-1582).
05 The full order: priority first, then deny, allow, prompt
Per permission: the highest priority wins; at equal priority deny > allow > prompt. The winning rule also sets audit and quiet for that permission.
Here's the whole ordering in one picture. Think of a ladder. The big steps are priorities. Inside each priority there are three small steps: deny on top, then allow, then prompt. For each permission, the rule standing highest decides. So a deny at priority zero beats an allow at priority zero, loses to anything at priority one, and beats everything at minus one. And the winner takes everything for that permission, including whether it's audited or kept quiet. When an audited allow at priority five wins, the lower deny's silence goes with it.
Details and sources
Details
- For one permission on one name, the deciding rule is found in this order:
- the highest
priority; - at equal priority: deny, then allow, then prompt.
- Rules on the same rung (same priority, same kind) add up: their permissions and their audit marks accumulate.
- The winner replaces what lower rules set for that permission in all five places: allow, deny, prompt, audit and quiet. A higher-priority allow therefore also removes the quiet of a lower deny, and a higher-priority rule without
auditremoves the audit of a lower rule. - The three rules on the slide are a worked example from the research notes, there with the path
/a:priority=-1 /a r, deny /a r, priority=5 audit /a r,gives the state(0x 10004/0//0/10004/0)with the parser built from the tree: read allowed and audited, no deny, no quiet. - One more rung exists for the exec permission only: a rule whose path has no wildcards ranks between deny and allow when it carries
x. That is how an exact path settles two different exec modes; see exec modes. - The ladder is per profile. Each profile is compiled on its own and priorities exist only inside that compilation, so they do not rank the profiles of a stack against each other. See stacking.
- Prompt: in mainline Linux prompt permissions are unpacked but not acted on; see prompt and upstream and Ubuntu.
Read more
for AppArmor developers for security researchers
In the code
- The kind is added to the scaled priority at hfa.cc:1536-1554: deny 3, exact-match node on an exec bit 2, allow 1, prompt 0.
- Scores for the read bit in the example:
-1*4 + 1 = -3, then0*4 + 3 = 3, then5*4 + 1 = 21. perms_t::clear_bitsclears allow, deny, prompt, audit and quiet for the bit (hfa.h:74-81).
06 priority*4 + kind, per bit for AppArmor developers for security researchers
Per bit, priority*4 + kind (parser/libapparmor_re/hfa.cc:1536-1554); lower scores are skipped, higher ones replace (:1556-1582). Priorities are not in the compiled policy.
The priority travels with the rule into every add_rule call and becomes part of the accept node. When the subset construction builds a state, pri_update_perm visits each permission bit a node names. The node's score is its priority times four plus its kind: three for deny, two for an exact match exec rule, one for allow, zero for prompt. A score below the bit's register is skipped. A higher one clears that bit in all five words and takes over. Equal scores add up. After this the priority is dropped: the compiled policy doesn't hold it. The parser's own class marker rules use 1001, above any profile.
Details and sources
for AppArmor developers for security researchers
Details
- The value is stored on the rule:
prefixes.priorityfor rule objects (rule.h:240-243) andcod_entry.priorityfor file rules (parser.h:140-141). - It is passed to every
add_ruleandadd_rule_veccall (file rules: parser_regex.c:675-688) and becomes part of the accept node:UniquePermis{ priority, mode, exact_match, perms, audit }(aare_rules.h:77-81). - Accept node classes, each constructed with the priority:
MatchFlag,ExactMatchFlag,DenyMatchFlag,PromptMatchFlag(expr-tree.h:1150-1201). An allow rule whose pattern has no wildcards gets anExactMatchFlag(aare_rules.cc:98-110); it scores as an allow except on exec bits. perms_t::perms_tgives each of the 32 bits a score register starting atMIN_INTERNAL_PRIORITY*4, which is -4004, and callspri_update_permfor every bit in a node'sperms | audit(hfa.cc:1661-1694).pri_update_perm(hfa.cc:1529-1653):- score:
priority << 2, plus 3 for a deny node, 2 for an exact-match node on an exec bit, 1 for any other node that is not a prompt node, 0 for a prompt node (lines 1536-1554); - register higher than the score: return, the node is skipped for this bit (1556-1560);
- register lower: store the score and
clear_bitsfor the bit, which clears allow, deny, prompt, audit and quiet (1575-1582); - then apply the node: a deny node sets deny and quiet and clears allow, audit and prompt (1585-1605); an allow node sets allow and audit (1626-1639); a prompt node sets prompt and audit (1640-1650).
- The comment at lines 1542-1543: "this is the last use of priority, it is dropped and not used in the backend". No priority is written into the compiled policy, and the AppArmor code of the kernel has no field for one (searched, not run).
- The slide's trace is the pair
priority=1 /x r,anddeny /x rw,. The resulting state(0x 10004/2800a//0/0/2800a)is from a run of the parser built from the AppArmor tree at 836052d21; the per-bit steps are read from the code. The slide shows four of the 32 bits and one of the two halves. MIN_INTERNAL_PRIORITYis -1001 andMAX_INTERNAL_PRIORITYis 1001 (immunix.h:201-207). The rules that mark a class as mediated are added withmediates_priority = MAX_INTERNAL_PRIORITY, so that no rule from a profile, in particular no deny, can remove them (parser_regex.c:1359-1372).-D dfa-perms-buildprints the comparisons while states are built (theDUMP_DFA_PERMSoutput in the same function).
Read more
- AppArmor wiki: TechnicalDoc_HFA_permissions: how permissions are encoded on accept states.
- apparmor.d(5), priority.
- Permissions in the compiled policy.
- The DFA and its states.
- How deny is compiled.
07 Where priority is refused or ignored
Range -1000 to 1000 ("invalid priority N > 1000"). Not allowed on blocks, network rules and all rules. Known limitation: accepted and ignored on capability rules.
The range is checked: 1001 is an invalid priority. A block in braces can't carry a priority. Network rules refuse it, and so does the all rule. And it has to come first: put audit ahead of it and you get a syntax error. Then a known limitation that doesn't complain at all. Capability rules accept a priority and, at this version, ignore it. So don't count on priority to make a capability allow beat a capability deny. If an override doesn't seem to work, check that both rules are of a kind that supports priority, and that they really name the same permission.
Details and sources
Details
- A parser error has the form
AppArmor parser error for FILE in profile FILE at line N: MESSAGE. The slide showsMESSAGE. - Run with the parser built from the AppArmor tree at 836052d21, each line inside a profile:
priority=1001 /etc/demo/** r,:invalid priority 1001 > 1000.priority=1 { /etc/demo/** r, }:priority is not allowed on rule blocks.priority=1 network inet,:priority prefix not allowed on network rules.audit priority=1 /etc/demo/** r,:syntax error, unexpected TOK_PRIORITY, expecting TOK_ID or TOK_MODE or TOK_SET_VAR.- The
allrule: the message in the parser source ispriority prefix not allowed on all rules(run as above withpriority=1 all,). - Capability rules. The pair
priority=1 capability chown,anddeny capability chown,is accepted without a message (run as above). The pair compiles to the same binary asdeny capability chown,alone (run): capabilities are kept as an allow set and a deny set and do not go through the per-permission comparison, and the check that would reject the prefix is commented out, with the note "priority is not supported on capability rules but this is currently not enforced". A denied capability stays denied. - Rule classes that accept a priority (the parser built from the tree accepts one rule of each): file, link, change_profile, signal, ptrace, mount, dbus, unix, userns, io_uring, mqueue. For unix rules the source says "partially supported": rules that are downgraded to plain socket mediation lose it.
- Known discrepancies, listed as such and not taught as intended behaviour (see the reference below):
- A value below the range is reported with the wrong sign:
priority=-1001 /a r,printsinvalid priority -1001 > -1000(run as above). priority=abcprints onlyflex scanner jammedand exits with status 2, with no file name or line (run as above).- A rule other than a file rule that carries a priority is refused inside any block with
priority levels not supported, while the same rule is accepted outside the block and file rules are accepted in both places. See qualifier blocks.
for security researchers
Attack surface
- A priority can undo a denial from another file.
priority=1on an allow rule in any included file overrides everydenyof lower priority for the same permission and name, so a review of what a profile denies has to read the priorities of every rule that can match, includes and abstractions too. - Priority exists only inside one profile's compilation: it is dropped once the states are built and is not written into the policy (hfa.cc:1542-1543). It cannot order the profiles of a stack or a parent against a child; each profile of a stacked label is still checked separately by the kernel.
- On capability rules
priority=is accepted and ignored, with no message:priority=1 capability chown,withdeny capability chown,compiles to the same binary as the deny alone (run with the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel; block_rules.cc:133-138). Here the failure is closed; a reader of the profile may think otherwise. - User priorities are limited to -1000..1000 so that they stay below the parser's own class-marker rules at 1001 (parser_regex.c:1359-1372). The comment there records that parsers without priority support had a deny rule able to wipe out the marker for dbus rules.
Read more
for AppArmor developers for security researchers
In the code
- Range check and both messages: parser_yacc.y:683-689. The lower-bound line reuses the format
"invalid priority %ld > %d". - Blocks: block.h:46-51. Network rules: network.h:269-273. The
allrule: all_rule.h:46-50. - Capabilities: block_rules.cc:133-138, block_rules.h:61-66.
- Unix rules: af_unix.h:52-55.
- A priority on a rule inside a block: rule objects fail in
prefix_rule_t::add_prefixwhen their own priority is not 0 (rule.h:385-395); file rules go throughgeneric_add_prefix, which has no such test (parser_misc.c:1121-1122). INTEGER_MODEhas rules only for=and an integer (parser_lex.l:697-704) and is not in the state list of the rule that reports an unexpected character (parser_lex.l:926-931).
08 Where to go from here
Next: syn-allow-deny, syn-prompt, syn-audit, syn-exec-modes, syn-qualifier-blocks, re-perms.
Remember the ladder: priority first, then deny over allow over prompt, and all of it one permission at a time. Use it sparingly. A profile that needs many priorities is hard to read, and often a narrower pattern is the better fix. From here, allow and deny covers the equal priority case, and prompt the lowest rung. The audit deck shows how the winning rule also controls logging. Exec modes shows priority settling two exec modes on one path. Qualifier blocks covers priority and blocks. And the compiler decks show the states where overlapping rules meet.
Details and sources
Details
priority=N, N from -1000 to 1000, default 0, first qualifier.- Per permission and per name: the highest priority decides; at equal priority deny, then allow, then prompt; rules of equal rank add up.
- The winning rule also decides audit and quiet for that permission.
- Priorities are resolved by the parser inside one profile. They are not part of the compiled policy.
- Not accepted on blocks,
networkrules andallrules; accepted and ignored oncapabilityrules (a known limitation). - Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825).
Read more
Basis of the statements on this page: "tree" means the parser built from the AppArmor commit 836052d21 (6.0.0~alpha2) was run on the fragment (-Q -K --skip-kernel-load --warn=all, with -D rule-exprs -D dfa-states-initial for state dumps), with nothing loaded into a kernel; "code" means the parser source, or the kernel source of mainline Linux 7.4, was read and not run; "derived" means the result was reasoned from that code. Nothing here was observed on a running kernel.
Grammar
RULE: [priority=N] [audit] [allow|deny|prompt] [owner|other] RULE , priority: 'priority' '=' N N: [+-]? digits -1000 <= N <= 1000, default 0
priority=Nis the first qualifier (code).- White space around
=is allowed:priority = -5 /a r,andpriority=+5 /b r,are accepted (tree). prioritymust be followed by=, after optional white space. Without it the rule is a syntax error (tree).- The bounds are
MIN_POLICY_PRIORITY(-1000) andMAX_POLICY_PRIORITY(1000) (code). - Examples in the parser's tests:
parser/tst/simple_tests/file/priority/holds 81 files at this commit, for examplepriority=-1 deny /usr/bin/foo r,(ok_deny_2.sd), andbad_1.sdandbad_2.sdfor the two bounds.
Ordering rule
For one permission on one name, among the rules of one profile that match the name and carry the permission:
| Step | Rule |
|---|---|
| 1 | The highest priority decides. |
| 2 | At equal priority: deny, then allow, then prompt. |
| 2a | For the exec permission only, a rule whose path has no wildcards ranks between deny and allow. See syn-exec-modes. |
| 3 | Rules of equal priority and equal kind accumulate. |
| 4 | The deciding rule sets allow, deny or prompt and also audit and quiet for that permission. What lower rules set for it is cleared. |
- A rule takes part only for the permissions it names. A higher-priority rule does not remove permissions it does not name (code; tree for
priority=1 /a r, /a w,). - All of this is from the parser source; the rows of the next table show it on single names.
Worked examples
State reached by the path /a unless a column says otherwise, format (allow/deny//prompt/audit/quiet). Per half x 0x1, w 0x2, r 0x4, a 0x8; the other half is shifted left by 14, so r for both halves is 0x10004, w with its implied append is 0x2800a and rw is 0x3800e.
| Rules | State | Meaning | Basis |
|---|---|---|---|
/a rw, deny /a w, | (0x 10004/2800a//0/0/2800a) | read allowed; write denied and quiet | tree |
priority=1 /a rw, deny /a w, | (0x 3800e/0//0/0/0) | read and write allowed; nothing quiet | tree |
priority=1 /a rw, priority=1 deny /a w, | (0x 10004/2800a//0/0/2800a) | both raised: as the first row | tree |
/a* rw, priority=-1 deny /** w, | /a*: (0x 3800e/0//0/0/0); other names: (0x 0/2800a//0/0/2800a) | the lowered deny applies only where no allow matches | tree |
priority=-1 /a r, deny /a r, priority=5 audit /a r, | (0x 10004/0//0/10004/0) | allowed and audited; the deny and its quiet are gone | tree |
priority=1 /a r, /a w, | (0x 3800e/0//0/0/0) | read from the first rule, write from the second | tree |
priority=1 /a r, audit /a rw, | (0x 3800e/0//0/2800a/0) | read and write allowed; only write and append audited | tree |
prompt /a rw, /a r, | (0x 10004/0//2800a/0/0) | allow beats prompt for read | tree |
priority=1 prompt /a rw, /a r, | (0x 0/0//3800e/0/0) | the raised prompt takes read as well | tree |
prompt /a rw, deny /a w, | (0x 0/2800a//10004/0/2800a) | deny beats prompt for write | tree |
priority=10 allow /etc/demo/override.conf r, deny /etc/demo/** r, | override.conf: (0x 10004/0//0/0/0); other names under /etc/demo/: (0x 0/10004//0/0/10004) | one file lifted out of a denied directory | tree |
priority=1 /x r, deny /x rw, | /x: (0x 10004/2800a//0/0/2800a) | read allowed; write and append denied and quiet | tree |
- All states are shown before the parser's deny filtering, which zeroes the deny word in the output: see syn-allow-deny.
- Prompt rows: in mainline Linux 7.4 the prompt permissions are not in the allow set and are not acted on, so those requests are denied and logged (code). See syn-prompt and upstream-and-ubuntu.
- Quiet: in mainline Linux 7.4 a refused request whose denied permissions are all quiet returns the error without a log record (code). See syn-audit.
Where priority is accepted
| Rule class | Behaviour | Basis |
|---|---|---|
| file, link | accepted | tree |
| change_profile, signal, ptrace, mount, dbus, userns, io_uring, mqueue | accepted | tree, one rule of each |
| unix | accepted; "partially supported": rules downgraded to plain socket mediation lose the priority | tree for acceptance; code for the rest |
capability | accepted and ignored (known limitation) | tree: accepted, and priority=1 capability chown, with deny capability chown, compiles to the same binary as the deny alone |
network | refused: priority prefix not allowed on network rules | tree |
all | refused: priority prefix not allowed on all rules | tree |
a block priority=N { ... } | refused: priority is not allowed on rule blocks | tree |
| a file rule with a priority inside a block | accepted: owner { priority=1 /a r, } | tree |
| any other rule with a priority inside a block | refused: priority levels not supported (see Known discrepancies) | tree |
Scope
- Priorities are resolved by the parser while it compiles one profile. They decide which rule's permissions end up in a state (code).
- The compiled policy holds no priority. The AppArmor code of mainline Linux 7.4 has no field for one (code).
- Each profile is compiled on its own, so priorities do not order the profiles of a stack, a parent and its child profiles, or a profile and its hats (derived).
- Rules from an included file take part like rules written in the profile: an abstraction's deny at priority 0 is outranked by the profile's
priority=1allow (derived). - The parser's own rules that mark a class as mediated use priority 1001, one above the highest value a profile can write (code).
Errors and warnings
The full form of a parser error is AppArmor parser error for FILE in profile FILE at line N: MESSAGE (tree). The table gives MESSAGE.
| Message | Example | When |
|---|---|---|
| invalid priority 1001 > 1000 | priority=1001 /etc/demo/** r, | N above 1000; the format is invalid priority %ld > %d (tree) |
| invalid priority -1001 > -1000 | priority=-1001 /a r, | N below -1000; the sign in the message is wrong (tree; see Known discrepancies) |
| invalid priority %s | none found | present in the parser source; cannot be reached, because the scanner passes only integers (code; see Known discrepancies) |
| priority is not allowed on rule blocks | priority=1 { /etc/demo/** r, } | a priority on a block (tree) |
| priority prefix not allowed on network rules | priority=1 network inet, | a priority on a network rule (tree) |
| priority prefix not allowed on all rules | priority=1 all, | a priority on an all rule (tree) |
| priority levels not supported | audit { priority=1 signal, } | a rule other than a file rule that has a priority, inside any block (tree) |
| syntax error, unexpected TOK_PRIORITY, expecting TOK_ID or TOK_MODE or TOK_SET_VAR | audit priority=1 /etc/demo/** r, | priority=N after another qualifier (tree) |
| syntax error, unexpected TOK_ID, expecting TOK_EQUALS | priority /a r, | the word priority without = (tree) |
| flex scanner jammed | priority=abc /foo r, | anything but = and an integer after priority; exit status 2, no file or line (tree; see Known discrepancies) |
Known discrepancies
These are differences between the documentation, the messages and the behaviour, listed as such. They are not taught as intended behaviour. They are on the AppArmor bug sweep list under the same titles; see also sec-bugs.
- Lower bound reported with ">". A value below -1000 prints
invalid priority -1001 > -1000(tree). The lower-bound check reuses the upper-bound format string (code). - "flex scanner jammed".
priority=abc /foo r,prints onlyflex scanner jammed, with exit status 2 and no file name or line number (tree). The scanner state entered afterpriorityhas rules only for=and an integer and is missing from the rule that reports unexpected characters (code). As a consequence the grammar's owninvalid priority %scannot be reached. - Priority inside blocks differs by rule class. Inside any block, including a bare
{ }, a rule other than a file rule that carries a priority fails withpriority levels not supported:audit { priority=1 signal, }and{ priority=1 signal, }are refused, whilepriority=1 signal,outside a block,owner { priority=1 /a r, }andaudit { priority=5 /etc/demo/override.conf r, }are accepted (tree). The refusal may be deliberate for now; the difference between file rules and the other classes is the discrepancy. See syn-qualifier-blocks. - Capability rules ignore priority.
priority=1 capability chown,is accepted (tree) and the priority has no effect (code): withdeny capability chown,in the same profile the capability is denied. The source says "priority is not supported on capability rules but this is currently not enforced", so this is known to the authors. - The manual page says "completely override". apparmor.d(5): rules with higher priority "will completely override permissions of lower priority rules where they overlap". The code overrides per permission:
priority=1 /a r, /a w,allowsrw(tree).
for AppArmor developers for security researchers
Code map
| What | Where |
|---|---|
opt_priority: value, range check, messages | parser_yacc.y:677-691 |
opt_prefix: the order of the four qualifiers | parser_yacc.y:705-711 |
scanner: priority/{WS}*=, INTEGER, INTEGER_MODE | parser_lex.l:428-432, parser_lex.l:292, parser_lex.l:697-704 |
scanner: the catch-all rules without INTEGER_MODE, and the comment naming "flex scanner jammed" | parser_lex.l:919-931, parser_lex.l:328-329 |
MIN_POLICY_PRIORITY, MAX_POLICY_PRIORITY, MIN_INTERNAL_PRIORITY, MAX_INTERNAL_PRIORITY | immunix.h:198-207 |
prefixes.priority | rule.h:240-243 |
cod_entry.priority | parser.h:140-141 |
prefix_rule_t::add_prefix: "priority levels not supported" | rule.h:385-395 |
generic_add_prefix (file rules in a block) | parser_misc.c:1121-1122 |
blocks, network rules, all rules: valid_prefix | block.h:46-51, network.h:269-273, all_rule.h:46-50 |
| capability rules: the check that is commented out | block_rules.cc:133-138, block_rules.h:61-66 |
| unix rules: "partially supported" | af_unix.h:52-55 |
file rules: priority passed to add_rule | parser_regex.c:675-688 |
UniquePermsCache::insert: the priority in the accept node | aare_rules.h:77-81 |
exact_match | aare_rules.cc:98-110 |
MatchFlag, ExactMatchFlag, DenyMatchFlag, PromptMatchFlag | expr-tree.h:1150-1201 |
pri_update_perm | hfa.cc:1529-1653 |
| score | hfa.cc:1536-1554 |
| lower score skipped | hfa.cc:1556-1560 |
| higher score clears the bit | hfa.cc:1575-1582 |
| deny, exact-match, allow, prompt branches | hfa.cc:1585-1650 |
perms_t::perms_t: registers start at -4004, loop over the bits | hfa.cc:1661-1694 |
perms_t::clear_bits | hfa.h:74-81 |
mediates_priority | parser_regex.c:1359-1372 |
| manual page text | apparmor.d.pod:2540-2548 |
| tests: fixtures | parser/tst/simple_tests/file/priority/, for example ok_deny_2.sd |
| tests: owner block keeps an inner priority on file rules | equality.sh:667-669 |
| tests: carve-out pattern equals a lowered deny | equality.sh:1926-1928 |
| kernel: quiet applied to a refused file request (mainline Linux 7.4) | file.c:95-154 |
Scores for the worked examples (priority*4 + kind): row 1, write bit: allow 1, deny 3. Row 2: allow 5, deny 3. Row 3: allow 5, deny 7. Row 4: allow 1, deny -1. Row 5, read bit: -3, 3, 21. Row 6: read 5, write and append 1. -D dfa-perms-build prints the comparisons while states are built.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
FILE ACCESS
- Exec modes — priority settles conflicting exec modes
- Globbing (AARE) — the overlapping patterns priority chooses between
QUALIFIERS
- allow and deny — what happens at equal priority
- The audit qualifier — a higher priority rule also decides what is audited
- The prompt qualifier — lifting a prompt above an allow
- Qualifier blocks — priority and blocks
THE DFA ENGINE · libapparmor_re
- Permissions in the DFA — where the scores are compared
- Building the DFA — the states that collect overlapping rules