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

Part of journeys

  • Write your first profile, step 1 of 12 · next: include

01 What stands above the profile

THE PREAMBLE 1 abi <abi/5.0>, 2 include <tunables/global> 3 @{APP_DATA} = /var/lib/demo /srv/demo 4 ${DEMO_DEBUG} = false 5 alias /usr/ -> /opt/demo/usr/, 6 profile demo /usr/bin/demo { ... 14 } the first profile starts here preamble five lines, no rule among them profiles is used by what these lines set up, every profile below uses
The first lines of demo's profile file: an abi rule, an include of tunables/global, a variable assignment, a boolean assignment and an alias rule, then the line profile demo /usr/bin/demo and its body. A line separates the first five lines from the profile. The five lines are labelled preamble, the rest profiles, and what the preamble sets up is used by every profile below.

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 then include <tunables/global>, for example lsblk:12-13. Under profiles/apparmor.d, 210 lines are abi <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 demo and its profile are invented for the map.

02 Five kinds of line, in any order

GRAMMAR abi <...>, include <...> alias FROM -> TO, @{NAME} = values ${NAME} = expression # comment any of them, any number of times profile ... { } then more profiles demo's lines: 1 abi 2 include 3 @{APP_DATA} = ... 4 ${DEMO_DEBUG} = ... 5 alias abi, alias end with a comma include, = end with the line @{MEEP} = meep moop alias /etc -> /Etcetera, alias /usr/ -> /Libraries/, alias /tmp -> /var/tmp, alias /usr/ -> /User/, @{FOO} = foo bar a variable, four aliases, a variable: any order (the parser's test alias_dupe_1.sd) an empty preamble is valid; so is a file with nothing but a preamble
Syntax diagram of the preamble: a loop over five alternatives, abi rule, include, alias rule, variable assignment and comment, repeated in any order, then an exit to the profiles. Demo's five lines are one of each of the first four kinds. abi and alias end with a comma; include and assignments end with the line. A preamble from the parser's tests mixes two variables and four aliases. An empty preamble is valid.

( 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.
  • abi and alias lines end with a comma. An include ends with its file name and an assignment with the end of the line.
  • The conditional block if is not a preamble line: above the first profile it gives syntax 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

03 Each line sets something for the profiles below

WHAT IT SETS UP abi <abi/5.0>, include <tunables/global> @{APP_DATA} = /var/lib/demo /srv/demo ${DEMO_DEBUG} = false alias /usr/ -> /opt/demo/usr/, policy ABI variables aliases abi/5.0 @HOMEDIRS = "/home/" @HOME = "/root/" "@{HOMEDIRS}/*/" 85 lines in all @APP_DATA = "/srv/demo" "/var/lib/demo" $DEMO_DEBUG = false /usr/ -> /opt/demo/usr/ profile demo owner @{APP_DATA}/{cache,state}/** rwk, {/srv/demo,/var/lib/demo}/{cache,state}/** what the compiler works with $ apparmor_parser -Q -D variables demo prints the table
Demo's five preamble lines on the left and three stores on the right: policy ABI, variables and aliases. The abi rule fills the policy ABI with abi/5.0. The include of tunables/global fills the variables, HOMEDIRS and HOME among 85 lines. The two assignments add APP_DATA and DEMO_DEBUG. The alias rule fills the aliases. Below, a rule of the profile written with the APP_DATA variable is compiled as two directories. The command apparmor_parser -Q -D variables prints the table.

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 variables on 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-exprs for 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.

for AppArmor developers for security researchers

In the code

04 After the first profile the preamble is over

ONE WAY profile demo /usr/bin/demo { } @{APP_DATA} = /var/lib/demo profile demo-helper /usr/bin/demo-helper { } syntax error, unexpected TOK_SET_VAR, expecting end of file exit status 1 profile demo /usr/bin/demo { } abi <abi/5.0>, syntax error, unexpected TOK_ABI, expecting end of file @{APP_DATA} = /var/lib/demo profile demo /usr/bin/demo { } profile demo-helper /usr/bin/demo-helper { } one preamble, at the top, for both profiles the message names the token it did not expect, not the reason
A file with a profile demo, then a variable assignment, then a profile demo-helper. The parser reports syntax error, unexpected TOK_SET_VAR, expecting end of file, exit status 1. An abi rule after a profile gives the same error with TOK_ABI. Moving the assignment above the first profile fixes it: one preamble at the top serves both profiles.

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.sd is the scratch name of the file.
  • The same file shape is recorded in the research notes with @{A}=/a between 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).

for AppArmor developers for security researchers

In the code

  • list: preamble profilelist: after preamble is reduced only profilelist can follow (parser_yacc.y:345-371).

05 Each file starts from nothing

PER FILE first @{SHARED} = /shared profile first { @{SHARED}/** r, } second profile second { @{SHARED}/** r, } $ apparmor_parser -Q first second variables: @SHARED variables: none emptied before each file Failed to find declaration for: @{SHARED} ERROR expanding variables for profile second, failed to load the fix: one shared file tunables/demo @{SHARED} = /shared first include <tunables/demo> profile first { @{SHARED}/** r, } second include <tunables/demo> profile second { @{SHARED}/** r, }
Two profile files compiled by one command. The file first defines the variable SHARED and uses it; the file second only uses it. The table of variables is emptied before each file, so the second file fails: Failed to find declaration for @{SHARED}. Below, the fix: a file tunables/demo holds the assignment, and each of the two files starts with include tunables/demo and no longer assigns the variable itself.

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} = /shared and a profile using it, the second with only a profile using it, compiled by one command. Output: Failed to find declaration for: @{SHARED} and ERROR 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/demo with the one line @{SHARED} = /shared, found through -I, and two files that each begin with include <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 includes tunables/global.
  • Keeping @{SHARED} = /shared in first next 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.

for AppArmor developers for security researchers

In the code

06 Three productions and no object for AppArmor developers for security researchers

IN THE PARSER scanner # comment include <...> no token grammar preamble: preamble alias | preamble varassign | preamble abi_rule alias tree global_symtab policy_features new_alias() add_var() abi_features() list: preamble { ... } profilelist the first profile token reduces preamble: the policy ABI is settled here reset_parser() before each file: aliases, symbol table, policy ABI, include cache
The scanner consumes comments and includes without producing a token. The grammar has three preamble productions: alias calls new_alias and fills the alias tree, varassign calls add_var on global_symtab, abi_rule calls abi_features and fills policy_features. Reducing preamble in the rule list: preamble profilelist settles the policy ABI. reset_parser clears aliases, symbol table, policy ABI and include cache before each file.

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

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 .d directories. See include if exists.

for AppArmor developers for security researchers

Read more

07 Lines in the wrong half

MISTAKES profile demo { @{APP_DATA} = /srv/demo ... } syntax error, unexpected TOK_EQUALS, expecting TOK_MODE profile demo { alias /usr/ -> /opt/demo/usr/, } syntax error, unexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VAR /etc/demo/** r, above the profile syntax error, unexpected TOK_MODE, expecting TOK_OPEN if ${DEMO_DEBUG} { ... } above the profile syntax error, unexpected TOK_IF, expecting end of file include <tunables/global> inside the profile in profile .../tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE none of them says "preamble" read the message as: which half of the file am I in?
Five misplaced lines and the parser's message for each. An assignment inside a profile: unexpected TOK_EQUALS, expecting TOK_MODE. An alias inside a profile: unexpected TOK_ALIAS. A rule above the profile: unexpected TOK_MODE, expecting TOK_OPEN. An if block above the profile: unexpected TOK_IF, expecting end of file. An include of tunables/global inside the profile: an error in tunables/home at line 15.

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

ROADS abi <abi/5.0>, include <tunables/global> @{APP_DATA} = /var/lib/demo /srv/demo ${DEMO_DEBUG} = false alias /usr/ -> /opt/demo/usr/, syn-abi syn-include syn-abstractions-tunables syn-variables syn-variable-assignment syn-boolean-variables syn-alias syn-comments syn-profile-name the line that ends it syntax-map where a hash starts a comment every kind of line
Demo's five preamble lines in the centre with roads to the decks syn-abi, syn-include and syn-abstractions-tunables on the left, syn-variables, syn-variable-assignment, syn-boolean-variables and syn-alias on the right, and syn-comments, syn-profile-name and syntax-map below.

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).
LineFormEnds withDeck
comment# textthe linesyn-comments
includeinclude <magic/path>, include "path", include if exists ...the file namesyn-include
set variable assignment@{NAME} OP valuesthe linesyn-variable-assignment
boolean assignment${NAME} OP expressionthe linesyn-boolean-variables
alias rulealias FROM -> TO,a commasyn-alias
abi ruleabi <magic/path>,a commasyn-abi

Where each construct may stand

ConstructPreambleProfile bodyAfter the first profile
commentyesyesyes
includeyesyesyes, if the included text is profiles (derived)
set variable assignmentyesunexpected TOK_EQUALS, expecting TOK_MODE (tree)unexpected TOK_SET_VAR, expecting end of file (tree)
boolean assignmentyesrefused (the test boolean_bad_5.sd expects a failure)refused (derived)
alias ruleyesunexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VAR (tree)refused (derived)
abi ruleyesaccepted by the grammar (code)unexpected TOK_ABI, expecting end of file (tree)
ruleunexpected TOK_MODE, expecting TOK_OPEN for /etc/demo/** r, (tree)yesthe same
if blockunexpected TOK_IF, expecting end of file (tree)yesthe same (derived)
profileends the preamblechild profileyes

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

MessageLine that causes itBasis
syntax error, unexpected TOK_SET_VAR, expecting end of file@{APP_DATA} = /var/lib/demo after a profiletree
syntax error, unexpected TOK_ABI, expecting end of fileabi <abi/5.0>, after a profiletree
syntax error, unexpected TOK_EQUALS, expecting TOK_MODE@{APP_DATA} = /srv/demo inside a profiletree
syntax error, unexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VARalias /usr/ -> /opt/demo/usr/, inside a profiletree
syntax error, unexpected TOK_MODE, expecting TOK_OPEN/etc/demo/** r, above the profiletree
syntax error, unexpected TOK_IF, expecting end of fileif ${DEMO_DEBUG} { ... } above the profiletree
in profile .../tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODEinclude <tunables/global> inside a profiletree
Failed to find declaration for: @{SHARED}a variable defined only in another filetree, recorded

for AppArmor developers for security researchers

In the code

Roads from here

START HERE

PREAMBLE AND REUSE

PROFILE HEAD

PROFILE STRUCTURE

INSIDE THE PARSER