Comments and line structure
and line structure for application developers for security researchers
How a profile file is divided. Rules end at a comma and not at the end of the line. Braces hold bodies. A hash starts a comment only where a new word could start and hash include is an include. The errors the parser prints for a missing comma or brace.
On the map: profile structure
▶ Watch this deck — 9 scenes, ~7 min
Worth seeing first
- The profile language at a glance — a whole profile, whose rules this deck takes apart
01 Where does a rule end?
Rules end with ,. Bodies are in { }. # starts a comment to the end of the line. include lines and comments take no comma.
Look at demo's profile and ask a simple question: where does one rule end and the next begin? It looks like one rule per line, and that's how everyone writes it. But the parser doesn't read lines. It reads words, and three characters give those words structure. A comma ends a rule. Braces hold a body. A hash starts a comment that runs to the end of the line. And a few lines, like the include, take no comma at all. Most of the time the line picture and the real one agree. This deck is about the places where they don't, because that's where the confusing error messages come from.
Details and sources
Details
- Three structural characters:
,ends a rule,{and}hold a body,#starts a comment that runs to the end of the line. - apparmor.d(5), Comments: "Comments start with # and may begin at any place within a line. The comment ends when the line ends." (apparmor.d.pod:1173-1176).
- The same page says "AppArmor configuration files are line-oriented" (apparmor.d.pod:98-101). For rules the parser is comma-oriented: only comments, include lines and variable assignments depend on line ends.
include <file>and the older#include <file>take no comma.- All of this is the parser's business only. Comments and line structure are gone before the policy is compiled; nothing of them reaches the kernel.
- The profile for
demois invented for the map. Statements about the parser were checked with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel).
Read more
- apparmor.d(5), Comments.
- Profiles quick reference: comments on apparmor.net.
- The syntax map.
for AppArmor developers for security researchers
In the code
END_OF_RULEis[,](parser_lex.l:254) and returnsTOK_END_OF_RULE(parser_lex.l:911-917); the braces returnTOK_OPENandTOK_CLOSE(parser_lex.l:834-836); the comment rule is#.*\r?\n(parser_lex.l:815-818).
02 What ends with what
Comma: every rule, abi, alias. Closing brace: profile, hat, child, qualifier block, if block. End of line: comments, include, variable assignments.
Here's the whole structure in three groups. Rules end with a comma: file rules, network rules, every rule keyword, and also the two preamble lines, abi and alias. Bodies end with a closing brace: profiles, hats, child profiles, qualifier blocks and if blocks, and no comma follows the brace. And three things end with the line itself: comments, include lines, and variable assignments. Those are the only parts of the language that care about line ends. Everywhere else, a new line is white space, no different from a blank.
Details and sources
Details
- Ends with a comma: every rule (file,
network,capability,mount,signal,change_profileand the others), and in the preambleabi <...>,andalias A -> B,. - Ends with
}and no comma: a profile, a hat, a child profile, a qualifier block (deny { },audit { }) and anifblock. - Ends with the line: a comment;
includeand#include; a variable assignment@{X} = ...and a boolean assignment${X} = .... A backslash directly before the new line continues an assignment. - A comma after an assignment is refused:
Variable declarations do not accept trailing commas. - A comma after an include is a syntax error:
include if exists <x>,givessyntax error, unexpected TOK_END_OF_RULE(run with the released parser 5.0.2). \r\nis accepted wherever\nis: dos_line_endings.sd.- A bare
{ }block with no qualifier is accepted, and blocks nest:audit { deny { /x w, } }(5.0.2).
Read more
- apparmor.d(5), FORMAT: the grammar, with the comma written out in each rule.
- apparmor.d(5), Qualifier Blocks.
- Include, variables, qualifier blocks, the preamble.
for AppArmor developers for security researchers
In the code
- Rules that end in
TOK_END_OF_RULEin the grammar:alias(parser_yacc.y:511),abi_rule(parser_yacc.y:1052),change_profile(parser_yacc.y:1648), and so on for every rule class. block: TOK_OPEN rules TOK_CLOSEand its use with qualifiers (parser_yacc.y:738-759).- Assignments: the scanner's
ASSIGN_MODEhas the trailing comma error, a comment rule, the backslash continuation and a new line rule that leaves the state (parser_lex.l:570-588); the boolean form repeats them (parser_lex.l:735-747). - New lines elsewhere only bump the line counter (parser_lex.l:919-924).
03 The comma ends the rule, not the line
New lines are white space inside and between rules. /etc/demo/a,b r, names the path /etc/demo/a,b: a comma followed directly by a word character is part of the word.
To see that lines don't matter, break one. Put the path on one line, the permission on the next, the comma on a third, and start the next rule right after that comma. The parser accepts it: two rules. The other way works too, and you'll see it in real profiles: two short rules on one line. Then the fine print. A comma only ends a rule when something other than a word character follows it. A comma glued to the next letter is part of the word, so a path may contain one. It's rare, and it's why you put a space or a new line after every comma that ends a rule.
Details and sources
Details
- A rule may span lines, and several rules may share a line: new lines are white space inside and between rules (parser built from the AppArmor tree at 836052d21,
-Q -K --skip-kernel-load --warn=all). - A comma ends a rule when a blank, a new line or another comma follows. A comma followed directly by a word character is part of the word.
/foo,bar r,is one rule for the path/foo,bar: ok_comma_1.sd, expected result PASS./foobar, r,fails: bad_comma_1.sd, expected result FAIL. The message issyntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE.- A path that ends in a comma has to be quoted,
"/foobar," r,: ok_comma_2.sd. - A doubled comma,
/etc/demo/** r,,, givessyntax error, unexpected TOK_END_OF_RULE, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. - The permission string of a file rule must be followed by white space or a comma (read from the source).
Read more
- apparmor.d(5), FORMAT.
- Quoting: a comma, a blank or a quote inside a path.
- Globbing: the comma inside
{a,b}.
for AppArmor developers for security researchers
In the code
- A word character is
ID_CHARS,[^ \t\r\n"!,];IDis one such character, or a comma followed by one, or an escape (parser_lex.l:264-266). - White space is skipped in the listed start conditions (parser_lex.l:372-373); new lines are counted at parser_lex.l:919-924.
- Permission strings match only before white space or a comma:
({MODES})/([[:space:],])(parser_lex.l:843).
04 Where a hash is a comment
# begins a comment at the start of a line, after a rule's comma and between the words of file and capability rules. It is not a comment inside a word (/a#b), inside ( ) lists, or inside rules such as signal, network, mount, dbus before their comma.
A hash starts a comment, and the comment runs to the end of the line. But only where the parser could start a new word. At the start of a line, yes. After a rule's comma, yes. Even between the words of a file rule or a capability rule. Inside a word it's just a character: a#b is a file name. And inside a parenthesised list, such as the flags, the parser takes the hash as a value: invalid profile flag, hash. The same goes for the insides of some keyword rules, signal and network for example. So the safe habit is simple: comments on their own line, or after the comma.
Details and sources
Details
Run with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel):
- Comment: at the start of a line; after a rule's comma (
/etc/demo/** r, # configuration); between the words of a file rule or acapabilityrule. - Not a comment: inside a word.
/etc/demo/a#b r,names the path/etc/demo/a#b. - Not a comment: inside a
( )list.flags=(complain # for nowgivesInvalid profile flag: #. - Not a comment: inside a keyword rule before its comma.
signal send # whygivessyntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE. The rules affected arenetwork,signal,ptrace,dbus,unix,mount,change_profile,rlimit,mqueue,usernsandabi. - Not a comment: directly after
profile,hat,^or->.profile #demo { }defines a profile named#demo. - After a variable assignment a
#is a comment and also ends the assignment:@{X} = /a /b # tail(run with the released parser 5.0.2). - A comment on the last line of a file needs its final new line; without it:
Lexer found unexpected character: '#' (0x23) in state: INITIAL. apparmor_parser -p(--preprocess, "Dump preprocessed profile") echoes comments to its output (parser_main.c:262, read from the source).
Read more
for AppArmor developers for security researchers
In the code
- The comment rule
#.*\r?\nexists in the scanner'sINITIALstate (parser_lex.l:815-818) and in the two assignment states (parser_lex.l:576-580, parser_lex.l:735-739). The list state,SUB_ID(parser_lex.l:456-461) and the rule states have none. - Rule keywords push their own start condition (parser_lex.l:856-909) and the comma pops it (parser_lex.l:911-917).
#is an ordinary word character:ID_CHARSdoes not exclude it (parser_lex.l:264).ID_FIRST_CHARSat parser_lex.l:262 does, but no other definition uses it.Invalid profile flag: %s.is at profile.h:261.
05 Hash include is not a comment
#include <file> is an include (deprecated spelling; warning class pound-include, off by default). # include <file> and ##include <file> are comments.
One exception to remember. In old profiles, includes were written with a hash in front: #include, like in C. The parser still accepts that. So a line that starts with #include isn't a comment, it's an include. That bites when you try to disable an include by putting a hash in front of it: nothing changes, the file is still pulled in. Put a space between the hash and the word, or use two hashes, and it really is a comment. The parser can tell you about the old spelling, deprecated use of #include, but only if you turn that warning on.
Details and sources
Details
#include <file>, with no blank after the hash, is an include.# include <file>and##include <file>are comments (parser built from the AppArmor tree at 836052d21).- apparmor.d(5): "The exception to this rule is that #include will include the contents of a file inline to the policy; this behaviour is modelled after cpp(1)" (apparmor.d.pod:98-101).
- The old spelling is deprecated. The warning is
Warning from FILE (FILE line N): deprecated use of '#include'. - Its warning class is
pound-include, "warn when #include is used" (parser_main.c:295). Turn it on with--warn=pound-includeor--warn=all; it is not in the default set (parser.h:77-78).apparmor_parser --help=warnlists the classes. - The pattern is not tied to the start of a line:
/a r, #include <x>performs the include after the rule (run with the released parser 5.0.2). - A comment may follow the file name on the same line: ok_27.sd.
- There is no word boundary after
#include: a comment that begins#included by handis read as an include of the filedand fails withCould not open 'd'(tree parser). - Old-style includes in the parser's own tests: new_style1.sd.
Read more
for AppArmor developers for security researchers
In the code
- The four patterns, in order:
#include if exists,include if exists,#include,include; the two with a hash callpwarn(WARN_INCLUDE, ...)(parser_lex.l:781-809). They precede the comment rule (parser_lex.l:815-818) and match the same length, so flex takes the earlier rule. - The file name is read in the
INCLUDEandINCLUDE_EXISTSstates (parser_lex.l:376-397).
06 Braces open bodies, unless they are inside a word
A { or } that stands alone delimits a body; bodies nest and take no trailing comma. Inside a word, {a,b} is a pattern. profile demo{ fails because the brace is read as part of the name.
Braces do two unrelated jobs, and the parser tells them apart by one thing: is the brace a word by itself, or is it inside a word? Standing alone, it opens or closes a body. The profile, a qualifier block like deny, a hat. Bodies nest, and no comma follows the closing brace. Inside a word, as in the path with {cache,state}, braces are a pattern: either of these. The commas in there don't end the rule either. This is why you need a space before an opening brace. Write profile demo and the brace with no space, and the brace becomes part of the name.
Details and sources
Details
- A
{or}that stands alone opens or closes a body. Bodies nest. No comma follows the closing brace. - Inside a word,
{a,b}is a pattern of alternatives, and its commas do not end the rule:/var/lib/demo/{cache,state}/** rw,. profile demo{fails withsyntax error, unexpected TOK_MODE, expecting TOK_OPEN: without a blank the brace is read as part of the name (parser built from the AppArmor tree at 836052d21,-Q -K --skip-kernel-load --warn=all).- The opening brace may sit on a later line than its head: new_style3.sd has
^HAT2on one line and{ /var/log/HAT2 rwl, }on the next. - A missing
}givessyntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VAR; one too many givessyntax error, unexpected TOK_CLOSE, expecting end of file. - A qualifier block may carry
audit,denyandownerbut not a priority:priority=1 { /a r, }givespriority is not allowed on rule blocks(block.h:46-52). - Known discrepancy: the word
openis accepted in place of{, as inprofile demo /usr/bin/demo open(tree parser). There is no closing counterpart and no diagnostic.
Read more
for AppArmor developers for security researchers
In the code
OPEN_BRACEandCLOSE_BRACE(parser_lex.l:249-250) returnTOK_OPENandTOK_CLOSEin theINITIALstate (parser_lex.l:834-836) and afterif(parser_lex.l:725-727). Braces are not excluded fromID_CHARS(parser_lex.l:264), so inside a word they stay in the word.- Bodies in the grammar:
profile_base: ... TOK_OPEN rules TOK_CLOSE(parser_yacc.y:391-399);block: TOK_OPEN rules TOK_CLOSE(parser_yacc.y:738-759). - Alternation is converted to a regular expression in
convert_aaregex_to_pcre(parser_regex.c:282-330).
07 The scanner states behind the structure for AppArmor developers for security researchers
Comment rule #.*\r?\n in INITIAL, ASSIGN_MODE, ASSIGN_EXPR_MODE only. #include rules precede it. {END_OF_RULE} pops rule-specific states. Known discrepancy: open yields TOK_OPEN, the token of {.
A comment is a pattern, hash to the end of the line, and it exists in three start conditions only: initial and the two assignment states. The #include patterns sit before it and match the same length, so flex picks them first. Rule keywords push their own states, which have no comment rule, and pop back to initial at the comma. The state SUB_ID, entered after profile, hat and caret, has neither a comment rule nor a white space rule. One oddity: the keyword table maps the word open to the same token as an opening brace, so in the initial state the word open acts as a brace.
Details and sources
for AppArmor developers for security researchers
Details
- Definitions:
OPEN_BRACE,CLOSE_BRACE,END_OF_RULE(parser_lex.l:249-254);ID_FIRST_CHARS,ID_CHARS,ID,IDS(parser_lex.l:262-267). - The comment rule
#.*\r?\nappears three times:INITIAL(parser_lex.l:815-818),ASSIGN_MODE(parser_lex.l:576-580) andASSIGN_EXPR_MODE(parser_lex.l:735-739). In the assignment states it also callsPOP(). - The four include patterns precede it (parser_lex.l:781-809); the
#includeones use trailing context/.*\r?\n, so their match is as long as the comment's and the earlier rule wins. - Keyword lookup:
get_keyword_token(yytext), thenPUSH_AND_RETURN(state, token)with a rule-specific state (parser_lex.l:856-909).{END_OF_RULE}returnsTOK_END_OF_RULEand pops when the state is notINITIAL(parser_lex.l:911-917). SUB_IDis absent from the white space rule's condition list (parser_lex.l:372-373); its only rule takes{IDS}or a quoted string and pops (parser_lex.l:456-461). A new line there reaches the catch-allLexer found unexpected character: '%s' (0x%x) in state: %s(parser_lex.l:930).keyword_table(parser_misc.c:81-138) has{"open", TOK_OPEN}at parser_misc.c:131.TOK_OPENis declared once (parser_yacc.y:82) and is also theopenpermission ofmqueuerules (parser_yacc.y:1566).- State names in messages come from
state_names[YY_START];apparmor_parser -pprints whatDUMP_PREPROCESSechoes.
Read more
- The lexer, the grammar.
- apparmor_parser(8):
-p,--preprocess.
08 What a missing comma looks like
"missing an end of line character? (entry: PATH)" is a missing comma after the rule for PATH, reported at the next rule. In syntax errors TOK_END_OF_RULE is the comma, TOK_OPEN and TOK_CLOSE are braces.
Finally, what broken structure looks like. Forget the comma between two file rules and the parser asks, in its own words, whether you're missing an end of line character. It means the comma, and it reports the line of the next rule, because that's where it noticed. Forget the comma on the last rule and you get a plain syntax error at the closing brace instead. A comma after a variable assignment is refused by name. A missing closing brace is unexpected end of file. One brace too many is unexpected TOK_CLOSE, expecting end of file. Read TOK_END_OF_RULE as comma, TOK_OPEN and TOK_CLOSE as braces, and these messages become readable.
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.
- Missing comma between two file rules:
missing an end of line character? (entry: PATH). PATH is the rule that lacks the comma; the line is that of the next rule. File rules only: other rule classes give a generic syntax error. - Missing comma on the last rule of a body:
syntax error, unexpected TOK_CLOSE, expecting TOK_END_OF_RULE. - Comma after an assignment,
@{X} = /a,:Variable declarations do not accept trailing commas. - Missing
}:syntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. Fixture: simple_bad_no_close_brace1.sd. - One
}too many:syntax error, unexpected TOK_CLOSE, expecting end of file. - Missing
{: fixture simple_bad_no_opening_brace1.sd, expected result FAIL. - Token names in these messages:
TOK_END_OF_RULEis the comma,TOK_OPENis{,TOK_CLOSEis}. - A body cannot be closed and continued later: a second top-level profile of the same name gives
Multiple definitions for profile NAME exist,bailing out.(parser_policy.c:60-66).
Read more
for AppArmor developers for security researchers
In the code
- The message is an error production:
file_rule_tail: opt_exec_mode id_or_var file_perms id_or_varcallsyyerror(_("missing an end of line character? (entry: %s)"), $2)(parser_yacc.y:1132-1139). - The trailing comma error for assignments is in the scanner (parser_lex.l:570-574); the unexpected character message at parser_lex.l:930.
09 Around line structure
Inside words: syn-globbing, syn-quoting. Blocks: syn-qualifier-blocks, syn-hats. Includes: syn-include. Assignments: syn-variables. The scanner: fe-lexer.
Each of these three characters has a second life. Commas and braces inside a path are pattern syntax, in the globbing deck. A path that needs a real comma, a space or a quote is the quoting deck, right next door. Braces after a qualifier are qualifier blocks, and bodies inside bodies are hats. The include line has its own deck too. Variable assignments, the other line-ended construct, have theirs. And if the scanner states made you curious, the lexer deck walks through them.
Details and sources
Details
,ends a rule,{ }hold a body,#starts a comment to the end of the line.- Only comments, include lines and variable assignments end with the line.
#includewith no blank after the hash is an include, not a comment.- None of this reaches the kernel: it is handled by apparmor_parser before compilation.
- Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2).
Read more
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, nothing loaded into a kernel); "5.0.2" means the released parser 5.0.2 was run; "code" means the parser source was read, not run. Comments and line structure exist only in the parser: nothing of them reaches the kernel.
Structure
FILE: { PREAMBLE-LINE | PROFILE | COMMENT }
PROFILE: HEAD '{' BODY '}'
BODY: { RULE ',' | BLOCK | PROFILE | HAT | INCLUDE | COMMENT }
BLOCK: [ QUALIFIERS ] '{' BODY '}'
COMMENT: '#' text to the end of the line
| Construct | Ends with |
|---|---|
every rule (file, network, capability, mount, signal, change_profile and the others) | , |
abi <...>, and alias A -> B, in the preamble | , |
| a profile, a hat, a child profile | } with no comma after it |
a qualifier block (deny { }, audit { }) and an if block | } with no comma after it |
| a comment | the end of the line |
include and #include | the end of the line; no comma |
a variable assignment @{X} = ... and a boolean assignment ${X} = ... | the end of the line; a backslash directly before the new line continues it |
- Outside the last three rows a new line is white space. One rule may span several lines and several rules may share a line (tree).
- A bare
{ }block with no qualifier is accepted, and blocks nest:audit { deny { /x w, } }(tree). - An opening brace may sit on a later line than its head (
parser/tst/simple_tests/change_hat/new_style3.sd). - The include line: syn-include. Assignments: syn-variables. Qualifier blocks: syn-qualifier-blocks. Hats: syn-hats.
Characters
| Character | Where it is structure | Where it is part of a word |
|---|---|---|
, | ends a rule when a blank, a new line or another , follows | when a word character follows directly: /etc/demo/a,b r, is one rule for the path /etc/demo/a,b (tree); inside {a,b} it separates alternatives; inside a quoted string ("/foobar," r,) |
{ } | standing alone: open and close a body | inside a word: a pattern of alternatives, see syn-globbing; profile demo{ reads the brace as part of the name |
# | starts a comment in ordinary rule text and in assignments | inside a word (/etc/demo/a#b); directly after profile, hat, ^ or ->; inside ( ) lists; inside the keyword rules listed under Comments |
| new line | ends a comment, an include line and an assignment | white space everywhere else; not accepted directly after profile, hat or ^ |
\r\nis accepted wherever\nis (parser/tst/simple_tests/file/dos_line_endings.sd). A carriage return that is not followed by a line feed is a lexer error (5.0.2).- The permission string of a file rule must be followed by white space or a comma (code).
- A path that needs a comma at its end, a blank or a quote: syn-quoting.
Comments
A # is a comment where the parser could start a new word:
| Place | Example | Result | Basis |
|---|---|---|---|
| the start of a line | # demo: a small network service | comment | tree |
| after a rule's comma | /etc/demo/** r, # configuration | comment | tree |
between the words of a file rule or a capability rule | capability # why then chown, on the next line | comment | tree |
| after a variable assignment | @{X} = /a /b # tail | comment; it also ends the assignment | tree |
| inside a word | /etc/demo/a#b r, | the path /etc/demo/a#b | tree |
inside a ( ) list | flags=(complain # for now | Invalid profile flag: #. | tree |
| inside a keyword rule, before its comma | signal send # why | syntax error | tree |
directly after profile, hat, ^, -> | profile #demo { } | a profile named #demo; known discrepancy, see below | tree |
- The keyword rules whose inside is not comment-safe:
network,signal,ptrace,dbus,unix,mount,change_profile,rlimit,mqueue,userns,abi. A comment after the comma of such a rule is fine. - The safe habit: a comment on its own line, or after a rule's comma.
apparmor_parser -p(preprocess) echoes comments to its output (code).- The parser gives no meaning to the text of a comment. The metadata that tools and the test harness keep there (
# Last Modified:,#=DESCRIPTION,#=EXRESULT) is a plain comment to it.
#include
The scanner tries these four patterns, in this order, before the comment pattern:
| Pattern | Meaning |
|---|---|
#include if exists FILE | include, old spelling |
include if exists FILE | include |
#include FILE | include, old spelling |
include FILE | include |
#includewith no blank after the hash is an include, not a comment. Putting one hash in front of anincludeline does not switch it off.# include <file>and##include <file>are comments (tree).- The old spelling is deprecated. The warning is
Warning from FILE (FILE line N): deprecated use of '#include'. Its class ispound-include: turn it on with--warn=pound-includeor--warn=all. It is not in the default set, and warnings are not printed with-Nor-q. - The pattern is not anchored to the start of a line:
/a r, #include <x>performs the include after the rule (tree). - A comment may follow the file name on the same line (
parser/tst/simple_tests/include_tests/ok_27.sd). - No comma follows an include:
include if exists <x>,is a syntax error (tree). - Search path, directories and
if exists: syn-include. The warning options: adm-parser.
Errors and warnings
Errors are printed as AppArmor parser error for FILE in profile FILE at line N: MESSAGE (tree). The line is where the parser noticed the problem, often one line after the mistake.
| Message | Cause |
|---|---|
missing an end of line character? (entry: PATH) | a missing comma between two file rules; PATH is the rule that lacks it; reported at the line of the next rule. File rules only: other rule classes give a generic syntax error |
syntax error, unexpected TOK_CLOSE, expecting TOK_END_OF_RULE | a missing comma on the last rule of a body |
syntax error, unexpected TOK_END_OF_RULE, expecting TOK_ID or TOK_MODE or TOK_SET_VAR | a doubled comma: /etc/demo/** r,, |
syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE | a comma right after a path: /etc/demo/c, r, (parser/tst/simple_tests/file/bad_comma_1.sd) |
syntax error, unexpected TOK_END_OF_RULE | a comma after an include line (5.0.2) |
Variable declarations do not accept trailing commas | @{X} = /a, |
syntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VAR | a missing } |
syntax error, unexpected TOK_CLOSE, expecting end of file | one } too many |
syntax error, unexpected TOK_MODE, expecting TOK_OPEN | no blank before {: profile demo{ |
Invalid profile flag: #. | a comment inside a flags=( ) list |
syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE | a comment inside a signal rule |
Lexer found unexpected character: 'C' (0xNN) in state: STATE | a # on a last line that has no final new line; a new line directly after profile; a carriage return without a line feed |
priority is not allowed on rule blocks | priority=1 { /a r, } |
Multiple definitions for profile NAME exist,bailing out. | a second top-level profile of the same name; a body cannot be closed and continued later |
Could not open 'FILE' | an include, also one written as #include, names a file that is not found |
warning: deprecated use of '#include' | the old spelling, with --warn=pound-include |
In syntax errors TOK_END_OF_RULE is the comma, TOK_OPEN is { and TOK_CLOSE is }.
Known discrepancies
These are things the parser does that do not look like intended design. They are described as behaviour, not as features to rely on.
- The word
openis accepted in place of{:profile demo /usr/bin/demo open, a rule and}is accepted (tree). There is no closing counterpart, and no diagnostic. No valid profile changes meaning. #includehas no word boundary: a comment that begins#included by handis read as an include of the filedand fails withCould not open 'd'(tree).- A comment on the last line of a file needs its final new line; without it the parser stops with
Lexer found unexpected character: '#' (0x23) in state: INITIAL(tree). By the pattern the same holds for a#includeline (code). - A name may begin with
#afterprofile,hat,^and->:profile #demo { }defines a profile named#demo(tree). - apparmor.d(5) says "AppArmor configuration files are line-oriented". For rules the parser is comma-oriented; only comments, include lines and assignments depend on line ends.
- Line numbers in error messages are too low after a quoted string that contains a new line: see syn-quoting.
for AppArmor developers for security researchers
Code map
| What | Where |
|---|---|
OPEN_BRACE, CLOSE_BRACE, END_OF_RULE definitions | parser/parser_lex.l:249-254 |
ID_CHARS, ID, IDS: a word excludes blank, tab, CR, LF, ", ! and ,; , followed by a word character is part of the word | parser/parser_lex.l:262-267 |
white space skipped, per start condition (SUB_ID is not in the list) | parser/parser_lex.l:372-373 |
INCLUDE, INCLUDE_EXISTS: the file name | parser/parser_lex.l:376-397 |
SUB_ID, SUB_ID_WS: the name after profile, hat, ^, -> | parser/parser_lex.l:456-461 |
ASSIGN_MODE: trailing comma error, comment with POP(), backslash continuation, new line with POP() | parser/parser_lex.l:570-588 |
EXPR_MODE: { after if | parser/parser_lex.l:725-727 |
ASSIGN_EXPR_MODE: comment, continuation, new line | parser/parser_lex.l:735-747 |
the four include patterns, with pwarn(WARN_INCLUDE, ...) | parser/parser_lex.l:781-809 |
the comment rule #.*\r?\n in INITIAL | parser/parser_lex.l:815-818 |
{ and } return TOK_OPEN and TOK_CLOSE | parser/parser_lex.l:834-836 |
| keyword lookup; rule keywords push their own start condition | parser/parser_lex.l:856-909 |
{END_OF_RULE} returns TOK_END_OF_RULE and pops a rule state | parser/parser_lex.l:911-917 |
| new lines counted | parser/parser_lex.l:919-924 |
Lexer found unexpected character | parser/parser_lex.l:930 |
keyword_table, with "open" mapped to TOK_OPEN | parser/parser_misc.c:81-138 (131) |
profile_base: TOK_OPEN rules TOK_CLOSE; the include cache is saved at { and restored at } | parser/parser_yacc.y:391-399, 453-455 |
block: TOK_OPEN rules TOK_CLOSE and its use with qualifiers | parser/parser_yacc.y:738-759 |
file_rule_tail: the "missing an end of line character?" production | parser/parser_yacc.y:1132-1139 |
Invalid profile flag | parser/profile.h:261 |
priority is not allowed on rule blocks | parser/block.h:46-52 |
Multiple definitions for profile | parser/parser_policy.c:60-66 |
warning class pound-include; the default warning set | parser/parser_main.c:295; parser/parser.h:77-78 |
- flex takes the longest match and, for equal length, the earlier rule. The
#includepatterns and the comment pattern both run to the end of the line, so the earlier#includerules win. - The comment rule exists in
INITIAL,ASSIGN_MODEandASSIGN_EXPR_MODEonly.LIST_VAL_MODE,SUB_IDand the rule states (NETWORK_MODE,SIGNAL_MODEand the others) have none. ID_FIRST_CHARS(parser/parser_lex.l:262) excludes#but no other definition uses it;ID_FIRSTis built fromID_CHARS. This is why a name may begin with#.TOK_OPENis also theopenpermission ofmqueuerules (parser/parser_yacc.y:1566); inMQUEUE_MODEthe scanner has its own rule for the word, so thekeyword_tableentry only has an effect inINITIAL.- The scanner as a whole: fe-lexer.
Roads from here
START HERE
- The profile language at a glance — the three habits on one slide
FILE ACCESS
- Globbing (AARE) — braces and commas inside a path
PREAMBLE AND REUSE
QUALIFIERS
- Qualifier blocks — braces after a qualifier
PROFILE STRUCTURE
- Quoting and escaping — commas and spaces and hashes inside a quoted path
- Hats — bodies inside bodies
RUNNING THE PARSER
- Running apparmor_parser (no slides yet) — the warn options mentioned here
INSIDE THE PARSER
- The lexer — the scanner states behind these rules