Rule conditionals

name=value, peer=( ) for application developers for AppArmor developers for security researchers

The words that narrow a rule after its permissions. name=value and name=(a b) in every class that has conditionals. in for mount rules. := for one network label. peer=( ) as a group in unix dbus and network rules and as a plain conditional in signal and ptrace rules. Each rule class checks its own names.

On the map: rule classes

▶ Watch this deck — 9 scenes, ~6 min

Worth seeing first

  • Network rules — a rule class with a keyword and a permission list

Part of journeys

01 A rule that says less than everything

RULE CONDITIONALS signal, demo demo//worker sshd init any signal, to any process signal (send) set=(term, hup) peer=demo//worker, term, hup which signals to whom the same shapes appear in unix, dbus, network, ptrace, mount and mqueue rules
The rule signal alone lets demo send any signal to demo's worker, to sshd and to init. With set=(term, hup) and peer=demo//worker only term and hup to the worker remain.

Conditionals are the name=value words after a rule's permissions. Without them the rule covers everything in its class.

Demo has to stop its workers now and then, so its profile needs a signal rule. Write just the word signal and you've said a lot: demo may send any signal to any process, and receive them too. That's rarely what you mean. The words after the permission narrow it. set= lists the signals, here term and hup. peer= names who's at the other end, demo's worker. These words are called conditionals, and this is line 18 of demo's profile. The same few shapes turn up in most rule classes, so learning them once pays off in every deck that follows.

Details and sources

Details

  • A conditional is NAME=VALUE or NAME=(VALUE ...), written after the permission list. The name is a word of letters, digits and _ that starts with a letter (parser_lex.l:296).
  • Rule classes without conditionals: capability, set rlimit, change_profile, link, file rules and all.
  • There is no kernel object for a conditional. Its value becomes part of what the kernel matches for that rule class; each class deck says how.
  • signal, alone grants both permissions, for every signal and every peer (signal.cc:193-195).
  • On the slide: signal (send) set=(term, hup) peer=demo//worker, is line 18 of demo's profile. set=(term, hup) names the signals, peer=demo//worker the label of the other process.
  • The program demo and its profile are invented for the map. Parser results were produced with the parser built from the AppArmor tree, with nothing loaded into a kernel.

02 Four shapes and one group

GRAMMAR QUALIFIERSKEYWORDPERMISSIONSCONDITIONALSpeer=( CONDITIONALS ), always in this order name=value set=hup name=(value ...) set=(hup, int) namein(value ...) options in (ro, nodev) mount rules only name:=value peer=(label:=NAME) network rules only peer=(name=value ...) peer=(label=demo-helper) about the other end
Six syntax diagrams. A rule: qualifiers, keyword, permissions, conditionals, the peer group, a comma. Then name = value; name = ( values ); name in ( values ), for mount rules only; name := value, for network rules only; and peer = ( name=value ... ).

name=value, name=(a b), name in (a b) (mount), name:=value (network label) and the group peer=(name=value ...). Conditionals follow the permissions; the group comes last.

Every rule with conditionals has the same skeleton. Qualifiers first, then the keyword, the permissions, the conditionals, and last the peer group if the class has one. A conditional is a name, an equals sign and a value. Put the value in parentheses and it's a list. Two more operators exist, and each has exactly one home. The word in belongs to mount rules. := belongs to a single label in network rules. And the peer group is a conditional whose value is more conditionals, all about the other end of the conversation.

Details and sources

Details

  • The order is fixed: permissions, conditionals, then the group. A conditional after the group, or a second group, is a syntax error.
  • Blanks around = are allowed (signal set = hup,). A line break between the name and = is not.
  • Names are case sensitive: signal Set=hup, gives invalid signal rule conditional "Set" (signal.cc:180).
  • in needs parentheses: signal set in hup, is a syntax error.
  • := can only be written inside peer=( ).
  • The five forms: name=value, name=(a b), name in (a b), name:=value, peer=(name=value ...).

for AppArmor developers for security researchers

In the code

03 Where a value ends

VALUES signal send set=hup, one signal: hup signal send set=(hup, int), set=(hup int) two signals comma or blank between them signal send set=hup,int, unknown signal "hup,int" a comma followed by text stays in the value unix addr="@a b", unix addr=@a\ b, one value with a blank in it quoted, or escaped signal send set=(), syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUE a list needs at least one value
Five rules and what the parser makes of them: set=hup is one signal; set=(hup, int) is two; set=hup,int is an unknown signal named hup,int; a quoted or escaped blank stays inside one value; an empty list is a syntax error.

A bare value ends at a blank. name=(a b) or name=(a, b) gives several. Quote or escape blanks inside a value.

The thing that trips people up is where a value stops. A bare value runs to the next blank. So to give two signals you need the list form: parentheses, with commas or just blanks between the values. Leave the parentheses out and write hup,int, and the parser reads one strange signal name, because the comma that ends a rule has to be followed by a blank or the end of the line. If your value itself contains a blank, quote it, or escape the blank with a backslash. And a list can't be empty: it needs at least one value.

Details and sources

Details

  • A bare value is everything up to a blank, a newline, ", !, or a , that is followed by one of those (parser_lex.l:262-267).
  • Inside a list, ( and ) also end a value and , is discarded (parser_lex.l:272-274, parser_lex.l:482). Test file: signal/ok_12.sd.
  • Quotes are removed and escapes processed before the rule class sees the value. The escaped form unix addr=@a\ b, is accepted; with --warn=all it prints Character was quotedunnecessarily, dropped preceding quote ('\') character, and nothing by default.
  • signal set=, gives Lexer found unexpected character: ',' (0x2c) in state: SUB_VALUE.
  • signal peer=/bin/bash /bin/dash, is a conditional followed by a stray word (signal/bad_04.sd).
  • Variables are expanded only in the fields a class expands: signal peer=@{profile_name}, works, signal set=@{sigs}, gives unknown signal "@{sigs}".
  • A list that is not closed is reported at the end of the file.
  • All results on the slide come from running the tree's parser on the line.

for security researchers

Attack surface

  • Known discrepancy: conditionals that take one value do not all refuse a list. dbus, io_uring and unix rules refuse it (... only supports a single value). network rules (ip, port, interface, label), mqueue rules (type, label) and pivot_root (oldroot) take the first value and drop the rest without a message (parser_misc.c:1240-1249, network.cc:451-469).
  • network inet port=(80 81), and network inet port=80, compile to byte-identical output (run with the tree's parser). A rule that reads as two ports is one port, also under deny.

04 peer: who is at the other end

PEER demo demo-helper unix socket unix (send, receive) type=stream peer=(label=demo-helper), about demo's socket about the other end signal (send) set=(term, hup) peer=demo//worker, plain peer: a label, no parentheses one idea, three spellings peer=LABEL signal, ptrace label=LABEL mqueue, io_uring peer=(label=LABEL) unix, dbus, network signal send peer=(label=demo//worker), syntax error, unexpected TOK_CONDLISTID, expecting TOK_CONDID or TOK_END_OF_RULE
demo and demo-helper joined by a unix socket. In the unix rule, type=stream is about demo's socket and peer=(label=demo-helper) about the other end. A signal rule has a plain peer. The label is spelled three ways: peer=LABEL, label=LABEL and peer=(label=LABEL). A group in a signal rule is a syntax error.

peer=( ... ) is a group in unix, dbus and network rules, written last and once. In signal and ptrace rules peer=LABEL is a plain conditional. mqueue and io_uring write label=LABEL.

Most of these rules are about two parties, and you usually care who the other one is. Unix, D-Bus and network rules put everything about the other end into a group: peer=, an open parenthesis, conditionals, a close parenthesis. What's outside the group describes your own end. The group comes last, and there's only one. Signal and ptrace rules are simpler. The other end is just a label, so peer takes it directly, with no parentheses. It's the same idea each time, spelled three ways depending on the class. Mix the spellings up and you get a syntax error that mentions a TOK_CONDLISTID.

Details and sources

Details

  • Inside the group each class allows: network rules ip, port, label (interface is refused: interface cannot be set for peer in network rules, network.cc:497-498); unix rules addr, label; dbus rules name, label.
  • peer is the group only when ( follows the =. signal peer=a, works; signal peer=(a), is a syntax error.
  • unix peer=(), is accepted and equals no group.
  • Order errors: unix peer=(addr=@b) type=stream, gives unexpected TOK_CONDID, expecting TOK_END_OF_RULE; two groups give unexpected TOK_CONDLISTID, expecting TOK_END_OF_RULE.
  • Permissions that concern only the local end cannot be combined with a non-empty group in unix and network rules (af_unix.cc:138-139, network.cc:525-526).
  • Inside the group a value list is not possible: unix peer=(label=(a b)), is a syntax error.
  • The second group name is xattrs, valid only on the profile head: network rule: invalid conditional group xattrs=() and profile id: invalid conditional group peer=() (parser_yacc.y:436, parser_yacc.y:1160).
  • The plain peer of signal and ptrace rules: signal.cc:177, ptrace.cc:45.

for AppArmor developers for security researchers

In the code

  • (peer|xattrs) followed by = and ( returns TOK_CONDLISTID (parser_lex.l:420-427).
  • The group has its own scanner states, which allow dots and : in names (parser_lex.l:524-549).
  • The grammar hands the plain list and the group's list to the class constructor as two arguments (parser_yacc.y:1427).

05 in and :=, each with one home

TWO MORE OPERATORS in mount options=(ro, nodev) /dev/a -> /mnt/,mount options in (ro, nodev) /dev/a -> /mnt/, = exactly these flags in any of these, or none signal set in (hup, int), only "=" allowed in conditions of signal rules := network send peer=(label:=NAME), accepted; marked unused in the parser network inet label:=foo, Lexer found unexpected character: ':' (0x3a) in state: NETWORK_MODE := can only be written inside peer=( )
Left: in. Two mount rules, options=(ro, nodev) meaning exactly these flags and options in (ro, nodev) meaning any of these or none; in on a signal rule is refused. Right: the := operator, accepted in peer=(label:=NAME) of a network rule and impossible to write outside the group.

in is accepted only by mount rules: "a subset of this list". := is accepted only for label inside peer=( ) of a network rule.

Two operators are left, and you'll meet each in exactly one place. The word in is for mount rules. options= a list means the mount must have exactly those flags. options in a list means any of those flags or none, as long as nothing else is set. Try in on a signal rule and the parser tells you only equals is allowed there. := is rarer still. It's accepted for the label inside the peer group of a network rule, and the parser itself marks that value as unused. Outside the group you can't even write it.

Details and sources

Details

  • Mount rules accept = and in (mount.cc:415-416); what the two mean for mount flags is in Mount rules.
  • Classes that refuse in: only "=" allowed in conditions of <class> rules for signal (signal.cc:169), ptrace, dbus, mqueue, io_uring and userns rules; unknown rule: operator used is not allowed in '%s' socket conditional for unix rules (af_rule.cc:51); unsupported operator used in conditions of network rules (network.cc:459).
  • := is accepted for label in the group of a network rule (network.cc:450-459); the field it fills is marked unused (network.h:144). Test file: network/skb/ok_setlabel_peer_1.sd.
  • network inet peer=(ip:=1.2.3.4), gives the network message above. signal set:=hup, gives syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE. Inside peer=( ) there is no in.
  • Known discrepancy: apparmor.d(5) lists a local label:= for network rules (apparmor.d.pod:224); the scanner cannot produce it outside the group.
  • Known discrepancy: pivot_root oldroot in (/a/) /new/, is accepted, because that rule does not look at the operator (parser_yacc.y:1820-1831).
  • All results on the slide come from running the tree's parser on the line.

06 The rule class decides which names it knows

WHO ACCEPTS WHAT set=hup signal ptrace unix accepted invalid ptrace rule conditional "set" unix rule: invalid conditional 'set' unix label=demo-helper, unknown rule: 'label' conditional is only valid in the peer expression unix peer=(label=demo-helper), accepted signal set peer unix type addr peer=(addr label) dbus bus path interface member name peer=(name label) the full table is in the reference below
The conditional set=hup is offered to three rule classes: signal accepts it, ptrace and unix refuse it, each with its own message. label=demo-helper is refused by a unix rule outside the peer group and accepted inside it. Three sample rows of the table of names per class.

Each rule class validates conditional names itself. An unknown name is an error that names the class and the conditional.

The syntax is shared, but the vocabulary isn't. Each rule class has its own short list of names. Set means something to a signal rule, and nothing at all to a ptrace or a unix rule, and each one says so in its own words. Some names are only valid on one side. A unix rule takes label inside the peer group and refuses it outside. So when a rule is rejected, read the message: it names the class and the conditional. The complete table of which class takes which name is in the reference under this deck.

Details and sources

Details

  • The messages on the slide: invalid ptrace rule conditional "set" (ptrace.cc:48), unix rule: invalid conditional 'set' (af_unix.cc:61) and unknown rule: 'label' conditional is only valid in the peer expression (the text at af_rule.cc:47, the prefix at af_rule.cc:66). All three are as printed by the tree's parser for ptrace set=hup,, unix set=hup, and unix label=demo-helper,.
  • The table of class, plain conditionals, group contents and operators is in the reference below.
  • A conditional given twice: <class> conditional "peer" can only be specified once in most classes (parser_misc.c:1243-1245); signal set=hup set=int, accumulates instead.
  • Classes with no conditionals refuse them in the grammar: capability set=hup, gives syntax error, unexpected TOK_CONDID, expecting TOK_ID or TOK_END_OF_RULE and file fstype=ext4 /a r, gives syntax error, unexpected TOK_CONDID, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. userns create foo=bar, fails in the scanner.
  • Known discrepancy: the messages for the shared unix conditionals type, protocol and label begin unknown rule: instead of unix rule: (af_rule.cc:66).
  • Known discrepancy: apparmor.d(5) documents attr= and opt= for unix rules and a local label; the parser has neither.
  • Known discrepancy: pivot_root checks only the name of the last conditional written: pivot_root bogus=/b oldroot=/a/ /new/, is accepted.

for AppArmor developers for security researchers

In the code

07 A word becomes a conditional by what follows it for AppArmor developers for security researchers

IN THE PARSER signal (send) set=(term, hup) peer=demo//worker, scanner set = TOK_CONDID set , TOK_ID decided by the next character SIGNAL_MODE EXTCOND_MODE LIST_VAL_MODE then pop, pop grammar {peer, EQ, [demo//worker]} {set, EQ, [term, hup]} cond_entry list, newest first signal_rule constructor set -> signals 15, 1 peer -> label pattern other -> error peer=( ) is a second list, scanned in its own states and passed separately
The signal rule passes three stations. The scanner turns set followed by = into TOK_CONDID and pushes and pops states. The grammar builds a list of two cond_entry nodes, newest first. The signal_rule constructor turns set into signal numbers and peer into a label pattern, and rejects anything else.

TOK_CONDID comes from scanner lookahead (parser_lex.l:437-453). The grammar builds a cond_entry list; each class's move_conditionals validates it.

None of this lives in the grammar of the individual rules. The scanner decides. A word followed by an equals sign, or by in and an open parenthesis, becomes a conditional token. The same word followed by anything else is an ordinary word. The scanner pushes a state for the value and pops it afterwards. The grammar then just builds a list of name, operator and values, newest first, and hands it to the constructor of the rule class. Only there do the names get a meaning, and only there are unknown ones rejected.

Details and sources

Details

for security researchers

Attack surface

  • The parser is where a conditional can be lost before the kernel sees anything. Known discrepancies, each reproduced with the tree's parser:
  • extra values of a list are dropped by network, mqueue and pivot_root rules (see "Where a value ends");
  • the := scanner rules outside the group are unreachable (parser_lex.l:495-497);
  • pivot_root ignores all but the last conditional written;
  • USERNS_MODE is not in the state list above although userns.cc:31-43 validates conditionals.
  • Conditionals that a feature set cannot express are dropped when the rule is compiled; see Network address conditionals.

08 Mistakes and their messages

MISTAKES unix peer=(addr=@b) type=stream, syntax error, unexpected TOK_CONDID, expecting TOK_END_OF_RULE the group goes last signal send peer=(demo//worker), syntax error, unexpected TOK_CONDLISTID, expecting TOK_CONDID or TOK_END_OF_RULE signal has a plain peer signal send set=hup set in (int), only "=" allowed in conditions of signal rules in is for mount rules dbus send bus=(session system), dbus conditional "bus" only supports a single value one bus per rule unix type=stream type=dgram, socket rule conditional "type" can only be specified once once per rule if { } else { } is not a rule conditional: see Boolean conditionals
Five refused rules with the message of the parser: a conditional after the peer group; a group after peer in a signal rule; in on a signal rule; a list for the dbus bus; type given twice in a unix rule. A footnote says if and else are not rule conditionals.

The group goes last; signal and ptrace take peer=LABEL without parentheses; only mount rules take in. if blocks are a different feature.

When a rule with conditionals is refused, it's usually one of these. A conditional after the peer group: the group has to be last. Parentheses after peer in a signal rule, where peer is plain. The word in, in a class that only knows equals. A list where the class wants a single value. The same conditional twice. One more thing. The if and else blocks of the language are also called conditionals, but they're a different feature, evaluated while the profile is read, and they have their own deck.

Details and sources

Details

  • The parser prints an error as AppArmor parser error for FILE in profile FILE at line N: MESSAGE; the slide shows MESSAGE. Every message on the slide was produced by the tree's parser.
  • The sources of rows 3 to 5: signal.cc:169, dbus.cc:48, parser_misc.c:1244 (called with the name socket rule at af_rule.cc:70).
  • signal set, gives syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE: without = after it, set is an ordinary word.
  • The if expression shares only the word "conditional": if EXPR { } else { }, with the operators ==, !=, in, >, >=, <, <=, defined, not, and, or (parser_yacc.y:862-1035, cond_expr.cc:29-161). Nothing of an if reaches the kernel.
  • The full table of messages is in the reference below.

09 Where the conditionals are used

ROADS name=value peer=( ) the shapes are shared; the meaning is in each class deck syn-signal set= and the plain peer syn-ptrace the plain peer syn-unix the peer group syn-dbus the peer group syn-network-inet ip= port= and := syn-mount in syn-xattrs the other group syn-boolean-conditionals if and else
Rule conditionals in the centre with roads to syn-signal and syn-ptrace for the plain peer, syn-unix, syn-dbus and syn-network-inet for the peer group, syn-mount for in, syn-xattrs for the other group and syn-boolean-conditionals for if and else.

Conditionals narrow a rule; each rule class deck says what its names mean.

You now know the shapes. What a name means is the business of its rule class. Signal and ptrace rules use the plain peer. Unix rules, D-Bus rules and the network address conditionals use the group. Mount rules are where the word in lives, and the profile head has the other group, for extended attributes. And if you came here looking for if and else, that's the boolean conditionals deck.

Details and sources

Details

  • Shapes: name=value, name=(a b), name in (a b) (mount rules), name:=value (the label in the group of a network rule), peer=(name=value ...) (unix, dbus and network rules).
  • Each rule class validates its own names; the table is in the reference below.
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2). Conditionals have no kernel side of their own.

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the line (-Q -K --skip-kernel-load --warn=all, feature set abi/5.0), with nothing loaded into a kernel; "code" means the parser source was read, not run. Conditionals have no kernel side of their own: a value becomes part of what the kernel matches for its rule class.

Grammar

RULE:        [QUALIFIERS] KEYWORD [PERMISSIONS] [CONDITIONAL ...] [peer=( CONDITIONAL ... )] ,
CONDITIONAL: NAME = VALUE
             NAME = ( VALUE ... )
             NAME in ( VALUE ... )        mount rules only
             NAME := VALUE                label inside peer=( ) of a network rule only
GROUP:       peer = ( NAME=VALUE ... )    unix, dbus and network rules
  • NAME is a word of letters, digits and _ that starts with a letter (code). Names are case sensitive (tree).
  • A bare VALUE runs to a blank, a newline, ", !, or a , followed by one of those (code). Quote a value or escape a blank with \ to keep a blank inside it (tree).
  • In a list, values are separated by blanks or commas; ( and ) end a value. A list needs at least one value (tree).
  • Blanks around = are allowed; a line break between the name and = is not (tree).
  • The order is permissions, conditionals, group. The group is written once and last (tree).
  • In signal and ptrace rules peer=LABEL is a plain conditional, not a group (tree).

Which class accepts which conditional

Rule classPlain conditionalsInside peer=( )Operators
capabilitynoneno group-
set rlimitnoneno group-
networkip, port, interface, labelip, port, label=; label also :=
unixtype, addr (protocol is named but refused; label is refused outside the group)addr, label=
dbusbus, path, interface, member, namename, label=
signalset, peerno group=
ptracepeerno group=
mqueuetype, labelno group=
io_uringlabelno group=
usernsnone that can be writtenno group-
mount, remount, umountfstype, vfstype, options, optionno group=, in
pivot_rootoldrootno groupnot checked
change_profile, link, file rules, allnoneno group-
profile headnonexattrs=( )= or a bare name

The label of the other party is one idea with three spellings: peer=LABEL (signal, ptrace), label=LABEL (mqueue, io_uring) and peer=(label=LABEL) (unix, dbus, network).

Operators

OperatorAccepted byMeaning
=every class with conditionalsthe value, or the list of values
inmount rules (options, fstype)within this list; see syn-mount
:=label inside peer=( ) of a network rule"set"; the parser marks the value unused (code)
bare name in a groupreaches the class and is refused, except in xattrs=( )-

Single value or list

ClassConditionalA list name=(a b)
signalsetaccepted: every value is a signal; repeated set= accumulate (tree)
mountoptions, fstypeaccepted (tree)
dbusallrefused: dbus conditional "bus" only supports a single value (tree)
io_uringlabelrefused: io_uring conditional "label" only supports a single value (code)
unixtype, addr, labelrefused: ... conditional 'type' only supports a single value (tree)
networkip, port, interface, labelKnown discrepancy: the first value is used, the rest dropped without a message (tree)
mqueuetype, labelKnown discrepancy: as for network (tree)
pivot_rootoldrootKnown discrepancy: as for network (tree)

Errors and warnings

Printed as AppArmor parser error for FILE in profile FILE at line N: MESSAGE. All rows are from the tree's parser unless marked (code).

RuleMessage
unix peer=(addr=@b) type=stream,syntax error, unexpected TOK_CONDID, expecting TOK_END_OF_RULE
unix peer=(addr=@a) peer=(addr=@b),syntax error, unexpected TOK_CONDLISTID, expecting TOK_END_OF_RULE
signal send peer=(label=demo//worker),syntax error, unexpected TOK_CONDLISTID, expecting TOK_CONDID or TOK_END_OF_RULE
signal set,syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE
signal set=(),syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUE
signal set=,Lexer found unexpected character: ',' (0x2c) in state: SUB_VALUE
signal set=hup,int,unknown signal "hup,int"
signal Set=hup,invalid signal rule conditional "Set"
signal set in (hup, int),only "=" allowed in conditions of signal rules
ptrace peer in (a),only "=" allowed in conditions of ptrace rules
signal set:=hup,syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE
network inet label:=foo,Lexer found unexpected character: ':' (0x3a) in state: NETWORK_MODE
network inet peer=(ip:=1.2.3.4),unsupported operator used in conditions of network rules
network inet xattrs=(a=b),network rule: invalid conditional group xattrs=()
profile t /bin/x peer=(a=b) { }profile id: invalid conditional group peer=()
dbus send bus=(session system),dbus conditional "bus" only supports a single value
dbus send bus=session label=unconfined,dbus "label" conditional can only be used inside of the "peer=()" grouping
unix type=stream type=dgram,socket rule conditional "type" can only be specified once
unix label=a,unknown rule: 'label' conditional is only valid in the peer expression
unix protocol=0,unknown rule: 'protocol' conditional is not currently supported
unix peer=(type=stream),unknown rule: 'type' conditional is not allowed in the peer expression
unix peer=(label=(a b)),syntax error, unexpected TOK_VALUE, expecting TOK_CONDID or TOK_CLOSEPAREN
a unix rule with an unknown nameunix rule: invalid conditional 'NAME'
a ptrace rule with an unknown nameinvalid ptrace rule conditional "NAME"
capability set=hup,syntax error, unexpected TOK_CONDID, expecting TOK_ID or TOK_END_OF_RULE
file fstype=ext4 /a r,syntax error, unexpected TOK_CONDID, expecting TOK_ID or TOK_MODE or TOK_SET_VAR
pivot_root oldroot=/a/ bogus=/b /new/,invalid pivotroot conditional 'bogus'

None of these is a warning: a rule with a wrong conditional is refused and the profile is not compiled.

Not this syntax

  • if EXPR { ... } else { ... } is evaluated while the profile is read; only the block of the first true branch is kept, and nothing of it reaches the kernel (code). Operators: ==, !=, in, >, >=, <, <=, defined, not, and, or. Its messages: Invalid boolean : '%s' is not true or false, Unset boolean variable %s used in if-expression, Error retrieving variable %s, Can only compare numbers with numbers, Value out of valid range (code). See syn-boolean-conditionals.
  • xattrs=( ... ) on the profile head is the other group. See syn-xattrs.

for AppArmor developers

In the parser

  • Scanner: a word followed by blanks and =, or by blanks and in (, returns TOK_CONDID (parser/parser_lex.l:437-453) in the states INITIAL, MOUNT_MODE, DBUS_MODE, SIGNAL_MODE, PTRACE_MODE, UNIX_MODE, MQUEUE_MODE, NETWORK_MODE (parser/parser_lex.l:419). (peer|xattrs)=( returns TOK_CONDLISTID (parser/parser_lex.l:420-427).
  • Value states EXTCOND_MODE, LIST_VAL_MODE (parser/parser_lex.l:462-505); group states EXTCONDLIST_MODE, LIST_COND_MODE, LIST_COND_VAL, LIST_COND_PAREN_VAL (parser/parser_lex.l:508-562).
  • Grammar: cond, opt_conds, cond_list (parser/parser_yacc.y:1196-1275) build a cond_entry list in reverse order, with the comparison kinds NONE, EQ, IN, SET (parser/parser.h:119-124).
  • move_conditional_value moves the first value into the rule and frees the entry (parser/parser_misc.c:1240-1249).
  • Consumers: parser/signal.cc:162, parser/ptrace.cc:36, parser/dbus.cc:39, parser/mqueue.cc:69, parser/io_uring.cc:31, parser/af_unix.cc:53 and 84, parser/network.cc:445, parser/mount.cc:407-447, parser/parser_yacc.y:1820.

for security researchers

Known discrepancies

Each was reproduced with the tree's parser; none is taught as intended behaviour.

  • name:=value cannot be written outside peer=( ), although the manual page lists a local label:= for network rules: network inet label:=foo, fails in the scanner, network inet peer=(label:=foo), is accepted.
  • pivot_root validates only the last conditional written and ignores the rest: pivot_root bogus=/b oldroot=/a/ /new/, is accepted; pivot_root oldroot in (/a/) /new/, is accepted.
  • Conditionals that take one value accept a list in network, mqueue and pivot_root rules and use the first value: network inet port=(80 81), compiles to the same bytes as network inet port=80,.
  • Errors for the shared unix conditionals name the rule class unknown: unix label=a, gives unknown rule: 'label' conditional is only valid in the peer expression.

Roads from here

START HERE

PREAMBLE AND REUSE

PROFILE HEAD

RULE CLASSES

PROFILE STRUCTURE

INSIDE THE PARSER

  • The lexer — how the scanner tells a conditional from a word