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
${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-exprsthat beginaare:: 106 with${DEMO_DEBUG} = false, 107 withtrue. They are compiled lines, not rules of the file: two are the attachment and its alias twin, three are peer labels (aare: demo) fromabstractions/base, 17 are alias twins, and the rest are the rules of the file and of the included abstraction. The extra line isaare: /tmp/demo-debug.log. Both were run with the tree's parser for this deck. -D variablesprints 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
${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
trueorfalse, 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 variablesprints$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
BOOL_VARIABLE $(\{VARIABLE_NAME\}|VARIABLE_NAME)(parser_lex.l:299).varassign: TOK_BOOL_VAR assign_op expr(parser_yacc.y:550-570).str_to_booleancompares without regard to case (parser_misc.c:538-547).
03 A boolean is only ever tested
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, }andif ${DEMO_DEBUG} { /tmp/demo-debug.log w, }, the dump of-D rule-exprshas/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} = 9andif @{V} { }isInvalid boolean : '@{V}' is not true or false(recorded in the research notes).
Read more
- apparmor.d(5), Conditional rules.
- Conditional blocks.
- Globbing: alternations in a path.
for AppArmor developers for security researchers
In the code
TOK_BOOL_VARinfactor(parser_yacc.y:937-943, parser_yacc.y:953-959).get_boolean_var(cond_expr.cc:43-48).
04 The right-hand side can be an 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 variablesprints$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 anddefined. 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} = trueon line 2 printAppArmor 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, andand/orand nestedifdo not short-circuit.
for AppArmor developers for security researchers
In the code
- The scanner states
ASSIGN_EXPR_STARTandASSIGN_EXPR_MODE(parser_lex.l:706-711, parser_lex.l:728-749, parser_lex.l:771-779). - The action stores
add_var(name, boolean)(parser_yacc.y:555-563).
05 Who can throw the switch
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.dis an invented directory and no shipped profile works this way. It was run with the tree's parser for this deck:${DEMO_DEBUG} = false, theninclude if exists <tunables/demo.d>, with the directory found through-Iand holding one filesite.localwith the line${DEMO_DEBUG} := true.-D variablesprints$DEMO_DEBUG = true,-D rule-exprshasaare: /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} = trueincluded first and${DEMO_DEBUG} ?= falseafter it, also ends with$DEMO_DEBUG = true, but prints'${DEMO_DEBUG}' is already definedon 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.ctouches the table of variables before parsing. It was not run. - Set and boolean variables share one name space:
${A} = truethen@{A} = /aisvariable @{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
.ddirectory: see include if exists. - A
:=in a file that is included later overrides the profile's own value. - Compare
-D rule-exprsfor the values that are possible.
06 The same table, a different scanner mode for AppArmor developers for security researchers
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
- In
INITIAL, a boolean variable followed by an assignment operator pushesASSIGN_EXPR_START(parser_lex.l:706-711); the operator switches toASSIGN_EXPR_MODE(parser_lex.l:771-779), which ends at the end of the line (parser_lex.l:728-749). - The words
and,or,not,definedandinare tokens only inEXPR_MODEandASSIGN_EXPR_MODE(parser_lex.l:750-763). varassign: TOK_BOOL_VAR assign_op expr(parser_yacc.y:550-570) evaluates the expression and stores the result.add_varfor a boolean: symtab.cc:42-45. The lookup that refuses a set:Variable %s is not a boolean variable(symtab.cc:160-164).trueandfalsego throughstr_to_boolean(cond_expr.cc:36-48).
Read more
07 Mistakes and their messages
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} = falsein 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}/xwith${A} = true) printsVariable 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} += /aon a booleanA, not the form in row 3.
08 The blocks that read the switch
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:=, fromtrue,falseor 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
trueandfalseare 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
| Place | Result | Basis |
|---|---|---|
if ${NAME} { } and any expression of an if | tested | tree |
| the right-hand side of another boolean assignment | tested | tree |
a path, without braces: /y/$B r, | the literal text /y/$B | tree |
a path, with braces: /tmp/${DEMO_DEBUG} r, | Regex grouping error: Invalid number of items between {}, exit status 255 | tree |
| the value of a set variable | text | the parser's test vars_assignment_reference_1.sd |
Assignments and the stored value
| Line | -D variables | Basis |
|---|---|---|
${A} = true | $A = true | tree |
${B} = ${A} and not false | $B = true | tree |
${C} = 3 > 2 | $C = true | tree |
${D} = defined @{NOPE} | $D = false | tree |
$VAR = True | $VAR = true | tree |
${BOOLEAN} = fALsE | $BOOLEAN = false | tree |
${DEMO_DEBUG} = false then ${DEMO_DEBUG} := true | $DEMO_DEBUG = true | tree |
${DEMO_DEBUG} = true then ${DEMO_DEBUG} ?= false | $DEMO_DEBUG = true | tree |
- The expression is evaluated when the line is parsed. A boolean used on the right must be assigned above:
${EARLY} = ${LATER}before${LATER} = trueisUnset boolean variable ${LATER} used in if-expression(tree).
One name space
- Set and boolean variables share one table.
${A} = truethen@{A} = /aisvariable @{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.ctouches 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
| Message | Cause | Exit | Basis |
|---|---|---|---|
Invalid boolean : 'maybe' is not true or false | a word that is not true or false | 1 | tree |
Invalid boolean : '1' is not true or false | a number | 1 | tree |
Invalid assignment += not allowed with boolean variables | += | 1 | tree |
Unset boolean variable ${NAME} used in if-expression | a name that was never assigned, in an if or in an assignment | 1 | tree |
Regex grouping error: Invalid number of items between {} | ${NAME} in a path | 255 | tree |
syntax error, unexpected TOK_BOOL_VAR, expecting TOK_ID or TOK_MODE or TOK_SET_VAR | an assignment inside a profile | 1 | tree |
variable %s was previously declared | = on a name that exists | 1 | code |
for security researchers
Attack surface
- Which rules a profile has depends on preamble state. That state can come from an included file or a
.ddirectory: see include if exists. - A
:=in a file that is included later overrides the profile's own value. -D rule-exprsprints the rules that were compiled; the profile text does not say which branch was taken.
for AppArmor developers for security researchers
In the code
BOOL_VARIABLE(parser_lex.l:299);ASSIGN_EXPR_STARTandASSIGN_EXPR_MODE(parser_lex.l:706-711, parser_lex.l:728-749, parser_lex.l:771-779).varassign: TOK_BOOL_VAR assign_op expr(parser_yacc.y:550-570).add_varfor a boolean (symtab.cc:42-45);get_boolean_varand its error (symtab.cc:160-164, cond_expr.cc:43-48);str_to_boolean(parser_misc.c:538-547).
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, andand/orand nestedifdo not short-circuit. +=on a boolean reports that the variable was not declared. Run:${A} = truethen@{A} += /aprintsVariable A is not a set variableand thenvariable @{A} was not previously declared, but is being assigned additional values.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
FILE ACCESS
- Globbing (AARE) — why a dollar and braces in a path are not a variable
PREAMBLE AND REUSE
- Conditional blocks — the if blocks that test a boolean
- Variable assignment — the three operators a boolean takes
- Variables — the other kind of variable in the same table
- The preamble — the only place a boolean is assigned
- Abstractions and tunables — a tunables file as the place for a site switch
INSIDE THE PARSER
- The grammar — the grammar rule for the assignment