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
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>andinclude <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'sprofiles/apparmor.dis 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
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/baseas the example: a comment header, an indentedabi <abi/5.0>,and nested includes such asinclude <abstractions/crypto>(base:13-15), rules, and the last lineinclude if exists <abstractions/base.d>(base:184). - 135 lines under
profiles/apparmor.dare the indentedabi <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 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
-pmarkers 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, theninclude 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 variableson the example file prints 85 lines;$DEMO_DEBUGand@APP_DATAare 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
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
-pmarkers 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 anaare:line of the same file's-D rule-exprsdump; 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 withFailed 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 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 ruleaudit deny @{HOME}/.ssh/** rw,is compiled as{/home/*,/root,/srv/nfs/home/*}/.ssh/**. In the run the line stood in a filesite.localin a directory given with-Iand was included withinclude if exists <site.local>afterinclude <tunables/global>; it stands in fortunables/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 namesiteand the rule/srv/shared/certs/** r,are invented, and the slide shows no dump for it. apparmor_parser -ris the reload command of Running apparmor_parser; no output is shown.- Shipped
.ddirectories:tunables/home.d,tunables/multiarch.d,tunables/xdg-user-dirs.d, each with asite.localof 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
.ddirectory are skipped: see include if exists. - A syntax error in a
NAME.dfile 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
- See the scene "A directory that every profile reads" of include if exists.
06 No special code, only the two halves of the grammar for AppArmor developers for security researchers
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. Therulesalternatives 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, andAppArmor 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/globaltwice in its preamble.
07 The right file in the wrong place
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}andERROR 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 definedandAppArmor 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
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
| Tunables | Abstractions | |
|---|---|---|
| Directory | tunables/ | abstractions/ |
| Included from | the preamble | a profile body, also of a child profile or a hat |
| May contain | variable assignments, alias rules, includes of other tunables files | rules, includes of other abstractions, an indented abi line |
| Last line | include if exists <tunables/NAME.d> | include if exists <abstractions/NAME.d> |
| Site changes | assignments in tunables/NAME.d/, usually with += | rules in abstractions/NAME.d/ |
| In the wrong place | a 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
| File | Included by global | Defines | Shipped .d directory |
|---|---|---|---|
home | 1 | @{HOMEDIRS}=/home/, @{HOME}=@{HOMEDIRS}/*/ /root/ | home.d with site.local |
multiarch | 2 | @{multiarch}=*-linux-gnu* | multiarch.d with site.local |
proc | 3 | @{PROC}=/proc/ | none |
alias | 4 | nothing: comments with two example alias rules | none |
kernelvars | 5 | @{pid}, @{tid}, @{pids}, @{uid}, @{uids}, @{sys}=/sys/ | none |
system | 6 | character classes and counted patterns such as @{int}, @{hex}, @{u16} (102 lines) | none |
xdg-user-dirs | 7 | @{XDG_DESKTOP_DIR}="Desktop" and seven more | xdg-user-dirs.d with site.local |
share | 8 | @{flatpak_exports_root}, @{system_share_dirs}, @{user_share_dirs} | none |
etc | 9 | @{etc_ro}=/etc/ /usr/etc/, @{etc_rw}=/etc/ | none |
run | 10 | @{run}=/run/ /var/run/ | none |
apparmorfs, securityfs, sys, dovecot, gs, ntpd, print-devices, rygel | no | not examined here | none |
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):
| Line | Text |
|---|---|
| 13 | abi <abi/5.0>, (indented) |
| 15 | include <abstractions/crypto> |
| 62 | @{etc_ro}/ld.so.cache mr, |
| 177 | owner @{HOME}/.Private/** mrixwlk, |
| 184 | include 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 withFailed to find declaration for: @{HOMEDIRS}(tree). - No profile head and no braces.
Site changes
- Where: a file in the
NAME.ddirectory 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 givesvariable @{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
| Message | Cause | Basis |
|---|---|---|
in profile .../tunables/home at line 15: syntax error, unexpected TOK_EQUALS, expecting TOK_MODE | include <tunables/global> inside a profile | tree |
in profile .../abstractions/consoles at line 16: syntax error, unexpected TOK_MODE, expecting TOK_OPEN | include <abstractions/consoles> above the profile | tree |
Failed to find declaration for: @{HOMEDIRS}, then ERROR expanding variables for profile demo, failed to load | include <abstractions/base> without include <tunables/global> | tree |
variable @{HOMEDIRS} was previously declared | @{HOMEDIRS} = ... after the tunables declared it | tree |
in profile FILE at line N: ... for a file of a NAME.d directory | a syntax error in a site file; every profile that includes NAME fails | tree, 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
preambleproductions (parser_yacc.y:506-509); an abstraction byrules(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
- The profile language at a glance — every kind of line on one page
PREAMBLE AND REUSE
- include — the line both conventions are built on
- include if exists — the NAME.d directories and site files
- Variables — what the tunables files define
- Variable assignment — extending a tunable from a site file
- alias rules — the tunables file that holds aliases
- The abi rule and the abi files — the abi line at the top of an abstraction
- The preamble — why a tunables file cannot go inside a profile
IN PRACTICE · general-purpose apps
- Choosing abstractions — which abstraction to choose and what each grants
TOOLS · utils/
- aa-logprof — the utilities propose abstractions