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

01 Deny the directory, allow one file in it

RULE PRIORITY deny /etc/demo/** r, from an abstraction you include allow /etc/demo/override.conf r, your exception demo /etc/demo/override.conf refused: deny wins both rules at priority 0 priority=10 /etc/demo/override.conf allowed priority 10 beats priority 0 /etc/demo/secret.key still denied and the rest of /etc/demo the example profile, line 28: priority=10 allow /etc/demo/override.conf r,
A profile fragment with deny /etc/demo/** r and allow /etc/demo/override.conf r. The program demo is refused the file override.conf because deny wins. With priority=10 in front of the allow rule the same file is allowed, and another file in the directory, secret.key, is still denied.

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=N in front of a rule, as in priority=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, and priority=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.conf is (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); 0x10004 is r for the owner half and the other half together.
  • The allow wins only for override.conf and only for r, 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

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's 10*4 + 1 = 41, so the deny node is skipped for that bit (hfa.cc:1536-1560).

02 priority=N, the first seat

GRAMMAR priority=N audit allow deny prompt owner | other RULE , 1: priority 2 3 4 -1000 1000 0 a rule without priority= raise the rule that should win priority=10 allow /etc/demo/override.conf r, lower the one that should lose priority=-1 deny /** w, priority = -5 /a r, priority=+5 /b r, a sign and spaces around = are accepted priority=1 audit deny owner /var/lib/demo/** w, whatever else is there, priority goes first
Syntax diagram of the four qualifier seats in fixed order: priority=N highlighted in first place, then audit, the access type allow, deny or prompt, and owner or other, followed by the rule. A number line from -1000 to 1000 with the default 0 in the middle, a rule lowered to -1 on the left and a rule raised to 10 on the right. Examples with a sign and with spaces around the equals sign.

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, and priority=+5 /b r, were accepted by the parser built from the AppArmor tree at 836052d21.
  • priority must be followed by =; white space in between is allowed. Without the = it is still the keyword: priority /a r, gives syntax error, unexpected TOK_ID, expecting TOK_EQUALS (run with the tree's parser).
  • Only the order of the numbers matters: priority=1 against 0 behaves like priority=1000 against 0.
  • The two examples on the number line are the rules of the scenes before and after this one.

for AppArmor developers for security researchers

In the code

03 A broad deny that gives way

priority=-1 priority=-1 deny /** w, a catch-all: no writes anywhere, and no log noise /var/lib/demo/** rw, /var/lib/demo/state write allowed: priority 0 beats -1 /etc/passwd write denied, quietly only the deny matches without priority=-1: deny /** w, /var/lib/demo/** rw, demo could not write its own state at equal priority deny beats allow the parser's own tests use this shape: priority=-1 deny /usr/bin/foo r,
A profile fragment: priority=-1 deny /** w and /var/lib/demo/** rw. Writing /var/lib/demo/state is allowed because priority 0 beats -1. Writing /etc/passwd is denied quietly because only the deny matches. Without priority=-1 the deny would also stop demo writing its own state.

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, with priority=-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.
  • w in a file rule carries the append permission with it, which is why the deny mask is 0x2800a and not only the write bit.
  • Without priority=-1 the 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 deny marks 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 that audit deny /[^a]* rwxlk, /a r, and priority=-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/passwd stands for any file no allow rule matches.

Read more

04 Priority works one permission at a time

PER PERMISSION /var/lib/demo/state r w priority=1 /var/lib/demo/state r, r priority 1 /var/lib/demo/state w, w priority 0 the priority 1 rule says nothing about w, so it does not take w away result: r and w allowed the manual: higher priority rules "completely override" lower ones where they overlap the code: overlap = the same permission on the same name priority=1 /x r, deny /x rw, r allowed: the priority 1 rule names r w denied: only the deny names w
Two rules for the file /var/lib/demo/state: priority=1 with r and a plain rule with w. The r permission is decided by the priority 1 rule, the w permission by the priority 0 rule, and the result is r and w. A second example, priority=1 /x r with deny /x rw, allows r and denies w.

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, with deny /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 half x 0x1, w 0x2, r 0x4, a 0x8; the other half is shifted left by 14, so r is 0x10004, w with its implied append is 0x2800a and rw is 0x3800e.
  • 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

for AppArmor developers for security researchers

In the code

  • Only the bits in a node's perms | audit are 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

WHO DECIDES priority 1 priority 0 priority -1 higher decides the default deny allow prompt deny allow prompt deny allow prompt deny /f r, priority=-1 /f r, beats everything below it outranked the winner also decides audit and quiet for that permission allow priority=5 audit /f r, priority 5 decides: allowed, and audited outranked now: its quiet goes too
A ladder with a band for each priority, 1, 0 and -1, and three rungs in each band: deny on top, then allow, then prompt. The rule deny /f r stands on the deny rung of priority 0 and priority=-1 /f r on the allow rung of priority -1. The rule priority=5 audit /f r stands above all of them and decides: the read is allowed and audited.

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 audit removes 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.

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, then 0*4 + 3 = 3, then 5*4 + 1 = 21.
  • perms_t::clear_bits clears 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

COMPILER: pri_update_perm prefixes.priority, cod_entry.priority -> add_rule(..., priority, ...) -> MatchFlag(priority, perms, audit) a state: one score per permission bit start: MIN_INTERNAL_PRIORITY*4 hfa.cc:1665 x w r a -4004 -4004 -4004 -4004 score = priority*4 + ( deny 3 | exact-match exec 2 | allow 1 | prompt 0 ) hfa.cc:1536-1554 allow node prio 1 perms r r: 1*4+1 = 5 > -4004 takes the bit deny node prio 0 perms rw quiet rw r: 0*4+3 = 3 < 5 skipped (:1556-1560) w, a: 3 > -4004 cleared, then applied (:1575-1592) -4004 3 5 3 (allow/deny//prompt/audit/quiet) (r / wa // 0 / 0 / wa) (0x 10004/2800a//0/0/2800a) equal score: the node's bits are added to what the bit already has "this is the last use of priority, it is dropped and not used in the backend" (hfa.cc:1542-1543) MAX_INTERNAL_PRIORITY = 1001 the parser's own class-marker rules (parser_regex.c:1359-1372)
The priority travels from the rule through add_rule into the accept node. A state keeps one score register per permission bit, starting at -4004. An allow node with priority 1 for r scores 5 and takes the r bit. A deny node with priority 0 for rw scores 3: it is skipped for r and applied for w and a. The state ends as allow r, deny w and a, quiet w and a.

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.priority for rule objects (rule.h:240-243) and cod_entry.priority for file rules (parser.h:140-141).
  • It is passed to every add_rule and add_rule_vec call (file rules: parser_regex.c:675-688) and becomes part of the accept node: UniquePerm is { 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 an ExactMatchFlag (aare_rules.cc:98-110); it scores as an allow except on exec bits.
  • perms_t::perms_t gives each of the 32 bits a score register starting at MIN_INTERNAL_PRIORITY*4, which is -4004, and calls pri_update_perm for every bit in a node's perms | 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_bits for 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, and deny /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_PRIORITY is -1001 and MAX_INTERNAL_PRIORITY is 1001 (immunix.h:201-207). The rules that mark a class as mediated are added with mediates_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-build prints the comparisons while states are built (the DUMP_DFA_PERMS output in the same function).

07 Where priority is refused or ignored

COMMON MISTAKES priority=1001 /etc/demo/** r, invalid priority 1001 > 1000 range: -1000 to 1000 priority=1 { /etc/demo/** r, } priority is not allowed on rule blocks priority=1 network inet, priority prefix not allowed on network rules the all rule refuses it the same way audit priority=1 /etc/demo/** r, syntax error write: priority=1 audit priority=1 capability chown, deny capability chown, known limitation: accepted, no message the priority is ignored: chown stays denied an override that does not work? check that both rules are of a kind that supports priority, and that they name the same permission

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 shows MESSAGE.
  • 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 all rule: the message in the parser source is priority prefix not allowed on all rules (run as above with priority=1 all,).
  • Capability rules. The pair priority=1 capability chown, and deny capability chown, is accepted without a message (run as above). The pair compiles to the same binary as deny 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, prints invalid priority -1001 > -1000 (run as above).
  • priority=abc prints only flex scanner jammed and 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=1 on an allow rule in any included file overrides every deny of 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, with deny 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.

for AppArmor developers for security researchers

In the code

08 Where to go from here

ROADS deny allow prompt highest priority first, then deny > allow > prompt one permission at a time use it sparingly: a narrower pattern is often the better fix syn-allow-deny the equal priority case syn-prompt the lowest rung syn-audit the winner decides the logging syn-exec-modes conflicting x modifiers syn-qualifier-blocks priority and blocks re-perms · re-dfa where overlapping rules meet also: syn-globbing (the overlapping patterns) · syntax-map
The ladder in miniature, deny over allow over prompt, with roads to the decks syn-allow-deny, syn-prompt, syn-audit, syn-exec-modes and syn-qualifier-blocks, and a row naming re-perms, re-dfa, syn-globbing and syntax-map.

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, network rules and all rules; accepted and ignored on capability rules (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=N is the first qualifier (code).
  • White space around = is allowed: priority = -5 /a r, and priority=+5 /b r, are accepted (tree).
  • priority must be followed by =, after optional white space. Without it the rule is a syntax error (tree).
  • The bounds are MIN_POLICY_PRIORITY (-1000) and MAX_POLICY_PRIORITY (1000) (code).
  • Examples in the parser's tests: parser/tst/simple_tests/file/priority/ holds 81 files at this commit, for example priority=-1 deny /usr/bin/foo r, (ok_deny_2.sd), and bad_1.sd and bad_2.sd for 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:

StepRule
1The highest priority decides.
2At equal priority: deny, then allow, then prompt.
2aFor the exec permission only, a rule whose path has no wildcards ranks between deny and allow. See syn-exec-modes.
3Rules of equal priority and equal kind accumulate.
4The 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.

RulesStateMeaningBasis
/a rw, deny /a w,(0x 10004/2800a//0/0/2800a)read allowed; write denied and quiettree
priority=1 /a rw, deny /a w,(0x 3800e/0//0/0/0)read and write allowed; nothing quiettree
priority=1 /a rw, priority=1 deny /a w,(0x 10004/2800a//0/0/2800a)both raised: as the first rowtree
/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 matchestree
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 gonetree
priority=1 /a r, /a w,(0x 3800e/0//0/0/0)read from the first rule, write from the secondtree
priority=1 /a r, audit /a rw,(0x 3800e/0//0/2800a/0)read and write allowed; only write and append auditedtree
prompt /a rw, /a r,(0x 10004/0//2800a/0/0)allow beats prompt for readtree
priority=1 prompt /a rw, /a r,(0x 0/0//3800e/0/0)the raised prompt takes read as welltree
prompt /a rw, deny /a w,(0x 0/2800a//10004/0/2800a)deny beats prompt for writetree
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 directorytree
priority=1 /x r, deny /x rw,/x: (0x 10004/2800a//0/0/2800a)read allowed; write and append denied and quiettree
  • 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 classBehaviourBasis
file, linkacceptedtree
change_profile, signal, ptrace, mount, dbus, userns, io_uring, mqueueacceptedtree, one rule of each
unixaccepted; "partially supported": rules downgraded to plain socket mediation lose the prioritytree for acceptance; code for the rest
capabilityaccepted and ignored (known limitation)tree: accepted, and priority=1 capability chown, with deny capability chown, compiles to the same binary as the deny alone
networkrefused: priority prefix not allowed on network rulestree
allrefused: priority prefix not allowed on all rulestree
a block priority=N { ... }refused: priority is not allowed on rule blockstree
a file rule with a priority inside a blockaccepted: owner { priority=1 /a r, }tree
any other rule with a priority inside a blockrefused: 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=1 allow (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.

MessageExampleWhen
invalid priority 1001 > 1000priority=1001 /etc/demo/** r,N above 1000; the format is invalid priority %ld > %d (tree)
invalid priority -1001 > -1000priority=-1001 /a r,N below -1000; the sign in the message is wrong (tree; see Known discrepancies)
invalid priority %snone foundpresent in the parser source; cannot be reached, because the scanner passes only integers (code; see Known discrepancies)
priority is not allowed on rule blockspriority=1 { /etc/demo/** r, }a priority on a block (tree)
priority prefix not allowed on network rulespriority=1 network inet,a priority on a network rule (tree)
priority prefix not allowed on all rulespriority=1 all,a priority on an all rule (tree)
priority levels not supportedaudit { 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_VARaudit priority=1 /etc/demo/** r,priority=N after another qualifier (tree)
syntax error, unexpected TOK_ID, expecting TOK_EQUALSpriority /a r,the word priority without = (tree)
flex scanner jammedpriority=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 only flex scanner jammed, with exit status 2 and no file name or line number (tree). The scanner state entered after priority has rules only for = and an integer and is missing from the rule that reports unexpected characters (code). As a consequence the grammar's own invalid priority %s cannot 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 with priority levels not supported: audit { priority=1 signal, } and { priority=1 signal, } are refused, while priority=1 signal, outside a block, owner { priority=1 /a r, } and audit { 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): with deny 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, allows rw (tree).

for AppArmor developers for security researchers

Code map

WhatWhere
opt_priority: value, range check, messagesparser_yacc.y:677-691
opt_prefix: the order of the four qualifiersparser_yacc.y:705-711
scanner: priority/{WS}*=, INTEGER, INTEGER_MODEparser_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_PRIORITYimmunix.h:198-207
prefixes.priorityrule.h:240-243
cod_entry.priorityparser.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_prefixblock.h:46-51, network.h:269-273, all_rule.h:46-50
capability rules: the check that is commented outblock_rules.cc:133-138, block_rules.h:61-66
unix rules: "partially supported"af_unix.h:52-55
file rules: priority passed to add_ruleparser_regex.c:675-688
UniquePermsCache::insert: the priority in the accept nodeaare_rules.h:77-81
exact_matchaare_rules.cc:98-110
MatchFlag, ExactMatchFlag, DenyMatchFlag, PromptMatchFlagexpr-tree.h:1150-1201
pri_update_permhfa.cc:1529-1653
scorehfa.cc:1536-1554
lower score skippedhfa.cc:1556-1560
higher score clears the bithfa.cc:1575-1582
deny, exact-match, allow, prompt brancheshfa.cc:1585-1650
perms_t::perms_t: registers start at -4004, loop over the bitshfa.cc:1661-1694
perms_t::clear_bitshfa.h:74-81
mediates_priorityparser_regex.c:1359-1372
manual page textapparmor.d.pod:2540-2548
tests: fixturesparser/tst/simple_tests/file/priority/, for example ok_deny_2.sd
tests: owner block keeps an inner priority on file rulesequality.sh:667-669
tests: carve-out pattern equals a lowered denyequality.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

FILE ACCESS

QUALIFIERS

THE DFA ENGINE · libapparmor_re