alias rules
path rewriting for application developers for administrators for security researchers
An alias rule in the preamble names two path prefixes. Every file rule and link rule and profile attachment that begins with the first prefix gains a copy that begins with the second. The original stays. The comparison is on text after variables are expanded and other rule classes are not touched.
On the map: preamble and reuse
▶ Watch this deck — 8 scenes, ~6 min
Worth seeing first
- The preamble — the preamble, where alias rules stand
- File rules — the file rules whose paths an alias rewrites
01 The same program, installed somewhere else
alias /usr/ -> /opt/demo/usr/, makes rules written for /usr/ apply under /opt/demo/usr/ as well.
Demo's profile was written for a program in /usr. One site installs the whole thing under /opt/demo/usr. Every path in the profile is now off by a prefix, including dozens of rules that come from the base abstraction, which you can't sensibly edit. An alias rule takes care of it in one line. For everything that starts with the first prefix, the same thing is also allowed under the other. The original paths keep working, and the rules for the second location are added next to them. No rule was edited.
Details and sources
Details
- The line is line 5 of the example file of this district. With it, 17 of the 106 compiled lines of that file begin with
/opt/demo/usr/(run with the tree's parser for this deck; see the scene "A rule gains a twin, and so does the attachment"). - The shipped examples are in tunables/alias, both commented out:
# alias /usr/ -> /mnt/usr/,and# alias /var/lib/mysql/ -> /home/mysql/,. No shipped file underprofiles/has an alias rule outside a comment. - Aliases are applied at compile time. The kernel receives the extra rules and has no alias table.
- The two trees and the program
demoare invented for the map.
Read more
02 alias, a prefix, an arrow, a prefix, a comma
alias FROM -> TO, in the preamble. Site aliases belong in tunables/alias.
The rule is written the way you'd say it: alias, the prefix your rules use, an arrow, the prefix to add, and a comma. It's one of the two preamble lines that end with a comma. Write both sides with the trailing slash, as the shipped examples do, and put quotes around a side that contains a space. You can write several aliases, even several for the same prefix, and each one adds its own copies. On a real system you wouldn't put the line in demo's profile. There's a tunables file called alias for exactly this, and every profile that includes tunables/global picks it up.
Details and sources
Details
- The manual's grammar:
ALIAS RULE = 'alias' ABS PATH '->' REWRITTEN ABS PATH ','(apparmor.d.pod:116). - The rule stands in the preamble only and ends with a comma.
- The quoted example is recorded in the research notes. The two aliases for
/usr/are from rewrite/alias_dupe_1.sd, a test the parser is expected to accept. - Aliases are per file.
tunables/aliasreaches a profile only throughinclude <tunables/global>in that file's preamble; the-poutput of the example file has##included <tunables/alias>(run with the tree's parser for this deck). - tunables/alias ends with
include if exists <tunables/alias.d>. - An alias from an included file works like one written in the file (rewrite/alias_good_4.sd), and variables and aliases may be mixed in any order (rewrite/alias_good_2.sd); the parser is expected to accept both tests.
- Known discrepancy: Alias operands are not checked: a variable, a pattern or a relative path is accepted.
for AppArmor developers for security researchers
In the code
alias: TOK_ALIAS TOK_ID TOK_ARROW TOK_ID TOK_END_OF_RULE(parser_yacc.y:511-517), inpreambleonly (parser_yacc.y:506-509).aliasis a keyword (parser_misc.c:105).
03 A rule gains a twin, and so does the attachment
Each matching rule is duplicated with the new prefix; the original stays. The attachment gains an alternate name.
Look at what the parser builds. Demo's rule for its worker binary starts with /usr. In the dump it's there twice: once as written, and once with the new prefix and the same permissions. Nothing was rewritten. A twin was added. The same happens to the profile's attachment. The profile now attaches to the program at the usual path and at the new one. That matters, because otherwise demo started from the second location wouldn't be confined at all. Rules that came in through the abstraction get twins too. Here that's seventeen extra lines out of a hundred and six.
Details and sources
Details
- Run with the tree's parser for this deck, on the example file of this district. Dump lines:
aare: /usr/lib/demo/worker -> /usr/lib/demo/workerandaare: /opt/demo/usr/lib/demo/worker -> /opt/demo/usr/lib/demo/worker, each followed by arule:line withpriority=0 (0x804201/0): the same permissions. - The attachment is listed as
/usr/bin/demoand/opt/demo/usr/bin/demo. - 106
aare:lines in all; 17 begin with/opt/demo/usr/: the attachment's twin and 16 rule twins, one for the worker rule and fifteen for rules ofabstractions/base, such as/usr/share/locale/**. - The slide shows the left side of each
aare:line, the rule text after expansion. - The manual calls aliases "remapping paths" and "an alternative form of path rewriting" (apparmor.d.pod:2455-2461). In the parser the original path stays allowed. The deck follows the parser.
04 Which rules get a twin
Twins for file rules, link rules and the attachment. No twins for mount, unix, dbus and change_profile paths or exec targets.
What does an alias reach? File rules, including deny rules, which stay deny rules. Link rules, on both sides of the arrow. The comparison is made on the rule's text after variables have been expanded, so what counts is the expanded text you see in the dump. What it doesn't reach: paths in other rule classes, like mount, change_profile or unix. Nor the target of an exec rule, nor a path that starts with a pattern, because then the text doesn't begin with the prefix. It doesn't matter where a rule stands: in a hat, a child profile, inside a block. So check the dump after adding an alias.
Details and sources
Details
- Recorded in the research notes, from a profile with
include <tunables/global>,alias /home/ -> /mnt/users/,andalias /usr -> /opt/usr,:/home/*/.config/demo r,gains/mnt/users/*/.config/demo;deny /home/secret r,gains/mnt/users/secret;link /home/a -> /home/b,gains/mnt/users/a, /mnt/users/b. The mount, change_profile and unix rules on the slide are not aliased. - Recorded with
alias /a/ -> /b/,: a rule in anif true { }block, in anaudit { }block, in a hat and in a child profile is aliased, and the childprofile /a/kidgets the attachment/b/kid./{a,x}/alt r,is not aliased. The exec target of/a/exe px -> /a/target,stays/a/target./a r,is not aliased and/a/ r,is. - Recorded: the quoted rule
"/with space/y" r,is aliased byalias "/with space/" -> "/other space/",and/with\ space/x r,is not: the two spellings are different text. @{exec_path} mr,is aliased afterwards like any file rule, while the variable itself holds the attachment as written.- Write both sides with the trailing slash, as the shipped examples do.
- With demo's own alias and a rule
deny /usr/share/secret r,, the dump has/usr/share/secretand/opt/demo/usr/share/secret, both as deny rules (run with the tree's parser for this deck). - Known discrepancy: An alias does not apply to a rule whose path begins with a variable of several values. Recorded: with
alias /home/ -> /mnt/users/,the rule@{HOME}/.demo r,compiles only as{/home/*,/root}/.demo. Recorded with the same alias:owner @{HOMEDIRS}/*/x w,is compiled as/home/*/xand/mnt/users/*/xwhile@{HOMEDIRS}has the one value/home/. With a second value (@{HOMEDIRS} += /srv/nfs/home/, the line of a site file) the rule is compiled as{/home,/srv/nfs/home}/*/xand has no twin (run with the tree's parser for the review of this deck). The slide therefore shows no rule that begins with a variable: compare the alias with the text that-D rule-exprsprints. - Known discrepancy: The alias match has no path component boundary. Recorded:
alias /usr -> /opt/usr,copies/usrlocal/yto/opt/usrlocal/y.
Read more
05 An alias only ever adds for security researchers
After an alias a profile matches a superset of paths and attaches to a superset of programs. Aliases do not chain.
For a reviewer, the word to hold on to is adds. The man page talks about rewriting paths, but the parser keeps every original rule and puts a copy next to it. So after an alias the profile attaches to more binaries, allows more paths than before, and denies more paths too. Nothing is taken away at the old location. If two aliases name the same prefix, both apply and you get two twins. A twin isn't fed back in, so aliases don't chain. And the alias may not be in the profile at all: it can come from the tunables.
Details and sources
for security researchers
Details
- The attachment and exec rows are from the dump of the example file of this district (run with the tree's parser for this deck).
- The deny row was run with the tree's parser for this deck: a profile with demo's alias,
/usr/lib/demo/worker ix,anddeny /usr/share/secret r,givesaare:lines for/usr/share/secretand/opt/demo/usr/share/secret, both followed by arule:line markeddeny. The path/usr/share/secretis invented. - The three-alias panel is recorded in the research notes: the rule
/a/x r,compiles as/a/x,/b/xand/c/x, and the attachments of that profile are/a/bin/demo,/c/bin/demo,/b/bin/demo./b/xis not aliased again to/d/x. - An exact duplicate alias prints
'/a/' is already definedon standard error and is dropped, with exit status 0 (recorded). tunables/aliasandtunables/alias.d/apply to every profile whose preamble includestunables/global.@{exec_path}and@{attach_path}do not include the alternates.- The manual's wording: "remapping paths", "an alternative form of path rewriting" (apparmor.d.pod:2455-2461).
for security researchers
Attack surface
- An alias is policy for every profile of every file that includes it, written in one place outside the profiles.
- An alias whose TO is writable by a less trusted user makes rules written for a trusted tree (exec rules with
ixorPx, the attachment) apply to files that user controls. This is reasoned from the mechanism and was not run. - Review the compiled attachment and exec rules with
-D rule-exprsafter any change undertunables/alias*. - Where an alias does not reach (other rule classes, exec targets), the profile is narrower at the second location, not wider.
- Known discrepancy: An alias does not apply to a rule whose path begins with a variable of several values.
- Known discrepancy: The alias match has no path component boundary.
- Known discrepancy: Allocation failure while adding an alias name for a profile is silent.
for security researchers
Read more
06 A prefix comparison after variable expansion for AppArmor developers for security researchers
parser_alias.c:111-157 copies entries by strncmp prefix; 159-191 adds alternate attachment names; both run after variable expansion.
An alias line just stores a pair in a tree. The work happens later, per profile, right after variables have been expanded. First, process_name looks at the attachment, or the name if there's no attachment, and adds a rewritten alternate name to the profile. Then every block's file entries are walked, even branches of an if that aren't taken. Where an entry's name starts with the from text, by a plain string comparison, a copy is inserted after it with the prefix swapped and a flag that says don't alias me again. Link names are compared the same way. And the tree is freed before the next file.
Details and sources
for AppArmor developers for security researchers
Details
new_alias()(parser_alias.c:37-94) returns 1 on every path, soFailed to create alias %s -> %scannot be reached (parser_yacc.y:513-514).replace_profile_aliases()(parser_alias.c:201-209) is called after a profile's variables are expanded (parser_policy.c:133-144).process_name(parser_alias.c:159-191); the attachment matcher is built from the attachment and every alternate (parser_regex.c:531-533).block::apply_aliases(block.cc:295-303);process_entries(parser_alias.c:111-157);do_alias(parser_alias.c:96-107).- Entries with
AA_SHARED_PERMSbits are skipped (parser_alias.c:123; immunix.h:66). free_aliases()is called fromreset_parser()(parser_main.c:1260).- The scanner's
SUB_ID_WSstate takes the right side of the arrow (parser_lex.l:822). - Known discrepancy: An alias does not apply to a rule whose path begins with a variable of several values.
- Known discrepancy: The alias match has no path component boundary.
- Known discrepancy: Alias operands are not checked: a variable, a pattern or a relative path is accepted.
for AppArmor developers for security researchers
Read more
07 Mistakes and their messages
An alias is per file and covers file rules, link rules and attachments only. Verify with -D rule-exprs.
The parser complains in three cases: an alias inside a profile, a missing comma, a missing arrow. A repeated alias just prints a line and carries on. The mistakes that hurt are quiet ones. An alias written in one profile's preamble applies to that file only, so the next profile knows nothing about it. Put site aliases in the tunables file. And an alias doesn't touch mount, unix or D-Bus rules, so if those name the old prefix, you write the second path yourself. After any alias change, compile with the rule dump and check the twins.
Details and sources
Details
- Rows 1 to 4 were run with the tree's parser for this deck, with demo's alias; rows 1 to 3 exit with status 1. The research notes record the same messages with other names.
- Row 1 in full:
AppArmor parser error for /work/p06b.sd in profile /work/p06b.sd at line 2: syntax error, unexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. The parser's test rewrite/bad_alias_inside_profile.sd expects a failure for it. - Row 2: the profile line follows the alias, so the unexpected token is
TOK_PROFILE:... at line 2: syntax error, unexpected TOK_PROFILE, expecting TOK_END_OF_RULE. - Row 3:
... at line 1: syntax error, unexpected TOK_ID, expecting TOK_ARROW. - Row 4:
'/usr/' is already definedon standard error, exit status 0, and the dump has each twin once. - Rows 5 and 6 have no run of their own: they restate that aliases are per file and that only file rules, link rules and attachments are aliased (see the scene "Which rules get a twin").
- How the utilities treat alias rules was not determined.
- The file names under
/work/are scratch names of the runs. - Known discrepancy: Alias operands are not checked: a variable, a pattern or a relative path is accepted. Recorded:
alias foo -> bar,andalias /x -> y,exit with status 0, and/x/1 r,gains the ruley/1.
08 Attachment, and the rules that are copied
An alias adds twins for file rules, link rules and the attachment.
That's the alias rule: one line in the preamble, a twin for every matching file rule and for the attachment. How the attachment decides which programs a profile applies to, alternates included, is the attachment deck. File rules and link rules, the two kinds that get copied, have their own decks. The tunables file where a site's aliases live is covered with abstractions and tunables. And other ways one file can have two names are in the deck on the limits of name-based mediation.
Details and sources
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 -D rule-exprs, with the tree's abi/5.0 file as kernel feature set), 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
ALIAS RULE: 'alias' FROM '->' TO ','
- Preamble only; inside a profile it is a syntax error (tree).
- Each side is one path text; quote a side that contains a space:
alias "/with space/" -> "/other space/",(tree). - Several aliases are allowed, also several for one FROM; each adds its own copies (tree; the test
rewrite/alias_dupe_1.sd). - An exact duplicate prints
'FROM' is already definedon standard error and is dropped; exit status 0 (tree). - Write both sides with the trailing slash, as the shipped examples do.
What gets a twin
Recorded results with alias /home/ -> /mnt/users/, unless the row names another alias (tree).
| Rule | Result |
|---|---|
/home/*/.config/demo r, | twin /mnt/users/*/.config/demo |
deny /home/secret r, | twin /mnt/users/secret, a deny rule |
link /home/a -> /home/b, | twin /mnt/users/a, /mnt/users/b |
owner @{HOMEDIRS}/*/x w, (a variable with one value) | /home/*/x and twin /mnt/users/*/x; with a second value in @{HOMEDIRS} the rule is {/home,/srv/nfs/home}/*/x and has no twin (see the known discrepancy below) |
the attachment /usr/bin/demo with alias /usr/ -> /opt/demo/usr/, | alternate /opt/demo/usr/bin/demo |
/usr/lib/demo/worker ix, with the same alias | twin /opt/demo/usr/lib/demo/worker, same permissions |
a rule in a hat, a child profile, an if true { } block, an audit { } block, with alias /a/ -> /b/, | twin |
the child profile /a/kid with alias /a/ -> /b/, | attachment /b/kid added |
"/with space/y" r, with alias "/with space/" -> "/other space/", | twin |
/with\ space/x r, with the same alias | no twin: a different spelling is different text |
mount /home/src -> /home/mnt/, | no twin |
change_profile /home/bin/x -> other, | no twin |
unix (bind) addr=@/home/sock, | no twin |
/a/exe px -> /a/target, with alias /a/ -> /b/, | the rule gets a twin; the target stays /a/target |
/{a,x}/alt r, with alias /a/ -> /b/, | no twin: the text does not begin with /a/ |
/a r, with alias /a/ -> /b/, | no twin; /a/ r, gets one |
/a/x r, with alias /a/ -> /b/,, alias /a/ -> /c/,, alias /b/ -> /d/, | /a/x, /b/x, /c/x: no chaining |
The running example: 17 of 106 compiled lines are twins (tree).
Where aliases live
- An alias applies to the file whose preamble holds it, directly or through an include (code; tree for the running example).
tunables/aliasis the shipped place for site aliases. It holds two commented examples and ends withinclude if exists <tunables/alias.d>.tunables/globalincludes it.- A profile file that does not include
tunables/globaldoes not see those aliases (derived).
"Rewriting"
apparmor.d(5) describes alias rules as "remapping paths" and "an alternative form of path rewriting". The parser adds a copy and keeps the original rule and the original attachment (tree). This page follows the parser.
Errors and messages
| Message | Cause | Exit status | Basis |
|---|---|---|---|
syntax error, unexpected TOK_ALIAS, expecting TOK_ID or TOK_MODE or TOK_SET_VAR | an alias inside a profile | 1 | tree |
syntax error, unexpected TOK_PROFILE, expecting TOK_END_OF_RULE | no comma, and a profile on the next line | 1 | tree |
syntax error, unexpected TOK_ID, expecting TOK_ARROW | no arrow | 1 | tree |
'/usr/' is already defined | the same alias twice | 0 | tree |
| none | an alias that matches nothing | 0 | tree |
for security researchers
Attack surface
- An alias widens: the profile attaches to more programs and its file rules, allow and deny alike, cover more paths. Nothing is removed at the original location.
- It can stand outside the profile, in
tunables/aliasortunables/alias.d/, and then applies to every profile file that includestunables/global. - An alias whose TO is writable by a less trusted user makes exec rules and the attachment apply to files that user controls (derived, not run).
- Where an alias does not reach, the profile is narrower at the second location.
- Review with
-D rule-exprsafter any change to an alias.
for AppArmor developers for security researchers
In the code
- Grammar: parser_yacc.y:511-517, in
preamble(parser_yacc.y:506-509). new_alias()(parser_alias.c:37-94),process_entries(parser_alias.c:111-157),process_name(parser_alias.c:159-191),replace_profile_aliases()(parser_alias.c:201-209).- Called after variable expansion (parser_policy.c:133-144); every block is walked (block.cc:295-303).
- Known discrepancy: An alias does not apply to a rule whose path begins with a variable of several values. Recorded: with
alias /home/ -> /mnt/users/,the rule@{HOME}/.demo r,compiles only as{/home/*,/root}/.demo. - Known discrepancy: Alias operands are not checked: a variable, a pattern or a relative path is accepted. Recorded:
alias foo -> bar,andalias /x -> y,exit with status 0;alias /a/* -> /b/,andalias @{V}/ -> /w/,are accepted and match nothing. - Known discrepancy: The alias match has no path component boundary. Recorded:
alias /usr -> /opt/usr,copies/usrlocal/yto/opt/usrlocal/y. - Known discrepancy: Allocation failure while adding an alias name for a profile is silent.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
ATTACHMENT, NAMESPACES, STACKING
- Profile attachment — the alternate names an alias gives a profile
FILE ACCESS
- File rules — the rules that gain a twin
- Link rules — both paths of a link rule are aliased
- Globbing (AARE) — why a pattern at the start of a path is not a prefix
PREAMBLE AND REUSE
- Abstractions and tunables — the tunables file where site aliases go
- The preamble — the only place an alias may stand
- Variables — expansion happens before aliases are applied
SECURITY · threat model and limits
- The limits of name-based mediation — other ways one file has two names
INSIDE THE PARSER
- Post-processing (no slides yet) — when aliases are applied