Child profiles

profiles inside profiles for application developers for security researchers

A profile declared inside another profile. It is loaded as parent//child and entered when the parent runs a program through a cx rule. A child has its own rules and may have its own attachment which only its parent's cx rules consult.

On the map: profile structure

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

  • Exec modes — cx, the exec mode that reaches a child profile
  • The profile name — the profile keyword and name, reused inside a body

Part of journeys

01 A helper that should get less

CHILD PROFILES profile demo demo exec worker /usr/lib/demo/worker ix: same rules as demo Px: a system-wide profile ux: no profile Cx: a profile of demo's own demo//worker child of demo used only when demo starts the program; written inside demo's braces, next to the rule that starts it
The program demo, confined by profile demo, execs its helper /usr/lib/demo/worker. Four choices for the helper are listed: ix, Px, ux and Cx. With Cx the worker runs in demo//worker, a child profile that belongs to demo.

A child profile is a profile declared inside another profile. It is used when the parent starts a program through an exec rule with a c mode such as Cx.

Demo starts a helper, the worker. What should confine it? It could inherit demo's rules, but the worker needs less, and different things. It could have a profile of its own at the top level, but then that profile applies to the worker whoever starts it, and it fills the namespace with something only demo cares about. No profile at all is not an answer. The fourth option is a child profile: a profile written inside demo, named after it, and used only when demo is the one starting the program. The rule that starts the helper and the rules for the helper live in one file, inside one pair of braces.

Details and sources

Details

  • Syntax: profile NAME { RULES } written inside the body of another profile, and an exec rule in the parent with a c mode, as in /usr/lib/demo/worker Cx -> worker,.
  • apparmor.d(5) calls it a subprofile or child profile: "subprofiles (aka child profiles) in a profile, limited only by kernel memory" (apparmor.d.pod:433-434). Its example profile has both the rule and the child: /usr/bin/baz Cx -> baz, (apparmor.d.pod:2880) and profile baz { ... } (apparmor.d.pod:2889-2896).
  • The exec modes that send the started program into a child are cx, Cx, cix, Cix, cux and CUx (apparmor.d.pod:865-905).
  • The child is loaded under the name demo//worker, next to its parent, not as a top-level profile of its own.
  • Kernel, read and not run: the decision is made in the LSM hook bprm_creds_for_exec, implemented by apparmor_bprm_creds_for_exec (lsm.c:1862, domain.c:985). For a c mode the search is over the current profile's own children; for a p mode over the namespace's top-level profiles (domain.c:603-611).
  • The program demo, its worker and the profile are invented for the map. Nothing on this slide was observed on a running kernel.

Read more

for AppArmor developers for security researchers

In the code

02 The profile keyword, inside a profile

GRAMMAR profile demo /usr/bin/demo { } profile NAME ATTACHMENT xattrs=( ) + identities=( ) flags=( ) { rules } grey parts are optional required here profile demo /usr/bin/demo { /usr/lib/demo/worker Cx -> worker, profile worker { /var/lib/demo/** rw, } } nothing is inherited from demo no comma after the closing brace any rules, more children too
Syntax diagram of a child profile inside the body of profile demo: the keyword profile, a name, an optional attachment, xattrs, identities and flags, and a body of rules in braces. Below it the running example: demo with a Cx rule and the child worker.

profile NAME [ATTACHMENT] [xattrs=( )] [+ identities=( )] [flags=( )] { rules } inside a profile body. The keyword is required. A child does not inherit its parent's rules.

The syntax is the one you already know. Inside the body of demo, write the keyword profile, a name, optionally an attachment and flags, and a body in braces. It's the same head as at the top level, with one difference. At the top level you may leave the keyword out when the name is a path. Inside a profile you may not, because a path at the start of a line there is the start of a file rule. Here is demo with its worker. Like a hat, a child inherits nothing: its body is all it has. And a child's body takes any rules, so children can contain children.

Details and sources

Details

  • Form: profile NAME [ATTACHMENT] [xattrs=( )] [+ identities=( )] [flags=( )] { RULES }, inside a profile body. There is no comma after the closing brace.
  • The keyword profile is required inside a body. Without it, /usr/lib/demo/worker { is read as the start of a file rule and the parser built from the AppArmor tree at 836052d21 answers syntax error, unexpected TOK_OPEN, expecting TOK_MODE (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel).
  • The name is on the same line as the keyword. A new line between them gives Lexer found unexpected character: '\n' (0xa) in state: SUB_ID (same parser, same options).
  • The attachment must begin with / or a variable: Profile attachment must begin with a '/' or variable.
  • A child may have xattrs; a hat may not (hat profiles can't use xattrs matches).
  • Nothing is inherited from the parent. The body is an ordinary profile body, so it may hold children and hats of its own.
  • Fixtures in the parser's tests: local_profiles_ok1.sd has a child named by a path, profile /bin/grep { }; local_named_profile_ok1.sd has profile true /bin/true { }, a name plus an attachment, next to a hat.

for AppArmor developers for security researchers

In the code

03 parent, two slashes, child

NAMING profile demo /usr/bin/demo { profile worker { ... } profile logger /usr/lib/demo/logger { ... } profile /usr/lib/demo/helper { ... } } $ apparmor_parser -N demo demo demo///usr/lib/demo/helper demo//logger demo//worker a path as the child's name gives three slashes worker label: demo//worker (enforce) apparmor="DENIED" ... profile="demo//worker" ... listed in alphabetical order, not file order
Profile demo with three children named worker, logger and a path; apparmor_parser -N lists them as demo, demo///usr/lib/demo/helper, demo//logger and demo//worker; a running worker carries the label demo//worker and a denial names profile demo//worker.

A child named worker in profile demo is demo//worker in listings, labels and logs. apparmor_parser -N prints the full names alphabetically. Inside the child, @{profile_name} expands to the full name.

What is the child called? In the file, just worker. Ask the parser for the names it would load, and you get demo//worker: the parent's name, two slashes, the child's. If you name a child with a path, the result has three slashes in a row, two for the separator and one from the path. It's legal, and a good reason to give children short names. The long form is the name the kernel knows: a running worker carries it as its label, and denials are filed under it, so that's what to search your logs for. One more thing about the listing: it's alphabetical, not in the order of your file.

Details and sources

Details

  • apparmor_parser -N (--names, "Dump names of profiles in input.") prints the full names without compiling or loading anything (parser_main.c:231, apparmor_parser.pod:102).
  • Run with the parser built from the AppArmor tree at 836052d21: profile worker { } in profile demo /usr/bin/demo { } is listed as demo//worker; profile /usr/lib/demo/helper { } as demo///usr/lib/demo/helper.
  • The listing and the load order are alphabetical, not file order: children and hats of one profile are kept in a sorted set (profilelist.h:28).
  • With the parent in a namespace ns the fully qualified name is :ns://demo//worker (profile.h:462-470, read from the source).
  • Inside the child @{profile_name} is the full name without the namespace (parser_variable.c:154-155; asserted by the tests at equality.sh:919-923).
  • Kernel, read and not run: the hierarchical name is built as prefix//name in aa_policy_init (lib.c:478-497).
  • Where the name shows up: the profile= field of log records; /proc/<pid>/attr/apparmor/current (and the older /proc/<pid>/attr/current); and int aa_getcon(char **label, char **mode) or int aa_gettaskcon(pid_t target, char **label, char **mode) from libapparmor (apparmor.h:110-111).
  • apparmor.d(5) says "Subprofile names are limited to 974 characters" (apparmor.d.pod:434). No such limit was found in the parser source.

for AppArmor developers for security researchers

In the code

04 Cx with an arrow: go to the child by name

ENTERING A CHILD demo label: demo execve("/usr/lib/demo/worker") /usr/lib/demo/worker Cx -> worker, the rule in demo that matches the parser stores demo//worker exec: find demo//worker demo//worker worker label: demo//worker found by name: no attachment needed no such child loaded: info="profile transition not found" the exec is refused (kernel source, enforce mode)

/usr/lib/demo/worker Cx -> worker, runs the helper in demo//worker. The child is found by name, so it needs no attachment. A missing child is found out only at exec: "profile transition not found" (read from the kernel source, for a profile in enforce mode).

How does the worker end up in the child? Through an exec rule in demo: the path of the helper, the mode Cx, an arrow, and the child's name. The C says child, the x says execute. You write the short name. The parser stores the full one, demo//worker, and at exec time the kernel looks that profile up and starts the program in it. The child doesn't need an attachment for this, because the rule names it. And if no child of that name is loaded when the exec happens? The kernel refuses the exec and reports that the profile transition was not found.

Details and sources

Details

  • Rule: /usr/lib/demo/worker Cx -> worker,. The target is the child's short name; the man page example is /usr/bin/baz Cx -> baz, (apparmor.d.pod:2880).
  • The parser stores the string demo//worker in the parent's exec table. Checked with the parser built from the AppArmor tree at 836052d21: the string is in the binary profile.
  • The parser does not check that the child exists: Cx -> missing, compiles without a message (same parser, -Q -K --skip-kernel-load --warn=all).
  • The exec table has 16 slots, of which the first 4 are reserved, so a profile can name 12 different targets. One more gives Profile NAME has too many specified profile transitions. (immunix.h:70, read from the source).
  • Kernel, read and not run: x_table_lookup walks the table entry and, for a child transition, calls aa_find_child(profile, name) (domain.c:523-559).
  • No child found, enforce mode: the exec is refused and the record carries info="profile transition not found" (domain.c:740-751). In complain mode a learning profile is created instead and the exec goes on (the same lines).
  • With a fallback in the mode the exec is not refused: cix continues in the parent (info="ix fallback"), cux unconfined (info="ux fallback") (domain.c:616-637).

for AppArmor developers for security researchers

In the code

  • add_named_transition builds the entry with sprintf(name, "%s//%s", prof->name, entry->nt_name) when the mode is a c mode and the target has no namespace (block_rules.cc:474-520); add_entry_to_x_table starts at index (AA_EXEC_LOCAL >> 10) + 1 and reuses an equal string (block_rules.cc:458-472).
  • post_parse_profile_file calls it for every entry with a target and prints the table-full error (block_rules.cc:576-611).
  • prof->name is the local name of the profile holding the rule, so a named cx -> inside a child stores child//target, not the full name; see "Known discrepancies" in the reference below.

05 Cx without an arrow: the child's attachment decides

CHILD ATTACHMENTS profile demo /usr/bin/demo { /usr/lib/demo/* Cx, profile logger /usr/lib/demo/logger { ... } profile worker /usr/lib/demo/worker { ... } } demo runs /usr/lib/demo/logger demo search demo's children logger /usr/lib/demo/logger worker /usr/lib/demo/worker logger demo//logger each child needs an attachment, or a name that is the path: profile /usr/lib/demo/logger { ... } a shell runs /usr/lib/demo/logger bash unconfined search top-level profiles demo's children: not searched logger unconfined the child's attachment is not consulted: no top-level profile matched, so no profile
Profile demo with a bare Cx rule for /usr/lib/demo/* and two children with attachments. When demo execs the logger the kernel searches demo's children and the logger runs in demo//logger. When a shell execs the same file the kernel searches top-level profiles only and the logger runs unconfined.

A bare Cx searches the parent's children by attachment (or by a name equal to the path). A child's attachment is used only for such execs from its parent. Started from elsewhere, the program is matched against top-level profiles only, and runs unconfined if none of those attaches to it.

There's a second way in. Write Cx with no arrow, and the kernel does for the children of demo what it normally does for all profiles: it compares the program's path with each child's attachment and picks the match. So one rule with a glob can spread several helpers over several children. For that, each child needs an attachment, or a name that is itself the path. Keep in mind who looks at that attachment: only an exec from demo through a Cx rule. Start the same logger from a shell and the kernel searches the top-level profiles only. The child stays out of it, and the logger runs unconfined.

Details and sources

Details

  • Rule: /usr/lib/demo/* Cx, with no arrow. Each child that should be found needs an attachment (profile logger /usr/lib/demo/logger { }) or a name that is the path (profile /usr/lib/demo/helper { }).
  • Kernel, read and not run: for a c mode x_to_label calls find_attach over the current profile's children, profile->base.profiles; for a p mode over the namespace's top-level profiles, ns->base.profiles (domain.c:603-611).
  • find_attach compares the program's path with each candidate's attachment and keeps the best match; a profile whose name equals the path also matches (domain.c:394-520, the name comparison at domain.c:485). Two equally good matches give info="conflicting profile attachments" (domain.c:33).
  • An exec by an unconfined task searches ns->base.profiles only (domain.c:697-699). A child is not on that list, so its attachment is never consulted there.
  • No child matches: cx refuses the exec, cix continues in the parent, cux runs unconfined (see the previous slide).
  • Fixture: local_named_profile_ok1.sd declares children with attachments, profile true /bin/true { }.

for AppArmor developers for security researchers

In the code

06 Child profile or hat?

CHILD OR HAT profile worker { } ^admin { } demo//worker demo//admin own rules, nothing inherited own rules, nothing inherited way in /usr/lib/demo/worker Cx -> worker, at exec, decided by a rule demo worker demo demo//worker a new program aa_change_hat("admin", token) any time, asked by the program demo demo -> demo//admin the same process way back none: the worker stays in the child aa_change_hat(NULL, token) aa_change_hat("worker", token) info="target not hat" a child declared with the profile keyword is not a hat (kernel source)
Child profile and hat side by side: both have their own rules and a parent//name. The child is entered at exec by a Cx rule, a new program, with no way back; the hat is entered by aa_change_hat in the same process and left with the token. aa_change_hat on a child is refused with target not hat.

Child profile: entered at exec through a cx rule, for a program you start. Hat: entered and left with aa_change_hat(), for part of your own program's work. change_hat on a child fails with "target not hat".

Children and hats look alike in the file, so here they are side by side. Both are nested rule sets named after the parent, and neither inherits anything. The difference is the door. A child is entered at exec: demo starts another program, and a rule in demo's profile sends it into the child. A hat is entered by the running program itself, with a library call, and left again with a token. So a child is for a helper program, and a hat is for a phase of your own program. The kernel keeps the doors apart: ask change_hat for a child declared with the profile keyword and the answer is "target not hat".

Details and sources

Details

  • A hat is written ^NAME { } or hat NAME { }; a child profile NAME { }. Both are loaded as parent//NAME, and the two share one set of names within a profile.
  • The hat's door is libapparmor: int aa_change_hat(const char *subprofile, unsigned long magic_token) and int aa_change_hatv(const char *subprofiles[], unsigned long token) (apparmor.h:79-83). aa_change_hat(NULL, token) returns to the parent.
  • The call writes changehat TOKEN^NAME to the task's /proc/<tid>/attr/apparmor/current (or /proc/<tid>/attr/current) (kernel.c:1033, path formats at kernel.c:424-426).
  • Kernel, read and not run: the write arrives in apparmor_setprocattr (lsm.c:943); change_hat looks the name up among the profile's children and, when the profile found is not a hat, fails with info="target not hat" and EPERM (domain.c:1232-1243).
  • The child's door is exec: the bprm_creds_for_exec hook and a c mode in the parent (domain.c:603-611). There is no way back: the started program keeps the child's label and its own execs follow the child's rules.
  • A profile that declares a child or a hat receives the implied rules that change_hat needs: /proc/*/attr/apparmor/ r,, /sys/module/apparmor/parameters/enabled r, and /proc/[0-9]*/attr/{apparmor/,}current w, (profile.cc:78-89, block_rules.h:27; rule dump made with the released parser 5.0.2).
  • Whether an exec rule cx -> NAME can enter a hat was not determined.

for AppArmor developers for security researchers

In the code

  • The hat rule is hat: hat_start profile_base and sets profile_flag_t::HAT; local_profile is the same without the flag (parser_yacc.y:480-504).

07 Local profiles and the exec table for AppArmor developers for security researchers

PARSER AND KERNEL grammar: local_profile local_profile: TOK_PROFILE profile_base rules: rules local_profile parser_yacc.y:480-488, 836-843 block::add_hat children and hats share defined_hats; duplicate: exit(1) block.cc:137-155 add_named_transition sprintf("%s//%s", prof->name, nt_name) into the exec table 16 slots, 4 reserved block_rules.cc:458-520, immunix.h:70 load_flattened_hats each child: its own blob, name = hname() parser_policy.c:84-89 parser_interface.c:488-490, 783-785 kernel: x_to_label AA_X_NAME|AA_X_CHILD: find_attach(profile->base.profiles) AA_X_TABLE: x_table_lookup, then aa_label_parse domain.c:523-559, 574-650 policy_compat.c:40-41 the prefix is prof->name, the profile's local name (block_rules.cc:497-504) a target equal to the rule's own path is turned back into the unnamed form (block_rules.cc:492-496)
Pipeline of a child profile: the grammar rule local_profile, storage in defined_hats by block::add_hat, add_named_transition building name//target for the exec table, load_flattened_hats writing each child as its own blob, and x_to_label in the kernel using find_attach over the profile's children or the exec table.

local_profile: TOK_PROFILE profile_base; storage in defined_hats; add_named_transition() stores name//target in the exec table; kernel x_to_label() uses find_attach() over the profile's children or x_table_lookup().

For developers. The grammar calls a child a local profile: the profile token and then profile_base, the same rule a hat uses, minus the hat bit. Children and hats are stored together in defined_hats, which is where the duplicate check lives. For an exec rule with a target and no namespace, add_named_transition glues the profile's name and the target together with two slashes and puts the result in the exec table, which has sixteen slots with four reserved. Each child is serialized as its own blob. In the kernel, x_to_label handles both doors: the child search goes through find_attach over the profile's own children, and table entries are parsed as labels.

Details and sources

for AppArmor developers for security researchers

Details

  • Grammar: local_profile: TOK_PROFILE profile_base (parser_yacc.y:480-488); rules: rules local_profile calls add_hat, with the message Assert: 'local_profile rule' returned NULL. (parser_yacc.y:836-843).
  • Storage: block::add_hat sets hat->parent and calls add_to_known_hats, which inserts into defined_hats and exits with Multiple definitions for profile NAME exist,bailing out. on a duplicate (block.cc:137-155).
  • Exec table: add_entry_to_x_table and add_named_transition (block_rules.cc:458-520), driven by post_parse_profile_file (block_rules.cc:576-611). AA_EXEC_COUNT is 16 (immunix.h:70); AA_EXEC_LOCAL is AA_EXEC_MOD_0 | AA_EXEC_MOD_1, index 3 (immunix.h:82), and the loop starts at index 4.
  • If the target of a cx -> rule equals the rule's own path the rule is turned back into the unnamed form (block_rules.cc:492-496).
  • Serialization: load_flattened_hats loads defined_hats as a policy list after the parent (parser_policy.c:84-89, called from parser_interface.c:783-785); each child's blob carries its full name (parser_interface.c:488-490).
  • Kernel, read and not run: packed exec index 3 is mapped to AA_X_NAME | AA_X_CHILD (policy_compat.c:40-41).
  • x_to_label (domain.c:574-650): AA_X_TABLE goes to x_table_lookup, which uses aa_find_child when AA_X_CHILD is set and aa_label_parse otherwise (domain.c:523-559); AA_X_NAME goes to find_attach over profile->base.profiles or ns->base.profiles.
  • A table entry that begins with & is a stack: the entry is looked up and then the AA_X_NAME search runs as well (domain.c:597-600).

08 Missing keyword, missing child

COMMON MISTAKES /usr/lib/demo/worker { } inside profile demo syntax error, unexpected TOK_OPEN, expecting TOK_MODE a path starts a file rule: write profile profile worker bin { } Profile attachment must begin with a '/' or variable. an attachment is a path profile worker { } ^worker { } Multiple definitions for profile worker exist,bailing out. children and hats share names /usr/lib/demo/worker Cx -> wroker, the child is worker the parser: no message at exec: info="profile transition not found" check the names: apparmor_parser -N lists every child
Four mistakes inside profile demo with the answer to each: a path and brace without the profile keyword gives a syntax error; an attachment not starting with a slash is refused; two nested profiles named worker stop the parser; a mistyped Cx target gets no parser message and fails at exec with profile transition not found.

Inside a profile the keyword profile is required. Children and hats of one profile share one set of names. The parser does not verify Cx -> targets; a wrong name shows up at exec as "profile transition not found".

Four mistakes. Leave out the keyword and write a path and a brace, as you could at the top level, and the parser expects permissions after the path: syntax error at the brace. An attachment that doesn't start with a slash is refused in so many words. Two children with one name, or a child and a hat with one name, stop the parser. The fourth is the one that reaches production: a typo in the target of a Cx rule. The parser doesn't check that the child exists. Everything loads, and the first exec of the helper is refused with profile transition not found.

Details and sources

Details

  • Messages from the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel). The full form is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.
  • A path and a brace without the keyword: syntax error, unexpected TOK_OPEN, expecting TOK_MODE.
  • profile worker bin { }: Profile attachment must begin with a '/' or variable.
  • Two children, or a child and a hat, with one name: Multiple definitions for profile NAME exist,bailing out. (block.cc:137-146). The released parser 5.0.2 words it Multiple definitions for hat NAME in profile (null) exist,bailing out.
  • Cx -> missing, compiles without a message; the parser does not verify that the target exists.
  • Kernel, read and not run: with no child of that name loaded the exec fails with info="profile transition not found" when the parent is in enforce mode (domain.c:740-751). The record's profile= is the parent and name= the program's path.
  • With the parent in complain mode the same exec is allowed and runs in a learning profile created for it (the same lines).
  • Reloading a parent with apparmor_parser -r after deleting a child from the file leaves the old child loaded (read from the kernel source, policy.c:1066-1091: __replace_profile moves children that the new version does not replace over to it).

for AppArmor developers for security researchers

In the code

09 Around child profiles

ROADS /usr/lib/demo/worker Cx -> worker, the mode letters syn-exec-modes cx, Cx, cix, cux and the fallbacks the arrow syn-named-transitions what a target may be next door syn-hats entered without exec syn-profile-name parent//child watch the kernel pick the child attachment a path to a profile k-exec exec in the kernel fe-grammar the shared rule syntax-map the whole profile

The mode letters: syn-exec-modes. The arrow: syn-named-transitions. The sibling: syn-hats. The kernel's side: k-exec.

Two parts of that exec rule have decks of their own. The exec modes deck explains Cx and its relatives, including what happens when no child is found and the rule has a fallback. The named transitions deck covers the arrow and everything a target can be. Hats are next door, and the profile name deck shows how the long names are built. And if you want to watch the kernel pick the child, the attachment deck explains the matching, and the exec deck in the kernel district follows the same call from the inside.

Details and sources

Details

  • A child profile is profile NAME { } inside a profile, loaded as parent//NAME.
  • It is entered at exec through cx, Cx, cix, Cix, cux or CUx: by name with -> NAME, by attachment without the arrow.
  • A missing child is reported only at exec, as info="profile transition not found" (the kernel, domain.c:746).
  • 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 was run on the fragment (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel); "5.0.2" means the released parser 5.0.2 was run; "code" means the kernel or parser source was read, not run. Everything said here about what happens at exec is "code".

Grammar

CHILD:  'profile' NAME [ATTACHMENT] [xattrs=( ... )] { '+' identities=( ... ) } [flags=( ... )] '{' rules '}'
  • Written inside the body of another profile. The head is the one a top-level profile has.
  • The keyword profile is required. At the top level a path may stand alone as a profile head; inside a body a path at the start of a line begins a file rule.
  • The name is on the same line as the keyword.
  • ATTACHMENT must begin with / or a variable.
  • rules is an ordinary profile body, so children may contain children and hats, to any depth.
  • No comma after the closing brace.
  • Nothing is inherited from the parent: the child's body is its whole rule set.
  • Other names for the same thing: "subprofile" in apparmor.d(5), "local profile" in the grammar.

Keywords

TokenMeaning
profileinside a body: starts a child profile
//the separator in loaded names: parent//child. Not written in the child's head
cx Cx cix Cix cux CUxthe exec modes that send the started program into a child of the current profile: syn-exec-modes
->names the child in an exec rule: syn-named-transitions

Names

For children of profile demo /usr/bin/demo { }:

In the fileLoaded nameBasis
profile worker { }demo//workertree
profile logger /usr/lib/demo/logger { }demo//loggertree
profile /usr/lib/demo/helper { }demo///usr/lib/demo/helpertree
profile inner { } inside workerdemo//worker//innertree
any of these when demo is in namespace ns:ns://demo//workercode
  • apparmor_parser -N prints the full names. Children and hats of one profile are listed and loaded in alphabetical order, not file order (tree).
  • The full name is what the kernel is given, what a task confined by the child carries as its label, and the profile= field of its log lines (code).
  • Inside a child @{profile_name} expands to the full name without the namespace (asserted by parser/tst/equality.sh).
  • A child named by a path does not get the "file paths as profile names" deprecation warning that a top-level profile gets (code).

Two ways in

Rule in the parentHow the child is foundThe child needs
/usr/lib/demo/worker Cx -> worker,by name: the parser stores demo//worker in the profile's exec table (tree: the string is in the binary profile) and the kernel looks that name up at exec (code)nothing more
/usr/lib/demo/* Cx,by search: the kernel matches the program's path against the attachments of the parent's children (code)an attachment, or a name that is the path
  • A child's attachment is consulted only for this search. An exec through px, or by an unconfined task, searches the namespace's top-level profiles (code).
  • Among several matching children the choice follows the rules for top-level profiles: attachment.
  • The parser does not check that the target of Cx -> exists: Cx -> missing, compiles without a message (tree).
  • No child found at exec (code):
ModeResult
cx, Cxthe exec is refused; the log line carries info="profile transition not found"
cix, Cixthe program runs in the parent profile
cux, CUxthe program runs unconfined
cx, Cx with the parent in complain modea learning profile is created and the exec goes on

The modes and their fallbacks: syn-exec-modes.

Child or hat

Child profileHat
Written asprofile NAME { }^NAME { } or hat NAME { }
Loaded asparent//NAMEparent//NAME
Enteredat exec, by a cx rule of the parentat any time, by the program calling aa_change_hat()
Leftnot at all: the started program keeps the child's label; its own execs follow the child's rulesaa_change_hat(NULL, token)
May have an attachmentyesyes (what it is for was not determined)
May have xattrs=( )yesno
  • change_hat to a child declared with profile fails with info="target not hat" (code).
  • Whether an exec rule cx -> NAME can enter a hat was not determined.
  • Hats: syn-hats.

What a parent with children gets

A profile that declares a child or a hat receives three implied file rules (tree, rule dump):

/proc/*/attr/apparmor/ r,
/sys/module/apparmor/parameters/enabled r,
/proc/[0-9]*/attr/{apparmor/,}current w,

They exist for change_hat. A parent that has only child profiles gets them too, although change_hat cannot enter such a child. A child without hats or children of its own does not get them. Details: syn-hats.

Loading and reloading

As for hats, see syn-hats:

  • Each child leaves the parser as a binary profile of its own, written after its parent under the full name.
  • Reloading a parent with -r after deleting a child from the file leaves the old child loaded (code).
  • apparmor_parser -R removes the parent, and the kernel removes its children with it (code).

Errors and warnings

MessageCause
syntax error, unexpected TOK_OPEN, expecting TOK_MODEa path and a brace inside a profile, without the keyword profile (tree)
Profile attachment must begin with a '/' or variable.profile worker bin { } (tree)
Multiple definitions for profile NAME exist,bailing out.two children, or a child and a hat, with one name in the same profile (tree). 5.0.2 words it Multiple definitions for hat NAME in profile (null) exist,bailing out.
Lexer found unexpected character: '\n' (0xa) in state: SUB_IDa new line between profile and the name; the character is printed raw (tree)
Profile NAME has too many specified profile transitions.more named exec targets than the exec table holds: 16 slots of which 4 are reserved (code)
FILE: Invalid profile name 'NAME' - bad regular expressionthe attachment, or a path-like name, is not a valid pattern (code)
Assert: 'local_profile rule' returned NULL.internal check in the grammar (code)
kernel: info="profile transition not found"plain cx or Cx and no child found at exec, enforce mode (code)
kernel: info="target not hat"change_hat to a child that is not a hat (code)

Known discrepancies

  • Named cx -> inside a child. The prefix the parser puts before the target is the local name of the profile that holds the rule, not its full name. For profile a { profile b { /z cx -> c, profile c { } } } the exec table of a//b holds b//c, while the grandchild is loaded as a//b//c (tree, strings of the binary profile). By the code of mainline Linux 7.4 the entry is resolved from the namespace root, where b//c does not exist unless a top-level profile b has a child c, so the rule does not reach the grandchild. Not run on a kernel. One level of nesting, as in this deck, is not affected.
  • A top-level profile written as a//b and a child b nested in a get the same loaded name. The parser keeps them in different lists and its duplicate check does not see the clash (code). What a running kernel does with the two was not determined.
  • apparmor.d(5) says "Subprofile names are limited to 974 characters". No such limit was found in the parser.
  • A named transition to another profile's child, Cx -> other//name, can be rewritten by the parser into a transition to a child of the current profile when name equals the rule's path (code; listed in the project's bug notes as a suspected parser bug).

for AppArmor developers for security researchers

Code map

StepWhere
local_profile: TOK_PROFILE profile_base; rules: rules local_profileparser/parser_yacc.y:480-488, 836-843
profile_base: name, attachment, xattrs, identities, flags, bodyparser/parser_yacc.y:391-399
attachment checkparser/parser_yacc.y:431-433
hat rule: the same profile_base plus the HAT flagparser/parser_yacc.y:490-504
profile keyword pushes SUB_ID; the name tokenparser/parser_lex.l:278, 456-461, 850
a bare path inside a body is TOK_IDparser/parser_lex.l:838-841
block::add_to_known_hats, block::add_hat: defined_hats, duplicate checkparser/block.cc:137-155
ordered set of children and hatsparser/profilelist.h:28
hname(), fqname()parser/profile.h:454-470
c modes set AA_EXEC_LOCALparser/parser_misc.c:649-687; parser/immunix.h:82
add_entry_to_x_table, add_named_transition: sprintf("%s//%s", prof->name, nt_name)parser/block_rules.cc:458-520
post_parse_profile_file: every entry with a target; the table-full errorparser/block_rules.cc:576-611
AA_EXEC_COUNT 16parser/immunix.h:70
attachment or path-like name compiled to the child's xmatchparser/parser_regex.c:478-520
@{profile_name}parser/parser_variable.c:154-155
implied rules for a profile with defined_hatsparser/profile.cc:78-89
serialization: name written is hname(); load_flattened_hatsparser/parser_interface.c:488-490, 783-785; parser/parser_policy.c:84-89
kernel: packed exec index 3 becomes `AA_X_NAME \AA_X_CHILD`linux:security/apparmor/policy_compat.c:40-41
kernel: x_table_lookup(), aa_label_parse()linux:security/apparmor/domain.c:523-559
kernel: x_to_label(); find_attach() over profile->base.profiles for cx, ns->base.profiles for pxlinux:security/apparmor/domain.c:574-650, 603-611
kernel: find_attach(); a name equal to the path matcheslinux:security/apparmor/domain.c:394-520, 485
kernel: "profile transition not found"; learning profile in complain modelinux:security/apparmor/domain.c:740-751
kernel: "target not hat"linux:security/apparmor/domain.c:1232-1243
kernel: hname built as prefix//namelinux:security/apparmor/lib.c:478-497
kernel: parent lookup on load; children kept on replacementlinux:security/apparmor/policy.c:523-544, 1071-1091, 1293-1323
  • post_parse_profile runs when the inner profile_base is reduced (parser/parser_yacc.y:450), before add_hat sets parent (parser/parser_yacc.y:836-843), so hname() is not yet usable in add_named_transition: the origin of the first known discrepancy above.
  • If the target of a cx -> rule equals the rule's own path, the rule is turned back into the unnamed form (parser/block_rules.cc:492-496).
  • Fixtures: parser/tst/simple_tests/profile/local/local_profiles_ok1.sd, local_named_profile_ok1.sd; parser/tst/simple_tests/xtrans/x-conflict.sd. Man page example: parser/apparmor.d.pod:2880, 2889-2896.

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

PROFILE HEAD

PROFILE STRUCTURE

IN THE KERNEL

INSIDE THE PARSER

  • The grammar — the grammar rule shared by profiles and children