The preamble
what comes before profiles for application developers
The preamble is the part of a profile file before its first profile. It holds variable assignments and alias rules and abi rules together with comments and includes. It sets up what every profile of that file uses and nothing of it is accepted after the first profile. Each file given to the parser starts with an empty one.
On the map: preamble and reuse
▶ Watch this deck — 8 scenes, ~5 min
Worth seeing first
- The profile language at a glance — the four regions of a profile file; the preamble is first
Part of journeys
- Write your first profile, step 1 of 12 · next: include
01 What stands above the profile
The preamble is everything before the first profile of a file. It holds no rules.
Open demo's profile file and look at the top. The first five lines aren't inside the profile at all. They sit above the line where the first profile starts. That part of the file has a name: the preamble. Nothing in it allows or denies anything. It says which feature set the file was written for, pulls in shared definitions, defines a variable and a switch, and adds an alias. Below it come the profiles. And everything the preamble sets up is used by each profile further down. This deck is about what may stand up there, and where it stops.
Details and sources
Details
- The manual's grammar summary:
PREAMBLE = ( COMMENT | VARIABLE ASSIGNMENT | ALIAS RULE | INCLUDE | ABI )*(apparmor.d.pod:107). - "The preamble must occur at the head of the file and once profile definitions begin, no more preamble rules are allowed" (apparmor.d.pod:87-94).
- Shipped profiles start with
abi <abi/5.0>,and theninclude <tunables/global>, for example lsblk:12-13. Underprofiles/apparmor.d, 210 lines areabi <abi/5.0>,in column 0. - The file on the slide is the 14-line example of this district. Compiled with the parser built from the AppArmor tree (
-Q -K --skip-kernel-load --warn=all) it gives exit status 0 and no warning. - The program
demoand its profile are invented for the map.
02 Five kinds of line, in any order
( comment | include | variable assignment | alias rule | abi rule )*, then the profiles. Order is free.
Five kinds of line may stand in the preamble, and you can mix them in any order: the abi rule, includes, assignments of variables, alias rules and comments. Demo's file has one of each of the first four. Two of them, abi and alias, are rules and end with a comma. Includes and assignments end where the line ends. Here's a preamble from the parser's own tests: a variable, four aliases, another variable. Any order is fine. The preamble may also be empty. And it's over the moment the parser meets the start of the first profile.
Details and sources
Details
- A file with nothing in it and a file with only a preamble both compile with exit status 0 and no output (recorded in the research notes).
- Comments and includes may stand anywhere between tokens, also inside profiles. The other three kinds are accepted only here.
abiandaliaslines end with a comma. Anincludeends with its file name and an assignment with the end of the line.- The conditional block
ifis not a preamble line: above the first profile it givessyntax error, unexpected TOK_IF, expecting end of file(run with the tree's parser for this deck). - The panel is the preamble of rewrite/alias_dupe_1.sd, a test the parser is expected to accept.
- The row of demo's lines stands for lines 1 to 5 of the example file shown in the first scene.
for AppArmor developers for security researchers
In the code
list: preamble { ... } profilelist(parser_yacc.y:345-371).preamble: | preamble alias | preamble varassign | preamble abi_rule(parser_yacc.y:506-509).- Comments and includes are consumed by the scanner and produce no token (parser_lex.l:781-818).
03 Each line sets something for the profiles below
The preamble sets the policy ABI, the variables and the aliases. -D variables prints the variables.
Think of the preamble as filling three things before any profile is looked at. The abi rule sets the feature set the file is compiled for. The include of tunables/global brings in dozens of variables, the @{HOME} variable among them. Your own two assignments add the @{APP_DATA} variable and the debug switch. The alias goes into a list of its own. Then the profile is compiled, and its rules pass through all three. Here the @{APP_DATA} variable becomes two directories. And you can print the table of variables yourself, with -D variables.
Details and sources
Details
- Run with the tree's parser for this deck:
-D variableson the example file prints 85 lines, among them the four on the slide:@HOMEDIRS = "/home/",@HOME = "/root/" "@{HOMEDIRS}/*/",@APP_DATA = "/srv/demo" "/var/lib/demo"and$DEMO_DEBUG = false. - The dump prints names without braces and booleans as
$NAME = value(variable.cc:412-420). - Values are stored as a set, so they print in string order and not in the order written: the file says
/var/lib/demo /srv/demo. - The compiled rule is the
aare:line of-D rule-exprsfor line 10 of the example:{/srv/demo,/var/lib/demo}/{cache,state}/**(run with the tree's parser for this deck). - The policy ABI is fixed when the first profile begins: the override option if given, else the abi rule, else the pinned set, else the built-in default. See The abi rule.
- What each store does: The abi rule, Variables, alias rules.
Read more
for AppArmor developers for security researchers
In the code
new_alias()is called from thealiasproduction (parser_yacc.y:511-517).global_symtab.add_var()fromvarassign(parser_yacc.y:524-570).abi_features()fromabi_rule(parser_yacc.y:1052-1063).
04 After the first profile the preamble is over
Nothing of the preamble is accepted after the first profile: syntax error, unexpected TOK_SET_VAR, expecting end of file.
You add a second profile to the file and, right above it, a variable just for that profile. The parser stops with a syntax error: an unexpected set variable token, where it expected the end of the file. What it's telling you is that after a profile it accepts only more profiles. The same happens with an abi rule down there. The cure is always the same: move the line to the top. One preamble serves every profile of the file. And notice that the message names the token it didn't expect, not the reason.
Details and sources
Details
- Run with the tree's parser for this deck, with the three lines on the slide:
AppArmor parser error for /work/p03a.sd in profile /work/p03a.sd at line 2: syntax error, unexpected TOK_SET_VAR, expecting end of file, exit status 1./work/p03a.sdis the scratch name of the file. - The same file shape is recorded in the research notes with
@{A}=/abetween two profiles, with the same message. - An abi rule on line 2, after a profile:
... at line 2: syntax error, unexpected TOK_ABI, expecting end of file, exit status 1 (run with the tree's parser for this deck). - "in profile" in the message names the file being parsed, not a profile.
- The corrected file in the third panel is the rule of the manual applied; it was not run on its own.
- The manual adds that the rule holds "even in files that are included into the profile" (apparmor.d.pod:87-94).
Read more
for AppArmor developers for security researchers
In the code
list: preamble profilelist: afterpreambleis reduced onlyprofilelistcan follow (parser_yacc.y:345-371).
05 Each file starts from nothing
Variables, aliases and the policy ABI are reset for each file. Share them with an include in each preamble.
Here's a mistake that looks reasonable. You define a variable in one profile file and use it in another, and you even compile both in one command. It fails, because the parser empties its tables before each file: variables, aliases, the policy ABI, all of it. The preamble belongs to one file. When two files need the same definitions, put them in a file of their own and include it from both preambles. That's exactly what the tunables files are.
Details and sources
Details
- Recorded in the research notes: two files, the first with
@{SHARED} = /sharedand a profile using it, the second with only a profile using it, compiled by one command. Output:Failed to find declaration for: @{SHARED}andERROR expanding variables for profile second, failed to load, exit status 1. - The profile bodies on the slide are a readable rendering of that run.
- The fix on the slide was run with the tree's parser for this deck: a file
tunables/demowith the one line@{SHARED} = /shared, found through-I, and two files that each begin withinclude <tunables/demo>and no longer assign the variable. Both compile/shared/**, exit status 0. It is what the shipped tunables files do for every profile that includestunables/global. - Keeping
@{SHARED} = /sharedinfirstnext to the include is refused:variable @{SHARED} was previously declared(see variable assignment). - A second include of the same file in one preamble is skipped, so including a shared file from two places is safe: see include.
- Known discrepancy: An undefined variable is reported without file name or line.
Read more
for AppArmor developers for security researchers
In the code
reset_parser()empties the alias table, the symbol table, the policy list, the policy ABI and the include cache (parser_main.c:1254-1269). It is called for each file (parser_main.c:1314).
06 Three productions and no object for AppArmor developers for security researchers
parser_yacc.y:506-509 is the preamble; the action at 345-369 fixes the policy ABI; parser_main.c:1254-1269 resets per file.
There's no preamble object in the parser. Comments and includes are handled by the scanner and don't show up as tokens. The grammar has three productions: one for an alias, one for a variable assignment, one for an abi rule. Each acts the moment it's reduced. One adds to the alias tree, one to the global symbol table, one loads a feature file. The interesting moment is the reduction of the preamble itself, when the first profile token arrives. That's where the policy ABI is settled for the file. And before the next file, reset_parser clears all of it.
Details and sources
for AppArmor developers for security researchers
Details
- The three productions: parser_yacc.y:506-509. Their actions:
new_alias()(parser_yacc.y:511-517),global_symtab.add_var()(parser_yacc.y:524-570),abi_features()(parser_yacc.y:1052-1063). - Order at the reduction of
preamble: the--override-policy-abiset if given, else the set from an abi rule, else the pinned set, else the built-in default with the warningFile '%s' missing feature abi, falling back to default policy feature abi(parser_yacc.y:346-369). The warning's class isabi, which is not inDEFAULT_WARNINGS(parser.h:77-78). - An abi rule is the one preamble rule the grammar also accepts in a body:
rules: rules abi_rule(parser_yacc.y:722; abi/ok_20.sd). - Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect.
reset_parser(): parser_main.c:1254-1269.- Comments and includes in the scanner: parser_lex.l:781-818.
for security researchers
Attack surface
- The preamble is the only place where compile-time state is set, and it is per file.
- What a profile's rules mean depends on every file its preamble includes: the tunables files and their
.ddirectories. See include if exists.
07 Lines in the wrong half
Assignments and alias rules only above the first profile; rules and if blocks only inside one.
Almost every mistake here is a line in the wrong half of the file. An assignment inside the profile: the parser takes the variable for the start of a file rule, and then trips over the equals sign. An alias inside the profile. A rule above the profile: the path is taken for a profile name, and then a brace is expected. An if block above the profile. And the indirect one: a tunables file included inside the profile, where the error points into the included file. None of the messages says preamble. So ask yourself which half you're in.
Details and sources
Details
- All five rows were run with the tree's parser for this deck, each as a small file with demo's names; every one exits with status 1. The first, second, fourth and fifth are also recorded in the research notes with other names.
- Row 1 in full:
AppArmor parser error for /work/p06a.sd in profile /work/p06a.sd at line 2: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE. - Row 2: the same with
unexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. The parser's test rewrite/bad_alias_inside_profile.sd expects a failure for it. - Row 3 in full:
AppArmor parser error for /work/p-rule.sd in profile /work/p-rule.sd at line 2: syntax error, unexpected TOK_MODE, expecting TOK_OPEN. - Row 4:
... at line 2: syntax error, unexpected TOK_IF, expecting end of file. - Row 5 in full:
AppArmor parser error for /work/p06e.sd in profile /src/apparmor/profiles/apparmor.d/tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE. "in profile" names the file being parsed; the slide shortens its directory to.... - A boolean assigned inside a profile is refused too: the parser's test boolean/boolean_bad_5.sd expects a failure.
- An abi rule inside a profile is accepted by the grammar; see the scene "Three productions and no object".
- The file names under
/work/are scratch names of the runs.
08 The five lines, one deck each
Preamble lines: abi, include, variables, alias. Then the profile head.
That's the preamble: the top of the file, five kinds of line, one file at a time. Each of demo's five lines has a deck of its own: the abi rule and include on one side, variables and their operators, the boolean switch and the alias on the other. And the line that ends the preamble, the profile's head, is the profile name deck.
Details and sources
Read more
Basis of the statements on this page: "tree" means the parser built from the AppArmor commit 836052d21 (6.0.0~alpha2) was run on the fragment (-Q -K --skip-kernel-load, with the tree's abi/5.0 file as kernel 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. Nothing here was observed on a running kernel.
Grammar
FILE: PREAMBLE PROFILE* PREAMBLE: ( COMMENT | INCLUDE | VARIABLE ASSIGNMENT | ALIAS RULE | ABI RULE )*
- The manual's line is
PREAMBLE = ( COMMENT | VARIABLE ASSIGNMENT | ALIAS RULE | INCLUDE | ABI )*(apparmor.d.pod:107). - Order is free and each kind may repeat (code; the test rewrite/alias_dupe_1.sd mixes them).
- An empty preamble is valid, and so is a file with nothing but a preamble (tree, recorded in the research notes).
| Line | Form | Ends with | Deck |
|---|---|---|---|
| comment | # text | the line | syn-comments |
| include | include <magic/path>, include "path", include if exists ... | the file name | syn-include |
| set variable assignment | @{NAME} OP values | the line | syn-variable-assignment |
| boolean assignment | ${NAME} OP expression | the line | syn-boolean-variables |
| alias rule | alias FROM -> TO, | a comma | syn-alias |
| abi rule | abi <magic/path>, | a comma | syn-abi |
Where each construct may stand
| Construct | Preamble | Profile body | After the first profile |
|---|---|---|---|
| comment | yes | yes | yes |
| include | yes | yes | yes, if the included text is profiles (derived) |
| set variable assignment | yes | unexpected TOK_EQUALS, expecting TOK_MODE (tree) | unexpected TOK_SET_VAR, expecting end of file (tree) |
| boolean assignment | yes | refused (the test boolean_bad_5.sd expects a failure) | refused (derived) |
| alias rule | yes | unexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VAR (tree) | refused (derived) |
| abi rule | yes | accepted by the grammar (code) | unexpected TOK_ABI, expecting end of file (tree) |
| rule | unexpected TOK_MODE, expecting TOK_OPEN for /etc/demo/** r, (tree) | yes | the same |
if block | unexpected TOK_IF, expecting end of file (tree) | yes | the same (derived) |
| profile | ends the preamble | child profile | yes |
Every message is prefixed AppArmor parser error for FILE in profile FILE at line N: syntax error, ; "in profile" names the file being parsed. Exit status 1.
Scope
- The preamble belongs to one file. Before each file named on the command line the parser empties the table of variables, the aliases, the policy ABI and its list of included files (code).
- Two files in one command, the second using a variable only the first defines:
Failed to find declaration for: @{SHARED},ERROR expanding variables for profile second, failed to load, exit status 1 (tree, recorded in the research notes). - Share definitions with an include in each preamble (derived). That is what
include <tunables/global>does.
The end of the preamble
When the first profile begins, the policy ABI of the file is settled, in this order: the --override-policy-abi option, the file's first abi rule, the --policy-features option, the parser's built-in default (code). See syn-abi.
Errors
| Message | Line that causes it | Basis |
|---|---|---|
syntax error, unexpected TOK_SET_VAR, expecting end of file | @{APP_DATA} = /var/lib/demo after a profile | tree |
syntax error, unexpected TOK_ABI, expecting end of file | abi <abi/5.0>, after a profile | tree |
syntax error, unexpected TOK_EQUALS, expecting TOK_MODE | @{APP_DATA} = /srv/demo inside a profile | tree |
syntax error, unexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VAR | alias /usr/ -> /opt/demo/usr/, inside a profile | tree |
syntax error, unexpected TOK_MODE, expecting TOK_OPEN | /etc/demo/** r, above the profile | tree |
syntax error, unexpected TOK_IF, expecting end of file | if ${DEMO_DEBUG} { ... } above the profile | tree |
in profile .../tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE | include <tunables/global> inside a profile | tree |
Failed to find declaration for: @{SHARED} | a variable defined only in another file | tree, recorded |
for AppArmor developers for security researchers
In the code
list: preamble { ... } profilelist(parser_yacc.y:345-371); the action settles the policy ABI (parser_yacc.y:346-369).preamble: | preamble alias | preamble varassign | preamble abi_rule(parser_yacc.y:506-509).- Actions:
new_alias()(parser_yacc.y:511-517),global_symtab.add_var()(parser_yacc.y:524-570),abi_features()(parser_yacc.y:1052-1063). - Comments and includes are consumed by the scanner (parser_lex.l:781-818).
reset_parser()(parser_main.c:1254-1269).- Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect.
- Known discrepancy: An undefined variable is reported without file name or line.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
PREAMBLE AND REUSE
- The abi rule and the abi files — the first line of most preambles
- include — how tunables files get into the preamble
- Abstractions and tunables — which files belong above the profile and which inside
- Variables — the names a preamble defines
- Variable assignment — the four operators of an assignment
- Boolean variables — switches set in the preamble
- alias rules — the preamble rule that copies rules to a second location
PROFILE HEAD
- The profile name — the line that ends the preamble
PROFILE STRUCTURE
- Comments and line structure — where a hash starts a comment
INSIDE THE PARSER
- The grammar — the grammar rule behind the preamble