Abstractions and tunables

and tunables for application developers for administrators

Two conventions built on include. A tunables file holds variables and aliases and belongs in the preamble. An abstraction holds rules and belongs inside a profile. Each shipped file ends with an optional include of its NAME.d directory where site changes go. Including either in the other place is a syntax error.

On the map: preamble and reuse

▶ Watch this deck — 8 scenes, ~5 min

Worth seeing first

  • include — the include line that pulls these files in
  • The preamble — what a preamble may contain, which is what tunables hold

Part of journeys

01 Two includes, two kinds of file

ABSTRACTIONS AND TUNABLES abi <abi/5.0>, include <tunables/global> profile demo /usr/bin/demo { include <abstractions/base> ... } /etc/apparmor.d/tunables/ above the profile @{HOME}=... definitions /etc/apparmor.d/abstractions/ inside the profile @{etc_ro}/ld.so.cache mr, rules to the parser both are just files; the difference is what they contain
Demo's profile file with include tunables/global above the profile and include abstractions/base inside it. The first comes from the directory /etc/apparmor.d/tunables, which holds definitions such as the HOME variable. The second comes from /etc/apparmor.d/abstractions, which holds rules such as @{etc_ro}/ld.so.cache mr. To the parser both are just files; the difference is what they contain.

tunables/ files hold definitions for the preamble. abstractions/ files hold rules for a profile body.

Demo's profile includes two files, and it's no accident that one include is above the profile and the other inside it. The first comes from a directory called tunables: files of definitions, like the @{HOME} variable, that every profile on the machine should agree on. The second comes from abstractions: files of ready-made rules for things most programs need. The parser itself doesn't know either word. These are conventions, and what makes them work is simply what the files contain and where you include them.

Details and sources

Details

  • Neither directory has syntax of its own: the lines are include <tunables/NAME> and include <abstractions/NAME>.
  • Both directories are found on the include search path: see include. On the slide they are drawn under /etc/apparmor.d, where the tree's profiles/apparmor.d is installed.
  • A shipped profile with both lines: lsblk:13-16.
  • The rule on the slide is base:62; the file aligns the mode with blanks.
  • The kernel has no notion of an abstraction or a tunable: it receives the compiled rules.

02 What each kind of file may contain

SHAPE tunables/NAME abstractions/NAME @{NAME} = values alias FROM -> TO, include <tunables/OTHER> abi <abi/5.0>, include <abstractions/OTHER> rules ... include if exists <tunables/NAME.d> include if exists <abstractions/NAME.d> rules ... @{NAME} = ... fits only above a profile fits only inside a profile neither may hold what the other holds
Two columns. A tunables file holds variable assignments, alias rules and includes of other tunables files. An abstraction holds an abi line, includes of other abstractions and rules. Both end with include if exists of their NAME.d directory. Rules do not fit in a tunables file and assignments do not fit in an abstraction: a tunables file fits only above a profile and an abstraction only inside one.

Tunables: assignments, aliases, includes. Abstractions: rules and includes. Both end with include if exists <.../NAME.d>.

There's no grammar to learn here, only two shapes. A tunables file contains what a preamble may contain: variable assignments, alias rules and includes of more tunables. An abstraction contains what a profile body may contain: rules, and includes of more abstractions, with an abi line at the top. No profile head, no braces. And both end the same way, with an optional include of a directory named after the file, with .d on the end. Because of what's inside, a tunables file only fits above a profile, and an abstraction only fits inside one.

Details and sources

Details

  • A tunables file is preamble text; an abstraction is body text. The shape of each is the grammar of the place it is included in: see The preamble.
  • The shape of a shipped abstraction, with abstractions/base as the example: a comment header, an indented abi <abi/5.0>, and nested includes such as include <abstractions/crypto> (base:13-15), rules, and the last line include if exists <abstractions/base.d> (base:184).
  • 135 lines under profiles/apparmor.d are the indented abi <abi/5.0>,.
  • Three shipped abstractions define profiles; see Choosing abstractions.
  • abstractions/ubuntu-browsers.d/ is not an extension directory: it holds separate abstractions that are included by name.
  • Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect.

03 One line brings in ten files

TUNABLES/GLOBAL $ apparmor_parser -p demo | grep '^##' tunables/global home @{HOMEDIRS} @{HOME} multiarch @{multiarch} proc @{PROC} alias comments only kernelvars @{pid} @{tid} @{uid} @{sys} ... system @{int} @{hex} @{u16} ... xdg-user-dirs @{XDG_DESKTOP_DIR} ... share @{system_share_dirs} ... etc @{etc_ro} @{etc_rw} run @{run} .d .d .d .d .d .d .d .d .d .d .d the directory exists: ##included .d nothing there yet: ##failed include 85 lines in demo's table of variables, two of them demo's own
The markers printed by apparmor_parser -p for demo show that tunables/global includes ten files in this order: home defining HOMEDIRS and HOME, multiarch, proc, alias with comments only, kernelvars with pid, tid, uid and sys, system with int, hex, u16 and more, xdg-user-dirs, share, etc with etc_ro and etc_rw, and run. Each tries its .d directory: those of home, multiarch and xdg-user-dirs exist, the others give ##failed include. Demo's table of variables has 85 lines.

tunables/global includes home, multiarch, proc, alias, kernelvars, system, xdg-user-dirs, share, etc, run.

The file tunables/global mostly includes other files. Ask the parser for the markers and you see ten of them go by, in this order: home, multiarch and proc. Then alias, kernelvars and system. Then four more: xdg-user-dirs, share, one called etc after the directory, and run. Nine of them define variables, from the @{HOME} variable to patterns for a process ID or a hexadecimal number. And each ends by trying its own .d directory. Three of those directories exist as shipped. The others are reported as failed include, which only means there's nothing there yet.

Details and sources

Details

  • Run with the tree's parser for this deck: the -p markers of the example file, in order: ##included <tunables/global>, <tunables/home>, <tunables/home.d>, <tunables/multiarch>, <tunables/multiarch.d>, <tunables/proc>, ##failed include <tunables/proc.d>, ##included <tunables/alias>, ##failed include <tunables/alias.d>, ##included <tunables/kernelvars>, ##failed include <tunables/kernelvars.d>, ##included <tunables/system>, ##failed include <tunables/system.d>, ##included <tunables/xdg-user-dirs>, ##included <tunables/xdg-user-dirs.d>, ##included <tunables/share>, ##failed include <tunables/share.d>, ##included <tunables/etc>, ##failed include <tunables/etc.d>, ##included <tunables/run>, ##failed include <tunables/run.d>, ##failed include <tunables/global.d>.
  • The ten include lines: global:15-27.
  • What each file defines: home: @{HOMEDIRS}=/home/, @{HOME}=@{HOMEDIRS}/*/ /root/; multiarch: @{multiarch}=*-linux-gnu*; proc: @{PROC}=/proc/; kernelvars: @{pid}, @{tid}, @{pids}, @{uid}, @{uids}, @{sys}=/sys/; run: @{run}=/run/ /var/run/; etc: @{etc_ro}=/etc/ /usr/etc/, @{etc_rw}=/etc/; share: @{flatpak_exports_root}, @{system_share_dirs}, @{user_share_dirs}; xdg-user-dirs: @{XDG_DESKTOP_DIR}="Desktop" and seven more; system (102 lines): character classes and counted patterns; alias: comments, then include if exists <tunables/alias.d>.
  • Not pulled in by global: apparmorfs, securityfs, sys, dovecot, gs, ntpd, print-devices, rygel.
  • The shipped tunables use only =.
  • -D variables on the example file prints 85 lines; $DEMO_DEBUG and @APP_DATA are demo's. The three built-in variables are not in this dump.
  • Known discrepancy: @{u16} has an unbalanced bracket and also matches [ and 65536 to 69999.

04 An abstraction is rules, and more includes

ABSTRACTIONS/BASE abstractions/base abi <abi/5.0>, include <abstractions/crypto> @{etc_ro}/ld.so.cache mr, owner @{HOME}/.Private/** mrixwlk, ... include if exists <abstractions/base.d> profile demo the rules of base crypto openssl upki ##included <abstractions/base> ##included <abstractions/crypto> ##included <abstractions/openssl> ##included <abstractions/upki> {/home/*,/root}/.Private/** a rule of base written with @{HOME}: it needs tunables/global in your preamble the rules belong to the profile that includes them: also a child profile or a hat
The file abstractions/base holds an abi line, an include of abstractions/crypto, rules such as @{etc_ro}/ld.so.cache mr and owner @{HOME}/.Private/** mrixwlk, and a final include if exists of abstractions/base.d. Its rules flow into the profile demo. crypto includes openssl and upki, and their rules flow in too: four ##included markers. One rule of base is compiled as {/home/*,/root}/.Private/**: it is written with @{HOME} and needs tunables/global in the preamble.

An abstraction's rules become rules of the profile that includes it. Its variables come from tunables/global.

An abstraction is nothing more than rules in a file. Include abstractions/base and those rules become demo's rules, exactly as if you'd typed them. Base itself includes the crypto abstraction, which includes two more, so one line gives you four files. There's one dependency to know about. Many of these rules are written with variables like home and proc, and those come from the tunables. That's why the include of tunables/global in your preamble isn't optional once you use an abstraction.

Details and sources

Details

  • The lines in the file box are base:13-15, base:62, base:177 and base:184.
  • Run with the tree's parser for this deck: the -p markers inside demo's profile, in order: ##included <abstractions/base>, ##included <abstractions/crypto>, ##included <abstractions/openssl>, ##failed include <abstractions/openssl.d>, ##included <abstractions/upki>, ##failed include <abstractions/upki.d>, ##failed include <abstractions/crypto.d>, ##failed include <abstractions/base.d>.
  • The compiled rule {/home/*,/root}/.Private/** is an aare: line of the same file's -D rule-exprs dump; it comes from line 177 of base.
  • Including one abstraction in a parent and in its child profile is two includes. A second include of the same abstraction in one profile is skipped: see include.
  • Without include <tunables/global>, a profile that includes base fails with Failed to find declaration for: @{HOMEDIRS} (run with the tree's parser for this deck). The manual describes the case with @{HOME} (apparmor.d.pod:2812-2820).
  • Known discrepancy: An undefined variable is reported without file name or line.
  • Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect. Recorded in the research notes, with --warn=all, for a file whose preamble has no abi rule: Warning from /work/a1.sd (/src/apparmor/profiles/apparmor.d/abstractions/base line 13): ... features abi 'abi/5.0' differs from policy declared feature abi, using the features abi declared in policy.

05 Change the dot d directory, not the shipped file

SITE CHANGES tunables/home abstractions/base shipped: leave it alone shipped: leave it alone tunables/home.d/site.local @{HOMEDIRS} += /srv/nfs/home/ {/home/*,/root,/srv/nfs/home/*}/.ssh/** every rule written with @{HOME} follows abstractions/base.d/site /srv/shared/certs/** r, every profile that includes base gets the rule $ apparmor_parser -r /etc/apparmor.d/ recompile and reload: the change is in the compiled profiles, not looked up at run time
Two rows. The shipped file tunables/home is extended by tunables/home.d/site.local with the line @{HOMEDIRS} += /srv/nfs/home/; a rule written with @{HOME} is then compiled as {/home/*,/root,/srv/nfs/home/*}/.ssh/**. The shipped file abstractions/base is extended by a file in abstractions/base.d with the rule /srv/shared/certs/** r, which every profile that includes base gets. apparmor_parser -r /etc/apparmor.d/ recompiles and reloads the profiles.

Site definitions go in tunables/NAME.d/, site rules in abstractions/NAME.d/. Reload the profiles afterwards.

Sooner or later a machine differs from what the package assumed: home directories somewhere else, certificates in an unusual place. Don't edit the shipped files. Each of them ends by including a directory named after it, with .d on the end, and that directory is yours. For a tunables file, put assignments there, usually with +=, to add a value. Every rule written with the variable follows. For an abstraction, put rules there, and every profile that includes it gets them. Then reload the profiles, because all of this happens when a profile is compiled, not while the program runs.

Details and sources

Details

  • Row 1, run with the tree's parser for this deck: with the one line @{HOMEDIRS} += /srv/nfs/home/ added, demo's rule audit deny @{HOME}/.ssh/** rw, is compiled as {/home/*,/root,/srv/nfs/home/*}/.ssh/**. In the run the line stood in a file site.local in a directory given with -I and was included with include if exists <site.local> after include <tunables/global>; it stands in for tunables/home.d/site.local, which could not be changed in the tree used for the runs.
  • Row 2 is derived: no run added a file to abstractions/base.d/. The file name site and the rule /srv/shared/certs/** r, are invented, and the slide shows no dump for it.
  • apparmor_parser -r is the reload command of Running apparmor_parser; no output is shown.
  • Shipped .d directories: tunables/home.d, tunables/multiarch.d, tunables/xdg-user-dirs.d, each with a site.local of comments, for example #@{HOMEDIRS}+=/srv/nfs/home/ /mnt/home/ (home.d/site.local).
  • = on a variable that a tunables file declared is an error, so a site file uses +=: see Variable assignment.
  • Which names in a .d directory are skipped: see include if exists.
  • A syntax error in a NAME.d file stops every profile that includes NAME from compiling.
  • Known discrepancy: The files of an included directory are compiled in reverse alphabetical order, and an error in one is reported with a neighbour's file name.

for security researchers

Attack surface

06 No special code, only the two halves of the grammar for AppArmor developers for security researchers

IN THE PARSER preamble: preamble alias | preamble varassign | preamble abi_rule rules: rules opt_prefix rule | rules abi_rule | rules cond_rule | ... tunables/home varassign abstractions/base rule abstractions/consoles unexpected TOK_MODE, expecting TOK_OPEN tunables/home unexpected TOK_EQUALS, expecting TOK_MODE current_filename, current_lineno from the include stack: the message says "in profile <included file> at line N" ##skipped duplicate include <tunables/global> the preamble's include cache makes a second include of global harmless
The two halves of the grammar: the preamble productions alias, varassign and abi_rule, and the rules productions. tunables/home reduces to varassign in the preamble; abstractions/base reduces to rule in a profile. Swapped, abstractions/consoles in the preamble gives unexpected TOK_MODE, expecting TOK_OPEN, and tunables/home in a profile gives unexpected TOK_EQUALS, expecting TOK_MODE. The file name in the message comes from the include stack. The preamble's include cache makes a second include of tunables/global a skipped duplicate.

preamble (parser_yacc.y:506-509) takes tunables; rules takes abstractions. Errors name the included file.

The grammar has no rule for either word, abstractions or tunables. A tunables file parses because every line in it reduces to one of the three preamble productions. An abstraction parses because its lines reduce to rules. Swap them and the grammar is simply in the wrong state: an equals sign where a mode was expected, or a mode where an opening brace was expected. The error then carries the name of the included file, taken from the include stack. And the include cache means global can be included from several places in one preamble at no cost.

Details and sources

for AppArmor developers for security researchers

Details

  • The findings for this district record "Grammar: none of its own" for both conventions; the statement was not established by a search of the whole tree for the two words.
  • preamble: parser_yacc.y:506-509. The rules alternatives on the slide: parser_yacc.y:722, parser_yacc.y:724, parser_yacc.y:845-850.
  • Recorded in the research notes (the same two messages were obtained again for this deck, with files of other names): AppArmor parser error for /work/t1.sd in profile /src/apparmor/profiles/apparmor.d/tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE, and AppArmor parser error for /work/t2.sd in profile /src/apparmor/profiles/apparmor.d/abstractions/consoles at line 16: syntax error, unexpected TOK_MODE, expecting TOK_OPEN. In the second, the first rule of the abstraction is taken for a profile name.
  • The include stack: parser_include.c:197-239.
  • One include cache for the preamble and a new one per profile: parser_yacc.y:396-397, parser_yacc.y:454-455. The marker on the slide is recorded for a file that includes tunables/global twice in its preamble.

for AppArmor developers for security researchers

Read more

07 The right file in the wrong place

MISTAKES profile demo { include <tunables/global> } in profile .../tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE include <abstractions/consoles> in the preamble in profile .../abstractions/consoles at line 16: syntax error, unexpected TOK_MODE, expecting TOK_OPEN when the message names a shipped file you did not touch, look at where you included it include <abstractions/base> no tunables/global Failed to find declaration for: @{HOMEDIRS} @{HOMEDIRS} = /srv/nfs/home/ in a site file variable @{HOMEDIRS} was previously declared use +=
Four mistakes. include tunables/global inside a profile: an error in tunables/home at line 15, unexpected TOK_EQUALS. include abstractions/consoles above the profile: an error in abstractions/consoles at line 16, unexpected TOK_MODE. include abstractions/base without tunables/global: Failed to find declaration for @{HOMEDIRS}. @{HOMEDIRS} = in a site file: variable @{HOMEDIRS} was previously declared; use +=.

Tunables above the profile, abstractions inside, and tunables/global whenever you use an abstraction.

Three mistakes cover most of it. Include a tunables file inside the profile and you get a syntax error that points into the shipped file, at its first assignment. Include an abstraction above the profile and the error points at the abstraction's first rule. In both cases the shipped file is fine. It's just in the wrong half of yours. Third, use an abstraction and forget tunables/global: now a variable has no declaration. And in a site file, a plain equals on a variable the shipped file already declared is refused. Add to it instead.

Details and sources

Details

  • All four rows were run with the tree's parser for this deck, each as a small file for demo; each exits with status 1. Rows 1 and 2 are also recorded in the research notes.
  • Row 1 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. The slide shortens the directory to ....
  • Row 2 in full: AppArmor parser error for /work/at06b.sd in profile /src/apparmor/profiles/apparmor.d/abstractions/consoles at line 16: syntax error, unexpected TOK_MODE, expecting TOK_OPEN.
  • Row 3 prints two lines and no file or line: Failed to find declaration for: @{HOMEDIRS} and ERROR expanding variables for profile demo, failed to load. @{HOMEDIRS} is the first undefined name met; the manual describes the case with @{HOME}.
  • Row 4: the assignment stood in the profile file's own preamble, after include <tunables/global>, as a stand-in for a site file. Output: '@{HOMEDIRS}' is already defined and AppArmor parser error for /work/at06d.sd in profile /work/at06d.sd at line 3: variable @{HOMEDIRS} was previously declared.
  • The file names under /work/ are scratch names of the runs.
  • Known discrepancy: An undefined variable is reported without file name or line.

08 Which abstraction, and what the variables do

ROADS tunables/ abstractions/ prac-abstractions which to choose ut-logprof the tools propose them syn-variables syn-variable-assignment syn-alias the alias file among the tunables syn-include-if-exists the .d directories syn-preamble syntax-map
The two directories tunables and abstractions in the centre. Roads from abstractions to the decks prac-abstractions and ut-logprof, from tunables to syn-variables, syn-variable-assignment and syn-alias, and below to syn-include-if-exists, syn-preamble and syntax-map.

Mechanism here; choosing abstractions is its own deck.

So: two directories, one for each half of a profile file, both extended through .d directories. Which abstraction fits your program, and what each one grants, is the deck on choosing abstractions. What the variables from the tunables do inside a rule is the variables deck, and the alias file among the tunables leads to the deck on alias rules. And the .d directories themselves are in the deck on include if exists.

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 and the tree's profiles/apparmor.d on the search path), with nothing loaded into a kernel; "code" means the parser source or a shipped policy file was read and not run; "derived" means the result was reasoned from that code. Nothing here was observed on a running kernel.

The two conventions

TunablesAbstractions
Directorytunables/abstractions/
Included fromthe preamblea profile body, also of a child profile or a hat
May containvariable assignments, alias rules, includes of other tunables filesrules, includes of other abstractions, an indented abi line
Last lineinclude if exists <tunables/NAME.d>include if exists <abstractions/NAME.d>
Site changesassignments in tunables/NAME.d/, usually with +=rules in abstractions/NAME.d/
In the wrong placea syntax error in the tunables file (tree)a syntax error in the abstraction (tree)

Neither has syntax of its own. Both are files found on the include search path (code).

The tunables files

FileIncluded by globalDefinesShipped .d directory
home1@{HOMEDIRS}=/home/, @{HOME}=@{HOMEDIRS}/*/ /root/home.d with site.local
multiarch2@{multiarch}=*-linux-gnu*multiarch.d with site.local
proc3@{PROC}=/proc/none
alias4nothing: comments with two example alias rulesnone
kernelvars5@{pid}, @{tid}, @{pids}, @{uid}, @{uids}, @{sys}=/sys/none
system6character classes and counted patterns such as @{int}, @{hex}, @{u16} (102 lines)none
xdg-user-dirs7@{XDG_DESKTOP_DIR}="Desktop" and seven morexdg-user-dirs.d with site.local
share8@{flatpak_exports_root}, @{system_share_dirs}, @{user_share_dirs}none
etc9@{etc_ro}=/etc/ /usr/etc/, @{etc_rw}=/etc/none
run10@{run}=/run/ /var/run/none
apparmorfs, securityfs, sys, dovecot, gs, ntpd, print-devices, rygelnonot examined herenone

The order is that of the -p markers of the running example (tree). tunables/global also tries tunables/global.d (tree: ##failed include). The shipped tunables use only = (code).

The shape of an abstraction

abstractions/base as the example (code):

LineText
13abi <abi/5.0>, (indented)
15include <abstractions/crypto>
62@{etc_ro}/ld.so.cache mr,
177owner @{HOME}/.Private/** mrixwlk,
184include if exists <abstractions/base.d>
  • Including it gives the markers ##included <abstractions/base>, <abstractions/crypto>, <abstractions/openssl>, <abstractions/upki> (tree).
  • Its rules use variables of the tunables; without include <tunables/global> the profile fails with Failed to find declaration for: @{HOMEDIRS} (tree).
  • No profile head and no braces.

Site changes

  • Where: a file in the NAME.d directory of the shipped file. Which names are skipped there is in syn-include-if-exists.
  • What shape: the shape of the file it extends. Assignments for a tunables file, rules for an abstraction.
  • Which operator: +=. A plain = on a declared variable gives variable @{HOMEDIRS} was previously declared (tree, with the assignment in the profile file's own preamble).
  • Afterwards: reload the profiles with apparmor_parser -r. The change takes effect when a profile is compiled (derived).
  • A worked change to @{HOMEDIRS} with its dump is in the scene "Change the dot d directory, not the shipped file".

Errors

MessageCauseBasis
in profile .../tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODEinclude <tunables/global> inside a profiletree
in profile .../abstractions/consoles at line 16: syntax error, unexpected TOK_MODE, expecting TOK_OPENinclude <abstractions/consoles> above the profiletree
Failed to find declaration for: @{HOMEDIRS}, then ERROR expanding variables for profile demo, failed to loadinclude <abstractions/base> without include <tunables/global>tree
variable @{HOMEDIRS} was previously declared@{HOMEDIRS} = ... after the tunables declared ittree
in profile FILE at line N: ... for a file of a NAME.d directorya syntax error in a site file; every profile that includes NAME failstree, with a stand-in file

Which abstractions exist and what each grants is prac-abstractions.

for AppArmor developers for security researchers

In the code

  • A tunables file is accepted by the preamble productions (parser_yacc.y:506-509); an abstraction by rules (parser_yacc.y:722-724, parser_yacc.y:845-850).
  • Messages take the file name and line from the include stack (parser_include.c:197-239).
  • One include cache for the preamble and one per profile (parser_yacc.y:396-397, parser_yacc.y:454-455).
  • Known discrepancy: The files of an included directory are compiled in reverse alphabetical order, and an error in one is reported with a neighbour's file name.
  • 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.
  • Known discrepancy: Stale comment headers in two abstractions.
  • Known discrepancy: @{u16} has an unbalanced bracket and also matches [ and 65536 to 69999.

Roads from here

START HERE

PREAMBLE AND REUSE

IN PRACTICE · general-purpose apps

TOOLS · utils/