Variables

@{VAR} and sets for application developers

A set variable is a name for one or several pieces of path text. It is assigned in the preamble and a reference in a rule is replaced by its values before the rule is compiled. Several values become an alternation. Slashes next to a reference are trimmed. The kernel receives only the expanded pattern.

On the map: preamble and reuse

▶ Watch this deck — 8 scenes, ~6 min

Worth seeing first

Part of journeys

01 One name for two directories

VARIABLES /var/lib/demo /srv/demo @{APP_DATA} = /var/lib/demo /srv/demo line 3, in the preamble profile demo /usr/bin/demo { owner @{APP_DATA}/{cache,state}/** rwk, } $ apparmor_parser -Q -D rule-exprs demo {/srv/demo,/var/lib/demo}/{cache,state}/** one rule in the file; the compiled rule names both places; the kernel never sees the variable
Two directories, /var/lib/demo and /srv/demo. Line 3 of the preamble assigns both to the variable @{APP_DATA}, and a rule in the profile demo uses the variable. Lines run from the rule to both directories. The parser prints the compiled rule as one pattern with both directories in an alternation.

@{APP_DATA} = /var/lib/demo /srv/demo names two directories. A rule that uses the variable is compiled for both.

Demo keeps its data in two places: the usual one, /var/lib/demo, and a second one, /srv slash demo. You could write every rule twice. Instead, line 3 of the preamble gives the pair a name, and the rules use the name. That's the @{APP_DATA} variable. When the profile is compiled, the name is replaced by its values, so the one rule covers both directories. Ask the parser for the rule it actually built, and you see the two directories side by side in one pattern. The variable itself is gone by then: the kernel only ever gets the expanded rule.

Details and sources

Details

  • The line is line 3 of this district's example file: @{APP_DATA} = /var/lib/demo /srv/demo. The rule is its line 10: owner @{APP_DATA}/{cache,state}/** rwk,.
  • The dump line in full, run with the tree's parser for this deck (-Q -K --skip-kernel-load -D rule-exprs): aare: {/srv/demo,/var/lib/demo}/{cache,state}/** -> (/srv/demo|/var/lib/demo)/(cache|state)/[^/\x00][^\x00]*. The slide shows the text left of the arrow.
  • Expansion is done when the profile is compiled, and only then. The compiled profile holds the expanded pattern; the kernel has no variables.
  • The utilities do not expand variables when they match a path against a rule.
  • Known discrepancy: The utilities' path matching ignores variables, so aa-logprof does not see that a rule with @{...} covers a logged path.
  • The program demo, its files and its profile are invented for the map.

Read more

for AppArmor developers for security researchers

In the code

02 A name in curly braces, and a line of values

GRAMMAR @{ NAME } @{APP_DATA} demo's variable @{NAME} = value value ... end of line, no comma += ?= := separated by blanks @{APP_DATA} = /var/lib/demo /srv/demo line 3 /srv/demo "with space" "" a word, a quoted string, the empty value @{APP_DATA} = /var/lib/demo \ /srv/demo # two places a backslash continues the line; a comment may follow a letter, then letters, digits, _ @{Case} @{case} two different variables their own deck
Two syntax diagrams. A reference is @{ NAME }. An assignment is @{NAME}, an operator = (or +=, ?=, :=), one or more values separated by blanks, and the end of the line without a comma. Under them demo's line 3, three kinds of value (a word, a quoted string, the empty value), a line continued with a backslash and followed by a comment, and two names that differ only in case.

@{NAME} = value value ... up to the end of the line. Names are case sensitive; values may be quoted.

A variable is an at sign, an opening curly brace, a name and a closing brace. You give it values in the preamble: the variable, an operator, and then values separated by blanks, up to the end of the line. A value is a word, or a quoted string if it has a space in it, and two quotes with nothing between them make an empty value. Note what's missing: there's no comma. The line end finishes the assignment, unless a backslash carries it on. The name starts with a letter and goes on with letters, digits and underscores, and case matters. The other operators have their own deck.

Details and sources

Details

  • A reference is @{NAME}. The name is a letter followed by letters, digits and underscores, and it is case sensitive: @{Case} and @{case} are two variables (run with the tree's parser for this deck: -D variables prints @case = "/lower" and @Case = "/upper").
  • apparmor.d(5) gives the same form: VARIABLE = '@{' ALPHA [ ( ALPHANUMERIC | '_' ) ... ] '}' (apparmor.d.pod:112).
  • An assignment is the variable, one of four operators and values up to the end of the line. Each word or quoted string is one value. "" is the empty value.
  • A quoted value may hold a comma: @{LIBVIRT} = "libvirt," (vars_simple_assignment_13.sd, expected to pass).
  • A comma outside quotes is refused: Variable declarations do not accept trailing commas.
  • The continued line on the slide was run with the tree's parser for this deck: @{APP_DATA} = /var/lib/demo \ followed by /srv/demo # two places gives @APP_DATA = "/srv/demo" "/var/lib/demo", exit status 0.
  • Assignments stand in the preamble only: see the preamble. The four operators are in variable assignment.
  • The scanner also accepts @NAME without braces in an assignment, and it is the same variable as @{NAME}.
  • Known discrepancy: @NAME without braces is accepted in a rule and compiled as literal text. Recorded in the research notes: @NOBRACE = /nb and the rule @NOBRACE/x r, print aare: @NOBRACE/x, exit status 0.

for AppArmor developers for security researchers

In the code

  • VARIABLE_NAME [[:alpha:]][[:alnum:]_]* and SET_VARIABLE @(\{VARIABLE_NAME\}|VARIABLE_NAME) (parser_lex.l:296-298).
  • After the operator the scanner is in ASSIGN_MODE until the end of the line (parser_lex.l:564-590, parser_lex.l:824-832): each word or quoted string is one TOK_VALUE, \ at the end of a line continues the list, a comma is the error.
  • varassign: TOK_SET_VAR assign_op valuelist (parser_yacc.y:524-548).

03 The home variable, step by step

EXPANSION audit deny @{HOME}/.ssh/** rw, line 11 variables @HOME = "/root/" "@{HOMEDIRS}/*/" @HOMEDIRS = "/home/" "/home//*/" "/root/" @{HOMEDIRS} filled in /home//* /root the rule goes on with a slash, so the values lose theirs {/home/*,/root}/.ssh/** two values: an alternation a doubled slash in a path becomes one one value: no braces @{PROC}/sys/ becomes /proc/sys/
The rule audit deny @{HOME}/.ssh/** rw passes three stations. The table of variables gives @HOME the values "/root/" and "@{HOMEDIRS}/*/", and @HOMEDIRS the value "/home/". The values resolve to "/home//*/" and "/root/", their trailing slashes are struck out, and the result is the alternation {/home/*,/root}/.ssh/**, in which the doubled slash has become one.

@{HOME}/.ssh/** becomes {/home/*,/root}/.ssh/**: the values joined as an alternation, with slashes trimmed at the joint.

Follow one rule through. Demo denies access to .ssh under the @{HOME} variable. The table says that variable has two values: root's own directory, and a second one that's built from another variable, the @{HOMEDIRS} variable. The parser fills that in first, so the second value becomes every directory under /home. Then it tidies the joints. The rule continues with a slash after the variable, so each value drops its own trailing slash. Finally the two values go into curly braces, separated by a comma: an alternation, the same one you could have written by hand. A variable with a single value is simply replaced, without braces.

Details and sources

Details

  • The rule is line 11 of the example file: audit deny @{HOME}/.ssh/** rw,.
  • The two table lines are from -D variables, which prints the table as written: @HOME = "/root/" "@{HOMEDIRS}/*/" and @HOMEDIRS = "/home/". Both variables come from the shipped file tunables/home: see abstractions and tunables.
  • The resolved values are from -D expanded-variables: @HOME = "/home//*/" "/root/".
  • The result is the aare: line of -D rule-exprs: {/home/*,/root}/.ssh/**. All three dumps were run with the tree's parser for this deck.
  • The double slash in /home//*/ is what the dump prints. The compiled rule has /home/*: file rule paths pass through a filter that turns repeated slashes into one.
  • Trimming: when the text before the reference ends in /, leading slashes of each value are trimmed; when the text after it begins with /, trailing slashes are trimmed. Recorded in the research notes: /srv/@{HOME}/x r, compiles as /srv/{home/*,root}/x.
  • A value may refer to other variables. They are resolved when the variable is first needed, so a reference may stand before the assignment it refers to: @{b} = @{A}/fwd before @{A} = /a is accepted (recorded in the research notes).
  • The single-value example was run with the tree's parser for this deck: with tunables/global included, @{PROC}/sys/ r, prints aare: /proc/sys/. The shipped value is @{PROC}=/proc/.
  • Known discrepancy: A variable after a prefix of only slashes keeps its leading /, so the rule starts with // and never matches.

for AppArmor developers for security researchers

In the code

  • variable::expand_by_alternation (variable.cc:252-340); the trimming is at lines 288-295 and 310-322.
  • expand_variable resolves nested references and keeps the result in expanded (variable.cc:342-404).
  • Path rules then pass through filter_slashes.

04 Values are a set, not a list

VALUES @{D} = "with space" plain @{E} = "" @{APP_DATA} = /var/lib/demo /srv/demo /q/@{D} r, /q/{plain,with space} the quotes are gone; the space stays /e/@{E}/x r, /e/x the empty value: nothing is inserted $ apparmor_parser -Q -D variables demo @APP_DATA = "/srv/demo" "/var/lib/demo" as written /var/lib/demo /srv/demo printed in text order the order of an alternation has no effect on what the rule matches
Three assignments: @{D} with a quoted value and a plain one, @{E} with the empty value, and demo's @{APP_DATA}. The rule /q/@{D} becomes /q/{plain,with space}. The rule /e/@{E}/x becomes /e/x. The dump of variables prints the two values of @APP_DATA in text order, /srv/demo before /var/lib/demo, the reverse of the order written.

Values are stored as a set: no duplicates, and printed in text order. "" is the empty value.

Three small facts about values. A quoted value keeps its space, and in the expanded rule it's just one of the alternatives. The empty value, two quotes, expands to nothing, which is handy for an optional part of a path. And the values form a set, not a list. Write the same value twice and it's stored once. Print the table, and the values come out in text order, not in the order you wrote them. That doesn't change what a rule matches, since an alternation doesn't care about order, but it explains why the dump looks rearranged.

Details and sources

Details

  • The first two assignments and their rules are from a profile recorded in the research notes: @{D} = "with space" plain with /q/@{D} r, prints aare: /q/{plain,with space}; @{E} = "" with /e/@{E}/x r, prints aare: /e/x.
  • The third line is the example file's line 3. -D variables prints @APP_DATA = "/srv/demo" "/var/lib/demo" for it (run with the tree's parser for this deck). The whole dump has 85 lines, because tunables/global defines the rest.
  • Duplicates collapse: @{DUP} = /a /a /b prints @DUP = "/a" "/b", and @{DUP}/x r, compiles as {/a,/b}/x (run with the tree's parser for this deck).
  • -D variables prints the table as written (@HOME = "/root/" "@{HOMEDIRS}/*/"), -D expanded-variables after expansion (@HOME = "/home//*/" "/root/"). Both print names as @NAME without braces, and boolean variables as $NAME = true.
  • A comma is not a separator: @{A} = /a, is the error Variable declarations do not accept trailing commas.
  • That the order of an alternation does not change what a rule matches is derived: the alternation is compiled as a regular expression of alternatives.

for AppArmor developers for security researchers

In the code

05 Where a reference is expanded

WHERE variables profile demo /usr/bin/demo { the name and the attachment: also expanded owner @{APP_DATA}/** rw, file rules: the path link @{APP_DATA}/current -> @{APP_DATA}/releases/*, link rules: both paths signal (send) peer=@{profile_name}//worker, signal and ptrace: the peer mount fstype=tmpfs tmpfs -> @{run}/demo/, dbus send path=/org/demo/@{pid}, mount, dbus and unix rules: their paths, names and labels } network, userns and capability rules have no text to expand
The table of variables feeds a profile. Five lines of the profile each carry a variable: a file rule with @{APP_DATA}, a link rule with it on both sides, a signal rule whose peer uses @{profile_name}, a mount rule whose mount point uses @{run}, and a dbus rule whose path uses @{pid}. Network, userns and capability rules have no text to expand.

Variables are expanded in the paths, names and labels of most rule classes and in the profile head, once per profile after parsing.

Where can you use a variable? Almost anywhere a rule has a path, a name or a label. Even the profile's own name and attachment may use one. File rules, of course. Link rules, on both sides of the arrow. The peer of a signal or ptrace rule. The mount point of a mount rule, D-Bus paths and names, unix socket addresses. Rule classes that are made of fixed words only, like capability or network, have nothing to expand. All of this happens once per profile, after the whole file has been parsed. So order matters little: one variable's value can even mention another that's assigned further down.

Details and sources

Details

  • The five rule lines are illustrations built from the list of places where the parser expands variables. They were run together through the tree's parser for this deck, with tunables/global included, and compile with exit status 0. The dump shows {/srv/demo,/var/lib/demo}/**, {/srv/demo,/var/lib/demo}/current and {/srv/demo,/var/lib/demo}/releases/*, demo//worker, {/run,/var/run}/demo/ and /org/demo/ followed by the alternation of digit patterns that @{pid} stands for.
  • Expanded: the profile name, the attachment and the attach_disconnected.path and attach_disconnected.ipc values; file rule paths and link targets; mount point, device, transition and option and fstype values; dbus bus, name, peer label, path, interface and member; signal and ptrace peer labels; labels and unix addresses; mqueue name and label.
  • Nothing to expand: network, io_uring and userns rules (from the code). That a capability rule has no text to expand is derived: it is a list of fixed words.
  • Expansion runs once per profile after the whole file has been parsed. A value may mention a variable that is assigned further down: @{b} = @{A}/fwd before @{A} = /a is accepted (recorded in the research notes).
  • Known discrepancy: A variable in an exec target is accepted and never expanded.
  • Known discrepancy: Variables in io_uring ... label= are not expanded.
  • Known discrepancy: A variable cannot begin an mqueue name.
  • Known discrepancy: A profile name that begins with a variable is refused unless the head has the profile keyword.

for AppArmor developers for security researchers

In the code

06 One table, text substitution, per profile for AppArmor developers for security researchers

IN THE PARSER global_symtab HOME -> { "/root/", "@{HOMEDIRS}/*/" } HOMEDIRS -> { "/home/" } DEMO_DEBUG -> false one map for set and boolean variables expand_by_alternation() @{HOME}/.ssh/** extract_variable(): the first "@{" ... "}" get_set_var("HOME") -> expand_variable() resolves nested references once prefix ends in "/": trim leading slashes suffix begins with "/": trim trailing slashes one value: insert; several: "{" v1 "," v2 "}" repeat on the rest of the string process_profile_variables(prof) once per profile; each rule class has its own expand_variables()
The symbol table global_symtab with the entries HOME, HOMEDIRS and DEMO_DEBUG. The function expand_by_alternation takes the string @{HOME}/.ssh/**, extracts the first reference, looks it up in the table, resolves nested references, trims slashes and inserts one value or an alternation, then repeats on the rest of the string. process_profile_variables runs this once per profile.

variable.cc:252-340 expands the first @{...} and repeats; parser_variable.c:137-179 runs it per profile.

Under the hood there's one symbol table, a map from a name to a variable object. It holds booleans as well as sets, which is why the two kinds can't share a name. Expansion is plain text substitution. A function finds the first at sign and curly brace in a string, looks the name up, makes sure its own nested references are resolved, trims slashes at the joint, and writes either the single value or a brace alternation. Then it repeats on the rest of the string. This runs per profile after parsing, and every rule class brings its own function that says which of its strings to expand.

Details and sources

for AppArmor developers for security researchers

Details

  • The table is a map from name to variable (symtab.cc:25-151): add_var (25-76), add_set_value (90-101), delete_var (103-112), get_set_var (135-151).
  • In variable.cc: is_var (74-131), process_var (133-151), extract_variable (variable.cc:169-221), expand_by_alternation (variable.cc:252-340), expand_variable (variable.cc:342-404).
  • Only @{ starts a reference inside a string; \@ does not (variable.cc:184-194).
  • A nested reference is resolved the first time the variable is needed and the result is kept in expanded (variable.cc:353-355).
  • Recursion is detected: Variable @{A} is referenced recursively (by @{B}) (variable.cc:378-383).
  • process_profile_variables (parser_variable.c:137-179) is called once per profile from parser_policy.c:133.
  • Known discrepancy: A failed expansion inside a variable's value ends in std::bad_alloc instead of an error. Recorded in the research notes: @{A} = /a/@{UNDEF} with the rule @{A}/x r, prints Failed to find declaration for: @{UNDEF} and then terminate called after throwing an instance of 'std::bad_alloc'.
  • Known discrepancy: A variable defined from @{profile_name}, @{attach_path} or @{exec_path} keeps the value of the first profile that uses it. Recorded in the research notes: @{DIR} = /var/lib/@{profile_name} used in the profiles one and two compiles /var/lib/one/** in both.

for security researchers

Attack surface

  • A variable widens every rule that uses it, in every profile whose preamble includes its definition.
  • The definition can be extended from a .d directory: see include if exists.
  • The expanded rule, not the written one, is what is enforced. Review with -D rule-exprs.
  • Values are not checked for pattern characters. A value * or ** is a glob in every rule that uses the variable (derived from the substitution being textual; not run).

07 Mistakes and their messages

MISTAKES @{APP_DATA} = /var/lib/demo, Variable declarations do not accept trailing commas @{APP_DATA} = syntax error, unexpected TOK_PROFILE, expecting TOK_VALUE @{4DATA} = /var/lib/demo Lexer found unexpected character: '@' (0x40) in state: INITIAL @{APPDATA}/** rw, Failed to find declaration for: @{APPDATA} ERROR expanding variables for profile demo, failed to load a name nobody assigned ${DEMO_DEBUG} = false @{DEMO_DEBUG}/x r, Variable DEMO_DEBUG is not a set variable Failed to find declaration for: @{DEMO_DEBUG} the last two name the profile but no line: search the file for the name
Five wrong lines and the parser's messages. A trailing comma: Variable declarations do not accept trailing commas. No value: syntax error, unexpected TOK_PROFILE, expecting TOK_VALUE. A name that starts with a digit: Lexer found unexpected character. A name nobody assigned: Failed to find declaration for @{APPDATA}. A boolean used as a set: Variable DEMO_DEBUG is not a set variable.

No comma after an assignment. Failed to find declaration for: @{NAME} means the name was never assigned in this file's preamble.

The mistakes. A comma at the end of an assignment, out of habit from rules: the parser says so in plain words. Nothing after the equals sign. A name that starts with a digit, which the scanner doesn't recognise as a variable at all. Then the common one: a name that was never assigned, usually a typo or a missing include of the tunables. And a boolean variable used in a path is refused, because a boolean isn't a set. Those last two messages give you the variable and the profile, but no line number, so search the file for the name.

Details and sources

Details

  • Every row ends with exit status 1. All five were run with the tree's parser for this deck, with demo's names.
  • Row 1 in full: AppArmor parser error for /work/v-comma.sd in profile /work/v-comma.sd at line 1: Variable declarations do not accept trailing commas. The words in profile are followed by the name of the file being parsed, not by a profile name.
  • Row 2 in full: ... at line 2: syntax error, unexpected TOK_PROFILE, expecting TOK_VALUE. The token named is whatever follows the empty assignment; here it is the profile keyword of the next line.
  • Row 3: the scanner does not take @{4DATA} for a variable, so it stops at the @.
  • Row 4: the two lines on the slide are all that is printed. The rule was @{APPDATA}/** rw, in the profile demo, with tunables/global included.
  • Row 5 prints three lines: Variable DEMO_DEBUG is not a set variable, Failed to find declaration for: @{DEMO_DEBUG}, ERROR expanding variables for profile demo, failed to load. The slide shows the first two.
  • From the code, not run: Variable '%s' must start with alphabet letters and Variable '%s' contains invalid characters, for a malformed name inside a string.
  • @{a,b} in a rule is left as it is and, with --warn=all, draws The usage of comma in the variable formatting to indicate alternation is deprecated. Escape the character @ to indicate it is not a variable. The warning class is deprecated, off by default (recorded in the research notes).
  • Known discrepancy: An undefined variable is reported without file name or line.
  • Known discrepancy: The deprecation warning for @{a,b} advises escaping @, the escape draws a warning of its own, and a later variable in the same string is left unexpanded.
  • Known discrepancy: @NAME without braces is accepted in a rule and compiled as literal text.

for AppArmor developers for security researchers

In the code

08 Setting them, and the ones you get for free

ROADS @{APP_DATA} {/srv/demo,/var/lib/demo} a name, some values, an alternation syn-variable-assignment = += ?= := syn-abstractions-tunables @{HOME} and friends syn-builtin-variables @{profile_name} @{exec_path} syn-boolean-variables ${NAME} syn-globbing {a,b} syn-file-rules where most variables are used syn-profile-name variables in the head also: syn-rule-conditionals · syn-quoting · fe-post-process · syntax-map
The variable @{APP_DATA} and its alternation in the middle, with roads to the decks syn-variable-assignment, syn-abstractions-tunables, syn-builtin-variables, syn-boolean-variables, syn-globbing, syn-file-rules and syn-profile-name, and a line naming fe-post-process and syntax-map.

Onward: syn-variable-assignment, syn-builtin-variables, syn-boolean-variables, syn-globbing.

That's a set variable: a name, some values, and an alternation in the compiled rule. How the four operators set, extend and replace a variable is in the deck on variable assignment, and the tunables deck shows where the shipped variables come from. The three variables the parser defines for you, like the profile's own name, have the built-in variables deck, and the boolean kind has a deck too. And if the curly braces of the alternation are new to you, the globbing deck explains them.

Details and sources

Details

  • @{NAME} is a set of strings, assigned in the preamble, case sensitive.
  • A reference is replaced by the single value, or by {v1,v2,...} when there are several. Slashes at the joint are trimmed.
  • Expansion happens once per profile, after parsing. The compiled profile holds only the expanded patterns.
  • -D variables and -D expanded-variables print the table; -D rule-exprs prints the rules after expansion.
  • Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2). Variables have no kernel side.

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 as kernel feature set and the dump option named), 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

reference:   @{NAME}
NAME:        a letter, then letters, digits and _       (case sensitive)
assignment:  @{NAME} ( = | += | ?= | := ) VALUE ...     up to the end of the line
VALUE:       a word | "a quoted string" | ""
  • Assignments stand in the preamble, before the first profile (code).
  • Values are separated by blanks. There is no comma at the end; a comma outside quotes is an error (tree).
  • A quoted value keeps its spaces and may hold a comma: @{LIBVIRT} = "libvirt," (the parser's test vars_simple_assignment_13.sd).
  • "" is the empty value (tree).
  • A # comment may follow the values, and \ at the end of a line continues the list on the next line (tree).
  • @{Case} and @{case} are two variables (tree).
  • @NAME without braces is accepted in an assignment and is the same variable as @{NAME} (tree).
  • The four operators: see variable assignment.

Expansion

CaseWrittenCompiledBasis
one value@{PROC}/sys/ with @{PROC}=/proc//proc/sys/tree
several values@{HOME}/.ssh/**{/home/*,/root}/.ssh/**tree
text before ends in //srv/@{HOME}/x/srv/{home/*,root}/xtree
quoted value/q/@{D} with @{D} = "with space" plain/q/{plain,with space}tree
empty value/e/@{E}/x with @{E} = ""/e/xtree
duplicate value@{DUP}/x with @{DUP} = /a /a /b{/a,/b}/xtree
  • When the text before the reference ends in /, leading slashes of each value are trimmed. When the text after it begins with /, trailing slashes are trimmed (code).
  • File rule paths then pass through a filter that turns repeated slashes into one (code).
  • A value may refer to other variables. They are resolved the first time the variable is needed (code).
  • A reference may stand before the assignment it refers to: @{b} = @{A}/fwd before @{A} = /a (tree).
  • Values are a set: duplicates are stored once, and the order is that of the strings, not of writing (code; tree for the dump).

Where a reference is expanded

PlaceFieldsSource
profile headthe name, the attachment, the attach_disconnected.path and .ipc valuesparser_variable.c:58-85
file rulesthe pathblock_rules.cc:393-407
link rulesthe link and the targetblock_rules.cc:393-407
mount rulesmount point, device, transition, option and fstype valuesmount.cc:641
dbus rulesbus, name, peer label, path, interface, memberdbus.cc:176
signal rulesthe peer labelsignal.cc:249
ptrace rulesthe peer labelptrace.cc:108
unix ruleslabels and addressesaf_rule.cc:161, af_unix.cc:166
mqueue rulesthe name and the labelmqueue.cc:179
  • Not expanded, because the class has no text to expand: network, io_uring, userns (code).
  • The table is from the code. One rule each of the file, link, signal, mount and dbus rows was run (tree).

The two dumps

OptionPrintsFor the example file
-D variablesthe table as written@HOME = "/root/" "@{HOMEDIRS}/*/", @HOMEDIRS = "/home/", @APP_DATA = "/srv/demo" "/var/lib/demo", $DEMO_DEBUG = false; 85 lines
-D expanded-variablesthe table after expansion@HOME = "/home//*/" "/root/"; the others unchanged
-D rule-exprseach rule after expansionaare: {/home/*,/root}/.ssh/**, aare: {/srv/demo,/var/lib/demo}/{cache,state}/**
  • Names are printed as @NAME without braces, boolean variables as $NAME = true (tree).

Errors and warnings

MessageCauseExitBasis
Variable declarations do not accept trailing commasa comma at the end of an assignment1tree
syntax error, unexpected TOK_PROFILE, expecting TOK_VALUEno value after the operator; the token named is the next one in the file1tree
Lexer found unexpected character: '@' (0x40) in state: INITIALa name that starts with a digit1tree
Failed to find declaration for: @{NAME} then ERROR expanding variables for profile P, failed to loada name that was never assigned1tree
Variable NAME is not a set variable then the two lines abovea boolean variable used as a set1tree
Variable @{A} is referenced recursively (by @{B})two variables that refer to each othersee the known discrepanciestree
Variable '%s' must start with alphabet letters, Variable '%s' contains invalid charactersa malformed name inside a stringcode
The usage of comma in the variable formatting to indicate alternation is deprecated. Escape the character @ to indicate it is not a variable.@{a,b} in a rule; class deprecated, off by defaultwarningtree, with --warn=all

for security researchers

Attack surface

  • A variable widens every rule that uses it, in every profile whose preamble includes its definition.
  • A definition can be extended by any text that is included later, for example a file in a .d directory: see include if exists.
  • What is enforced is the expanded rule. -D rule-exprs prints it; the profile text does not.
  • Values are not checked for pattern characters, so a value * or ** is a glob in every rule that uses the variable (derived).

for AppArmor developers for security researchers

In the code

for AppArmor developers for security researchers

Known discrepancies

  • A variable defined from @{profile_name}, @{attach_path} or @{exec_path} keeps the value of the first profile that uses it. Run: @{DIR} = /var/lib/@{profile_name} used in the profiles one and two compiles /var/lib/one/** in both; -D expanded-variables prints @DIR = "/var/lib/one"; exit status 0.
  • A failed expansion inside a variable's value ends in std::bad_alloc instead of an error. Runs: @{A} = /a/@{UNDEF} with the rule @{A}/x r,; @{A} = @{B} and @{B} = @{A} with the rule /x/@{A} r,.
  • @NAME without braces is accepted in a rule and compiled as literal text. Run: @NOBRACE = /nb and the rule @NOBRACE/x r, print aare: @NOBRACE/x, exit status 0.
  • The deprecation warning for @{a,b} advises escaping @, the escape draws a warning of its own, and a later variable in the same string is left unexpanded. Runs: /a/@{x,y}/@{H} r, prints the warning and then Regex grouping error: Invalid number of items between {}, exit status 255; /a/\@{x,y} r, prints Character @ was quotedunnecessarily, dropped preceding quote ('\') character.
  • An undefined variable is reported without file name or line.
  • A variable after a prefix of only slashes keeps its leading /, so the rule starts with // and never matches.
  • A variable in an exec target is accepted and never expanded.
  • Variables in io_uring ... label= are not expanded.
  • A variable cannot begin an mqueue name.
  • A profile name that begins with a variable is refused unless the head has the profile keyword.
  • The utilities' path matching ignores variables, so aa-logprof does not see that a rule with @{...} covers a logged path.

Roads from here

START HERE

FILE ACCESS

PREAMBLE AND REUSE

PROFILE HEAD

RULE CLASSES

PROFILE STRUCTURE

INSIDE THE PARSER