File rules

path and permissions for application developers

A file rule is a path pattern followed by permission letters. It has two spellings and an optional file keyword. The bare rule "file," allows every file permission on every path.

On the map: file access

▶ Watch this deck — 8 scenes, ~6 min

Worth seeing first

Part of journeys

01 Which files may demo touch?

FILE RULES demo /usr/bin/demo /etc/demo/demo.conf /var/lib/demo/state /home/user/.ssh/id_rsa read read, write read /etc/demo/** r, /var/lib/demo/** rw, the profile's file rules no rule: refused one line = a path pattern + permission letters + a comma
The program demo opens three files: its configuration, its state and a private SSH key. The profile has file rules for the first two paths; the third has no rule and is refused.

A file rule is PATH MODE,: a path pattern and permission letters. A request with no matching rule is refused.

Demo opens three files. Two it needs: its configuration and its state. The third is somebody's private SSH key, and that one is a bug. A profile is a list of what's allowed, so for every open the question is the same: is there a rule for this path, with this permission? The file rule is the line that answers it. Demo's profile has one for the configuration and one for the state. There's no line for the key, so that open is refused. A path, some letters, a comma: this deck is about the shape of that line, its two spellings, and the one-word rule that allows everything.

Details and sources

Details

  • Syntax: PATH MODE, as in /etc/demo/** r,: a path pattern, permission letters, a comma. The man page's grammar line for FILE RULE is at apparmor.d.pod:397.
  • A profile is an allow list: a request for a name and a permission that no rule grants is refused.
  • Kernel, read and not run: an open reaches AppArmor through the LSM hook file_open, implemented by apparmor_file_open (lsm.c:1808, lsm.c:465), which calls aa_path_perm with the operation open.
  • The refusal: any requested permission that is not in the allowed set gives -EACCES (file.c:244-247).
  • A refused open is logged like this record from the libapparmor test suite (avc_syslog_01.in): apparmor="DENIED" operation="open" profile="/usr/sbin/cupsd" name="/boot/" pid=19651 comm="ls" requested_mask="r" denied_mask="r" fsuid=0 ouid=0.
  • The program demo, its files and its profile are invented for the map. Nothing on this slide was observed on a running kernel.

for AppArmor developers for security researchers

In the code

  • The path-first form of the rule in the grammar: frule: id_or_var file_perms opt_named_transition TOK_END_OF_RULE (parser_yacc.y:1072).

02 The shape of a file rule

GRAMMAR PATH MODE , /etc/demo/** r, MODE PATH r /etc/demo/**, the same rule file file /etc/demo/** r, optional, changes nothing QUALIFIERS priority=N audit allow|deny|prompt owner|other safe | unsafe exec rules only -> TARGET a link target or an exec target [QUALIFIERS] [file] [safe|unsafe] ( PATH MODE | MODE [subset] PATH ) [-> TARGET] , PATH starts with / or @{ or is quoted; the order of the parts is fixed
Syntax diagram of a file rule: optional qualifiers, the optional word file, optional safe or unsafe, then either path and mode or mode and path, an optional arrow and target, and a comma.

[QUALIFIERS] [file] [safe|unsafe] (PATH MODE | MODE [subset] PATH) [-> TARGET],. The order of the parts is fixed. A path starts with / or a variable, or is quoted.

Read the diagram from the middle: a path, the letters, a comma. That's the whole rule. You can write the letters first instead; it's the same rule. The word file in front is optional and changes nothing. Qualifiers such as deny and owner go before everything else, and safe or unsafe go right after the word file; those two only matter for exec rules. An arrow at the end names a target: a link target when the letters include l, otherwise the profile an exec switches to. Each of those parts has its own deck. What stays fixed is the order of the parts.

Details and sources

Details

  • Form: [QUALIFIERS] [file] [safe|unsafe] ( PATH MODE | MODE [subset] PATH ) [-> TARGET] , with QUALIFIERS being [priority=N] [audit] [allow|deny|prompt] [owner|other]. The order of the slots is fixed.
  • apparmor.d(5) writes it as FILE RULE = [ QUALIFIERS ] [ 'owner' ] ( 'file' | [ 'file' ] ( FILEGLOB ACCESS | ACCESS FILEGLOB ) [ '->' EXEC TARGET ] ) (apparmor.d.pod:397) and ACCESS = ( 'r' | 'w' | 'a' | 'l' | 'k' | 'm' | EXEC TRANSITION )+ (apparmor.d.pod:408).
  • PATH starts with / or a variable @{...}, or is a quoted string (apparmor.d.pod:399-403).
  • MODE is one word of permission letters, followed by white space or a comma.
  • Accepted by the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel): file /a r,, file r /a,, file /a px -> b,, file safe /a px,, file unsafe px /a,, file l /a -> /b,, deny file /a w,, audit deny owner /a rw,.
  • safe or unsafe on a rule with no exec letters: unsafe rule missing exec permissions.
  • file is a reserved word only in rule position; /etc/file r, is an ordinary rule (read from the source).

for AppArmor developers for security researchers

In the code

03 Path first or letters first

TWO SPELLINGS, ONE RULE path first /etc/demo/** r, /var/lib/demo/** rw, /usr/bin/demo-helper Px, letters first r /etc/demo/**, rw /var/lib/demo/**, Px /usr/bin/demo-helper, one rule: /usr/bin/demo-helper, Px /usr/bin/demo-helper Px -> demo-helper , Px /usr/bin/demo-helper -> demo-helper , the target always follows the path /etc/demo/** r, + /etc/demo/** w, = /etc/demo/** rw, the same path written twice: the letters are added together
Three file rules written path first on the left and letters first on the right. Both spellings of the demo-helper line give one rule. With an arrow the target follows the path in both spellings.

/etc/demo/** r, and r /etc/demo/**, are the same rule. Rules with identical path text are merged by adding their permissions.

Most profiles put the path first. But the tree's own tests also write the letters first: r, then the path. The parser builds the same rule either way, so the two helper lines here are one rule. Add an arrow and a target, and the target comes after the path in both spellings. One more thing about identical paths: if two rules name exactly the same path, their letters are added together, so read on one line and write on another gives read and write. The one place the spellings differ, the letter l with an exec letter and an arrow, is in the link rules deck.

Details and sources

Details

  • /etc/demo/** r, and r /etc/demo/**, build the same rule (read from the source).
  • The parser's tests use the letters-first form: front_perms_ok_1.sd has r /foo1,, w /foo1,, px /foo1, and more, expected result PASS.
  • With an arrow the target follows the path in both spellings: /a px -> b, and px /a -> b, (parser built from the AppArmor tree at 836052d21). px -> b /a, gives syntax error, unexpected TOK_ARROW, expecting TOK_ID or TOK_SET_VAR.
  • subset exists in the letters-first form only and only with l: r subset /a, gives subset can only be used with link rules.
  • Rules with identical path text are merged before compilation by adding their permissions: /a r, and /a w, are /a rw,. Exec modes that disagree stop the parser: profile NAME: has merged rule PATH with conflicting x modifiers.
  • The one difference between the spellings, l with an exec letter and an arrow: path first gives the warning ambiguous rule specifies both link target and exec transition target. Using as exec transition (class deprecated, off by default); letters first gives the error link and exec perms conflict on a file rule using ->.

for AppArmor developers for security researchers

In the code

04 What the kernel does with the rule

ONE OPEN, ONE CHECK open("/etc/demo/demo.conf", O_RDONLY) demo AppArmor in the kernel name /etc/demo/demo.conf asked r rule /etc/demo/** r, allowed r nothing missing /etc/demo/demo.conf open("/etc/demo/demo.conf", O_WRONLY) asked w, allowed r EACCES: permission denied opendir("/etc/demo") name /etc/demo/ a directory's name ends in /: write /etc/demo/ r, to list it
demo opens /etc/demo/demo.conf for reading: the kernel builds the name, finds that the rule allows r and lets the open through. The same open for writing asks for w, which is not allowed, and fails with EACCES. A directory's name ends in a slash.

The kernel matches the full name against the profile and refuses with EACCES when a requested permission is not allowed. Directory names end in /.

Here's what happens at one open. When demo opens its configuration, the kernel, here the kernel, works out the full name of the file and looks up what the profile's rules allow for that name. The open asked for read, the rule gives read, and the open goes ahead. Ask for write on the same file and one requested permission is missing, so the call fails with permission denied, EACCES. One detail catches people. For a directory, the kernel puts a slash on the end of the name before it matches. So a rule that should match the directory itself, to list it, has to end in a slash.

Details and sources

Details

All statements are from the kernel source, read and not run.

  • Hooks: file_open for an open, file_permission for later reads and writes on the open file, and the path_* hooks (path_unlink, path_mkdir, path_rename, path_chmod and others) for operations on names (lsm.c:1796-1816).
  • aa_path_perm(op, subj_cred, label, path, flags, request, cond) runs the check once for each confined profile in the task's label (file.c:287-309).
  • The name is built from the path, then matched: aa_str_perms walks the profile's file DFA over the name and looks up the permissions for the task's fsuid (file.c:221-231).
  • if (request & ~perms->allow) e = -EACCES; (file.c:244-247). The result goes to aa_audit_file, which writes the log record.
  • Directory names get a trailing / before matching, except the root (path.c:167-177). /etc/demo/ r, matches the directory itself; /etc/demo r, does not.
  • apparmor.d(5) says the same: "Only rules that match a trailing slash will match directories" (apparmor.d.pod:2507-2509).
  • The buffer for a name is path_max bytes, by default twice PATH_MAX; readable by root in /sys/module/apparmor/parameters/path_max (lsm.c:1998-1999).
  • Which half of a rule applies, owner or other, is decided by comparing the task's fsuid with the owner of the object; the record shows both as fsuid= and ouid=.

Read more

05 The bare rule: file,

file, profile demo /usr/bin/demo { file, } /{**,} rwalkm + ix every name that starts with /, and / itself demo /etc/shadow /home/user/.ssh/id_rsa /usr/bin/anything read write exec, same profile owner file, the same, only for files the task owns other rule classes (network, capability, ...) are still checked
A profile containing only the bare rule file, which the parser rewrites to the path /{**,} with the letters rwalkm and ix. demo may then read, write and execute any file, staying in its own profile. owner file, limits this to files the task owns.

file, equals the path /{**,} with rwalkm and ix. owner file, keeps the owner half only.

Sometimes you want a profile that limits networking or capabilities but leaves files alone. The bare rule does that: the word file, and a comma. The parser rewrites it into a pattern that matches every name starting with a slash, with every file letter: read, write, append, link, lock and memory map. For exec it adds ix, so programs demo starts stay in demo's profile. Qualifiers still work: owner in front limits it to files the task owns. And it says nothing about other kinds of rule. Network, capabilities and the rest are still checked.

Details and sources

Details

  • file, is rewritten by the parser to the path /{**,} with the letters rwalkm and the exec mode ix, for the owner half and the other half (read from the source).
  • In the rule dump of the parser built from the AppArmor tree at 836052d21 (-D rule-exprs) the path is /([^\x00]*|): / followed by anything, and / alone. The permission word is 0x9fc27f; for owner file, it is 0x27f.
  • owner file, keeps the owner half only: the same access, for files owned by the task's fsuid.
  • It covers file rules only. network, capability, mount and the other rule classes are still checked against their own rules.
  • The pattern covers names that begin with /. A name that does not, such as the name of a disconnected object, is not matched (read from the source).
  • Known discrepancy: deny file, is rejected with Invalid perms, in deny rules 'x' must not be preceded by exec qualifier 'i', 'p', or 'u', because the bare rule carries ix. The test ok_bare_1.sd expects it to pass and is marked #=TODO https://launchpad.net/bugs/1215637.

for security researchers

Attack surface

  • File rules match the name the kernel builds at the time of the check, not the object: a file that has a second name, such as a hard link, is checked against the rules for the name that was used. See link rules.
  • file, is the widest file rule there is: it compiles to the pattern /{**,} with rwalkm and ix for owner and other (parser_yacc.y:1103-1113; run with the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel). Every program the task can name is then executable under the same profile.
  • The bare rule cannot be turned into a denial: deny file, is rejected because the bare rule carries ix (parser_misc.c:1093-1096). deny /** rwlkmx, and deny /{**,} rwlkmx, are accepted by the same parser when a blanket denial is wanted.
  • A rule that ends in /** does not cover the directory itself, and a rule without the trailing slash does not match a directory: check both forms when you review what a profile exposes (globbing).

for AppArmor developers for security researchers

In the code

  • file_rule: TOK_FILE TOK_END_OF_RULE builds the path "/{**,}" and the permissions (AA_BASE_PERMS & ~AA_EXEC_TYPE) | (AA_EXEC_INHERIT | AA_MAY_EXEC), copied to the other half with << AA_OTHER_SHIFT (parser_yacc.y:1103-1113). AA_OTHER_SHIFT is 14 (immunix.h:25).
  • The owner qualifier masks one half in entry_add_prefix, which ends with check_x_qualifier, the source of the deny file, error (parser_misc.c:1147-1159, parser_misc.c:1090-1096).

06 From text to a cod_entry for AppArmor developers for security researchers

PARSER: FILE RULE /etc/demo/** r, lexer TOK_ID TOK_MODE TOK_END_OF_RULE parser_lex.l:838,843 frule parser_yacc.y:1072 / 1085 file_rule: opt_file file_rule_tail do_file_rule cod_entry name /etc/demo/** perms 0x10004 nt_name / link_name rule_mode, audit, priority r, owner and other entry_add_prefix parser_misc.c:1147 owner keeps one half check_x_qualifier merge_file block_rules.cc:285 same name: perms |= process_dfa_entry parser_regex.c:648 file DFA
The rule /etc/demo/** r, passes through the lexer, the frule grammar rule and do_file_rule, which builds a cod_entry with name, perms 0x10004 and target fields; entry_add_prefix, merge_file and process_dfa_entry then act on that struct and produce the file DFA.

frule (parser/parser_yacc.y:1072,1085) builds a cod_entry; merge_file ORs entries with identical names; process_dfa_entry (parser/parser_regex.c:648) compiles each.

To the parser a file rule isn't a class like the newer rule types; it's a cod_entry. The lexer returns the path as an ID token and the letters as a mode token, but only when white space or a comma follows them. The grammar has two frule alternatives, one per spelling, and both call do_file_rule. By then parse_perms has filled both halves of the permission word, owner and other, which is why plain read is 0x10004. Prefixes are applied by entry_add_prefix, entries with identical names are merged by merge_file, and process_dfa_entry hands the pattern and the word to the DFA compiler.

Details and sources

for AppArmor developers for security researchers

Details

  • Scanner: a path is LABEL or QUOTED_LABEL and returns TOK_ID; the letters return TOK_MODE only before white space or a comma, ({MODES})/([[:space:],]) (parser_lex.l:301, parser_lex.l:838-846).
  • Grammar: two frule alternatives (parser_yacc.y:1072-1100); file_perms: TOK_MODE calls parse_perms (parser_yacc.y:1640-1646).
  • perm32_t parse_perms(const char *str_perms) shifts the parsed letters into both halves, AA_USER_SHIFT (0) and AA_OTHER_SHIFT (14) (parser_misc.c:736-745, immunix.h:24-25). With AA_MAY_EXEC 1, AA_MAY_WRITE 2, AA_MAY_READ 4, AA_MAY_APPEND 8 (immunix.h:35-38), r is 0x10004 and rw is 0x3800e.
  • struct cod_entry *do_file_rule(char *id, perm32_t perms, char *link_id, char *nt) calls new_entry and stores the target in nt_name (parser_yacc.y:1759-1769).
  • bool entry_add_prefix(struct cod_entry *entry, const prefixes &p, const char *&error) applies audit, mode and priority, masks a half for owner or other, then runs check_x_qualifier (parser_misc.c:1147-1159).
  • block_rules::process_variables expands variables in name and link_name (block_rules.cc:393-407).
  • block_rules::merge_file sorts with file_comp, checks is_merged_x_consistent and ORs perms (block_rules.cc:285-343).
  • bool process_dfa_entry(aare_rules *dfarules, struct cod_entry *entry) calls filter_slashes, convert_aaregex_to_pcre and dfarules->add_rule(pattern, priority, rule_mode, perms, audit, parseopts) (parser_regex.c:648-682).
  • Kernel: the compiled table is matched by aa_str_perms from start state rules->file->start[AA_CLASS_FILE] (file.c:221-247).

07 When the parser says no

COMMON MISTAKES /etc/demo/** r /var/lib/demo/** rw, no comma after r the error is reported at this line missing an end of line character? (entry: /etc/demo/**) etc/demo/demo.conf r, a path starts with / or @{ syntax error, unexpected TOK_ID, expecting TOK_MODE /etc/demo/my notes r, quote it: "/etc/demo/my notes" r, syntax error, unexpected TOK_ID, expecting TOK_MODE file deny /etc/demo/** w, qualifiers first: deny file /etc/demo/** w, syntax error, unexpected TOK_DENY, expecting TOK_ID or TOK_MODE or TOK_SET_VAR TOK_MODE is the permission letters, TOK_ID is a path the full list is in the reference below
Four rejected file rules with the parser's message: a rule without its comma, a path that does not start with a slash, a path with a space in it, and the qualifier deny written after the word file.

Missing comma: "missing an end of line character? (entry: ...)". Paths start with / or @{; quote paths with spaces. Qualifiers precede file; safe/unsafe follow it.

Four slips account for most file rule errors. Forget the comma and the parser reads on into the next rule, then asks whether you're missing an end of line character, naming the rule that had no comma. A path has to start with a slash or a variable; anything else is just a word. A space ends the path, so a name with a space in it needs quotes. And the parts have an order: deny goes before the word file, while safe and unsafe go after it. The messages with TOK in them come straight from the grammar. Read them as: I expected the letters here.

Details and sources

Details

Messages from the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all). The full form is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.

  • /a r then /b w,: missing an end of line character? (entry: PATH), reported at the line of the following rule and naming the rule without the comma.
  • /a b r, or etc/x r,: syntax error, unexpected TOK_ID, expecting TOK_MODE. A space inside an unquoted path, or a first word that is not a path. Fixture: bad_embedded_spaces_1.sd.
  • a r, or mark r,: syntax error, unexpected TOK_MODE, expecting TOK_ID or TOK_SET_VAR. The first word consists only of mode letters, so it is read as a mode.
  • file deny /a w,: syntax error, unexpected TOK_DENY, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. Qualifiers go before file.
  • safe file /a px,: syntax error, unexpected TOK_FILE, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. safe and unsafe go after file.
  • file /a,: syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE. A path with no mode.
  • Token names: TOK_ID is a path or another word, TOK_MODE the permission letters, TOK_SET_VAR a variable, TOK_END_OF_RULE the comma.

for AppArmor developers for security researchers

In the code

08 Where to go from here

ROADS owner /usr/bin/demo-* Px -> demo-helper, in front syn-owner syn-allow-deny the pattern syn-globbing the letters syn-access-modes syn-exec-modes the arrow syn-named-transitions syn-link-rules the rule from the inside, and the whole language fe-grammar how the parser reads it k-match how the kernel matches syntax-map every kind of line

Next: syn-access-modes (letters), syn-globbing (patterns), syn-exec-modes and syn-named-transitions (exec), syn-link-rules (links), syn-allow-deny and syn-owner (qualifiers).

Every part of this line has a deck of its own: the qualifier in front, the pattern, the letters, the arrow. Go to the owner and allow and deny decks for what stands in front. Globbing explains the stars. Access modes tells you what r and w really grant, and exec modes covers the letters that end in x. The arrow belongs to named transitions, or to link rules when the letters include l. And if you want to see the rule from the inside, follow it into the grammar deck or the kernel's matching deck.

Details and sources

Details

  • A file rule is PATH MODE, or MODE PATH,, optionally with qualifiers in front, the word file, and -> TARGET at the end.
  • file, alone allows every file access and ix for exec.
  • In the kernel a request that the rules do not allow fails with EACCES (file.c:244-247), and directory names are matched with a trailing / (path.c:167-177).
  • 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 above was run on the fragment (-Q -K --skip-kernel-load --warn=all), with nothing loaded into a kernel; "code" means the parser source or the kernel source of mainline Linux 7.4 (7.4-rc2, 97d73c825) was read, not run. Nothing here was observed on a running kernel.

Grammar

FILE RULE:   [QUALIFIERS] [file] [safe|unsafe] ( PATH MODE | MODE [subset] PATH ) [-> TARGET] ,
BARE RULE:   [QUALIFIERS] file ,
QUALIFIERS:  [priority=N] [audit] [allow|deny|prompt] [owner|other]
  • PATH starts with / or a variable @{...}, or is a quoted string. It ends at white space; a path that contains a space or a comma is quoted.
  • MODE is one word of permission letters followed by white space or a comma. The letters: syn-access-modes and syn-exec-modes.
  • The order of the parts is fixed: qualifiers, then file, then safe or unsafe, then the path and mode in either order, then the arrow and target, then the comma.
  • With an arrow, the target follows the path in both spellings: /a px -> b, and px /a -> b, (tree).
  • The two spellings build the same rule (code). They differ in one case, l together with an exec mode and an arrow: see syn-link-rules.

Keywords

KeywordWhereMeaning
filebefore the rule, after the qualifiersoptional marker with no effect; alone with a comma it is the bare rule
safe, unsafeafter file, before the path or modeexec rules only: syn-safe-unsafe
subsetletters-first spelling, between mode and pathlink rules only: syn-link-rules
->after the path and modea link target when the mode has l and no exec letters, otherwise an exec target: syn-named-transitions
priority=N, audit, allow, deny, promptin front, in this ordersyn-priority, syn-audit, syn-allow-deny
owner, otherlast qualifiersyn-owner

file is a reserved word only in rule position. It stays usable inside a path, as in /etc/file r, (code).

Accepted forms

Each of these lines is accepted by the tree's parser (tree).

LineNote
file /a r,keyword, path first
file r /a,keyword, letters first
file /a px -> b,exec target
file safe /a px,safe after file
file unsafe px /a,unsafe with letters first
file l /a -> /b,link target
deny file /a w,qualifier before file
audit deny owner /a rw,qualifiers in order
file,the bare rule
owner file,the bare rule, owner half
"/foobar," r,a quoted path that contains a comma

The bare rule

  • file, is rewritten by the parser to the path /{**,} with the letters rwalkm and the exec mode ix, for both the owner and the other half (code). In the parser's rule dump the path is /([^\x00]*|): / followed by anything, and / alone (tree).
  • owner file, keeps the owner half only: the same access, for files owned by the task's fsuid.
  • It covers file rules only. Network, capability, mount and the other rule classes are still checked against their own rules.
  • The pattern covers names that begin with /. A name that does not, such as the name of a disconnected object, is not matched (code).
  • file, outside a profile is an error.

What the kernel checks

All statements in this section are from the kernel source (code).

  • At each access the kernel builds the full name of the object and matches it against the profile's file rules.
  • The name of a directory gets a trailing / before matching. /etc/demo/ r, matches the directory itself; /etc/demo r, does not.
  • If any requested permission is not allowed for that name, the access fails with EACCES.
  • Which half of the rule applies, owner or other, is decided by comparing the task's fsuid with the owner of the object: syn-owner.
  • Rules with identical path text are merged before compilation by adding their permissions: /a r, and /a w, are /a rw,.

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. All of them are fatal except the last row.

MessageExampleWhen
missing an end of line character? (entry: PATH)/a r then /b w,a rule has no comma; reported at the line of the following rule, naming the rule without the comma
syntax error, unexpected TOK_ID, expecting TOK_MODE/a b r, and etc/x r,a space inside an unquoted path, or a first word that is not a path. When the word after the space is a keyword the message names its token: /a file r, gives unexpected TOK_FILE (tree)
syntax error, unexpected TOK_MODE, expecting TOK_ID or TOK_SET_VARa r, and mark r,the first word consists only of mode letters, so it is read as a mode
syntax error, unexpected TOK_DENY, expecting TOK_ID or TOK_MODE or TOK_SET_VARfile deny /a w,a qualifier after file
syntax error, unexpected TOK_FILE, expecting TOK_ID or TOK_MODE or TOK_SET_VARsafe file /a px,safe or unsafe before file
syntax error, unexpected TOK_LINK, ...file link /a -> /b,the link rule does not take the keyword
syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODEfile /a,a path with no mode
syntax error, unexpected TOK_ARROW, expecting TOK_ID or TOK_SET_VARpx -> b /a,the target written before the path
subset can only be used with link rules.r subset /a,subset with a mode other than l
link and exec perms conflict on a file rule using ->lpx /link/** -> /target,letters first, l with an exec mode and an arrow
link perms are not allowed on a named profile transition.l /a -> :ns:b,letters first, l with a target that names a namespace
conflicting mode prefixtwo of allow, deny, prompt reach the same rule
conflicting audit prefixaudit given twice for the same rule
ambiguous rule specifies both link target and exec transition target. Using as exec transition/a lpx -> b,warning, path first only; its class deprecated is off by default

In these messages TOK_ID is a path or another word, TOK_MODE is the permission letters, TOK_SET_VAR is a variable and TOK_END_OF_RULE is the comma.

Known discrepancies

  • deny file, is rejected with "Invalid perms, in deny rules 'x' must not be preceded by exec qualifier 'i', 'p', or 'u'" (tree). The bare rule is built with ix, and a deny rule may not carry an exec qualifier. The tree's own test parser/tst/simple_tests/file/ok_bare_1.sd expects the rule to pass and is marked as a known failure (launchpad 1215637).
  • An arrow on a rule with neither x nor l, such as /a r -> b,, is accepted and takes a slot in the exec table. See syn-named-transitions.

for AppArmor developers for security researchers

Code map

StepWhere
path as TOK_ID, LABEL start charactersparser/parser_lex.l:301, parser/parser_lex.l:838-841
letters as TOK_MODE, only before white space or a commaparser/parser_lex.l:843-846
file keyword to TOK_FILEparser/parser_misc.c:108
qualifiers, opt_prefixparser/parser_yacc.y:705-711
frule, path firstparser/parser_yacc.y:1072
frule, letters first, with the subset and link checksparser/parser_yacc.y:1085-1100
bare rule, file_rule: TOK_FILE TOK_END_OF_RULEparser/parser_yacc.y:1103-1113
file_rule: opt_file file_rule_tail, opt_exec_mode fruleparser/parser_yacc.y:1114, parser/parser_yacc.y:1117
the missing-comma errorparser/parser_yacc.y:1132-1139
parse_permsparser/parser_misc.c:736-745
do_file_rule, builds the cod_entryparser/parser_yacc.y:1759-1769
entry_add_prefix, with check_x_qualifierparser/parser_misc.c:1147-1159
process_variablesparser/block_rules.cc:393-407
merge_file, ORs the perms of identical namesparser/block_rules.cc:285-343
process_dfa_entryparser/parser_regex.c:648-682
kernel: aa_path_perm, profile_path_perm, __aa_path_perm, aa_str_permslinux:security/apparmor/file.c:221-309
kernel: request & ~perms->allow gives -EACCESlinux:security/apparmor/file.c:244-247
kernel: trailing / on directory nameslinux:security/apparmor/path.c:167-177

Permission words in the parser's rule dump (tree). Each half has x 0x1, w 0x2, r 0x4, a 0x8; the other half is shifted left by 14.

RuleWord
/a r,0x10004
/a rw,0x3800e
file,0x9fc27f
owner file,0x27f

Roads from here

START HERE

FILE ACCESS

QUALIFIERS

IN PRACTICE · security-sensitive programs

IN THE KERNEL

INSIDE THE PARSER