Boolean variables

${NAME} for application developers

A boolean variable holds true or false. It is assigned in the preamble from the words true or false or from an expression and it is tested in conditional blocks. It shares its name space with set variables and has no meaning inside a path. Its value is fixed when the profile is compiled.

On the map: preamble and reuse

▶ Watch this deck — 8 scenes, ~6 min

Worth seeing first

  • Variables — set variables, which booleans are written like

01 One line that switches a rule on

BOOLEAN VARIABLES ${DEMO_DEBUG} = false line 4 profile demo /usr/bin/demo { } if ${DEMO_DEBUG} { /tmp/demo-debug.log w, } line 13 ${DEMO_DEBUG} = false 106 lines ${DEMO_DEBUG} = true 107 lines /tmp/demo-debug.log compiled lines of -D rule-exprs the value is used when the profile is compiled; nothing is tested while demo runs
Four lines of demo's file: ${DEMO_DEBUG} = false in the preamble, and in the profile the block if ${DEMO_DEBUG} { /tmp/demo-debug.log w, }. A line links the two uses of the variable. With false the dump of -D rule-exprs has 106 compiled lines; with true it has 107, and the extra line is /tmp/demo-debug.log.

${DEMO_DEBUG} = false in the preamble; if ${DEMO_DEBUG} { ... } in the profile. The value decides what is compiled.

Demo has a debug log that only test builds should be allowed to write. You don't want two copies of the profile. Line 4 of the preamble declares a switch, the ${DEMO_DEBUG} variable, and sets it to false. Further down, one rule sits in a block that's only compiled if the switch is true. With false, the dump of the compiled profile has a hundred and six lines. Change the one word to true, compile again, and there are a hundred and seven, the extra one being the log file. The switch is thrown at compile time: the loaded profile simply has the rule or doesn't.

Details and sources

Details

  • The lines are lines 4, 6, 13 and 14 of this district's example file.
  • The counts on this slide are the lines of -D rule-exprs that begin aare:: 106 with ${DEMO_DEBUG} = false, 107 with true. They are compiled lines, not rules of the file: two are the attachment and its alias twin, three are peer labels (aare: demo) from abstractions/base, 17 are alias twins, and the rest are the rules of the file and of the included abstraction. The extra line is aare: /tmp/demo-debug.log. Both were run with the tree's parser for this deck.
  • -D variables prints the switch as $DEMO_DEBUG = false.
  • No shipped profile or tunables file defines a boolean (grep of profiles/apparmor.d).
  • Nothing of the variable reaches the kernel: the compiled profile has the rule or does not have it.

02 A dollar sign, a name, true or false

GRAMMAR ${NAME} $NAME = ?= := true false expression end of line ${DEMO_DEBUG} = false line 4 @{APP_DATA} a set: at sign ${DEMO_DEBUG} a boolean: dollar sign $VAR = True ${BOOLEAN} = fALsE $HO_HUM=TRUE accepted: braces optional, any case the name: as for set variables, a letter, then letters, digits, _ preamble only; no comma; += is not allowed
Syntax diagram: ${NAME} or $NAME, then = (or ?=, :=), then true, false or an expression, up to the end of the line. Demo's line 4 is the example. A set variable starts with an at sign, a boolean with a dollar sign. Three accepted spellings: $VAR = True, ${BOOLEAN} = fALsE, $HO_HUM=TRUE.

${NAME} = true or false, any case, in the preamble. $NAME without braces is the same variable.

A boolean variable looks like a set variable with a dollar sign in place of the at sign: dollar, curly brace, name, curly brace. You assign it in the preamble with an equals sign and the word true or false. The line ends the assignment, no comma. The dollar sign is the whole difference from a set. The braces are optional here, and true and false can be in any mix of case. The name follows the same rule as for sets. The default and replace operators work too; the add operator doesn't. And on the right you may write a whole expression, which is two scenes on.

Details and sources

Details

  • A boolean variable is written ${NAME} or $NAME. The name follows the rule for set variables: a letter, then letters, digits and underscores.
  • It is assigned in the preamble from true or false, in any mix of case, or from an expression. The line ends the assignment.
  • The three spellings on the slide are lines of the parser's own test boolean_good_1.sd (expected to pass). Run with the tree's parser for this deck, -D variables prints $VAR = true, $BOOLEAN = false, $HO_HUM = true, exit status 0.
  • apparmor.d(5): BOOL_VAR = '${' ALPHA [ ( ALPHANUMERIC | '_' ) ... ] '}' and one line of prose (apparmor.d.pod:110-114, apparmor.d.pod:2445-2451).
  • The operators =, ?= and :=: see variable assignment. += is refused.
  • A boolean assigned inside a profile is refused: see the scene "Mistakes and their messages".

for AppArmor developers for security researchers

In the code

03 A boolean is only ever tested

USE $DEMO_DEBUG = false if ${DEMO_DEBUG} { /tmp/demo-debug.log w, } false: block left out if not ${DEMO_DEBUG} { /etc/demo/** r, } true: block compiled in not, and, or may combine it /y/$B r, /y/$B in a path: ordinary text /tmp/${DEMO_DEBUG} r, Regex grouping error: Invalid number of items between {} with braces it is taken for an alternation
The table of variables holds $DEMO_DEBUG = false. The block if ${DEMO_DEBUG} { ... } is left out; the block if not ${DEMO_DEBUG} { ... } is compiled in. In a path, /y/$B compiles as the literal text /y/$B, and /tmp/${DEMO_DEBUG} is refused with Regex grouping error: Invalid number of items between {}.

A boolean variable is used only in the expression of an if. In a path, $NAME is literal text.

What can you do with a boolean once it's set? Exactly one thing: test it in the expression of an if block, alone or combined with not, and, or. There's no way to print it into a rule. Write a dollar sign and a name in a path, and the parser takes them as literal characters, dollar sign and all. Write it with braces and things get worse, because in a path curly braces mean an alternation, and one with a single item is an error. So keep booleans where they belong, between the word if and the opening brace.

Details and sources

Details

  • The two blocks were run together with the tree's parser for this deck: with ${DEMO_DEBUG} = false, if not ${DEMO_DEBUG} { /etc/demo/** r, } and if ${DEMO_DEBUG} { /tmp/demo-debug.log w, }, the dump of -D rule-exprs has /etc/demo/** and not the log file; exit status 0.
  • /y/$B r, compiles as the literal /y/$B (recorded in the research notes).
  • /tmp/${DEMO_DEBUG} r, was run with the tree's parser for this deck. It prints three lines: Regex grouping error: Invalid number of items between {}, Unable to parse input line '/tmp/${DEMO_DEBUG}', ERROR processing regexs for profile demo, failed to load. The exit status is 255: the failure is in the compile stage, not in the syntax stage.
  • In the value of a set variable ${FOO} is text too (vars_assignment_reference_1.sd, expected to pass).
  • A set variable alone is not a condition: @{V} = 9 and if @{V} { } is Invalid boolean : '@{V}' is not true or false (recorded in the research notes).

for AppArmor developers for security researchers

In the code

04 The right-hand side can be an expression

EXPRESSIONS ${A} = true variables $A = true ${B} = ${A} and not false $B = true another boolean, and, not ${C} = 3 > 2 $C = true a comparison of two numbers ${D} = defined @{NOPE} $D = false no set variable @{NOPE} ${EARLY} = ${LATER} ${LATER} = true Unset boolean variable ${LATER} used in if-expression worked out on the spot: assign a boolean above its use
Four assignments and the table of variables. ${A} = true gives $A = true. ${B} = ${A} and not false gives $B = true. ${C} = 3 > 2 gives $C = true. ${D} = defined @{NOPE} gives $D = false. A boolean ${EARLY} assigned from ${LATER}, which is assigned on the next line, is refused: Unset boolean variable ${LATER} used in if-expression.

${B} = ${A} and not false, ${C} = 3 > 2, ${D} = defined @{NOPE}: evaluated at once, stored as true or false.

True and false are the simple case. The right-hand side of a boolean assignment is really an expression, the same kind you write after if. So one switch can be computed from another, with and, or and not. It can be the result of a comparison. Or it can ask whether a set variable has been defined at all. The parser works the expression out the moment it reaches the line, and stores only the answer, which is why the table shows nothing but true and false. That also means order matters here: a boolean must be assigned above the line that uses it.

Details and sources

Details

  • The four assignments are from a profile recorded in the research notes. -D variables prints $B = true, $D = false, $C = true, $A = true, in the dump's own order; the slide orders the rows by line.
  • The right-hand side is the expression language of if: boolean variables, true, false, not, and, or, parentheses, comparisons and defined. The operators are explained in conditional blocks.
  • The expression is evaluated when the line is parsed, and only the result is stored.
  • The last example was run with the tree's parser for this deck: ${EARLY} = ${LATER} on line 1 and ${LATER} = true on line 2 print AppArmor parser error for /work/b-order.sd in profile /work/b-order.sd at line 1: Unset boolean variable ${LATER} used in if-expression, exit status 1. The message says "if-expression" although the line is an assignment.
  • Known discrepancy: Parser messages with wrong text or wrong line.
  • The man page describes the assignment of a boolean as "(space separated values)" (apparmor.d.pod:110); the code takes an expression. The deck follows the code.
  • Known discrepancy: apparmor.d(5): the grammar summary and text disagree with the parser in several places.
  • Known discrepancy: Conditionals: defined ${bool} is false for a defined boolean, and and/or and nested if do not short-circuit.

for AppArmor developers for security researchers

In the code

05 Who can throw the switch

WHERE THE VALUE COMES FROM demo's preamble ${DEMO_DEBUG} = false tunables/demo.d/site.local ${DEMO_DEBUG} := true include if exists <tunables/demo.d> the profile gives the default; the site file, included after it, replaces it the table holds $DEMO_DEBUG = true $ apparmor_parser ... no option sets a variable demo, loaded compiled with the value of that moment change the file, then compile and load again
Demo's preamble holds ${DEMO_DEBUG} = false and, below it, include if exists tunables/demo.d. A site file in that directory with ${DEMO_DEBUG} := true replaces the default, so the table holds $DEMO_DEBUG = true. A line from the apparmor_parser command line to the preamble is cut: no option sets a variable. The loaded profile demo was compiled with the value of that moment.

A boolean is set in the preamble or in a file it includes. There is no command-line switch; a change needs a recompile.

Where does the value come from? Only from the preamble of the file being compiled, including whatever that preamble includes. So a workable arrangement is this: the profile gives a default, and a small site file included after it replaces it, with :=. No site file, and the default stands. What you can't do is flip a boolean from the parser's command line: there's no option for it. And you can't flip it for a profile that's already loaded. The value was used up at compile time, so change the file, and load the profile again.

Details and sources

Details

  • A boolean gets its value from the preamble of the file being compiled and from the files that preamble includes.
  • The arrangement on the slide is an illustration; tunables/demo.d is an invented directory and no shipped profile works this way. It was run with the tree's parser for this deck: ${DEMO_DEBUG} = false, then include if exists <tunables/demo.d>, with the directory found through -I and holding one file site.local with the line ${DEMO_DEBUG} := true. -D variables prints $DEMO_DEBUG = true, -D rule-exprs has aare: /tmp/demo-debug.log, nothing is printed even with --warn=all, exit status 0. With ?= in place of = in the profile the result is the same (also run).
  • Without the directory the include is skipped and the default stands: see include if exists.
  • The other order, a file with ${DEMO_DEBUG} = true included first and ${DEMO_DEBUG} ?= false after it, also ends with $DEMO_DEBUG = true, but prints '${DEMO_DEBUG}' is already defined on standard error (run with the tree's parser for this deck). Known discrepancy: ?= on a declared variable prints '@{NAME}' is already defined.
  • ?= keeps an existing value, := replaces, = is an error for an existing name: see variable assignment.
  • "No option sets a variable" is derived: no option in parser/parser_main.c touches the table of variables before parsing. It was not run.
  • Set and boolean variables share one name space: ${A} = true then @{A} = /a is variable @{A} was previously declared (recorded in the research notes).
  • That the policy cache notices a changed included file is derived from the time stamp code and was not run: see the policy cache.
  • Nothing on this slide was observed on a running kernel.

for security researchers

Attack surface

  • Which rules a profile has depends on preamble state that can come from an included file or a .d directory: see include if exists.
  • A := in a file that is included later overrides the profile's own value.
  • Compare -D rule-exprs for the values that are possible.

06 The same table, a different scanner mode for AppArmor developers for security researchers

IN THE PARSER ${DEMO_DEBUG} = false scanner BOOL_VARIABLE + operator -> ASSIGN_EXPR_START operator -> ASSIGN_EXPR_MODE until the end of the line and, or, not, defined, in: tokens only here and after if grammar varassign: TOK_BOOL_VAR assign_op expr expr -> cond_expr -> false str_to_boolean(): any case add_var("DEMO_DEBUG", false) global_symtab DEMO_DEBUG -> false APP_DATA -> { "/srv/demo", "/var/lib/demo" } get_boolean_var() on a set: Variable %s is not a boolean variable
The line ${DEMO_DEBUG} = false enters the scanner. A BOOL_VARIABLE followed by an operator pushes ASSIGN_EXPR_START, and the operator switches to ASSIGN_EXPR_MODE until the end of the line. The grammar production varassign: TOK_BOOL_VAR assign_op expr evaluates the expression to false and calls add_var("DEMO_DEBUG", false) on global_symtab, which also holds the set variable APP_DATA.

parser_lex.l:706-779 switches to expression mode; parser_yacc.y:550-570 evaluates and stores into the shared symbol table.

For the scanner, a boolean variable followed by an assignment operator is a signal to change mode. After the operator it's in an expression mode until the end of the line, with the same vocabulary that follows the word if. The grammar has a second production for this case. Its action evaluates the expression right there and calls add_var with a boolean. The destination is the same global symbol table that holds the set variables, one map keyed by name, which is the whole reason a name can't be both. Lookups ask for one kind and complain if they find the other.

Details and sources

for AppArmor developers for security researchers

Details

07 Mistakes and their messages

MISTAKES ${DEMO_DEBUG} = maybe Invalid boolean : 'maybe' is not true or false ${DEMO_DEBUG} = 1 Invalid boolean : '1' is not true or false ${DEMO_DEBUG} += true Invalid assignment += not allowed with boolean variables if ${DEMO_DEBGU} { ... } Unset boolean variable ${DEMO_DEBGU} used in if-expression /tmp/${DEMO_DEBUG} r, Regex grouping error: Invalid number of items between {} exit status 255 profile demo /usr/bin/demo { ${DEMO_DEBUG} = false syntax error, unexpected TOK_BOOL_VAR, expecting TOK_ID or TOK_MODE or TOK_SET_VAR
Six wrong lines and the parser's messages. = maybe and = 1: Invalid boolean, is not true or false. += true: Invalid assignment += not allowed with boolean variables. A misspelt name in an if: Unset boolean variable ${DEMO_DEBGU} used in if-expression. A boolean in a path: Regex grouping error, exit status 255. An assignment inside the profile: syntax error, unexpected TOK_BOOL_VAR.

Only true or false (any case) or an expression. A misspelt name in an if is Unset boolean variable.

The mistakes. A boolean takes true or false. Not yes, not maybe, and not one or zero: the message quotes what you wrote. += is refused. A typo in the name inside an if shows up as an unset boolean, with the misspelt name in the message, which makes it easy to find. A boolean in a path fails in the compile stage with a message about curly braces, so if you see that one next to a dollar sign, this is why. And like every assignment, a boolean can't be set inside the profile: there it's a plain syntax error.

Details and sources

Details

  • All six rows were run with the tree's parser for this deck. Rows 1 to 4 and row 6 end with exit status 1, row 5 with 255.
  • Rows 1 and 2 are reported "at line 2" for an assignment on line 1: the line is that of the next token. The parser's own tests: $VAR = beeblebrox (boolean_bad_1.sd) and $FOO=1 (boolean_bad_8.sd), both expected to fail.
  • Row 3: ... at line 3: Invalid assignment += not allowed with boolean variables, for an assignment on line 2.
  • Row 4, with ${DEMO_DEBUG} = false in the preamble and the misspelt name in the block: ... at line 3: Unset boolean variable ${DEMO_DEBGU} used in if-expression.
  • Row 5 prints three lines: Regex grouping error: Invalid number of items between {}, Unable to parse input line '/tmp/${DEMO_DEBUG}', ERROR processing regexs for profile demo, failed to load.
  • Row 6 in full: ... at line 2: syntax error, unexpected TOK_BOOL_VAR, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. The parser's own test is boolean_bad_5.sd (expected to fail).
  • A boolean used as a set variable (@{A}/x with ${A} = true) prints Variable A is not a set variable (recorded in the research notes).
  • Known discrepancy: += on a boolean reports that the variable was not declared. This is the set-variable form @{A} += /a on a boolean A, not the form in row 3.

08 The blocks that read the switch

ROADS ${DEMO_DEBUG} = false a switch, set once, when the profile is compiled syn-variable-assignment = ?= := syn-variables the at-sign kind syn-boolean-conditionals if, else and the expressions syn-preamble where a boolean is assigned syn-abstractions-tunables a place for a site switch syn-globbing ${ } in a path syntax-map every kind of line also: fe-grammar
The line ${DEMO_DEBUG} = false in the middle, with roads to the decks syn-variable-assignment, syn-variables, syn-boolean-conditionals, syn-preamble, syn-abstractions-tunables, syn-globbing and syntax-map, and a line naming fe-grammar.

Onward: syn-boolean-conditionals, the blocks that test booleans.

A boolean variable by itself does nothing. It's a switch waiting for something to test it. The operators for assigning one are in the variable assignment deck, next to the set variables. What tests the switch is the conditional block, if and else. That deck also has the full expression language: comparisons, defined, and the order in which and, or and not bind. The preamble and tunables decks cover where a switch can live.

Details and sources

Details

  • ${NAME} holds true or false. It is assigned in the preamble with =, ?= or :=, from true, false or an expression.
  • Its one use is in the expression of a conditional block.
  • Set and boolean variables share one table.
  • The value is used when the profile is compiled.
  • Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2). Boolean 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

boolean:     ${NAME} | $NAME
NAME:        a letter, then letters, digits and _
assignment:  BOOLEAN ( = | ?= | := ) EXPRESSION      up to the end of the line
EXPRESSION:  true | false | a conditional expression
  • true and false are accepted in any mix of case: $VAR = True, ${BOOLEAN} = fALsE, $HO_HUM=TRUE (tree).
  • Assignments stand in the preamble only. Inside a profile the line is a syntax error (tree).
  • = is an error if the name exists, ?= keeps an existing value, := replaces, += is refused: see variable assignment.
  • The expression operators are in conditional blocks.

Where a boolean is used

PlaceResultBasis
if ${NAME} { } and any expression of an iftestedtree
the right-hand side of another boolean assignmenttestedtree
a path, without braces: /y/$B r,the literal text /y/$Btree
a path, with braces: /tmp/${DEMO_DEBUG} r,Regex grouping error: Invalid number of items between {}, exit status 255tree
the value of a set variabletextthe parser's test vars_assignment_reference_1.sd

Assignments and the stored value

Line-D variablesBasis
${A} = true$A = truetree
${B} = ${A} and not false$B = truetree
${C} = 3 > 2$C = truetree
${D} = defined @{NOPE}$D = falsetree
$VAR = True$VAR = truetree
${BOOLEAN} = fALsE$BOOLEAN = falsetree
${DEMO_DEBUG} = false then ${DEMO_DEBUG} := true$DEMO_DEBUG = truetree
${DEMO_DEBUG} = true then ${DEMO_DEBUG} ?= false$DEMO_DEBUG = truetree
  • The expression is evaluated when the line is parsed. A boolean used on the right must be assigned above: ${EARLY} = ${LATER} before ${LATER} = true is Unset boolean variable ${LATER} used in if-expression (tree).

One name space

  • Set and boolean variables share one table. ${A} = true then @{A} = /a is variable @{A} was previously declared (tree).
  • A boolean used as a set: Variable A is not a set variable (tree). A set used as a boolean: Variable %s is not a boolean variable (code).

Where the value comes from

  • The preamble of the file being compiled and the files it includes (code).
  • No command-line option sets a variable (derived: no option in parser/parser_main.c touches the table before parsing).
  • The value is used when the profile is compiled. A change takes effect at the next compile and load (derived).
  • No shipped profile or tunables file defines a boolean (grep of profiles/apparmor.d).

Errors

MessageCauseExitBasis
Invalid boolean : 'maybe' is not true or falsea word that is not true or false1tree
Invalid boolean : '1' is not true or falsea number1tree
Invalid assignment += not allowed with boolean variables+=1tree
Unset boolean variable ${NAME} used in if-expressiona name that was never assigned, in an if or in an assignment1tree
Regex grouping error: Invalid number of items between {}${NAME} in a path255tree
syntax error, unexpected TOK_BOOL_VAR, expecting TOK_ID or TOK_MODE or TOK_SET_VARan assignment inside a profile1tree
variable %s was previously declared= on a name that exists1code

for security researchers

Attack surface

  • Which rules a profile has depends on preamble state. That state can come from an included file or a .d directory: see include if exists.
  • A := in a file that is included later overrides the profile's own value.
  • -D rule-exprs prints the rules that were compiled; the profile text does not say which branch was taken.

for AppArmor developers for security researchers

In the code

for AppArmor developers for security researchers

Known discrepancies

  • apparmor.d(5): the grammar summary and text disagree with the parser in several places. The man page describes the assignment of a boolean as "(space separated values)" (apparmor.d.pod:110); the code takes an expression (tree).
  • Conditionals: defined ${bool} is false for a defined boolean, and and/or and nested if do not short-circuit.
  • += on a boolean reports that the variable was not declared. Run: ${A} = true then @{A} += /a prints Variable A is not a set variable and then variable @{A} was not previously declared, but is being assigned additional values.

Roads from here

START HERE

FILE ACCESS

PREAMBLE AND REUSE

INSIDE THE PARSER