Globbing (AARE)
* ** ? [] {} for application developers for security researchers
The pattern syntax of paths and names. One star stays inside a path component and two stars cross slashes. A question mark is one character. Brackets are a character set and braces are alternatives. A pattern must match the whole name.
On the map: file access
▶ Watch this deck — 9 scenes, ~7 min
Worth seeing first
- File rules — the rule whose path is a pattern
Part of journeys
- Write your first profile, step 5 of 12 · previous: Variables · next: Exec modes
- File access in depth, step 2 of 12 · previous: File rules · next: File access modes
01 One rule, many files
Paths in rules are AARE patterns: *, **, ?, [...], {a,b}. A pattern matches a name only if it matches all of it.
Demo reads its configuration from a directory, and you don't want to write one rule per file. You couldn't keep up anyway: files come and go. So a path in a rule is a pattern. It looks like a shell glob, with a few differences that matter for security. AppArmor calls these patterns AARE, AppArmor regular expressions. There are five constructs: one star, two stars, the question mark, brackets and braces. One rule before we start. In the kernel a pattern has to match the whole name, from the first slash to the last character. A pattern that only matches the beginning matches nothing.
Details and sources
Details
- The pattern syntax is called AARE, AppArmor regular expressions. The manual page describes it in the section "Globbing (AARE)" (apparmor.d.pod:2463-2504).
- The five constructs:
*,**,?,[set]or[^set], and{alt,alt}. A backslash in front of one of these characters makes it literal. - Whole-name matching, the kernel:
aa_dfa_matchwalks the compiled policy over the complete, NUL-terminated name and returns the state it finished in (match.c:507-519); the permissions are those of that final state (file.c:221-231). A pattern that covers only the beginning of a name ends in a state without the permission. - The name the kernel matches is the absolute path of the file as the kernel builds it, with a
/at the end if it is a directory (path.c:167-177). - The same syntax is used in rule paths, in both names of a link rule and in profile attachments.
- To see what a pattern compiles to, run
apparmor_parser -Q -K --skip-kernel-load -D rule-exprs FILE. It prints each pattern and the regular expression made from it, and loads nothing. - The program
demoand its files are invented for the map. Nothing on this slide was observed on a running kernel.
Read more
- apparmor.d(5), Globbing (AARE).
- apparmor.net: Profiles quick reference, file globbing.
- File rules and profile attachment: where patterns are written.
02 The five constructs
* and ? do not match /. ** does. [^a] matches any character except a, including /. {a,b} is alternation.
Here they are. One star is any run of characters inside one path component: it stops at a slash. Two stars is any run of characters including slashes, so it reaches down into subdirectories. A question mark is exactly one character, and not a slash. Brackets are one character from a set, or with a caret in front, one character that isn't in the set. Watch that one: a negated set does match a slash. Braces list alternatives separated by commas, and an alternative can be anything, even more braces. Put a backslash in front of any of these and it's an ordinary character again.
Details and sources
Details
- What each construct matches:
*: any run of characters except/, also none;**: any run of characters including/, also none;?: exactly one character except/;[set]: exactly one character of the set, with ranges such as[a-c];[^set]: exactly one character not in the set, and that can be/;{alt,alt}: one of the comma-separated alternatives; at least one comma. - "Also none" has one exception: a
*or**that makes up a whole path component must match at least one character. See the scene "The directory itself". - What the parser built from the AppArmor tree at 836052d21 (
-Q -K --skip-kernel-load -D rule-exprs, nothing loaded into a kernel) prints for them:*becomes[^/\x00]*,**becomes[^\x00]*,?becomes[^/\x00], brackets are copied unchanged,{a,b}becomes(a|b). - Escapes:
\*,\?,\[,\],\{,\}are the literal characters;\,is a literal comma inside braces;\\is a backslash. - A backslash before any other character is dropped. With
--warn=format(or--warn=all) the parser saysCharacter q was quotedunnecessarily, dropped preceding quote ('\') character; the missing space is in the parser's text. - The manual page lists the constructs at apparmor.d.pod:2469-2504. It does not mention that a negated set matches
/.
Read more
- apparmor.d(5), Globbing (AARE).
- apparmor.net: Profiles quick reference, file globbing examples.
- Quoting and escaping: names with spaces, and escape sequences such as
\x41.
for AppArmor developers for security researchers
In the code
- The conversion is
convert_aaregex_to_pcre(parser_regex.c:118-431):*and**at parser_regex.c:169-229,?at parser_regex.c:231-254, brackets at parser_regex.c:256-280, braces and commas at parser_regex.c:282-357. - A negated set is not limited to one path component because the brackets are passed through to the regular expression parser of the DFA compiler, where
[^...]is aNotCharSetNode: every character except the listed ones (expr-tree.h:683-709).
03 * stays in the directory, ** goes down
/etc/demo/* matches one level; /etc/demo/** matches every level. Neither treats dot files specially.
Take the same directory and four rules that differ only in the last part of the pattern. A single star matches demo.conf and nothing else here. The other files are one level down, and a star doesn't cross a slash. Two stars match all of it: every file and both subdirectories. *.conf picks the files ending in .conf in this directory only. **.conf picks them at any depth, so the one inside conf.d is included. And unlike the shell, a star does match a leading dot, so hidden files are covered too.
Details and sources
Details
- Conversions printed by the parser built from the AppArmor tree at 836052d21 (
-Q -K --skip-kernel-load -D rule-exprs, nothing loaded into a kernel):/etc/demo/*becomes/etc/demo/[^/\x00][^/\x00]*;/etc/demo/**becomes/etc/demo/[^/\x00][^\x00]*;/etc/demo/*.confbecomes/etc/demo/[^/\x00]*\.conf;/etc/demo/**.confbecomes/etc/demo/[^\x00]*\.conf. - Neither star treats a leading dot specially:
/foo/*matches/foo/.hidden. The shell's rule about hidden files does not apply. /foo/*does not match/foo/a/bor the directory/foo/a/./foo/**matches/foo/a,/foo/a/and/foo/a/b/c.- A star in the middle of a component may match nothing:
/foo/*barmatches/foo/barand/foo/xbar;/a*bmatches/aband not/a/b. /foo**(no slash before the stars) matches/foo,/foobar,/foo/and/foo/a/b./**/foomatches/a/fooand/a/b/foo, and not/foo.- Three stars are read as
**followed by*, which matches the same names as**. - The match verdicts are derived from the printed regular expressions; they were not tested on a running kernel.
Read more
for AppArmor developers for security researchers
In the code
**:[^\x00]*and theTailGlobclassification when the two stars end a pattern that had no other glob (parser_regex.c:206-221).*:[^/\x00]*(parser_regex.c:222-226).
04 The directory itself
Directory names end in /. /etc/demo/** does not match /etc/demo/; /etc/demo/ r, or /etc/demo/{,**} r, does.
Listing a directory is a read of the directory itself, and the kernel writes a directory's name with a slash at the end. You might expect the two star rule to cover it, with the stars matching nothing. It doesn't. When stars make up a whole path component, right after a slash, they must match at least one character. That's deliberate: a rule for the contents isn't a rule for the directory. So write the directory with its slash, or use the brace idiom: an empty alternative, or two stars. */ gives you the subdirectories one level down. And doubled slashes in a pattern are collapsed for you.
Details and sources
Details
- In the kernel the name of a directory is given a
/at the end before it is matched, except for the root directory, which is already/(path.c:167-177). The manual page says the same: "Only rules that match a trailing slash will match directories" (apparmor.d.pod:2506-2529). - The slash rule: a
*or**that stands directly after a/and is followed by a/or by the end of the pattern must match at least one character. The source gives the purpose:/foo/*should not match/foo/,/foo/*barshould match/foo/bar, and/*/fooshould not match//foo(parser_regex.c:178-205). - What to write: the directory itself, for listing it:
/dir/ r,; the directory and everything below:/dir/{,**} r,; everything below, not the directory:/dir/** r,; the files directly in it:/dir/* r,; the directories directly in it:/dir/*/ r,. - The rule looks only at the character just before the star, so it does not apply inside braces:
/foo/{*,bar}matches/foo/. /**matches every name that starts with/except/itself;/{**,}includes/.- Repeated slashes in a pattern are collapsed to one before conversion:
/etc//demo///xcompiles as/etc/demo/x. A pattern that starts with exactly two slashes keeps them, and a trailing slash is kept. - The collapsing works on the text and does not look inside braces:
/a/{/b,c}keeps the inner/. - Conversions were printed by the parser built from the AppArmor tree at 836052d21 (
-Q -K --skip-kernel-load -D rule-exprs, nothing loaded into a kernel). The kernel behaviour is read from the kernel source, not observed.
Read more
- apparmor.d(5), Globbing (AARE): the paragraph on directories and the trailing slash.
- apparmor.net: Profiles quick reference, file globbing.
- Access modes: what
ron a directory allows.
for AppArmor developers for security researchers
In the code
- The check before a star: if the last character written is
/and the stars are followed by/or the end of the pattern, emit a mandatory[^/\x00]first (parser_regex.c:178-205). filter_slashes, including the special case for a leading//(parser_regex.c:61-96). It is called for the pattern a profile attaches by (parser_regex.c:495), for a rule path (parser_regex.c:659) and for a link target (parser_regex.c:700).
05 ? and brackets
? is one non-slash character. [a-c] is one of a range. [^b] is any one character except b, including /; write [^b/] to exclude the slash.
A question mark is one character. Not a slash, and not zero characters: the log rule matches demo-1.log but not demo-10.log. Brackets are one character from a list or a range. [a-c]*, matches names beginning with a, b or c. With a caret the set is negated: [^.]*, is a way to skip hidden files. But be careful with negated sets. They match anything that isn't listed, and that includes the slash. /a[^b]c matches /a/c. When that matters, put the slash in the set.
Details and sources
Details
?is exactly one character and never/:/a?cmatches/abc, and not/ac,/a/cor/abbc.[bc]is one of the listed characters,[b-d]one of a range:/a[b-d]ematches/abe,/aceand/ade.[^b]is any one character exceptb, and/is such a character:/a[^b]cmatches/axcand also/a/c. Write[^b/]to keep the match inside one path component.- Conversions printed by the parser built from the AppArmor tree at 836052d21 (
-Q -K --skip-kernel-load -D rule-exprs, nothing loaded into a kernel):/var/log/demo-?.logbecomes/var/log/demo-[^/\x00]\.log;/var/lib/demo/[a-c]*becomes/var/lib/demo/[a-c][^/\x00]*;/var/lib/demo/[^.]*becomes/var/lib/demo/[^\.][^/\x00]*. - Inside brackets
{,}and,are literal. - A defect of the parser at this commit:
*and?inside brackets are converted as globs instead of being literal./a[?]bcompiles without a message to/a[[^/\x00]]b, which does not match/a?b. Write\?outside brackets for a literal question mark. - An empty set fails without a pattern message:
/a[] r,prints onlyERROR processing regexs for profile NAME, failed to load. - A negated set in the parser's tests:
/foo[^me]bar r,(ok_inv_char_class.sd). - The match verdicts are derived from the printed regular expressions; they were not tested on a running kernel.
for security researchers
Attack surface
- A negated class crosses directories:
[^b]matches/unless the slash is listed, as in[^b/](run with the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel,-D rule-exprs).*and?stop at a slash;[^...]does not. *and?inside brackets are not literal./a[?]bcompiles to/a[[^/\x00]]band/c[x*]dto/c[x[^/\x00]*]d, each a different set from the one written, with no message and exit status 0 (run with the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel; parser_regex.c:169-254 has no test for being inside a class, unlike the brace case at parser_regex.c:286-289). Write[\*]or[\?]for the literal character.- An alternation defeats the slash rule:
/foo/*needs at least one character after the slash, while/foo/{*,bar}compiles to/foo/([^/\x00]*|bar)and also matches the directory/foo/(same run). - Matching is done on the name the kernel builds for the object at the time of the check. Names that are disconnected or outside the task's root are handled by the
attach_disconnectedfamily of flags: other profile flags.
Read more
for AppArmor developers for security researchers
In the code
?(parser_regex.c:231-254);[and], copied to the output (parser_regex.c:256-280).- The character set grammar of the DFA compiler (parse.y:109-150) and
NotCharSetNode, "match all except one character" (expr-tree.h:683-709).
06 Braces, and variables that become braces
{a,b} matches a or b. A variable with several values expands to {v1,v2}. {a} and {} are errors; {a,} is allowed.
Braces are a choice: cache or state. This rule is line 26 of the example profile, and it also uses a variable. APP_DATA has two values, and the parser rewrites the variable into a brace group of its values before it does anything else with the pattern. So one line covers four directory trees. Alternatives can be nested, can be empty, and can contain slashes and stars. A group does need at least one comma, because without one there's no choice to make. And if you need a real brace in a name, put a backslash in front of it.
Details and sources
Details
{a,b}matchesaorb. An alternative may be empty, may contain/, globs and further brace groups:/a{b,c{d,e}}matches/ab,/acdand/ace;/a{b,}matches/aband/a.- A group needs at least one comma.
{a}and{}are refused withRegex grouping error: Invalid number of items between {};{a,}is accepted. - Groups nest up to 49 levels; the 50th is refused with
Regex grouping error: Exceeded maximum nesting of {}. \{and\}are literal braces,\,a literal comma inside a group:/a{b\,c,d}matches/ab,cand/ad.- A variable is replaced by its values before the pattern is converted. One value is inserted as it is; several become a brace group (variable.cc:252-340).
- With
@{APP_DATA} = /var/lib/demo /srv/demo, the path@{APP_DATA}/{cache,state}/**is expanded to{/srv/demo,/var/lib/demo}/{cache,state}/**and compiled to(/srv/demo|/var/lib/demo)/(cache|state)/[^/\x00][^\x00]*. Printed by the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load -D rule-exprs, nothing loaded into a kernel); the order of the values is the parser's. - Glob characters in a value stay active, and a doubled slash where a value meets the rest of the path is trimmed.
- Expansion applies to rule paths and to link targets (block_rules.cc:399-406).
- An undeclared variable:
Failed to find declaration for: @{NAME}, thenERROR expanding variables for profile NAME, failed to load.
Read more
- apparmor.d(5), Globbing (AARE) and Variables.
- Variables, quoting and escaping.
- The syntax map: the example profile this rule is line 26 of.
for AppArmor developers for security researchers
In the code
{,,and}become(,|and)(parser_regex.c:282-357);MAX_ALT_DEPTHis 50 (parser_regex.c:122); the nesting error is at parser_regex.c:295, the item count error at parser_regex.c:317.variable::expand_by_alternationbuilds the brace group and setsfilter_leading_slashandfilter_trailing_slashfor the joins (variable.cc:252-340).
07 convert_aaregex_to_pcre for AppArmor developers for security researchers
convert_aaregex_to_pcre (parser/parser_regex.c:118-431) emits [^/\x00]* for *, [^\x00]* for ** and a leading [^/\x00] under the slash rule; filter_slashes (parser/parser_regex.c:61-96) runs first.
By the time convert_aaregex_to_pcre runs, variables are expanded and repeated slashes are filtered. The function walks the pattern once. At a star it looks at the last character it wrote: after a slash, and before another slash or the end, it first emits one mandatory non-slash character. That's the slash rule. Then two stars become a run of anything but NUL, and one star a run without slashes. Braces become a group with bars. Brackets are copied through for the regex parser, which is why a negated class can match a slash. The return value says basic, tail glob or regex.
Details and sources
for AppArmor developers for security researchers
Details
- Signature:
pattern_t convert_aaregex_to_pcre(const char *aare, int anchor, int glob, std::string& pcre, int *first_re_pos)(parser_regex.c:118-119; declared at parser.h:460). - Order for a file rule in
process_dfa_entry:filter_slashes(entry->name), thenconvert_aaregex_to_pcre(entry->name, 0, glob_default, tbuf, &pos)(parser_regex.c:658-660). Variables were expanded earlier (block_rules.cc:399-406).anchoris 0 at every call for rules. - The slash rule: when the last character written is
/and the run of stars is followed by/or the end,[^/\x00]is emitted first (parser_regex.c:178-205). **emits[^\x00]*(parser_regex.c:206-221);*emits[^/\x00]*(parser_regex.c:222-226);?emits[^/\x00](parser_regex.c:231-254).globselects the second set of outputs:glob_defaultis 0 andglob_nullis 1 (parser.h:458-459). Withglob_nullthe globs may also match a NUL byte (.*,[^/]*,[^/]); it is used forxattrs=values (parser_regex.c:582-584).- Brackets are copied to the output and parsed later by the regular expression grammar of the DFA compiler (parser_regex.c:256-280, parse.y:109-150).
- Braces:
(,|,), withMAX_ALT_DEPTH50 (parser_regex.c:282-357, parser_regex.c:122). - The return type:
enum class pattern_t { Basic, TailGlob, Regex, Invalid }(immunix.h:139-144).Basichas no glob;TailGlobis a literal followed by one final**; everything else with a glob isRegex. - Error exits and the
Unable to parse input line '%s'message (parser_regex.c:411-431). filter_slashes(parser_regex.c:61-96).- Dump option:
-D rule-exprs, "Dump rule to expr tree conversions" (common_optarg.c:31).
Read more
- From AARE to regular expressions.
- The expression tree.
- Exec modes: where an exact match takes precedence.
- apparmor_parser(8), -D.
08 Patterns the parser refuses
Pattern errors read "Regex grouping error: ..." followed by "Unable to parse input line 'PATTERN'" and name the profile, not the line.
Three pattern mistakes you'll meet: a group with no comma, a group that's left open, and a closing bracket with no opening one. Each gets a regex grouping error. But these are found late, after the whole file has been parsed, so the message has no line number. Instead the parser quotes the pattern back at you: unable to parse input line, then the pattern, and then the profile failed to load. Search your file for the quoted text. One more looks like a pattern problem and isn't: a path can't end in a comma unless you quote it, because the comma ends the rule.
Details and sources
Details
- Messages are from the parser built from the AppArmor tree at 836052d21 (
-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel). /var/lib/demo/{cache} rw,:Regex grouping error: Invalid number of items between {}. Test file: bad_re_brace_3.sd./var/lib/demo/{cache,state rw,:Regex grouping error: Unclosed grouping or character class, expecting close }. An unclosed[gives the same text, also with "expecting close }"./var/lib/demo/cache] rw,:Regex grouping error: Invalid close ], no matching open [ detected.- Each is followed by
Unable to parse input line 'PATTERN'andERROR processing regexs for profile NAME, failed to load, thenERROR generating policy re for profile NAME, failed to loadandErrors found in file. Aborting.. The first two lines are prefixed with the path of the parser program. None has a file name or a line number. - A pattern that ends in a backslash:
Regex error: trailing '\' escape character. This one is from the source and was not run. - A syntax error, by contrast, has the form
AppArmor parser error for FILE in profile FILE at line N: MESSAGE./etc/demo/extra, r,gives one:syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE. - An unquoted path cannot end in a comma:
/foobar, r,fails (bad_comma_1.sd) and"/foobar," r,is accepted (ok_comma_2.sd).
for AppArmor developers for security researchers
In the code
- The messages in
convert_aaregex_to_pcre: close bracket (parser_regex.c:275), item count (parser_regex.c:317), unclosed group or set (parser_regex.c:414), trailing backslash (parser_regex.c:421),Unable to parse input line(parser_regex.c:430). ERROR processing regexs for profile %s, failed to load(parser_regex.c:1277).- There is no line number because the conversion runs after the whole file has been parsed, when the rules are turned into expressions.
09 Where to go from here
Next: syn-variables, syn-quoting, attachment (patterns in profile heads), fe-aare and re-tree (compilation).
You'll use these five constructs in every profile you write. The same patterns appear in the head of a profile, where they decide which programs it attaches to, and in both names of a link rule. Variables and quoting feed into them: one expands into braces, the other lets a name hold a space or a comma. And if you want to know how a pattern becomes something the kernel can match in one pass over the name, follow it into the compiler decks: the conversion, the expression tree, and the kernel's matcher.
Details and sources
Details
*stays inside one path component;**crosses slashes;?is one character and not/;[set]is one character;{a,b}is a choice.- A pattern must match the whole name. A directory's name ends in
/(the kernel, read from the source). [^set]can match/.apparmor_parser -Q -K --skip-kernel-load -D rule-exprs FILEprints what each pattern compiles to.- 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 pattern (-Q -K --skip-kernel-load --warn=all, with -D rule-exprs for the regular expressions), with nothing loaded into a kernel; "ran" means the researcher ran the pattern as recorded in the findings, without the run being repeated for this page; "code" means the parser or kernel source was read, not run. Match verdicts are derived from the regular expression the parser prints. Nothing here was observed on a running kernel.
Grammar
PATTERN: a sequence of
* any run of characters except /, also none
** any run of characters including /, also none
? exactly one character except /
[set] exactly one character of the set; ranges with - ([a-c])
[^set] exactly one character not in the set (this can be /)
{alt,alt} one of the comma-separated alternatives; at least one comma
\c the character c, literally
c any other character, literally
- The pattern language is called AARE, AppArmor regular expressions.
- A pattern matches a name only if it matches the whole name. In mainline Linux 7.4 the kernel walks the complete name and uses the permissions of the state it ends in (code: linux:security/apparmor/match.c:518, linux:security/apparmor/file.c:226-228).
*and**that make up a whole path component must match at least one character: see The slash rules.*,**and?do not treat a leading dot specially./foo/*matches/foo/.hidden(tree).- An alternative may be empty, may contain
/, globs and further brace groups. - AARE is used in rule paths (syn-file-rules), in both names of a link rule (syn-link-rules) and in profile attachments (attachment). Values in
xattrs=(...)use the same syntax with one difference: there the globs may also match a NUL byte (code:glob_null, parser/parser_regex.c:582-587). See syn-xattrs.
Translation table
What apparmor_parser -D rule-exprs prints for each construct in a path (tree; lines in parser/parser_regex.c).
AARE regular expression lines
* [^/\x00]* 221-226
** [^\x00]* 207-220
* or ** right after / and
followed by / or the end [^/\x00] then the above 180-205
? [^/\x00] 231-254
[ ... ] copied unchanged 256-280
{ , } ( | ) 282-357
^ $ outside [ ] \^ \$ 361-368
. + | ( ) escaped with \ 374-379
\* \[ \] \{ \} kept escaped 169-177, 256-309
\? and \, outside [ ] ? and , 232-237, 333-346
\\ \\ 152-167
\ and any other character the character (warning) 382-403
Conversions of the patterns on the slides (tree):
| Pattern | Regular expression |
|---|---|
/etc/demo/* | /etc/demo/[^/\x00][^/\x00]* |
/etc/demo/** | /etc/demo/[^/\x00][^\x00]* |
/etc/demo/*.conf | /etc/demo/[^/\x00]*\.conf |
/etc/demo/**.conf | /etc/demo/[^\x00]*\.conf |
/etc/demo/{,**} | a group of two alternatives: empty, or [^\x00]* |
/var/log/demo-?.log | /var/log/demo-[^/\x00]\.log |
/var/lib/demo/[a-c]* | /var/lib/demo/[a-c][^/\x00]* |
/var/lib/demo/[^.]* | /var/lib/demo/[^\.][^/\x00]* |
/etc//demo///x | /etc/demo/x |
Worked matches
Verdicts are derived from the printed regular expression (tree for the conversion; /a[^b]c, /a[bc]d, /a[b-d]e and the brace rows were also run by the researcher).
| Pattern | Matches | Does not match |
|---|---|---|
/foo/*bar | /foo/bar, /foo/xbar | /foo/x/bar |
/foo/* | /foo/a, /foo/.hidden | /foo/ (the directory), /foo/a/, /foo/a/b |
/foo/*/ | the directories directly in /foo | /foo/, /foo/a |
/a*b | /ab, /axb | /a/b |
/foo/** | /foo/a, /foo/a/, /foo/a/b/c | /foo/, /foo |
/foo** | /foo, /foobar, /foo/, /foo/a/b | /fo |
/**/foo | /a/foo, /a/b/foo | /foo |
/** | every name that starts with / | / itself |
/{**,} | every name that starts with /, and / | names that do not start with / |
/a?c | /abc | /ac, /a/c, /abbc |
/a[bc]d | /abd, /acd | everything else |
/a[b-d]e | /abe, /ace, /ade | everything else |
/a[^b]c | /axc, /a/c | /abc, /ac |
/a{b,c{d,e}} | /ab, /acd, /ace | /ac |
/a{b,} | /ab, /a | /ac |
/a{b\,c,d} | /ab,c, /ad | /ab |
/*** | read as ** then *: the same names as /** | / itself |
The slash rules
- A
*or**that stands directly after a/and is followed by a/or by the end of the pattern must match at least one character (code: parser/parser_regex.c:180-205). The purpose, from the comment in the source:/foo/*should not match/foo/,/*/fooshould not match//foo, and/foo/*barshould still match/foo/bar. - The test looks only at the character written just before the star, so it applies only directly after a literal
/./foo/{*,bar}matches/foo/(tree)./{*,x}/ymatches//y, a name the kernel does not produce (code). - In mainline Linux 7.4 the name of a directory ends in
/, except the root directory (code: linux:security/apparmor/path.c:167-177). A pattern matches a directory only if it can end in/.
| To allow | Write |
|---|---|
| the directory itself (for listing it) | /dir/ r, |
| the directory and everything below | /dir/{,**} r, |
| everything below, not the directory | /dir/** r, |
| the files directly in it | /dir/* r, |
| the directories directly in it | /dir/*/ r, |
Repeated slashes
- Before conversion, runs of
/in a pattern are collapsed to one/(code:filter_slashes, parser/parser_regex.c:61-96)./a//b///c/compiles as/a/b/c/(tree). - A pattern that starts with exactly two slashes keeps them:
//a//bcompiles as//a/b;///usrbecomes/usr. - Trailing slashes are collapsed to one and not removed.
- It runs after variable expansion, on rule paths, link targets and profile attachments.
- It works on the text and does not look inside brace groups:
/a/{/b,c}keeps the inner/and requires//in the name (tree).
Variables in patterns
The variable syntax is in syn-variables. For patterns:
- A variable is replaced by its values before conversion. One value is inserted as it is; several become a brace group
{v1,v2}(code: parser/variable.cc:252-340). - With
@{APP_DATA} = /var/lib/demo /srv/demo, the path@{APP_DATA}/{cache,state}/**is expanded to{/srv/demo,/var/lib/demo}/{cache,state}/**(tree; the order of the values is the parser's). - At the joins a doubled slash is trimmed: with
@{V}=/x/,@{V}/zbecomes/x/z(tree). - Glob characters in a value stay active: with
@{V}=a*b,/@{V}compiles as/a[^/\x00]*b(tree). - A value list counts as one level toward the nesting limit.
- Expansion applies to rule paths and link targets (code: parser/block_rules.cc:399-406). A variable in an exec target is not expanded: see syn-named-transitions.
- An undeclared variable:
Failed to find declaration for: @{NAME}, thenERROR expanding variables for profile NAME, failed to load(tree).
Escapes
| Written | Means |
|---|---|
\* \? \[ \] \{ \} | the literal character |
\, | a literal comma inside a brace group |
\\ | a backslash |
\ and any other character | that character; the backslash is dropped, with a warning of class format that is off by default |
Escape sequences such as \x41 are decoded earlier, by the lexer: see syn-quoting.
Limits
- Brace groups nest up to 49 levels; the 50th is refused (tree;
MAX_ALT_DEPTHis 50, parser/parser_regex.c:122). - A brace group needs at least one comma.
{a}and{}are errors;{a,}is accepted. - Inside brackets
{,}and,are literal. - An unquoted path cannot end in a comma or contain a comma followed by white space, because the comma ends the rule there.
/foobar, r,fails and"/foobar," r,is accepted (parser/tst/simple_tests/file/bad_comma_1.sd, ok_comma_2.sd)./a,b r,is accepted (ran).
Errors and warnings
Syntax errors are printed as AppArmor parser error for FILE in profile FILE at line N: MESSAGE (tree). Pattern errors come from a later stage and have no line number. Each of them is followed by Unable to parse input line 'PATTERN' and ERROR processing regexs for profile NAME, failed to load, and every line is prefixed with the path of the parser program.
| Message | Cause | Example |
|---|---|---|
Regex grouping error: Invalid number of items between {} | a brace group without a comma | /var/lib/demo/{cache} rw, (tree) |
Regex grouping error: Unclosed grouping or character class, expecting close } | a { or a [ that is not closed | /var/lib/demo/{cache,state rw, (tree) |
Regex grouping error: Invalid close ], no matching open [ detected | a ] without a [ | /var/lib/demo/cache] rw, (tree) |
Regex grouping error: Invalid close }, no matching open { detected | a } without a {; printed after the "Invalid number of items" message | /a} r, (ran) |
Regex grouping error: Exceeded maximum nesting of {} | 50 nested brace groups | (tree) |
Regex error: trailing '\\' escape character | the pattern ends in a backslash | (code) |
Character %c was quotedunnecessarily, dropped preceding quote ('\\') character | a warning, class format, off by default; the missing space is in the parser's text | /a\qb r, (ran) |
Failed to find declaration for: @{NAME} then ERROR expanding variables for profile NAME, failed to load | an undeclared variable | @{HOME}/x r, without the tunables (ran) |
syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE | an unquoted path that ends in a comma; a syntax error, with a line number | /etc/demo/extra, r, (tree) |
Known discrepancies
These are defects in the parser at the commit above, not intended behaviour. They are listed so that you can avoid them.
*and?inside brackets are translated as globs instead of being literal./a[?]bcompiles without a message to/a[[^/\x00]]b, which matches/a[]band not/a?b(tree). Write\?outside brackets, and[\*]for a star in a set.- An unclosed
[reports "expecting close }". - The warning text reads "quotedunnecessarily", without the space.
- An empty set fails without a pattern message:
/a[] r,prints onlyERROR processing regexs for profile NAME, failed to load(tree).
for AppArmor developers for security researchers
Code map
pattern_t convert_aaregex_to_pcre(const char *aare, int anchor, int glob,
std::string& pcre, int *first_re_pos)
parser/parser_regex.c:118
| What | Where |
|---|---|
the slash rule (mandatory [^/\x00]) | parser/parser_regex.c:180-205 |
** and the TailGlob classification | parser/parser_regex.c:207-220 |
* | parser/parser_regex.c:221-226 |
? | parser/parser_regex.c:231-254 |
[ and ] | parser/parser_regex.c:256-280 |
{, , and }; MAX_ALT_DEPTH | parser/parser_regex.c:282-357, 122 |
| error exits | parser/parser_regex.c:405-431 |
filter_slashes | parser/parser_regex.c:61-96 |
| the call for a rule path and for a link target | parser/parser_regex.c:659-660, 700-701 |
glob_default (0, paths) and glob_null (1, xattr values) | parser/parser.h:458-459 |
pattern_t: Basic, TailGlob, Regex, Invalid | parser/immunix.h:139-144 |
variable::expand_by_alternation | parser/variable.cc:252-340 |
negated sets: NotCharSetNode | parser/libapparmor_re/expr-tree.h:683-709 |
| the character set grammar | parser/libapparmor_re/parse.y:109-150 |
| unit tests | parser/parser_regex.c:1505-1516, 1576-1671 |
anchoris 0 at every call for rules.Basicmeans the pattern has no glob. Exec conflicts use a different test, made on the expression tree (parser/libapparmor_re/aare_rules.cc:98-105): a rule is exact when it has no star, any-character or negated-set node, so braces and plain sets are exact too: see syn-exec-modes.TailGlobis a literal followed by one final**; everything else with a glob isRegex.- The brackets are copied to the output and parsed by the regular expression grammar of the DFA compiler, which is why a negated set is not limited to one path component. The next steps are in fe-aare and re-tree.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
ATTACHMENT, NAMESPACES, STACKING
- Profile attachment — the same patterns in a profile head
FILE ACCESS
- File rules — the rules the patterns are written in
- Link rules — patterns in both names of a link
PREAMBLE AND REUSE
- Variables — variables that expand into alternatives
PROFILE STRUCTURE
- Quoting and escaping — escapes and paths with spaces
IN PRACTICE · security-sensitive programs
- Writing rules for /sys and /proc — globbing device paths under /sys
IN THE KERNEL
- Matching at run time — how the kernel walks a name
INSIDE THE PARSER
- From AARE to regular expressions — the conversion step in the parser
THE DFA ENGINE · libapparmor_re
- The expression tree — the expression tree built from the result