The grammar

parser_yacc.y for AppArmor developers for security researchers for application developers

The bison grammar turns tokens into objects in one pass. A file is a preamble and a list of profiles. Inside a profile every line is one alternative of the rules symbol and ends by adding to a block. Qualifiers are four slots in a fixed order. The first error ends the run with a line number and bison's token names.

On the map: inside the parser

▶ Watch this deck — 8 scenes, ~6 min

Worth seeing first

Part of journeys

01 Tokens in, objects out

THE GRAMMAR TOK_ID TOK_MODE TOK_END_OF_RULE tokens from the scanner the grammar · parser_yacc.y Profile name demo attachment /usr/bin/demo block: three entries /etc/demo/** r @{HOME}/.ssh/** rw deny, audit /usr/bin/[a-z]* ix one pass no syntax tree in between the first error ends the run for people who work on the parser; one scene for anyone reading a syntax error
Tokens flow into the grammar, which builds a Profile object named demo with an attachment and a block of three entries; a note says one pass and the first error ends the run

yyparse(), generated from parser/parser_yacc.y, consumes the scanner's tokens and builds Profile objects directly in its actions. The first error calls exit(1).

The scanner hands over tokens; something has to decide what they add up to. That's the grammar: about nineteen hundred lines of bison rules, each with a piece of code attached. When a run of tokens matches a rule, its code runs and builds something: a rule entry, a block, and at the closing brace, a profile object. It's one pass, with no syntax tree in between, and the first mistake ends the run. This deck walks the grammar's shape, then follows one of demo's rules until it's an object in memory. It's for people who work on the parser. The scene on syntax errors is for anyone.

Details and sources

Details

  • The grammar is parser/parser_yacc.y, 1906 lines; bison generates yyparse() from it. process_profile() calls it once per policy file (parser_main.c:1353).
  • An action is the C++ code in braces after a grammar rule. It runs when the rule has been matched, and its result ($$) is the value of the rule's symbol: a struct cod_entry *, a block *, a Profile * and so on (the %union, parser_yacc.y:213-254).
  • There is no separate syntax tree: the objects built here are the ones that post-processing and the backend work on.
  • Errors go through yyerror, which prints one message and calls exit(1) (parser_yacc.y:1748-1757). The grammar has no error recovery.
  • The profile followed in this deck (file demo3.sd):
abi <abi/5.0>,
include <tunables/global>
profile demo /usr/bin/demo {
  /etc/demo/** r,
  audit deny @{HOME}/.ssh/** rw,
  /usr/bin/[a-z]* ix,
}
  • Output shown here is from the parser built from the AppArmor tree at 836052d21, run with -Q -K (nothing loaded into a kernel, no cache) and the tree's abi/5.0 feature set.

Read more

02 A file is a preamble, then profiles for AppArmor developers for security researchers

list: preamble profilelist abi <abi/5.0>,include <tunables/global>profile demo /usr/bin/demo {/etc/demo/** r,audit deny @{HOME}/.ssh/** rw,/usr/bin/[a-z]* ix,} preamble alias | varassign | abi_rule include is gone: the scanner pulled the file in action: choose the policy feature set profile opt_profile_flag profile_base the flag is nothing, profile, hat or ^ profile_base TOK_IDnameopt_id_or_varattachmentopt_cond_listxattrs=( )identitiesidentitiesflagsflags=( )TOK_OPEN{rulesbodyTOK_CLOSE} hat and local_profile are the same profile_base with another keyword in front
The demo profile with its first two lines marked as the preamble and the rest as a profile; an action between them chooses the policy feature set; below, the eight parts of profile_base: name, attachment, xattrs, identities, flags, open brace, rules, close brace

list: preamble profilelist (parser/parser_yacc.y:345). The policy feature set is chosen in the action between the two. profile_base (391) is shared by profiles, hats and child profiles.

From the top, a policy file is two things in a fixed order: a preamble, then a list of profiles. So an assignment after the first profile is a syntax error. The preamble holds variable assignments, aliases and ABI lines. The include line isn't there; the scanner already dealt with it, and the variables it brought in arrive as more preamble. Between the two parts sits a small action that settles which feature set the policy is written for. A profile is then an optional keyword and a profile_base: name, optional attachment, conditions, flags, and a body in braces. Hats and child profiles reuse that same base.

Details and sources

Details

  • list: preamble { ... } profilelist (parser_yacc.y:345-371). preamble is any sequence of alias, varassign and abi_rule (parser_yacc.y:506-509); profilelist is any number of profile (parser_yacc.y:373-379).
  • The action in the middle picks the policy feature set: the override from the command line, else the abi rule already seen, else the pinned features, else the built-in default with the warning File 'NAME' missing feature abi, falling back to default policy feature abi (parser_yacc.y:346-370).
  • An assignment after a profile: syntax error, unexpected TOK_SET_VAR, expecting end of file. An assignment inside a profile: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE (both run with the tree's parser).
  • profile: opt_profile_flag profile_base (parser_yacc.y:460-478); the flag is empty, TOK_PROFILE or hat_start (parser_yacc.y:381-383).
  • profile_base: TOK_ID opt_id_or_var opt_cond_list identities flags TOK_OPEN rules TOK_CLOSE (parser_yacc.y:391-458).
  • hat: hat_start profile_base (parser_yacc.y:490-504) and local_profile: TOK_PROFILE profile_base (parser_yacc.y:480-488) appear as alternatives of rules.
  • varassign covers the four operators =, +=, ?= and := through assign_op, once for set variables and once for boolean variables (parser_yacc.y:519-570).
  • An abi rule is also accepted inside a profile body (parser_yacc.y:722).

03 Every line adds to a block for AppArmor developers for security researchers

rules: rules ... block new block() rules opt_prefix ruleadd_entry rules opt_prefix change_profileadd_entry file and link rules entries cod_entry list rules opt_prefix prefix_ruleadd_rule rules opt_prefix network_ruleadd_rule mount dbus signal ptrace unix userns mqueue io_uring all rule_ents vector of rule_t * rules opt_prefix capabilityadd_capabilities rules TOK_SET TOK_RLIMIT ...add_rlimit bit masks, limits no objects rules opt_prefix blockadd_subblock rules hat | rules local_profileadd_hat rules cond_ruleadd_cond_set sub-blocks, hats, conditions
The alternatives of the grammar symbol rules on the left, each with the block method its action calls: add_entry for file, link and change_profile rules, add_rule for the rule classes, add_capabilities, add_rlimit, add_subblock, add_hat and add_cond_set; a block on the right with three storage areas

rules (parser/parser_yacc.y:713-859) is left-recursive. File, link and change_profile rules become cod_entry list items; other classes become rule_t objects; capabilities are a bit mask.

Inside the braces everything is one grammar symbol called rules, and it's defined in terms of itself: rules is rules plus one more thing. It starts empty, as a new block object. Every line you write matches one of eleven alternatives, and nearly all end the same way, by adding to that block. File and link rules, and change_profile, go into an old linked list of entries. Signal, mount, D-Bus and the newer classes are objects that go into a vector. Capabilities aren't objects, just bits in a mask. Nested blocks, hats, child profiles and conditionals hang off the block. So a rule is stored in one of three ways.

Details and sources

Details

  • The alternatives of rules and what each action does:
AlternativeLinesAction
emptyparser_yacc.y:713-720new block()
rules abi_ruleparser_yacc.y:722nothing more
rules opt_prefix ruleparser_yacc.y:724-736entry_add_prefix, add_entry; rule is file_rule or link_rule
rules opt_prefix blockparser_yacc.y:743-759subblock->add_prefix, add_subblock
rules opt_prefix network_ruleparser_yacc.y:761-783add_prefix, a unix_rule for each AF_UNIX entry, add_rule, add_compat_net
rules opt_prefix prefix_ruleparser_yacc.y:795-802add_prefix, add_rule; the classes are listed at parser_yacc.y:785-793
rules opt_prefix change_profileparser_yacc.y:804-819owner refused, generic_add_prefix, add_entry
rules opt_prefix capabilityparser_yacc.y:821-825add_capabilities
rules hatparser_yacc.y:827-834add_hat
rules local_profileparser_yacc.y:836-843add_hat
rules cond_ruleparser_yacc.y:845-850add_cond_set
rules TOK_SET TOK_RLIMIT TOK_ID TOK_LE TOK_VALUE opt_id TOK_END_OF_RULEparser_yacc.y:852-859add_rlimit
  • block_rules::add_entry puts the entry at the head of a singly linked list; add_rule appends to a vector (block_rules.cc:23-36). The other methods are in block.cc:112-175.
  • A block in braces inside a profile is TOK_OPEN rules TOK_CLOSE, the same rules symbol again (parser_yacc.y:738-741); cond_rule is if, else if and else around such blocks (parser_yacc.y:862-900).
  • The condition of an if is evaluated in the grammar action, while parsing (parser_yacc.y:872-886); both branches stay attached to the block.

04 Qualifiers are four slots in a fixed order for AppArmor developers for security researchers

opt_prefix priority=Nauditallow | deny | promptowner | other audit deny @{HOME}/.ssh/** rw, audit allow | deny | prompt file entry entry_add_prefix: masks the owner or other half of the permissions rule object add_prefix: stores them and checks for conflicts block add_prefix on every entry and rule inside wrong order: the grammar refuses owner audit /etc/demo/** r, syntax error, unexpected TOK_AUDIT, expecting TOK_ID or TOK_MODE or TOK_SET_VAR a conflict: the rule refuses audit deny { allow /etc/demo/** r, } conflicting mode prefix
Four qualifier slots in order: priority, audit, allow or deny or prompt, owner or other; the rule audit deny fills the second and third; three ways the prefix is applied; two error examples, a wrong order and a conflict inside a block

opt_prefix: opt_priority opt_audit_flag opt_rule_mode opt_owner_flag (parser/parser_yacc.y:705). Order mistakes are syntax errors; conflicts are found by add_prefix.

Most alternatives begin with the same symbol: an optional prefix. It has four slots in a fixed order: priority, audit, then allow, deny or prompt, then owner or other. Demo's deny rule fills the second and third. The grammar only collects them; the rule decides what they mean. A file entry masks its permissions for owner. A rule object checks for conflicts. A block pushes its prefix down to everything inside. So mistakes come in two kinds. Write the qualifiers in another order and the grammar refuses: a syntax error. Put allow inside a deny block and the grammar is content, but the rule reports a conflicting mode prefix.

Details and sources

Details

  • opt_prefix: opt_priority opt_audit_flag opt_rule_mode opt_owner_flag fills a struct prefixes with priority, audit, rule_mode and owner (parser_yacc.y:705-711). Each part may be empty (parser_yacc.y:677-703).
  • Six alternatives of rules begin with opt_prefix: rule, block, network_rule, prefix_rule, change_profile and capability. An abi rule, a hat, a child profile, a conditional and set rlimit take no prefix: audit set rlimit nofile <= 10, is syntax error, unexpected TOK_SET, expecting TOK_ID or TOK_MODE or TOK_SET_VAR (run with the tree's parser).
  • opt_priority converts the number and checks the range -1000 to 1000 (parser_yacc.y:677-691).
  • Applying a prefix: - file and link entries: entry_add_prefix (parser_misc.c:1147-1160) calls generic_add_prefix (parser_misc.c:1109), keeps the owner or the other half of the permissions, and checks the exec qualifiers; - rule objects: prefix_rule_t::add_prefix (rule.h:381-440); - blocks: block::add_prefix applies the prefix to every entry and rule in the block and its sub-blocks (block.cc:273-283, block_rules.cc:612).
  • Messages of add_prefix: priority levels not supported, conflicting audit prefix, conflicting mode prefix, conflicting owner prefix (rule.h:392-422).
  • deny without audit sets the audit field to "implied", which is how a deny rule is quiet; audit deny resets it (rule.h:428-440).
  • A change_profile rule refuses owner in its grammar action: owner conditional not allowed on change_profile rules (parser_yacc.y:812-813).
  • The two messages on the slide are the text after the header AppArmor parser error for FILE in profile FILE at line N:. The conflict is reported at the line of the block's closing brace, where the action runs.
  • Output shown here is from the parser built from the AppArmor tree at 836052d21, run with -Q -K (nothing loaded into a kernel, no cache) and the tree's abi/5.0 feature set.
  • Known discrepancies, by title: "Priority below the minimum is reported with \">\""; "priority= on a rule inside a block is refused for every rule class except file rules"; "A deny block around an audit deny rule drops the audit".

05 One rule becomes one entry for AppArmor developers for security researchers

ONE RULE BECOMES ONE ENTRY /etc/demo/** r, TOK_ID TOK_MODE TOK_END_OF_RULE file_perms parse_perms("r") = 0x10004 read for owner, read for other frule do_file_rule(id, perms, NULL, NULL) new_entry(id, perms, NULL) struct cod_entryname "/etc/demo/**"perms 0x10004rule_mode unspecifiedaudit unspecifiedpriority 0pattern_type Invalid name is still a glob: not converted yet rules entry_add_prefix(entry, prefix) block->add_entry(entry) signal_rule new signal_rule(perms, conds) then block->add_rule(rule)
The tokens of /etc/demo/** r, reduce in steps: TOK_MODE to file_perms through parse_perms giving 0x10004, then frule calling do_file_rule and new_entry, giving a struct cod_entry with name, perms and unset qualifiers, which the rules action adds to the block

frule: id_or_var file_perms opt_named_transition TOK_END_OF_RULE calls do_file_rule and new_entry; the entry's name is the unconverted pattern.

Now follow demo's first rule. Three tokens arrive: a name, a mode, a comma. The mode reduces first: its letters go through parse_perms and come back as a number, read for owner and read for other. Then the whole line matches the file rule, whose action allocates one entry and stores the name and that number. The name is still a glob; the grammar hasn't looked inside it. Then the prefix is applied and the entry is put at the front of the block's list. A signal rule goes the same way, except that its action is one line: new signal rule, with the permissions and the conditions.

Details and sources

Details

  • file_perms: TOK_MODE calls parse_perms (parser_yacc.y:1640-1646), which parses the letters once and shifts the result into the owner half and the other half (parser_misc.c:736-745). r is 0x4 in each half: 0x10004.
  • frule: id_or_var file_perms opt_named_transition TOK_END_OF_RULE (parser_yacc.y:1072-1083); the permissions-first spelling is the second frule (parser_yacc.y:1085-1101). file_rule_tail applies safe and unsafe (parser_yacc.y:1117-1130); bare file, becomes the path /{**,} with all permissions (parser_yacc.y:1103-1114).
  • do_file_rule (parser_yacc.y:1759-1769) calls new_entry (parser_misc.c:970-992): a zeroed struct cod_entry with name, perms and link_name, audit and rule_mode unspecified, priority 0 and pattern_type set to pattern_t::Invalid until the pattern is converted.
  • The rules action: entry_add_prefix($3, $2, error) and $1->add_entry($3) (parser_yacc.y:724-736).
  • A link rule is new_entry(name, AA_LINK_BITS, target) (parser_yacc.y:1141-1152); a change_profile rule is a cod_entry too, with the target as the name and ** when no target is written (parser_yacc.y:1648-1692).
  • signal_rule: TOK_SIGNAL opt_signal_perm opt_conds TOK_END_OF_RULE { signal_rule *ent = new signal_rule($2, $3); $$ = ent; } (parser_yacc.y:1466-1470). The constructor reads the conditions; that is where a rule class reports an unknown condition.
  • -d prints the entries after post-processing: Perms: r:r priority=0 Name: (/etc/demo/**).
  • Known discrepancy, by title: "-d lists deny and audit file rules as plain allow rules".

06 The profile object is made last for AppArmor developers for security researchers

AT THE CLOSING BRACE TOK_CLOSE the action of profile_base runs new Profile() parse_label(...) namespace and name prof->attachment = $2 must begin with / or @{ prof->flags = $5 prof->add_block($8) the block that has been growing prof->post_parse_profile() an error raised here carries the line of the closing brace policy_list a set ordered by name demo add_to_list a second profile demo in the same file: Multiple definitions for profile demo exist,bailing out.
At the token TOK_CLOSE the action of profile_base runs: new Profile, parse_label, the attachment check, flags, add_block and post_parse_profile; the profile is then inserted into the policy list, where a second profile named demo gives the message Multiple definitions for profile demo exist

The final action of profile_base (parser/parser_yacc.y:399-458) creates the Profile; add_to_list (parser/parser_policy.c:60) inserts it into a set and exits on a duplicate.

The profile object itself is created last. Only when the closing brace arrives does the profile_base action run. It makes a new profile, splits the name into namespace and name, checks that the attachment starts with a slash or a variable, takes the flags, and attaches the block built so far. One consequence: an error found here is reported at the line of the closing brace, not at the head where the mistake is. Then the profile joins the policy list. That list is a set ordered by name, so a second profile called demo is caught here, with a message that has no file and no line.

Details and sources

Details

  • profile_base has two actions. The first runs right after TOK_OPEN and swaps in an empty include cache (parser_yacc.y:392-398). The second runs after TOK_CLOSE (parser_yacc.y:399-458): - new Profile() and parse_label(&self_stack, &prof->ns, &prof->name, $1, true); a name that begins with & is refused (parser_yacc.y:401-411); - the namespace from -n replaces the one in the profile, with a warning (parser_yacc.y:414-429); - Profile attachment must begin with a '/' or variable. (parser_yacc.y:431-433); the scanner lets few such attachments through, one is profile demo &x {, reported at the line of the closing brace (run with the tree's parser); - the conditional group must be xattrs: profile id: invalid conditional group %s=() (parser_yacc.y:434-440); - identities, flags, prof->add_block($8) and prof->post_parse_profile() (parser_yacc.y:441-450, profile.cc:91); - the include cache of the surrounding level is restored (parser_yacc.y:453-455).
  • profile then warns about a path used as a name and refuses a name without /, namespace or keyword: Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'. (parser_yacc.y:468-472). For a four-line profile demo { ... } the parser reports this at line 4, the closing brace (run with the tree's parser).
  • profilelist: profilelist profile calls add_to_list($2) (parser_yacc.y:375-379), an insert into policy_list, a std::set of profile pointers with its own ordering (profilelist.h:22-37). When the insert finds an equal profile: Multiple definitions for profile %s exist,bailing out. and exit(1) (parser_policy.c:60-68). This message does not go through yyerror, so it has no file and no line.
  • Hats and child profiles are added to their parent's block with add_hat instead (parser_yacc.y:827-843).
  • Output shown here is from the parser built from the AppArmor tree at 836052d21, run with -Q -K (nothing loaded into a kernel, no cache) and the tree's abi/5.0 feature set.
  • Known discrepancy, by title: "Duplicate-definition and load messages name a profile without its namespace or parent".

Read more

07 How to read a syntax error

READING A SYNTAX ERROR 3 /etc/demo/** r4 /usr/bin/[a-z]* ix,AppArmor parser error for /work/g1.sd in profile /work/g1.sd at line 4: missing an end of line character? (entry: /etc/demo/**) noticed one line late 3 /etc/demo/** rw px, syntax error, unexpected TOK_MODE, expecting TOK_END_OF_RULE TOK_IDa name or a pathTOK_MODEpermission lettersTOK_END_OF_RULEthe commaTOK_OPEN TOK_CLOSE{ and }TOK_SET_VAR@{variable}TOK_ARROW-> (no closing brace) syntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VAR the brace is not in the list
Three syntax errors: a missing comma on line 3 reported at line 4 as missing an end of line character; a second permission string reported as unexpected TOK_MODE, expecting TOK_END_OF_RULE; a missing closing brace reported as unexpected end of file; and a legend of token names

A syntax error names the token found and the tokens that could follow. The line is that of the token being read, often one after the mistake. TOK_END_OF_RULE is the comma.

Syntax errors look cryptic until you know two things. One: the line number is where the parser noticed the problem. It reads one token ahead, so a comma missing at the end of line 3 is reported on line 4; that case has its own message. Two: the capitalised words are token names. ID is a name or a path, mode is permission letters, end of rule is the comma, open and close are the braces. So the second message says: permission letters where the comma belongs. And the list after expecting can be incomplete: at the end of a file it leaves out the brace you forgot.

Details and sources

Details

  • Form: AppArmor parser error for FILE in profile FILE at line N: syntax error, unexpected X, expecting Y or Z. The second and third examples on the slide show only the part after the colon.
  • The line number is the line of the token the parser was looking at. The parser needs the next token to decide that a rule is complete, so a mistake at the end of a line is usually reported on the following line.
  • Token names you are likely to meet:
TokenIn the profile
TOK_IDa name, a path or a pattern
TOK_MODEpermission letters such as r, rw, ix
TOK_END_OF_RULEthe comma that ends a rule
TOK_OPEN, TOK_CLOSE{ and }
TOK_SET_VAR, TOK_BOOL_VAR@{name} and ${name}
TOK_EQUALS=
TOK_ARROW->
TOK_VALUEa value after =, or an item of a list in parentheses
TOK_CONDIDa word in front of =, such as peer or set
TOK_OPENPAREN, TOK_CLOSEPAREN( and )
a keyword tokenthe keyword in capitals: TOK_AUDIT, TOK_DENY, TOK_CAPABILITY, ...
end of filethe end of the policy file
  • More examples, all run with the tree's parser:
MistakeMessage
capability chown with no comma, then }syntax error, unexpected TOK_CLOSE, expecting TOK_ID or TOK_END_OF_RULE
owner audit /etc/demo/** r,syntax error, unexpected TOK_AUDIT, expecting TOK_ID or TOK_MODE or TOK_SET_VAR
@{CONF}=/etc/demo inside a profilesyntax error, unexpected TOK_EQUALS, expecting TOK_MODE
one } too manysyntax error, unexpected TOK_CLOSE, expecting end of file
/etc/demo/** rq,syntax error, unexpected TOK_ID, expecting TOK_MODE
  • Errors that are not syntax errors use the same header with their own text, for example Invalid capability nosuch. or invalid priority 2000 > 1000.
  • The parser stops at the first error; exit status 1.
  • Output shown here is from the parser built from the AppArmor tree at 836052d21, run with -Q -K (nothing loaded into a kernel, no cache) and the tree's abi/5.0 feature set. The paths start with /work/ because that is where the files were when the parser ran.

Read more

for AppArmor developers for security researchers

In the code

  • The token names are the %token declarations (parser_yacc.y:78-193). The long form of the message comes from bison's parse.error=verbose, which the build passes when bison is version 3 or later (Makefile:38-45).
  • file_rule_tail: opt_exec_mode id_or_var file_perms id_or_var exists only to give the missing-comma message (parser_yacc.y:1132-1139).
  • vprintyyerror builds the header from profilename, current_filename and current_lineno; yyerror then calls exit(1) (parser_yacc.y:1721-1757).
  • Derived: the "expecting" list is taken from the parser state in which the error is detected. Bison may already have applied default reductions, so the list can be shorter than what the grammar allows at that point; the missing TOK_CLOSE at the end of a file is such a case. The parser generated by bison 3.8.2 collects the list from the tables of the state on top of its stack and names at most four tokens; when five or more are possible it prints none, and the message ends after the unexpected token (yypcontext_expected_tokens and YYARGS_MAX = 5 in the generated parser_yacc.c, a build product that is not in the repository; no such message was produced in the runs for this deck).

08 Where to go from here

ROADS The grammar From AARE to regular expressions the name inside an entry The preamble the author's side Qualifier blocks blocks and prefixes File rules the two spellings The lexer the token names Running apparmor_parser options and exit status
Roads from the grammar: from AARE to regular expressions, the lexer, the preamble, qualifier blocks, file rules and running apparmor_parser

Next: from AARE to regular expressions. Related: the lexer, the preamble, qualifier blocks, file rules, running apparmor_parser.

So that's the grammar: a preamble and a list of profiles, a rules symbol that grows a block one line at a time, four prefix slots, and objects built directly in the actions. When it's done, no pattern has been looked into. The name inside a file entry is still a glob, and the deck on the glob conversion shows how it becomes a regular expression. If you want the same constructs from the author's side, the decks on the preamble, on qualifier blocks and on file rules have them. The lexer deck explains the token names. And the deck on running the parser covers options and exit status.

Details and sources

Details

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit 836052d21 (6.0.0~alpha2) was run (-Q -K, with the tree's abi/5.0 feature set), with nothing loaded into a kernel. "code" means the parser source was read and not run; "derived" means the result was reasoned from that code.

The top of the grammar

list:          preamble profilelist
preamble:      (alias | varassign | abi_rule)*
profilelist:   profile*
profile:       opt_profile_flag profile_base
profile_base:  TOK_ID opt_id_or_var opt_cond_list identities flags TOK_OPEN rules TOK_CLOSE
rules:         (abi_rule | opt_prefix rule | opt_prefix block | opt_prefix network_rule
               | opt_prefix prefix_rule | opt_prefix change_profile | opt_prefix capability
               | hat | local_profile | cond_rule | set-rlimit)*
opt_prefix:    opt_priority opt_audit_flag opt_rule_mode opt_owner_flag
block:         TOK_OPEN rules TOK_CLOSE
rule:          file_rule | link_rule
prefix_rule:   mnt_rule | dbus_rule | signal_rule | ptrace_rule | unix_rule | userns_rule
               | mqueue_rule | io_uring_rule | all_rule

The notation is shortened: * stands for the left-recursive lists of the source (code).

Where each kind of line ends up

LineObjectStored by
file rule, link rule, change_profile rulestruct cod_entryblock::add_entry
mount, remount, umount, pivot_root, dbus, signal, ptrace, unix, userns, mqueue, io_uring, all, networka class derived from rule_tblock::add_rule
capabilitybits in a 64-bit maskblock::add_capabilities
set rlimitan entry in the limits tableblock::add_rlimit
{ ... } with qualifiersblockblock::add_subblock
hat, child profileProfileblock::add_hat
if / elsecond_expr_setblock::add_cond_set
alias (preamble)alias tablenew_alias
variable assignment (preamble)symbol tableglobal_symtab.add_var, add_set_value
abipolicy feature setabi_features

Messages raised in the grammar file

MessageCauseBasis
syntax error, unexpected X, expecting Ythe tokens match no ruletree
missing an end of line character? (entry: NAME)no comma after a file ruletree
Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'.a bare name without profiletree
Profile attachment must begin with a '/' or variable.an attachment such as &xtree
hat profiles can't use xattrs matchescode
variable NAME was previously declared= on an existing variablecode
variable NAME was not previously declared, but is being assigned additional values+= on a new variablecode
invalid priority N > 1000priority out of rangetree
conflicting mode prefix, conflicting audit prefix, conflicting owner prefixqualifiers of a block and of a rule inside it disagreetree (mode), code
owner conditional not allowed on change_profile rulesowner change_profile -> x,tree
Invalid capability NAME.unknown capabilitytree
subset can only be used with link rules.code
link and exec perms conflict on a file rule using ->code
unsafe rule missing exec permissionssafe or unsafe without an exec permissioncode
Exec condition must begin with '/'.change_profilecode
Multiple definitions for profile NAME exist,bailing out.two profiles with one name (printed without file and line)tree

for AppArmor developers for security researchers

Functions

FunctionWhereWhat
yyerror, vprintyyerrorparser_yacc.y:1721-1757header, message, exit(1)
do_file_ruleparser_yacc.y:1759-1769new_entry plus the transition name
new_entryparser_misc.c:970-992allocate a cod_entry
parse_permsparser_misc.c:736-745permission letters to bits for owner and other
entry_add_prefix, generic_add_prefixparser_misc.c:1109-1160qualifiers on a cod_entry
prefix_rule_t::add_prefixrule.h:381-440qualifiers on a rule object
block::add_prefix, block::add_subblockblock.cc:161-283qualifiers on a block
add_to_listparser_policy.c:60-68insert a profile, exit on a duplicate
abi_featuresparser_yacc.y:1884-1906read the feature file of an abi rule

Roads from here

FILE ACCESS

PREAMBLE AND REUSE

QUALIFIERS

PROFILE STRUCTURE

RUNNING THE PARSER

INSIDE THE PARSER