Built-in variables

@{profile_name}… for application developers

The parser defines three variables for each profile while it expands that profile's rules. The profile name variable holds the name of the profile. The attach path and exec path variables hold its attachment pattern and exist only for a profile that has one. They are filled in at compile time and the kernel has no variables.

On the map: preamble and reuse

▶ Watch this deck — 8 scenes, ~6 min

Worth seeing first

01 The program's own path, without typing it twice

BUILT-IN VARIABLES profile demo /usr/bin/demo { /usr/bin/demo mr, the same text twice } @{exec_path} mr, $ apparmor_parser -Q -D rule-exprs demo @{exec_path} mr, is compiled as /usr/bin/demo 176 shipped profile files use this variable nobody assigned it: the parser defines it for each profile
The profile demo with the head profile demo /usr/bin/demo. Its rule /usr/bin/demo mr repeats the path of the head and is struck out; the rule @{exec_path} mr takes its place, linked to the path in the head. The parser prints the compiled rule as /usr/bin/demo. 176 shipped profile files use this variable.

@{exec_path} mr, allows the profile's own program. The parser defines the variable from the profile head.

Nearly every profile needs to let its program map and read its own binary. You could write the path a second time, under the head that already names it, and keep the two in step by hand. Shipped profiles do something neater: they write @{exec_path}. Compile it, and the rule comes out as the path from the head. A hundred and seventy-six profile files in the tree use this variable, most of them in exactly this rule. It's a variable nobody assigns. The parser defines it for each profile, from the attachment in that profile's head. There are three such built-in variables, and this deck goes through them.

Details and sources

Details

  • @{exec_path} mr, lets the confined program map (m) and read (r) the file it was started from.
  • The dump is from a side profile run with the tree's parser for this deck (profile demo /usr/bin/demo { @{exec_path} mr, ... }, -D rule-exprs): the rule prints aare: /usr/bin/demo. The same text is printed once more for the attachment itself.
  • Shipped policy uses @{exec_path} in 176 files under profiles/apparmor.d, @{profile_name} in 4 and @{attach_path} in none (counted with grep in the AppArmor tree at 836052d21).
  • The rule is given alias twins like any file rule: see alias rules.
  • The variables are filled in when the profile is compiled. The compiled profile holds /usr/bin/demo; the kernel has no variables.

for AppArmor developers for security researchers

In the code

02 Three names you use and do not assign

GRAMMAR @{profile_name} @{attach_path} @{exec_path} the profile's name the profile's attachment pattern the same value /run/@{profile_name}/** rw, inside a profile: defined @{profile_name} in the preamble: no profile to name usable wherever a variable is: file rules, peer labels, mount points ...
Three variables in a column: @{profile_name}, the profile's name; @{attach_path} and @{exec_path}, both the profile's attachment pattern, with the same value. A rule /run/@{profile_name}/** rw inside a profile is marked defined; the same variable in the preamble is marked as having no profile to name.

@{profile_name}, @{attach_path}, @{exec_path}: defined by the parser, separately for each profile.

There's no new syntax here. The three built-in variables are written exactly like the ones you assign yourself: an at sign and a name in curly braces. The first, @{profile_name}, is the name of the profile the rule is in. The other two, @{attach_path} and @{exec_path}, are both its attachment, the pattern of programs it applies to, and they hold the same value. What makes them special is their lifetime. The parser sets them just before it expands one profile's rules, and takes them away again afterwards. So each profile sees its own values, wherever a variable can be used.

Details and sources

Details

  • The three names are written like any set variable and are never assigned by the profile author.
  • @{profile_name} holds the name of the profile the rule stands in. @{attach_path} and @{exec_path} hold its attachment and have the same value.
  • They exist while one profile's rules are expanded: the parser sets them before that and removes them afterwards.
  • The man page says of @{exec_path}: "If the kernel supports it as a kernel variable, it will be set to the specific path that matches the executable at run time" (apparmor.d.pod:2367-2371). No code implements this and the kernel tree has no such variable (searched under security/apparmor/, not run). The deck follows the code: both variables have the same value.
  • Known discrepancy: apparmor.d(5): the grammar summary and text disagree with the parser in several places.
  • 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: the preamble line @{DIR} = /var/lib/@{profile_name} used in the profiles one and two compiles /var/lib/one/** in both.

for AppArmor developers for security researchers

In the code

03 One rule text, three profiles, three values

@{profile_name} profile demo /usr/bin/demo { /run/@{profile_name}/** rw, } /run/demo/** profile worker /usr/lib/demo/worker { /run/@{profile_name}/** rw, } /run/demo/worker/** ^admin { /run/@{profile_name}/** rw, } /run/demo/admin/** demo//worker is the value; in a file path the two slashes become one in a label they stay: signal peer=@{profile_name}, in worker names demo//worker
The profile demo with its child profile worker and its hat ^admin. Each holds the rule /run/@{profile_name}/** rw. The compiled rules are /run/demo/** in demo, /run/demo/worker/** in the child and /run/demo/admin/** in the hat. The value in the child is demo//worker; in a file path the two slashes become one, in a label they stay.

@{profile_name} is demo, demo//worker and demo//admin. In a path, // becomes /.

Here's the same rule written three times: once in demo, once in its child profile worker, once in its hat, ^admin. A directory for runtime files, named after the profile. Compile it, and each copy comes out different. In demo it's /run/demo. In the child, the value is the full name, demo//worker. The hat works the same way. Since this is a file path, the doubled slash collapses into a directory level. Where the variable is used as a label, for instance the peer of a signal rule, the name is used as it is.

Details and sources

Details

  • The three compiled rules are from a side profile run with the tree's parser for this deck (-D rule-exprs): aare: /run/demo/**, aare: /run/demo/worker/**, aare: /run/demo/admin/**, exit status 0.
  • The value is the hierarchical name of the profile without the namespace: demo, demo//worker, demo//admin. In a file path the // collapses to /.
  • In a label the // stays: signal peer=@{profile_name}, in the child profile worker prints aare: demo//worker, and in demo it prints aare: demo (run with the tree's parser for this deck).
  • Pattern characters in the name are escaped: see the next scene.
  • It is the profile's name, not the program's path. For a profile named by its path the two are the same text.
  • Examples in the tree: /var/run/@{profile_name} rwk, (vars_auto_profile_name_01.sd, expected to pass); signal peer=@{profile_name}, and ptrace (read) peer=@{profile_name}, in base.

for AppArmor developers for security researchers

In the code

04 The exec path variable is the pattern, as written

@{exec_path} profile kid /usr/bin/k* { @{exec_path} mr, } /usr/bin/k* still a glob: the rule covers every program the profile can attach to /usr/bin/path[12] { @{exec_path} mr, /p@{profile_name} r, } @{exec_path} /usr/bin/path[12] a character class /p@{profile_name} /p/usr/bin/path\[12\] escaped: the literal name /usr/bin/kate started later: the variable was filled in when the profile was compiled
Two profiles from the research runs. In profile kid /usr/bin/k*, the rule @{exec_path} mr compiles to /usr/bin/k*, still a glob. In the profile /usr/bin/path[12], @{exec_path} compiles to /usr/bin/path[12], a character class, while /p@{profile_name} compiles to /p/usr/bin/path\[12\], escaped. A program /usr/bin/kate starts long after the variable was filled in.

@{exec_path} is the attachment pattern, unescaped. @{profile_name} is the name, with {}[]*? escaped.

The name @{exec_path} suggests the path of the program that was executed. It isn't. The value is taken from the profile's head at compile time, and it's the attachment exactly as written. If that's a pattern, the rule you get is a pattern: a profile attached to every program whose name starts with k gets a rule for all of them, not for the one that's running. The profile's name is treated differently. It's a name, so pattern characters in it are escaped and match themselves. The third variable, @{attach_path}, always equals the exec path. All of this is settled long before any program starts.

Details and sources

Details

  • All compiled text on the slide is from a profile recorded in the research notes (-D rule-exprs): in the child profile profile kid /usr/bin/k*, @{exec_path} mr, prints aare: /usr/bin/k*; in /usr/bin/path[12] { }, @{exec_path} mr, prints aare: /usr/bin/path[12] and /p@{profile_name} r, prints aare: /p/usr/bin/path\[12\].
  • /usr/bin/kate is an invented program, drawn to show the order of events. Nothing on this slide was observed on a running kernel.
  • The attachment is the written one, or the profile name when that begins with /. Variables in the attachment are expanded first.
  • @{attach_path} has the same value as @{exec_path}. Recorded in the research notes: in profile one /usr/bin/one, /a@{attach_path} r, prints aare: /a/usr/bin/one.
  • The two variables do not include alias twins of the attachment.
  • With demo's names (run with the tree's parser for this deck): profile helpers /usr/lib/demo/* { @{exec_path} mr, } prints aare: /usr/lib/demo/*.

for security researchers

Attack surface

  • @{exec_path} mr, in a profile with a wide attachment grants map and read on every path the attachment matches, not on the binary that was executed.
  • With m this is every file a broad pattern such as /usr/bin/* covers.
  • Read the compiled rule (-D rule-exprs), not the variable.

for AppArmor developers for security researchers

In the code

05 No attachment, no exec path

NOT DEFINED profile demo /usr/bin/demo { @{exec_path} mr, /usr/bin/demo profile noattach { @{exec_path} mr, Failed to find declaration for: @{exec_path} ERROR expanding variables for profile noattach, failed to load ^admin { @{exec_path} mr, (inside demo) Failed to find declaration for: @{exec_path} ERROR expanding variables for profile admin, failed to load @{profile_name} works in both a profile whose name is a path has an attachment: the name itself a variable of your own with one of these names is replaced by the built-in wherever the built-in exists
Three profiles with the rule @{exec_path} mr. In profile demo /usr/bin/demo it compiles to /usr/bin/demo. In profile noattach, which has no attachment, the parser prints Failed to find declaration for: @{exec_path}. In the hat ^admin inside demo it prints the same message. @{profile_name} works in both. A variable of your own with one of these names is replaced by the built-in wherever the built-in exists.

@{exec_path} and @{attach_path} need an attachment. In a profile without one, and in a hat, they are undefined.

The attachment variables exist only where there's an attachment. Give a profile a plain name and no path, the kind you switch into by name, and @{exec_path} has no value there. The parser stops and says it failed to find a declaration, as it would for any unknown variable. A hat is the same case. A hat is entered by the program asking for it, not by attaching to a file, so it has no exec path either. The name is always there, since every profile has one: @{profile_name} works in both. And a profile named by its path does have an attachment, the name itself.

Details and sources

Details

  • Row 1 is the side profile of the scene "One rule text, three profiles, three values": @{exec_path} mr, in profile demo /usr/bin/demo prints aare: /usr/bin/demo (run with the tree's parser for this deck).
  • Row 2 is recorded in the research notes: profile noattach { @{exec_path} mr, } prints Failed to find declaration for: @{exec_path} and ERROR expanding variables for profile noattach, failed to load, exit status 1. The parser's own test is vars_auto_attach_path_bad_1.sd (expected to fail).
  • Row 3 was run with the tree's parser for this deck: @{exec_path} mr, in ^admin inside profile demo /usr/bin/demo prints Failed to find declaration for: @{exec_path} and ERROR expanding variables for profile admin, failed to load, exit status 1.
  • The message has no file name and no line.
  • Known discrepancy: An undefined variable is reported without file name or line.
  • @{profile_name} in a hat: /run/@{profile_name}/** rw, in ^admin compiles as /run/demo/admin/** (run with the tree's parser for this deck). In a named profile without attachment it is the name, by the same code path (derived; not run for this deck).
  • A profile whose name begins with / uses the name as its attachment: /usr/bin/demo { @{profile_name} mr, } prints aare: /usr/bin/demo (run with the tree's parser for this deck).
  • The last line of the slide: inside a profile that has the built-in, a variable of your own with the same name does not change a rule. Recorded in the research notes: with @{profile_name} = hijack and @{exec_path} = /hijack in the preamble, the rules of profile one /usr/bin/one get one and /usr/bin/one. The scene "Set before a profile, removed after it" of this deck shows the mechanism.
  • Recorded in the research notes, and not determined whether intended: in a profile without attachment a user variable named exec_path from the preamble is used. With @{exec_path} = /hijack in the preamble, @{exec_path} mr, in profile noattach compiles as /hijack.

for AppArmor developers for security researchers

In the code

06 Set before a profile, removed after it for AppArmor developers for security researchers

IN THE PARSER before the profile profile_name -> "hijack" the user's own assignment HOME -> ... process_profile_variables(prof) profile_name -> "one" attach_path -> "/usr/bin/one" exec_path -> "/usr/bin/one" only if prof->attachment expand_variables() on every rule: /p/@{profile_name} /p/one after the profile profile_name -> "hijack" the built-ins are removed, the old entry is back $ apparmor_parser -Q -D expanded-variables @profile_name = "hijack" the dump runs after all profiles: the built-in values are gone
The symbol table at three moments. Before the profile it holds the user's entry profile_name -> "hijack". During process_profile_variables that entry is replaced by profile_name -> "one", and attach_path and exec_path -> "/usr/bin/one" are added if the profile has an attachment; the rule /p/@{profile_name} expands to /p/one. After the profile the three entries are removed and "hijack" is back, which is what the dump of expanded variables prints.

parser_variable.c:137-179 swaps the three names in and out of the symbol table around each profile.

The mechanism is a swap on the one global symbol table. Suppose the preamble has its own variable called profile name. The function process_profile_variables runs once per profile. It removes any variable of that name, adds one holding the profile's escaped name, and does the same for the two attachment names when the profile has an attachment. Then every rule class expands its strings. Afterwards the three entries are deleted, and whatever was there before is put back. That's why your own variable with one of these names doesn't change a rule in a profile that has the built-in, and why the dump never shows the built-in values.

Details and sources

for AppArmor developers for security researchers

Details

  • All values are from a profile recorded in the research notes: the preamble has @{profile_name} = hijack and @{exec_path} = /hijack, the profile is profile one /usr/bin/one. Its rules get the built-in values (/p/@{profile_name} r, prints aare: /p/one), and -D expanded-variables afterwards prints @profile_name = "hijack" and @exec_path = "/hijack".
  • For each profile: any variable of the three names is saved and removed, the built-in values are added to the global table, the profile's rules are expanded, and the table is restored (parser_variable.c:105-179).
  • The parser's own test vars_auto_exec_path_09.sd ("exec_path variable overrides with user defined", expected to pass) covers a profile with an attachment.
  • The expansion of a variable is cached in the table (expanded, variable.cc:353-355).
  • 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

  • The three names are not reserved: a preamble, or a file in a tunables .d directory, may assign them.
  • Inside a profile that has the built-in, the user's value is not used.
  • In a profile without attachment the user's exec_path is used (recorded in the research notes; intent not determined).

07 What people expect and what they get

MISTAKES profile helpers /usr/lib/demo/* { @{exec_path} mr, /usr/lib/demo/* every helper, not the one that started profile demo-admin { @{exec_path} mr, Failed to find declaration for: @{exec_path} ^admin { @{attach_path} r, Failed to find declaration for: @{attach_path} profile demo /usr/bin/demo { @{profile_name} mr, demo the compiled rule: the name, not /usr/bin/demo /usr/bin/demo { @{profile_name} mr, /usr/bin/demo works: here the name is the path
Five profiles and what the parser makes of them. @{exec_path} in profile helpers /usr/lib/demo/* compiles to /usr/lib/demo/*, every helper. @{exec_path} in profile demo-admin, which has no attachment, and @{attach_path} in the hat ^admin fail with Failed to find declaration. @{profile_name} mr in profile demo /usr/bin/demo compiles to the word demo. In a profile named /usr/bin/demo it compiles to /usr/bin/demo.

@{exec_path}: the head's pattern. @{profile_name}: the name. They are the same text only for a profile named by its path.

The mistakes are all expectations. One: that @{exec_path} narrows a rule to the running program. With a pattern in the head, it covers everything the pattern does. Two and three: using the attachment variables where there's no attachment, in a named profile without a path or in a hat. Four: using @{profile_name} where you meant the path. For a profile called demo, that gives the single word demo, which isn't a path at all. It only works when the profile is named by its path, and then the two are the same text.

Details and sources

Details

  • All five rows were run with the tree's parser for this deck.
  • Row 1: aare: /usr/lib/demo/*, exit status 0.
  • Row 2: Failed to find declaration for: @{exec_path}, then ERROR expanding variables for profile demo-admin, failed to load, exit status 1.
  • Row 3, with the hat inside profile demo /usr/bin/demo: Failed to find declaration for: @{attach_path}, then ERROR expanding variables for profile admin, failed to load, exit status 1.
  • Row 4: aare: demo -> demo, exit status 0 and no message. That the rule matches no file is derived: the kernel compares absolute paths, and demo is not one.
  • Row 5: aare: /usr/bin/demo, exit status 0. With --warn=all the parser adds The use of file paths as profile names is deprecated. See man apparmor.d for more information.
  • A variable of your own named after a built-in is not used inside a profile that has the built-in: see the scene "Set before a profile, removed after it".

08 The attachment and the name

ROADS @{profile_name} @{attach_path} @{exec_path} the name · the attachment, twice attachment the pattern in the head syn-profile-name the name syn-child-profiles demo//worker syn-hats no attachment syn-variables how any variable expands prac-general-purpose the rule in practice fe-post-process when the swap happens also: syn-globbing · syntax-map
The three built-in variables @{profile_name}, @{attach_path} and @{exec_path} in the middle, with roads to the decks attachment, syn-profile-name, syn-child-profiles, syn-hats, syn-variables, prac-general-purpose and fe-post-process, and a line naming syn-globbing and syntax-map.

@{profile_name} repeats the name; @{exec_path} and @{attach_path} repeat the attachment.

Three variables you get for free: the profile's name, and its attachment twice. How the attachment in the head decides which programs a profile applies to is the attachment deck, and the profile name has a deck too. Child profiles and hats, whose names you've seen spelled with two slashes, each have one. And everything about how a variable is expanded is the variables deck.

Details and sources

Details

  • @{profile_name}: the hierarchical name of the profile, with {}[]*? escaped.
  • @{attach_path} and @{exec_path}: the attachment pattern as written, the same value in both; defined only in a profile that has an attachment.
  • All three are set for one profile at a time and are filled in when the profile is compiled.
  • Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2). The kernel has no variables.

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.

The three variables

VariableValueEscapingDefined
@{profile_name}the hierarchical name of the profile, without the namespacea backslash before each of {}[]*?in every profile
@{attach_path}the attachment as written, after variable expansion; the profile name when that begins with /noneonly in a profile with an attachment
@{exec_path}the same value as @{attach_path}noneonly in a profile with an attachment
  • They are written like any set variable and may be used wherever one may (code).
  • They are set before one profile's rules are expanded and removed afterwards (code).

Value by kind of profile

Profile@{profile_name}@{attach_path} and @{exec_path}Basis
profile demo /usr/bin/demodemo/usr/bin/demotree
/usr/bin/demo { } (named by its path)/usr/bin/demo/usr/bin/demotree for the name; code for the attachment
/usr/bin/path[12] { }/usr/bin/path\[12\]/usr/bin/path[12]tree
profile noattach { }noattach (derived)undefined: Failed to find declaration for: @{exec_path}tree
child profile worker /usr/lib/demo/worker in demodemo//worker/usr/lib/demo/workertree
child profile kid /usr/bin/k*one//kid in profile one/usr/bin/k*tree
hat ^admin in demodemo//adminundefined: Failed to find declaration for: @{exec_path}tree

In a path and in a label

UseIn demoIn the child workerBasis
/run/@{profile_name}/** rw,/run/demo/**/run/demo/worker/**tree
signal peer=@{profile_name},demodemo//workertree
  • In a file path the // of a hierarchical name collapses to /. In a label it stays.

Use in shipped policy

  • @{exec_path} appears in 176 files under profiles/apparmor.d, @{profile_name} in 4, @{attach_path} in none (counted with grep in the tree).
  • abstractions/base has signal peer=@{profile_name}, and ptrace (read) peer=@{profile_name},.
  • The parser's tests: /var/run/@{profile_name} rwk, (vars_auto_profile_name_01.sd), /run/@{exec_path}/tmp rwk, (vars_auto_exec_path_03.sd), both expected to pass.

The man page

  • apparmor.d(5) says of @{exec_path}: "If the kernel supports it as a kernel variable, it will be set to the specific path that matches the executable at run time" (apparmor.d.pod:2367-2371).
  • No code implements this, and the kernel source has no match for exec_path or attach_path under security/apparmor/ (code). This page follows the code.

Errors

MessageCauseExitBasis
Failed to find declaration for: @{exec_path} then ERROR expanding variables for profile P, failed to load@{exec_path} in a profile without attachment or in a hat1tree
Failed to find declaration for: @{attach_path} then the same second line@{attach_path} in the same places1tree
none; the rule compiles as the text demo@{profile_name} mr, in profile demo /usr/bin/demo0tree

for security researchers

Attack surface

  • @{exec_path} mr, in a profile with a wide attachment grants map and read on every path the attachment matches, not on the binary that was executed. Run: profile helpers /usr/lib/demo/* { @{exec_path} mr, } compiles the rule as /usr/lib/demo/*.
  • The three names are not reserved. A preamble or a tunables .d file may assign them. Inside a profile that has the built-in, the user's value is not used.
  • In a profile without attachment, a user variable named exec_path is used: with @{exec_path} = /hijack in the preamble, @{exec_path} mr, in profile noattach compiles as /hijack (tree; intent not determined).

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: the preamble line @{DIR} = /var/lib/@{profile_name} and the rule @{DIR}/** rw, in the profiles one and two print aare: /var/lib/one/** for both; -D expanded-variables prints @DIR = "/var/lib/one"; exit status 0.
  • An undefined variable is reported without file name or line.
  • apparmor.d(5): the grammar summary and text disagree with the parser in several places (the sentence on @{exec_path} above).
  • Not determined: whether a user variable named exec_path taking effect in a profile without attachment is intended.

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

PREAMBLE AND REUSE

PROFILE HEAD

PROFILE STRUCTURE

IN PRACTICE · general-purpose apps

INSIDE THE PARSER

  • Post-processing (no slides yet) — when the three variables are set and removed