Named exec transitions

-> target for application developers for security researchers

An arrow after an exec rule names the profile the new program gets instead of leaving the choice to the attachment search. Targets can be a profile or a child or a profile in another namespace or a stack. A profile can name at most twelve different targets.

On the map: file access

▶ Watch this deck — 9 scenes, ~6 min

Worth seeing first

  • Exec modes — the exec modes an arrow and target extend

Part of journeys

01 When the path does not pick the profile

NAMED EXEC TRANSITIONS demo profile: demo execve("/usr/bin/demo-helper") profiles loaded demo /usr/bin/demo demo-helper (no path in its head) /usr/bin/demo-helper Px, nothing attaches to /usr/bin/demo-helper /usr/bin/demo-helper Px -> demo-helper, by name, with no search demo-helper demo-helper line 31 of the example profile

PATH EXECMODE -> NAME, sends the exec to the profile called NAME. By the kernel source the attachment search is not used for such a rule.

Demo starts a helper, and you want that helper confined by a profile of its own. Plain Px asks the kernel to find a profile from the program's path. That fails when the profile you want has no path in its head. It's also no use when you want a shell to get a special profile only when demo starts it, or when two profiles could match. An arrow solves all three. After the mode you write the name of the profile, and the exec goes there, with no search. In the example profile that's line thirty-one: Px -> demo-helper.

Details and sources

Details

  • PATH EXECMODE -> NAME, or EXECMODE PATH -> NAME,. The manual page calls these "Directed profile transitions" (apparmor.d.pod:1078-1091).
  • The parser stores NAME in a table of names inside the compiled profile and points the rule at that table entry.
  • Kernel, read and not run: for such a rule the name from the table is looked up first (domain.c:592-599). The attachment search over paths runs only for a &name target.
  • The case of the letter keeps its meaning: Px -> name is the safe form: safe and unsafe.
  • "Line thirty-one" refers to the example profile demo used across the map.

for AppArmor developers for security researchers

In the code

02 The arrow and its target

GRAMMAR PATH EXEC MODE -> TARGET , /usr/bin/demo-helper Px -> demo-helper, Px /usr/bin/demo-helper -> demo-helper, the same rule name a profile in the current namespace parent//child a child profile, by its full name :ns:name a profile in another namespace &name add name to the stack one word, taken literally: no globs, no variables a * in the target is a *, so write a real profile name

EXEC RULE = PATH EXECMODE -> TARGET,. TARGET is name, parent//child, :ns:name or &name: one literal word.

The arrow goes after the path and the letters, whichever of the two you write first. The target is a single word, and it comes in four forms. A plain name is a profile in the same namespace. A name with a double slash is a child profile, spelled out in full. A name that starts with a colon lives in another namespace. And one that starts with an ampersand doesn't replace the confinement, it adds to it. The word is stored exactly as you wrote it. A star in it is a star, not a pattern, so it has to be a real profile name.

Details and sources

Details

  • EXEC RULE: [QUALIFIERS] [file] [safe|unsafe] ( PATH EXECMODE | EXECMODE PATH ) -> TARGET,.
  • TARGET: name | parent//child | :ns:name | :ns://name | &name. One word, unquoted or quoted, read literally.
  • After -> the lexer reads the next word as a plain name (parser_lex.l:822, parser_lex.l:456-462), so the target need not start with / and may equal a keyword or a mode word.
  • No pattern characters are interpreted: /a px -> b*, names a profile literally called b* (observed with the released parser 5.0.2).
  • A leading : marks a namespace; both :ns:name and :ns://name are recognised (parser_misc.c:863-882).
  • When the mode has l and no exec letters, the arrow is a link target: link rules.
  • A variable in the target (/a px -> @{T},) is accepted and stored unexpanded by the parser built from the AppArmor tree at 836052d21. Do not rely on it.

for AppArmor developers for security researchers

In the code

03 Px -> demo-helper

LOOKED UP AT EXEC TIME /usr/bin/demo-helper Px -> demo-helper, demo compiled profile exec targets demo-helper the name is copied, not checked execve("/usr/bin/demo-helper") demo rule matches: go to demo-helper look up demo-helper now demo-helper the helper runs here if no profile called demo-helper is loaded EACCES info="profile transition not found" read from the the kernel source, for a profile in enforce mode apparmor_parser does not check that demo-helper exists Pix -> demo-helper falls back to demo's own profile when the name is missing

The target is resolved at each exec, not at load. By the kernel source (read, not observed), a target that is not loaded gives info="profile transition not found" and, in enforce mode, EACCES, unless the mode has an i or u fallback.

What happens to that name? When the parser compiles demo's profile, it doesn't go looking for the helper's profile. It just writes the name into a small table inside demo's compiled profile. The lookup happens in the kernel, each time demo executes the helper. So the order in which you load the two profiles doesn't matter. But a typo isn't caught by the parser. Going by the source of the kernel, the exec is then refused, with profile transition not found. If you'd rather keep going, pick a fallback mode: Pix -> demo-helper tries the name, and inherits when it's missing.

Details and sources

Details

Kernel facts are from the kernel source, read and not run.

  • The parser does not look for the target profile; it stores the name. Example with several targets: ok_link_4.sd.
  • At each exec the stored name is resolved relative to the profile the rule is in: x_table_lookup (domain.c:523-559), called for a table entry at domain.c:592-599.
  • Not found, mode with i: info="ix fallback", the program stays in the current profile. Mode with u: info="ux fallback", unconfined (domain.c:616-638).
  • Not found, no fallback: info="profile transition not found" and EACCES in enforce mode; in complain mode a learning profile is created instead (domain.c:740-754).
  • Nothing checks the target when the profile is compiled or loaded, so the load order of the two profiles does not matter.
  • ix -> name and ux -> name are accepted (released parser 5.0.2) with a changed meaning: ix -> name goes to name and falls back to inherit; ux -> name goes to name and does not run unconfined. The manual page lists targets for the p and c families only.

for AppArmor developers for security researchers

In the code

04 Cx -> worker: the child by its short name

THE cx PREFIX profile demo /usr/bin/demo { /usr/lib/demo/worker Cx -> worker, profile worker { /var/lib/demo/jobs/** rw, } } demo//worker the parser adds "demo//" the child's full name demo execve("/usr/lib/demo/worker") worker demo//worker Cx -> demo//worker is stored as demo//demo//worker do not write the prefix yourself a child of another profile: Px -> other//child

In profile demo, Cx -> worker is stored as demo//worker. The prefix is always added with c modes; a target with a namespace is left as written.

In the exec modes deck, a child with a short name couldn't be reached by plain Cx. The arrow fixes that. With a c mode, the target is taken to be a child of the profile the rule is in, and the parser puts the parent's name and a double slash in front. So in demo, Cx -> worker means demo//worker. That's line thirty-two of the example. The prefix is always added, so writing the full name yourself doubles it. If you need a child of some other profile, use Px with the full name instead.

Details and sources

Details

  • With a c mode (cx Cx cix Cix cux CUx) the parser stores PROFILE//TARGET, where PROFILE is the name of the profile the rule is in (block_rules.cc:488-506).
  • Observed with the released parser 5.0.2 (-S, reading the serialized table): in profile t, /a cx -> c, stores t//c; /a2 Cx -> t//c2, stores t//t//c2.
  • A target with a namespace is stored as written, also with a c mode (block_rules.cc:479, block_rules.cc:515-522).
  • When the target text equals the rule's path, no table entry is made and the rule stays a plain cx (block_rules.cc:492-496).
  • Parser test with rcx -> pgrep: ok_link_4.sd.
  • Inside a nested child the prefix is the child's local name, not its full name: in profile t { profile kid { /a cx -> gk, ... } } the table of t//kid holds kid//gk while the grandchild is t//kid//gk (parser built from the AppArmor tree at 836052d21, -S). By the kernel source that name does not resolve.

05 Twelve names per profile

THE EXEC TABLE 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 four bits, sixteen values 0 to 3: the plain modes none unconfined profile child /usr/bin/demo-helper Px -> demo-helper, slot 4 /usr/lib/demo/worker Cx -> worker, slot 5: demo//worker /usr/libexec/demo/job Px -> demo-helper, same name, same slot t3 ... t12: ten more names a thirteenth name /opt/x Px -> t13, Profile demo has too many specified profile transitions. each child profile and hat has its own table
The exec table drawn as sixteen cells numbered 0 to 15. Cells 0 to 3 are the plain modes: none, unconfined, profile and child. Cell 4 holds demo-helper and cell 5 holds demo//worker; a second rule naming demo-helper shares cell 4. Cells 6 to 15 fill with ten more names. A thirteenth name fails with Profile demo has too many specified profile transitions. Each child profile and hat has its own table.

A profile's exec table has 12 usable slots. Distinct target names beyond twelve fail with "Profile NAME has too many specified profile transitions."

There's a limit you only meet in large profiles. The exec mode is stored in four bits: sixteen values. The first four mean the plain modes. The other twelve are slots in a table of names. Each different target takes a slot, and rules that name the same target share one. So a profile can send execs to twelve named profiles. The thirteenth name stops the parser, with too many specified profile transitions. If you hit that, split the work into child profiles or hats. Each of them has a table of its own.

Details and sources

Details

  • The exec type is a four bit value. 0 to 3 are "none", unconfined, profile and child (immunix.h:80-82); AA_EXEC_COUNT is 16 (immunix.h:70), which leaves slots 4 to 15.
  • One slot per distinct stored string per profile; rules naming the same target share a slot (block_rules.cc:458-472).
  • The 13th distinct target: Profile NAME has too many specified profile transitions. (block_rules.cc:584-587). Twelve px -> tN rules compile and the thirteenth gives the error (parser built from the AppArmor tree at 836052d21).
  • With a c mode the stored string includes the parent prefix, so Cx -> a and Px -> a are different strings and take two slots (from the code, not run).
  • The table belongs to the profile: rules inside qualifier blocks share it; each child profile and each hat has its own.
  • An arrow on a rule with neither x nor l (/z rw -> q,) is accepted and uses a slot (released parser 5.0.2). Do not rely on it.
  • Link targets (l -> /tmp/bar) do not use slots: ok_link_4.sd.

06 Colon and ampersand targets

: AND & /usr/bin/demo-sandboxed Px -> :sandbox:demo-helper, root namespace demo exec namespace :sandbox: demo-sandboxed demo-helper /usr/bin/demo-report Px -> &demo-limits, demo exec demo-report (found by path, as Px would) demo-report demo-limits (named in the rule, stacked on top) both profiles of a stack must allow an access

-> :ns:name names a profile in another namespace. -> &name stacks name with the profile that attaches to the executable (the kernel source). See namespaces and stacking.

Two more target forms, briefly, because each has a deck of its own. A target written :ns:name puts the new program under a profile in another policy namespace. That's how a container manager hands a program over to the container's own policy. A target that starts with an ampersand doesn't replace anything. Going by the kernel source, the kernel finds the profile for the program as plain Px would, then stacks the named profile on top. From then on, both must allow each access.

Details and sources

Details

Kernel facts are from the kernel source, read and not run.

  • -> :ns:name: the parser recognises the namespace by the leading : (parser_misc.c:863-882) and writes the entry as :ns, a NUL byte, name (parser_interface.c:433-448). :ns://name is stored as :ns, NUL, //name (released parser 5.0.2, -S).
  • When the profile is loaded the kernel restores the : and rejects an entry where : is followed directly by a NUL (policy_unpack.c:499-512).
  • -> &name: the kernel strips the & for the lookup (domain.c:540), then runs the ordinary attachment search for the executable (domain.c:597-602) and merges the two labels (domain.c:651-658).
  • If the attachment search finds nothing, the fallback letters or the failure apply as for plain px.
  • Malformed namespace targets are not rejected by the parser: -> ::x, -> :ns: and -> :ns compile with exit status 0. By the kernel source ::x is expected to make the kernel refuse the whole profile at load; this was not run.
  • The kernel writes a stacked label as A//&B (label.c:1672).

07 add_named_transition and x_table_lookup for AppArmor developers for security researchers

PARSER AND KERNEL: THE XTABLE do_file_rule: entry->nt_name = "worker" parser/parser_yacc.y:1759 parser post_parse_profile_file -> add_named_transition AA_EXEC_LOCAL and no namespace: "demo//worker" block_rules.cc:576,474 before variables expand add_entry_to_x_table: same string, or first free slot from 4 type bits := slot << 10; inherit, pux and unsafe bits kept block_rules.cc:458,581 sd_serialize_xtable: struct "xtable" ":ns:name" is written as ":ns" NUL "name" parser_interface.c:413 unpack_strs_table(e, "xtable", ...) -> pdb->trans dfa_map_xindex: slot n -> AA_X_TABLE | (n - 4) policy_unpack.c:1075, policy_compat.c:42 the kernel x_table_lookup: aa_label_parse(&profile->label, name, ...) "&" prefix: stack with the find_attach result domain.c:523 at each exec
Six stages. In the parser: do_file_rule stores the target in nt_name; post_parse_profile_file calls add_named_transition, which builds demo//worker for a local type; add_entry_to_x_table picks a slot from 4 and the slot number replaces the type bits; sd_serialize_xtable writes the struct xtable. In the kernel: unpack_strs_table loads it and dfa_map_xindex maps slot n to AA_X_TABLE with index n minus 4; x_table_lookup resolves the name with aa_label_parse at exec.

add_named_transition (parser/block_rules.cc:474-525) fills exec_table; x_table_lookup (linux:security/apparmor/domain.c:523-559, the kernel) resolves the string with aa_label_parse.

The grammar stores the target in nt_name. post_parse_profile_file runs at the end of the profile body, before variables are expanded, and calls add_named_transition. For a local type without a namespace, that builds parent//target. add_entry_to_x_table reuses an existing string or takes the next slot, counting from four. The slot number replaces the type bits, which is why the letter no longer selects the lookup. The table is serialized as xtable. In the kernel the index is range checked at load, and x_table_lookup parses the string as a label, relative to the current profile, at each exec.

Details and sources

for AppArmor developers for security researchers

Details

  • do_file_rule stores the target in nt_name (parser_yacc.y:1759-1769).
  • post_parse_profile_file runs at the end of the profile body, before variables are expanded, and calls add_named_transition for each entry with nt_name (block_rules.cc:576-596).
  • add_named_transition: the c prefix "%s//%s" and the namespace test (block_rules.cc:474-525). add_entry_to_x_table: slots from (AA_EXEC_LOCAL >> 10) + 1, that is 4, up to AA_EXEC_COUNT, reusing equal strings (block_rules.cc:458-472).
  • The slot replaces the type bits: entry->perms = ((entry->perms & ~AA_ALL_EXEC_MODIFIERS) | (perms & AA_ALL_EXEC_MODIFIERS)) (block_rules.cc:591-596).
  • sd_serialize_xtable writes struct xtable with an array of strings; in a namespace target the second : becomes NUL (parser_interface.c:413-456). apparmor_parser -S (--stdout, "Dump compiled profile to stdout", parser_main.c:232) shows the result.
  • Kernel: unpack_strs_table(e, "xtable", false, &pdb->trans) (policy_unpack.c:1075); the entry check restores the : (policy_unpack.c:499-512); every AA_X_TABLE index is range checked at load (policy_unpack.c:1542-1548).
  • dfa_map_xindex: slot n becomes AA_X_TABLE | (n - 4) (policy_compat.c:36-45).
  • x_table_lookup resolves the string with aa_label_parse(&profile->label, lookup, GFP_KERNEL, true, false) at each exec (domain.c:523-559). Its aa_find_child branch needs AA_X_CHILD with AA_X_TABLE, which dfa_map_xindex never produces.

08 Arrows that go wrong

COMMON MISTAKES the parser refuses /usr/bin/demo-helper x -> demo-helper, no exec mode in front of x Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u' /usr/bin/demo-helper Px -> demo helper, the target is one word syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE /usr/bin/demo-* Px -> one, /usr/bin/* Px -> two, overlapping patterns, two targets profile has merged rule with conflicting x modifiers the parser accepts, the exec fails /usr/bin/demo-helper Px -> demo-helpr, loads; each exec: "profile transition not found" /usr/bin/demo-* Px -> demo-*, loads; looks for a profile literally named demo-* the target is not checked when the profile is compiled exec results are read from the the kernel source, not observed
Three rules the parser refuses, with its messages: an arrow after a bare x, a target of two words, and two overlapping patterns with different targets. Two rules the parser accepts that fail at exec: a misspelled target, and a target with a star, which is looked up as a profile literally named demo-*.

The target is not checked when the profile is compiled. By the kernel source, a wrong name loads and then fails each exec with "profile transition not found".

An arrow needs a real exec mode in front. An x alone is refused, with the same message as any bare x. The target is one word, so a name with a space in it is a syntax error. Two rules with different targets, whose patterns overlap, are two exec modes for one file: a conflict. And then the quiet ones. The parser doesn't know which profiles exist, so a misspelled target loads fine and, by the kernel source, fails at every exec. And a star in the target is not a pattern. The kernel will look for a profile with a star in its name.

Details and sources

Details

Messages of the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel.

  • /a x -> b,: Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u' (parser_misc.c:1099).
  • /a px -> b c,: syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE.
  • px -> b /a, (the arrow before the path): syntax error, unexpected TOK_ARROW, expecting TOK_ID or TOK_SET_VAR (released parser 5.0.2).
  • /usr/bin/demo-* Px -> one, with /usr/bin/* Px -> two,: profile has merged rule with conflicting x modifiers, no line number. The slot number is part of the exec type, so two targets are two modes. Related test: x-conflict.sd.
  • An exact path next to a pattern is not a conflict: the exact rule wins.
  • A misspelled target compiles and loads. By the kernel source each exec then gives info="profile transition not found" and, in enforce mode, EACCES (domain.c:740-754). Not observed on a running kernel.
  • /a px -> b*, names a profile literally called b* (released parser 5.0.2).

for security researchers

Attack surface

  • A target is a string that is resolved at each exec, in the namespace of the running profile. Nothing checks it at compile or load time, so the profile that an exec lands in depends on what is loaded under that name at that moment: whoever can load a profile with the name chooses the confinement.
  • cx -> name inside a nested child is stored with the child's local name, not its full name: in profile t { profile kid { /a cx -> gk, profile gk { } } } the table of t//kid holds kid//gk (run with the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel, -S; block_rules.cc:498-504). The kernel parses the entry as a full name (domain.c:551-552; read from the kernel source, not observed on a running kernel), so it resolves to a top-level profile kid with a child gk if one is loaded, and to nothing otherwise.
  • A variable in a target is not expanded: /a px -> @{T}, asks the kernel for a profile literally named @{T} (block_rules.cc:581-596).
  • Malformed namespace targets (-> ::x, -> :ns:, -> :ns) compile with exit status 0 (parser_misc.c:903-912).
  • By reading the kernel code, ux -> name does not run unconfined and ix -> name goes to name first; an arrow on a rule with no x and no l still takes one of the twelve table entries (parser_yacc.y:1080-1082). A reviewer who reads ux or counts targets by exec rules gets the wrong answer.
  • With a fallback letter (Pix -> name, Pux -> name) a missing target is not an error: by reading the same kernel code, the exec continues under the current profile or unconfined.

for AppArmor developers for security researchers

In the code

  • The conflict message for overlapping patterns is printed at hfa.cc:1705.

09 Where to go from here

ROADS -> target name parent//child :ns:name &name syn-profile-name attachment syn-child-profiles namespaces stacking the letters in front of the arrow, and the rule from the inside syn-exec-modes the modes syn-safe-unsafe upper and lower case k-exec the lookup in the kernel syntax-map every kind of line
The arrow and target in the centre with its four forms. name leads to syn-profile-name and attachment; parent//child to syn-child-profiles; :ns:name to namespaces; &name to stacking. Also syn-exec-modes, syn-safe-unsafe, k-exec and syntax-map.

Next: syn-child-profiles, namespaces, stacking, syn-profile-name; syn-safe-unsafe for the case of the letter.

You can now send an exec exactly where you want it. Each target form has a home on the map. For the plain form: profile names and how they're written, and attachment, the search the arrow replaces. Child profiles for the double slash. Namespaces for the colon form. Stacking for the ampersand. And remember that the arrow doesn't change what upper and lower case mean: Px with a capital P, then an arrow and a name, is still the safe form.

Details and sources

Details

  • -> name: a profile in the same namespace. -> parent//child: a child by its full name. -> :ns:name: another namespace. -> &name: stack name with the profile that attaches to the executable.
  • Cx -> name is stored as PROFILE//name. A profile can name 12 different targets.
  • The target is resolved by the kernel at each exec, not by the parser (source of the kernel, not observed on a running kernel).
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825).

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above (6.0.0~alpha2) was run on the fragment (-Q -K --skip-kernel-load --warn=all, or -S to inspect the serialized table), with nothing loaded into a kernel; "code" means the parser or kernel source was read, not run. Kernel behaviour is that of the mainline Linux 7.4 source (7.4-rc2). Nothing here was observed on a running kernel.

Grammar

EXEC RULE:  [QUALIFIERS] [file] [safe|unsafe] ( PATH EXECMODE | EXECMODE PATH ) -> TARGET ,
TARGET:     name | parent//child | :ns:name | :ns://name | &name
  • TARGET is one word, unquoted or quoted, and is read literally. After -> the lexer reads the next word as a plain name, so the target does not have to start with / and may equal a keyword or a mode word (code).
  • The arrow follows the path in both spellings: /a px -> b, and px /a -> b, (tree).
  • No pattern characters are interpreted: /a px -> b*, is accepted and names a profile literally called b* (tree).
  • When the mode has l and no exec letters, the arrow is a link target instead: syn-link-rules.
  • The modes themselves: syn-exec-modes. Qualifiers: syn-file-rules.

Target forms

FormStored in the profile asResolved by the kernel as (code)
namenamea profile in the current namespace
parent//childparent//childa child profile, by its full name
:ns:name:ns, a NUL byte, namea profile in the namespace ns: namespaces
:ns://name:ns, a NUL byte, //namethe same (tree, -S)
&name&namename stacked with the profile the attachment search finds for the executable: stacking

With a c mode (cx, Cx, cix, Cix, cux, CUx) the parser stores PROFILE//TARGET, where PROFILE is the name of the profile the rule is in (code):

  • In profile t, /a cx -> c, stores t//c (tree, -S).
  • The prefix is always added: /a2 Cx -> t//c2, in profile t stores t//t//c2 (tree, -S).
  • A target with a namespace is stored as written, even with a c mode (code).
  • When the target text equals the rule's path, no table entry is made and the rule stays a plain cx (code).

What the mode letters mean with a target

LettersMeaning with -> TARGET
p, Pgo to TARGET
c, Cgo to the child TARGET of the current profile (the prefix above)
i after them (pix, Cix, ...)if TARGET is not found, stay in the current profile
u after them (pux, CUx, ...)if TARGET is not found, run unconfined
upper or lower casesafe or unsafe exec, as without a target: syn-safe-unsafe

With a target, the letter no longer selects the kind of lookup: the kernel resolves the stored name in every case (code).

The exec table

  • The exec type of a rule is a 4-bit value: 16 values. 0 to 3 are reserved for "none", unconfined, profile and child, the plain modes. 4 to 15 are slots in the profile's table of target names (code).
  • One slot per distinct stored string per profile. Rules that name the same target share a slot (code).
  • A profile can therefore name 12 different targets. The 13th fails with Profile NAME has too many specified profile transitions. Twelve px -> tN rules load and the thirteenth gives the error (tree).
  • The table belongs to the profile, so rules inside qualifier blocks share it. Each child profile and each hat is a profile with a table of its own (code).

At exec time

All statements in this section are from the mainline Linux 7.4 source (code); none was observed.

  • The stored name is looked up at every exec, relative to the profile the rule is in. Nothing checks the target when the profile is compiled or when it is loaded, so the load order of the two profiles does not matter.
  • If the name is found, the new program runs under that profile.
  • If it is not found and the mode has an i fallback, the program stays in the current profile (info="ix fallback"); with a u fallback it runs unconfined (info="ux fallback").
  • If it is not found and there is no fallback, the record has info="profile transition not found". In enforce mode the exec fails with EACCES. In complain mode the kernel creates a learning profile for the program instead of failing.
  • For &name: name is looked up first, then the ordinary attachment search runs for the executable and the two are stacked. If the search finds nothing, the fallback or the failure above applies.
  • A name that is not loaded makes the label parser return an error (linux:security/apparmor/label.c:1928-1976), which the exec code treats as not found (code, mainline Linux 7.4).

Errors and warnings

The parser prints errors as AppArmor parser error for FILE in profile FILE at line N: MESSAGE. Errors from the later compile stage have no line number and are followed by ERROR ... for profile NAME, failed to load.

MessageCauseBasis
Profile NAME has too many specified profile transitions.a 13th distinct target in one profiletree
Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u'/a x -> b,: a bare x in front of the arrowtree
syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE/a px -> b c,: a target of two wordstree
syntax error, unexpected TOK_ARROW, expecting TOK_ID or TOK_SET_VARpx -> b /a,: the arrow before the pathtree
profile has merged rule with conflicting x modifierstwo rules with different targets whose patterns overlap, such as /usr/bin/demo-* Px -> one, and /usr/bin/* Px -> two, (compile stage, no line number)tree
link perms are not allowed on a named profile transition.letters-first rule with l and a namespace target: l /a -> :ns:b,code
link and exec perms conflict on a file rule using ->letters-first rule with both l and an exec mode and an arrowcode
warning ambiguous rule specifies both link target and exec transition target. Using as exec transitionpath-first rule with l, an exec mode and an arrow; warning class deprecatedtree
kernel record info="profile transition not found"the target is not loaded at exec and the mode has no fallbackcode

An exact path next to a pattern is not a conflict: the exact rule wins (syn-exec-modes). The conflict arises between two patterns because the slot number is part of the exec type.

Known discrepancies

Each item below is behaviour of the tree's parser that differs from the documentation or from what the syntax suggests. It is not intended behaviour; do not rely on it.

  • A variable in the target (/a px -> @{T},) is accepted and stored unexpanded, so the kernel is given the name @{T} (tree, -S). The same variable in a link target or a change_profile target is expanded.
  • cx -> name inside a nested child profile is prefixed with the child's local name, not its full name: in profile t { profile kid { /a cx -> gk, profile gk { } } } the table of t//kid holds kid//gk while the grandchild is t//kid//gk (tree, -S). By the kernel code the name does not resolve.
  • px -> other//PATH, where the child's name equals the rule's path, is rewritten to a local (cx) transition (code; listed in the AppArmor bug sweep).
  • Malformed namespace targets are not rejected: -> ::x, -> :ns: and -> :ns compile with exit status 0 (tree). By the kernel code, ::x is expected to make the kernel refuse the whole profile at load; this was not run.
  • An arrow on a rule with no x and no l (/z rw -> q,) is accepted and uses a slot of the exec table (tree). The manual page says a target requires an exec transition.
  • ux -> name still prints the warning about an unconfined exec (Unconfined exec qualifier (ux) allows some dangerous environment variables ...) although no unconfined exec can result (tree).
  • ix -> name and ux -> name are accepted with a meaning different from the plain modes: ix -> name goes to name and falls back to inherit; ux -> name goes to name and does not run unconfined (tree for acceptance, code for the meaning). The manual page lists targets for the p and c families only. This one may be intended.

for AppArmor developers for security researchers

Code map

StepWhere
grammar: opt_named_transition: TOK_ARROW id_or_varparser/parser_yacc.y:1043-1047
lexer state SUB_ID_WS after ->: the next word is a plain TOK_IDparser/parser_lex.l:822, parser/parser_lex.l:456-462
do_file_rule stores nt_nameparser/parser_yacc.y:1759-1769
post_parse_profile_file: runs at the end of the profile body, before process_variablesparser/block_rules.cc:576-596
add_named_transition: the c prefix, the namespace testparser/block_rules.cc:474-525
add_entry_to_x_table: slots 4 to 15, reuse of equal stringsparser/block_rules.cc:458-472
slot limits: AA_EXEC_COUNT, the reserved valuesparser/immunix.h:70, parser/immunix.h:80-82
sd_serialize_xtable: struct xtable, the NUL in namespace targetsparser/parser_interface.c:413-456
unpack_strs_table(e, "xtable", ...) into pdb->translinux:security/apparmor/policy_unpack.c:1075
process_strs_entry: restores the :, rejects : followed by NULlinux:security/apparmor/policy_unpack.c:499-512
range check of every AA_X_TABLE index at loadlinux:security/apparmor/policy_unpack.c:1542-1548
dfa_map_xindex: slot n becomes `AA_X_TABLE \(n - 4)`linux:security/apparmor/policy_compat.c:36-45
x_table_lookup: aa_label_parse relative to the current profilelinux:security/apparmor/domain.c:523-559
x_to_label: the & stack, the ix and ux fallbackslinux:security/apparmor/domain.c:574-650
"profile transition not found", the learning profilelinux:security/apparmor/domain.c:740-754

x_table_lookup also has an aa_find_child branch for an index carrying AA_X_CHILD (linux:security/apparmor/domain.c:542-550). dfa_map_xindex never sets AA_X_CHILD together with AA_X_TABLE, so policy written by this parser does not reach it.

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

PROFILE HEAD

PROFILE STRUCTURE

IN THE KERNEL