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
- Variables — how a variable is written and expanded
- Profile attachment — the name and attachment these variables stand for
01 The program's own path, without typing it twice
@{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 printsaare: /usr/bin/demo. The same text is printed once more for the attachment itself. - Shipped policy uses
@{exec_path}in 176 files underprofiles/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.
Read more
for AppArmor developers for security researchers
In the code
- The names:
PROFILE_NAME_VARIABLE,PROFILE_ATTACH_VAR,PROFILE_EXEC_VAR(parser.h:335-337). - The two attachment variables are set at parser_variable.c:159-175.
02 Three names you use and do not assign
@{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 undersecurity/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 profilesoneandtwocompiles/var/lib/one/**in both.
for AppArmor developers for security researchers
In the code
PROFILE_NAME_VARIABLE "profile_name",PROFILE_ATTACH_VAR "attach_path",PROFILE_EXEC_VAR "exec_path"(parser.h:335-337).- Set and removed around each profile: parser_variable.c:105-179.
03 One rule text, three profiles, three values
@{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 profileworkerprintsaare: demo//worker, and indemoit printsaare: 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},andptrace (read) peer=@{profile_name},in base.
for AppArmor developers for security researchers
In the code
- The value is
escape_re(prof->get_name(false))(parser_variable.c:105-135, parser_variable.c:154-157);get_name(false)leaves the namespace out (profile.h:472-477).
04 The exec path variable is the pattern, as written
@{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 profileprofile kid /usr/bin/k*,@{exec_path} mr,printsaare: /usr/bin/k*; in/usr/bin/path[12] { },@{exec_path} mr,printsaare: /usr/bin/path[12]and/p@{profile_name} r,printsaare: /p/usr/bin/path\[12\]. /usr/bin/kateis 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: inprofile one /usr/bin/one,/a@{attach_path} r,printsaare: /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, }printsaare: /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
mthis 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
- The attachment that is used: parser_variable.c:58-78. The two variables: parser_variable.c:159-175.
escape_reputs a backslash before each of{}[]*?(parser_variable.c:87-103); it is applied to the name only.- The comment "update to use kernel vars if available" (parser_variable.c:170) marks the only difference intended between the two variables. No code follows it.
05 No attachment, no exec path
@{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,inprofile demo /usr/bin/demoprintsaare: /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, }printsFailed to find declaration for: @{exec_path}andERROR 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^admininsideprofile demo /usr/bin/demoprintsFailed to find declaration for: @{exec_path}andERROR 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^admincompiles 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, }printsaare: /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} = hijackand@{exec_path} = /hijackin the preamble, the rules ofprofile one /usr/bin/onegetoneand/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_pathfrom the preamble is used. With@{exec_path} = /hijackin the preamble,@{exec_path} mr,inprofile noattachcompiles as/hijack.
Read more
for AppArmor developers for security researchers
In the code
- The two variables are set only
if (prof->attachment)(parser_variable.c:159-175).
06 Set before a profile, removed after it for AppArmor developers for security researchers
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} = hijackand@{exec_path} = /hijack, the profile isprofile one /usr/bin/one. Its rules get the built-in values (/p/@{profile_name} r,printsaare: /p/one), and-D expanded-variablesafterwards 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 profilesoneandtwocompiles/var/lib/one/**in both.
for security researchers
Attack surface
- The three names are not reserved: a preamble, or a file in a tunables
.ddirectory, 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_pathis used (recorded in the research notes; intent not determined).
Read more
07 What people expect and what they get
@{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}, thenERROR 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}, thenERROR 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, anddemois not one. - Row 5:
aare: /usr/bin/demo, exit status 0. With--warn=allthe parser addsThe 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
@{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
| Variable | Value | Escaping | Defined |
|---|---|---|---|
@{profile_name} | the hierarchical name of the profile, without the namespace | a backslash before each of {}[]*? | in every profile |
@{attach_path} | the attachment as written, after variable expansion; the profile name when that begins with / | none | only in a profile with an attachment |
@{exec_path} | the same value as @{attach_path} | none | only 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/demo | demo | /usr/bin/demo | tree |
/usr/bin/demo { } (named by its path) | /usr/bin/demo | /usr/bin/demo | tree 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 demo | demo//worker | /usr/lib/demo/worker | tree |
child profile kid /usr/bin/k* | one//kid in profile one | /usr/bin/k* | tree |
hat ^admin in demo | demo//admin | undefined: Failed to find declaration for: @{exec_path} | tree |
In a path and in a label
| Use | In demo | In the child worker | Basis |
|---|---|---|---|
/run/@{profile_name}/** rw, | /run/demo/** | /run/demo/worker/** | tree |
signal peer=@{profile_name}, | demo | demo//worker | tree |
- 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 underprofiles/apparmor.d,@{profile_name}in 4,@{attach_path}in none (counted with grep in the tree).abstractions/basehassignal peer=@{profile_name},andptrace (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_pathorattach_pathundersecurity/apparmor/(code). This page follows the code.
Errors
| Message | Cause | Exit | Basis |
|---|---|---|---|
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 hat | 1 | tree |
Failed to find declaration for: @{attach_path} then the same second line | @{attach_path} in the same places | 1 | tree |
none; the rule compiles as the text demo | @{profile_name} mr, in profile demo /usr/bin/demo | 0 | tree |
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
.dfile 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_pathis used: with@{exec_path} = /hijackin the preamble,@{exec_path} mr,inprofile noattachcompiles as/hijack(tree; intent not determined).
for AppArmor developers for security researchers
In the code
- The names: parser.h:335-337.
process_profile_variables(parser_variable.c:137-179); the name variable (parser_variable.c:105-135, parser_variable.c:154-157); the attachment variables (parser_variable.c:159-175);escape_re(parser_variable.c:87-103).get_name(false): profile.h:472-477.
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 profilesoneandtwoprintaare: /var/lib/one/**for both;-D expanded-variablesprints@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_pathtaking effect in a profile without attachment is intended.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
ATTACHMENT, NAMESPACES, STACKING
- Profile attachment — the pattern the exec path variable repeats
FILE ACCESS
- Globbing (AARE) — the pattern characters that are escaped in the name
PREAMBLE AND REUSE
- Variables — how any variable expands
PROFILE HEAD
- The profile name — the name the profile name variable holds
PROFILE STRUCTURE
- Child profiles — the name of a child profile
- Hats — why a hat has no exec path
IN PRACTICE · general-purpose apps
- Profiles for general-purpose apps — the rule most shipped profiles start with
INSIDE THE PARSER
- Post-processing (no slides yet) — when the three variables are set and removed