Profile attachment

which profile a program gets for application developers for administrators for AppArmor developers for security researchers

How the kernel picks the profile for a program at exec. Names and attachments; the score that ranks overlapping globs; ties; xattr conditions; exec rules; and what happens when nothing matches.

On the map: attachment namespaces stacking

▶ Watch this deck — 16 scenes, ~12 min

Worth seeing first

Part of journeys

01 Which profile does foo get?

PROFILE ATTACHMENT bash unconfined execve("/usr/bin/foo") foo foo /usr/bin/foo bin /usr/bin/* binf /usr/bin/f* usr /usr/** exec: pick one foo (enforce) one program, four candidates, one winner, or none
An unconfined shell executes /usr/bin/foo; the kernel looks at four candidate profiles and attaches the profile named foo.

Attachment happens at exec. The kernel compares the executable's path with the attachment of every candidate profile and keeps the best one. A profile loaded later does not attach to programs that are already running.

You wrote a profile for a program, and the program started without it. Or with a different one. Who decided? The kernel did, once, at the moment the program was exec'd. Here an unconfined shell starts /usr/bin/foo, and four loaded profiles all claim that path. The kernel has to pick one of them, or none. This deck shows how it ranks the candidates, what happens on a tie, and what happens when no profile claims the path. Profile authors get the profile head, administrators get the labels and logs to check, and AppArmor developers get the parser and kernel code near the end.

Details and sources

Details

Kernel behaviour in this deck is read from the kernel source; it was not run on a kernel, except where a regression test of the AppArmor tree is named.

  • Attachment is decided at exec, in the LSM hook bprm_creds_for_exec (lsm.c:1862), which is apparmor_bprm_creds_for_exec (domain.c:985).
  • For an unconfined task the kernel searches the top-level profiles of the task's policy namespace for the best attachment (domain.c:697-699).
  • A candidate is a profile whose attachment pattern matches the path of the executable. The path is the one the kernel builds for the opened file, so a symlink is already resolved.
  • If the search finds nothing, an unconfined task stays unconfined (domain.c:720-721).
  • There is no later pass: a profile loaded after the program started does not attach to it. Replacing a profile that is already attached does update the running tasks.
  • To see the result: cat /proc/PID/attr/current, ps -Z, aa-status.

02 A name and an attachment

THE PROFILE HEAD profile NAME ATTACHMENT xattrs=(...) flags=(...) { } NAME: the identifier in labels, logs and rules ATTACHMENT: the pattern for executables profile foo /usr/bin/foo { } name: foo attaches to /usr/bin/foo /usr/bin/foo { } name: /usr/bin/foo attachment copied from the name --warn=deprecated: The use of file paths as profile names is deprecated. ... profile foo { } name: foo no attachment: the search at exec skips it reached only by name: px -> foo, aa-exec -p foo
Syntax diagram of the profile head with a name and an optional attachment, and three spellings: name with attachment, path as name, and name alone.

profile foo /usr/bin/foo { } is named foo and attaches to /usr/bin/foo. A path-named profile uses its name as its attachment. profile foo { } has no attachment and is only reached by name. The order after the name is fixed: attachment, xattrs=, flags=.

The line that opens a profile has two separate parts. The name is the identifier: it's what ps -Z and the audit log print, and what rules refer to. The attachment is a pattern that says which executables the profile is a candidate for. Spelling one gives both, name first, and it's the recommended form. Spelling two uses a path as the name. The parser copies it into the attachment, and the manual calls this deprecated because that long name shows up everywhere; the warning only prints if you ask for it. Spelling three is a name alone. The search at exec skips it, so a task gets that profile only when something asks for it by name.

Details and sources

Details

  • Syntax: [profile] NAME [ATTACHMENT] [xattrs=(...)] [flags=(...)] {. The order after the name is fixed.
  • Man page on the name: "The name of the profile is its identifier. It is what is displayed during introspection (eg. ps -Z), and defines how the profile is referenced by policy rules" (apparmor.d.pod:453-455).
  • Path as name: "the name is also used as the profile's exec attachment conditional. This use however has been deprecated and is discouraged" (apparmor.d.pod:460-463). The parser copies the name into the attachment after expanding variables (parser_variable.c:65-71).
  • The warning, verbatim: The use of file paths as profile names is deprecated. See man apparmor.d for more information. Its class is deprecated; it prints only with apparmor_parser --warn=deprecated or --warn=all.
  • Errors, verbatim: Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'. and Profile attachment must begin with a '/' or variable.
  • Example of spelling one from the parser's tests: profile exist /does/not/exist { (profile_basic_named_ok1.sd:8).
  • A profile with a name alone is reached by name: Px -> NAME in another profile, aa-exec -p NAME -- COMMAND, or aa_change_profile("NAME").

for AppArmor developers for security researchers

In the code

03 How a match is scored

THE SCORE how far does each pattern get before it loops? / 1 u 2 s 3 r 4 / 5 b 6 i 7 n 8 / 9 f 10 o 11 o 12 /usr/bin/foo 12 profile foo every character is literal /usr/bin/* 10 profile bin first character the * takes: counted then it loops: stop /usr/** 6 profile usr the ** takes b: counted then it loops the score comes from the path that was run, not from the length of the pattern
The path /usr/bin/foo as twelve character cells; the exact pattern counts twelve, /usr/bin/* counts ten and /usr/** counts six.

The score is the number of leading characters of the path consumed before the match first returns to a state it was just in. For /usr/bin/foo: /usr/bin/foo scores 12, /usr/bin/* 10, /usr/** 6, /** 2. Worked out from the code; not measured on a kernel.

The kernel doesn't compare how long the patterns are. It walks the path that was executed through each profile's pattern and counts characters. Every literal character counts, so the exact path scores twelve. Now the glob, /usr/bin/*. Nine literal characters, then the star takes the f, and that still counts: ten. The next character lands in the same place again, and there the counting stops; the rest of the path only has to match. /usr/** gets five literals plus one, so six. These numbers come from reading the kernel's matching code, not from a test run.

Details and sources

Details

The scores are worked out from the kernel source; they were not measured on a kernel.

  • The score is the count returned by aa_state_t aa_dfa_leftmatch(const struct aa_dfa *dfa, aa_state_t start, const char *str, unsigned int *count) (match.c:816-824).
  • Counting: one for each character consumed, until the walk enters a state it was in recently; then the rest of the path is matched without counting (match.c:765-777).
  • "Recently" is a history of the last 32 states: #define WB_HISTORY_SIZE 32 (match.h:154-159); the test is is_loop (match.c:720-739).
  • For the path /usr/bin/foo: /usr/bin/foo 12, /usr/bin/fo? 12, /usr/bin/fo* 11, /usr/bin/f* 10, /usr/bin/* 10, /usr/** 6, /** 2. The full table is in the reference under this deck.
  • The score depends on the path that was run: /usr/*/foo scores 6 for /usr/bin/foo and 10 for /usr/b/foo.
  • The man page apparmor_xattrs(7) words it as "The priority of each profile is determined by the length of the path" (apparmor_xattrs.pod:61); apparmor.d(5) calls it "a longest left match heuristic" (apparmor.d.pod:500-501).

for AppArmor developers for security researchers

In the code

  • The parser turns the attachment glob into a regular expression in convert_aaregex_to_pcre (parser_regex.c:118); the kernel sees only the DFA built from it, which is why the count is over DFA states and not over characters of the pattern.

04 The highest score wins

PICKING A WINNER bash unconfined foo /usr/bin/foo usr /usr/** 6 bin /usr/bin/* 10 lower score: out foo /usr/bin/foo 12 lower score: out /usr/lib/x/foo usr /usr/** the only match no score, no candidate: a pattern that does not match is not in the race
Three profiles scored for /usr/bin/foo: usr 6, bin 10, foo 12; foo attaches. For /usr/lib/x/foo only usr matches and attaches.

A candidate is replaced only by a profile with a strictly higher score. foo (12) beats bin (10) beats usr (6) for /usr/bin/foo, in any load order. Worked out from the code; not measured on a kernel.

Line the candidates up for /usr/bin/foo. Going by the kernel's rules, the broad profile scores six. The directory glob scores ten, so the six drops out. The exact path scores twelve and takes over. It wins whatever order the kernel meets them in: a lower score is skipped, and a higher one replaces the candidate. Now move the binary to /usr/lib. Only the broad profile matches there, so that one attaches. That's how a general profile and a specific one live side by side. And a pattern that doesn't match at all isn't in the race.

Details and sources

Details

Worked out from the kernel source; not measured on a kernel.

  • A profile whose count is lower than the current best is skipped: if (count < candidate_len) continue; (domain.c:439-440).
  • A profile with a higher count replaces the candidate (domain.c:480-483). The result therefore does not depend on the order in which the profiles were loaded.
  • A profile takes part only if the walk ends in a state with exec permission, which means the pattern matches the whole path (domain.c:435-436).
  • Example: for /usr/bin/foo the profiles /usr/bin/foo, /usr/bin/* and /usr/** score 12, 10 and 6. For /usr/lib/x/foo only /usr/** matches.
  • The parser rejects two profiles with the same name. It does not reject two profiles with the same attachment; that is a tie at exec.
  • Tested in the AppArmor tree: an exact path beats a glob that also lists a matching xattr (xattrs_profile.sh:84-99).

Read more

05 Two globs can tie

A TIE / 1 u 2 s 3 r 4 / 5 b 6 i 7 n 8 / 9 f 10 o 11 o 12 /usr/bin/* 10 profile bin the * takes f: counted /usr/bin/f* 10 profile binf f is literal; the * adds nothing 10 = 10: no winner conflicting profile attachments /usr/bin/fo* 11 a third pattern one more literal character breaks the tie or load an exact profile: 12 beats both and the tie no longer matters
The patterns /usr/bin/* and /usr/bin/f* both count ten characters of /usr/bin/foo and tie; /usr/bin/fo* counts eleven.

Equal score and equal matched xattrs is a conflict: the search returns no profile and sets conflicting profile attachments. /usr/bin/* and /usr/bin/f* tie at 10 for /usr/bin/foo; /usr/bin/fo* scores 11. Worked out from the code and recorded as a known discrepancy with what people expect; not measured on a kernel.

Here's the surprise. You have a profile for everything in /usr/bin, and you add one for names starting with f, expecting it to be more specific. By the kernel's counting, they tie. In the first pattern the star takes the f, and that counts: ten. In the second the f is a literal, which is also ten, and its star adds nothing. Equal scores and no xattrs on either side: the search reports conflicting profile attachments and returns no profile. Make the literal part one character longer, fo*, and it works out to eleven, which wins. A third profile with a higher score clears the tie as well.

Details and sources

Details

Worked out from the kernel source and recorded as a known discrepancy with what profile authors expect; not measured on a kernel.

  • Tie rule: equal count and equal number of matched xattrs sets a conflict flag (domain.c:469-475). A later profile with a higher count clears it (domain.c:480-483).
  • After the loop a conflict returns no profile and sets the text conflicting profile attachments (domain.c:495-499).
  • Why /usr/bin/* and /usr/bin/f* tie for /usr/bin/foo: the first character a * takes is counted, and counting stops when the walk stays in the same state (match.c:769-774). Nine literals plus one is 10; ten literals plus nothing is 10.
  • /usr/bin/fo* scores 11 and wins over both.
  • What to look for when the parent is unconfined: a record with operation="exec" and info="conflicting profile attachments" (type AUDIT by the code, since the exec itself is allowed), and the program running unconfined. No sample of this record exists in the trees; only the operation, info and name fields are certain.
  • Ways out: make one pattern score higher for the paths in question, give one profile an xattrs= condition, or drop the overlap.

Read more

for AppArmor developers for security researchers

In the code

  • The comment above the comparison reads TODO: allow for more flexible best match (domain.c:463-468).
  • The candidate's stored length is max(count, attach->xmatch_len) (domain.c:481), while later profiles are compared by their raw count.

06 A tie is not always a denial

AFTER A TIE bin 10 = binf 10 who called execve? unconfined bash foo runs unconfined ... operation="exec" info="conflicting profile attachments" ... name="/usr/bin/foo" ... launcher: /usr/bin/foo px, exec denied ... operation="exec" info="profile transition not found" ... launcher: /usr/bin/foo pix, foo runs as launcher ... info="conflicting profile attachments - ix fallback" ... launcher: /usr/bin/foo pux, foo runs unconfined the manual says a tie denies the exec; the code denies only in the px lane
After a tie between bin and binf: an unconfined shell runs foo unconfined, a px rule denies the exec, pix keeps the launcher profile and pux runs unconfined.

On a tie: an unconfined task stays unconfined and an operation="exec" record with info="conflicting profile attachments" is forced; px/cx deny with info="profile transition not found"; pix keeps the current profile with info="conflicting profile attachments - ix fallback"; pux runs unconfined. Known limitation: under px the audit record cannot tell a tie from a missing profile; the kernel log can.

The manual says that when no winner can be found, the exec is denied. The code is more forgiving, and it's worth knowing how. If the shell starting foo is unconfined, foo simply runs unconfined; the kernel forces an audit record saying conflicting profile attachments, and that record is your only clue. If a confined launcher uses px, there's nothing to transition to, and the exec is denied. The record says profile transition not found, the same text as for a missing profile. With pix, foo runs under the launcher's profile. With pux, it runs unconfined. So the manual's sentence holds in just one of these four lanes.

Details and sources

Details

Read from the kernel source; not run on a kernel.

  • The three texts are constants: conflicting profile attachments, conflicting profile attachments - ix fallback, conflicting profile attachments - ux fallback (domain.c:33-37).
  • Unconfined task: the record is forced by setting the audit bit for exec, and the task keeps its label (domain.c:697-721). Fields: operation="exec", info="conflicting profile attachments", name= the path.
  • px or cx: no label is found, so info becomes profile transition not found and the error is -EACCES (domain.c:741-754).
  • pix or cix: the task keeps its profile, info="conflicting profile attachments - ix fallback" (domain.c:617-628).
  • pux or cux: the namespace's unconfined profile, info="conflicting profile attachments - ux fallback" (domain.c:629-636).
  • Under px the conflict text goes only to the kernel log, rate-limited: AppArmor: profile_transition (from profile launcher) audit info "conflicting profile attachments" dropped on missing transition (domain.c:742-746). Look for it with dmesg or journalctl -k.
  • The man page says "If the heuristic can not determine a winner between multiple matches the exec will be denied." (apparmor.d.pod:504-505). By the code that holds only for px and cx without a fallback.

for AppArmor developers for security researchers

In the code

  • The forced record for the two fallbacks sits behind new->proxy == profile->label.proxy (domain.c:730-737), a comparison that a ux fallback does not appear to satisfy; not confirmed by a run.

07 Extended attributes narrow the match and break ties

XATTR CONDITIONS file /usr/bin/foo same path, same score foo /usr/bin/foo 12 tagged /usr/bin/foo xattrs=(user.foo=hello) 12 no xattr on the file: tagged is not a candidate, foo attaches $ setfattr --name=user.foo --value=hello /usr/bin/foo user.foo=hello + 1 xattr bin /usr/bin/* xattrs=(user.foo=hello) 10 + 1 xattr path first: 12 beats 10 whatever the xattrs no abi rule, or an old kernel: attaches by path alone xattr attachment conditional ignored printed only with --warn=rule-not-enforced
Two profiles for /usr/bin/foo with score 12; once the file carries user.foo=hello the profile with the xattrs condition wins; a glob with xattrs still loses to the exact path.

xattrs=(name=value ...) adds required extended attributes to the attachment. With equal path scores the profile with more matched xattrs wins; a higher path score wins regardless. The parser drops the condition when the kernel or the profile's ABI lacks xattr attachment, and a file with no abi rule is in that case: the profile is then broader than written. The warning xattr attachment conditional ignored appears only with --warn=rule-not-enforced or --warn=all.

Sometimes the path isn't enough: you want a profile only on binaries you've marked. The xattrs condition does that. Here two profiles have the same path and the same score. Without the attribute on the file, tagged is out of the race and foo attaches. Set the attribute, and tagged matches one xattr more than foo, so it wins the tie. The path score is still compared first, though: an exact path beats a glob, whatever xattrs the glob carries. And one trap to take seriously. The parser drops the condition when the kernel, or the profile's ABI, lacks xattr attachment, and a profile file with no abi rule is in that case. The profile then applies to every file its path matches, and the warning only prints if you ask for it.

Details and sources

Details

  • Syntax: profile tagged /usr/bin/foo xattrs=(user.foo=hello) {. Values are globs; a bare name means any value. Man page example: profile trusted /usr/bin/* xattrs=(security.apparmor="trusted") { (apparmor_xattrs.pod:39).
  • Set and read an attribute: setfattr -n user.foo -v hello /usr/bin/foo, getfattr -d /usr/bin/foo.
  • Order of comparison in the kernel: the path count first, then the number of matched xattrs; equal on both is a conflict (domain.c:469-475). A profile whose listed xattrs do not all match is out (domain.c:460-461).
  • Tested in the AppArmor tree: xattrs break a tie between two profiles with the same path (xattrs_profile.sh:122-137); a file with extra, unlisted xattrs still matches (xattrs_profile.sh:58-59).
  • Features needed: domain/attach_conditions/xattr in both the kernel and the ABI of the profile (parser_main.c:1096-1098), and policy/outofband in the kernel (parser_main.c:1758-1759). Check with ls /sys/kernel/security/apparmor/features/domain/attach_conditions/.
  • If a feature is missing the parser drops the condition and loads the profile (parser_regex.c:548-552). The warning is xattr attachment conditional ignored (parser_regex.c:472-476) and prints only with --warn=rule-not-enforced or --warn=all (parser_common.c:169-171).
  • A profile file needs abi <abi/3.0>, or newer for the condition to be kept; without an abi rule the parser's default ABI is used, which has no xattr attachment.
  • Hats cannot use xattrs=: hat profiles can't use xattrs matches.

for AppArmor developers for security researchers

In the code

08 Exec rules decide whether the search runs

WHO SEARCHES unconfined task search: top-level profiles foo the best match attaches exec rule in profile launcher /usr/bin/foo px, search: top-level profiles foo same search as unconfined /usr/bin/foo cx, search: launcher's children launcher//foo a child with attachment /usr/bin/foo /usr/bin/foo px -> usr, lookup by name usr its attachment is not consulted /usr/bin/foo ix, launcher no search aa-exec -p NAME / aa_change_onexec(): an on-exec request is tested first and overrides the rule
Five rows: an unconfined task and a px rule search the top-level profiles, cx searches the children of launcher, a named target is looked up by name, ix does not search.

Unconfined tasks and px search the top-level profiles of the namespace; cx searches the current profile's children; px -> name and cx -> name look the target up by name; ix and ux do not search. An on-exec request (aa-exec -p, aa_change_onexec) is tested first.

So far an unconfined shell started foo. A confined parent is different: its own exec rule for the path decides first. Plain px runs the same search over the same profiles. With cx the search runs over the parent's child profiles instead, matching the children's attachments. An arrow with a name skips the search: the kernel finds that profile by name and doesn't look at its attachment. And ix doesn't ask at all; foo stays in the launcher's profile. One thing comes before all of these. If the task asked for a profile on exec, with aa-exec -p or the library call, that request is tried first.

Details and sources

Details

Read from the kernel source; not run on a kernel.

  • On-exec request first: "Test for onexec first as onexec override other x transitions." (domain.c:1027-1030). The request is made with aa-exec -p NAME -- COMMAND, which calls aa_change_onexec(name) (aa_exec.c:210-211), or from C with int aa_change_onexec(const char *profile);. libapparmor sends the string exec NAME with the lsm_set_self_attr system call when it is available, and otherwise writes it to the task's exec attribute under /proc/PID/attr/ (kernel.c:997-1011).
  • Unconfined task: the search runs over the top-level profiles of its namespace (domain.c:697-699).
  • Confined task: its own file rules are consulted for the path first (domain.c:724-728). No exec permission means the exec is denied, or learned in complain mode.
  • px: the same search over the namespace's top-level profiles. cx: the search over the children of the current profile (domain.c:603-611).
  • px -> name, cx -> name: a lookup by name in the profile's transition table; the target's attachment is not consulted (domain.c:592-597).
  • ix keeps the current profile; ux goes to the namespace's unconfined profile (domain.c:617-636).
  • aa-exec -i -p NAME changes the profile at once with aa_change_profile instead of at exec (aa_exec.c:205-207).

for AppArmor developers for security researchers

In the code

  • The exec index bits are AA_X_NAME 0x04000000, AA_X_TABLE 0x08000000, AA_X_CHILD, AA_X_INHERIT and AA_X_UNCONFINED (file.h:56-64); x_to_label dispatches on them (domain.c:574-578) and x_table_lookup resolves a named target (domain.c:523-524).

09 When no profile matches

NO CANDIDATE no profile attaches to /usr/bin/foo unconfined bash foo runs unconfined no record launcher: /usr/bin/foo px, exec denied apparmor="DENIED" operation="exec" class="file" info="profile transition not found" error=-13 profile="launcher" name="/usr/bin/foo" ... requested_mask="x" denied_mask="x" launcher: /usr/bin/foo pix, foo runs as launcher info="ix fallback" launcher: /usr/bin/foo pux, foo runs unconfined info="ux fallback" info, logged only if the rule audits launcher (complain): px, foo launcher//null-/usr/bin/foo a learning profile
With no profile attaching to /usr/bin/foo: an unconfined shell runs foo unconfined with no record, px is denied, pix and pux fall back, and complain mode creates a learning profile.

No match: unconfined stays unconfined with no record; px/cx fail with EACCES and info="profile transition not found"; pix keeps the current profile (info="ix fallback"); pux goes to the namespace's unconfined profile (info="ux fallback"); complain mode creates <profile>//null-<path>. The two fallback texts are logged only if the rule audits. With no exec rule for the path at all, the exec is denied, or learned in complain mode.

Now suppose nothing attaches to /usr/bin/foo. From an unconfined shell nothing happens and nothing is logged: foo runs unconfined. That's the usual reason a profile seems not to work, so check its attachment first. From the launcher with px, the exec fails with permission denied, and the record says profile transition not found. The modes pix and pux exist for this case: stay in the launcher's profile, or drop to unconfined. In complain mode the kernel creates a learning profile, named after the parent and the path, so the logs show what a real profile would need.

Details and sources

Details

Read from the kernel source; not run on a kernel. The two log lines quoted are from the libapparmor test corpus.

  • Unconfined: the task keeps its label and no record is written (domain.c:720-721).
  • px or cx: info="profile transition not found", error -EACCES (domain.c:747-754). The info= and error= fields are written together (audit.c:111-115).
  • pix, cix: the current profile, info="ix fallback". pux, cux: the namespace's unconfined profile, info="ux fallback" (domain.c:617-636). A record is written for these only if the rule audits.
  • Complain mode: a learning profile is created and named PARENT//null-PATH (policy.c:756-757). A real record: apparmor="ALLOWED" operation="exec" profile="/home/cb/bin/hello.sh" name="/usr/bin/rm" ... target="/home/cb/bin/hello.sh//null-/usr/bin/rm" (exec01.in:1).
  • No exec rule at all for the path: the exec fails with -EACCES (domain.c:768-770). A real record: apparmor="DENIED" operation="exec" profile="/usr/bin/wireshark" name="/usr/lib64/wireshark/extcap/androiddump" ... requested_mask="x" denied_mask="x" (exec02.in:1).
  • First checks when a profile "does not work": aa-status (is it loaded), cat /proc/PID/attr/current (what the process carries), then the attachment in the profile head against the real path of the binary (readlink -f).

for AppArmor developers for security researchers

In the code

  • The learning profile comes from aa_new_learning_profile(profile, false, name, GFP_KERNEL) (domain.c:756-759) and is added to the parent's children (policy.c:789).

10 A path the kernel cannot name

DISCONNECTED PATHS launcher execve usr/bin/foo no leading slash: disconnected exec denied info="Failed name lookup - disconnected path" without the flag profile launcher /usr/bin/launcher flags=(attach_disconnected.path=/dis) { the name becomes /dis/usr/bin/foo it goes to launcher's exec rules and, for px, into the search profile foo /dis/usr/bin/foo { } matches unconfined task: keeps its label, no profile attaches
A confined launcher executes a file whose path comes out as usr/bin/foo without a leading slash; the exec is denied unless the launcher profile has attach_disconnected, which turns the name into /dis/usr/bin/foo.

attach_disconnected and attach_disconnected.path=/prefix belong to the profile confining the task that calls execve; the flag attaches the path to a root, it does not attach a profile. Without it a confined exec of a disconnected file fails with info="Failed name lookup - disconnected path"; an unconfined task keeps its label and nothing attaches.

Attachment needs a path, and sometimes the kernel can't produce one: the file sits on a mount the task can't see. The name comes out without its leading slash, and it's called disconnected. A confined task's exec then fails with failed name lookup. The flag attach_disconnected repairs the name, optionally under a prefix you choose, and matching carries on with that name: first in the launcher's exec rules, then, for px, in the search. Mind whose flag it is. It belongs to the profile of the task calling exec, because that profile's settings build the name. An unconfined task with such a file just keeps its label, and no profile attaches.

Details and sources

Details

Read from the kernel source; not run on a kernel, except the regression test named below.

  • Syntax: flags=(attach_disconnected) or flags=(attach_disconnected.path=/prefix) (profile.h:231-242). A relative prefix is the error attach_disconnected path must begin with a / (parser_variable.c:49-50).
  • Without the flag a disconnected name loses its leading / and the lookup fails with -EACCES (path.c:53-61). With it the / is put back and the prefix, if any, in front (path.c:62-68).
  • The info= texts: Failed name lookup - disconnected path, Failed name lookup - deleted entry, Failed name lookup - name too long, Failed name lookup (path.c:208-216).
  • At exec the name is built with the flags of the current profile, the one confining the task that calls execve (domain.c:684-685).
  • On a naming error an unconfined task keeps its label, and no search is made (domain.c:686-694).
  • Regression test in the AppArmor tree: attach_disconnected.sh.
  • Related flags in the same list: no_attach_disconnected, chroot_attach, chroot_no_attach, mediate_deleted, delegate_deleted.

Read more

for AppArmor developers for security researchers

In the code

  • int aa_path_name(const struct path *path, int flags, char *buffer, const char **name, const char **info, const char *disconnected) (path.c:202-203) calls d_namespace_path, which marks a path as not connected when it is outside the task's mount namespace (path.c:125-127).
  • The unconfined profile of a namespace carries FLAG_IX_ON_NAME_ERROR (policy_ns.c:91-92).

12 The attachment text is reused

ONE STRING, THREE USES profile foo /usr/bin/foo { } /usr/bin/foo matched at exec alias /usr/ -> /opt/x/, /opt/x/bin/foo also attaches here; the original still matches @{exec_path} r, @{exec_path} r, is compiled as /usr/bin/foo r, and, via alias, /opt/x/bin/foo r, @{attach_path} holds the same text profile bin /usr/bin/* { @{exec_path} r, } /usr/bin/* r, the pattern, globs included
The attachment string /usr/bin/foo is used three times: matched at exec, rewritten by an alias into /opt/x/bin/foo, and substituted for @{exec_path} inside the profile.

alias /usr/ -> /opt/x/, gives profile foo /usr/bin/foo a second attachment /opt/x/bin/foo. @{exec_path} and @{attach_path} both hold the attachment pattern, globs included, and an alias rewrites the resulting rule like any other file rule; in a profile without an attachment they are undefined (Failed to find declaration for: @{attach_path}).

The attachment is just a string in the profile head, and the parser uses it twice more. The first use you know: it's matched at exec. Second, if your policy has an alias whose left side is the start of the attachment, the profile gets a second attachment with the prefix replaced, and the original still matches. Third, inside the profile, @{exec_path} and @{attach_path} both expand to the attachment. Read that carefully: it's the pattern, not the program that was actually started. With a glob attachment, a rule on @{exec_path} grants access to everything the glob matches.

Details and sources

Details

  • Alias: alias /usr/ -> /opt/x/, in the preamble. If the alias source is a prefix of the attachment text, the profile gets an alternate attachment with the prefix replaced (parser_alias.c:176-190). It is a test on the pattern text: /us*/bin/foo is not aliased by /usr/.
  • The variables are filled in by the parser: profile_name, attach_path, exec_path (parser.h:334-337).
  • @{attach_path} and @{exec_path} are both set to the attachment text (parser_variable.c:159-175). The source notes update to use kernel vars if available, so @{exec_path} is not the path that was executed.
  • Example: profile bin /usr/bin/* { @{exec_path} r, } grants read on everything /usr/bin/* matches.
  • @{profile_name} is escaped so that its characters are not read as globs; the other two are not (parser_variable.c:151-155).
  • Without an attachment they are undefined: Failed to find declaration for: @{attach_path}.
  • Parser tests: vars_auto_attach_path_01.sd, vars_auto_exec_path_07.sd.
  • To see the expansion without loading: apparmor_parser -Q -K -D variables FILE.

13 What the parser sends: the xmatch table and xmatch_len for AppArmor developers

PARSER: process_profile_name_xmatch profile_base parser_yacc.y:391 $1 name: foo $2 attachment: /usr/bin/foo process_profile_variables parser_variable.c:67-76 variables expanded; a path name is copied to prof->attachment replace_profile_aliases parser_alias.c:200 alias /usr/ -> /opt/x/, altnames += /opt/x/bin/foo process_profile_name_xmatch parser_regex.c:478 convert_aaregex_to_pcre one AA_MAY_EXEC rule per name; an xattr tail after the path create_dfablob: aadfa + xmatch_len /usr/bin/foo 12 /usr/bin/* 10 /usr/bin/f* 10 /usr/** 6 profile foo { }: no xmatch (observed, parser 6.0.0~alpha2) kernel: unpack_pdb policy_unpack.c:1174-1196 attach.xmatch, attach.xmatch_len, attach.xattrs[] no DFA only when: Basic pattern, no altname, no attachment, no xattrs (parser_regex.c:511)
The parser pipeline for an attachment: profile_base, process_profile_variables, replace_profile_aliases, process_profile_name_xmatch, create_dfablob, and unpack_pdb in the kernel.

process_profile_name_xmatch (parser/parser_regex.c:478) builds the xmatch DFA for every profile with an attachment; xmatch_len is min_match_len() of the expression tree. The kernel unpacks them into struct aa_attachment. The parser does not write the optional attach string. The lengths shown were read from the output of apparmor_parser 6.0.0~alpha2 (836052d21).

On the parser side, the grammar splits the head into a name and an attachment. Then variables are expanded, a path name is copied into the attachment, and aliases add alternate names. All of that feeds process_profile_name_xmatch. Each name becomes a rule with exec permission in one small DFA, and an xattrs list adds a tail after the path. The blob is written right after the profile name, followed by xmatch_len, the minimum match length of the tree. The kernel unpacks both into the profile's attachment. One thing to note: at this commit a plain path with no glob still gets a DFA, so the kernel's old exact-name comparison isn't reached for attached profiles.

Details and sources

for AppArmor developers for security researchers

Details

Read at AppArmor 836052d21 (6.0.0~alpha2) and the kernel.

  • bool process_profile_name_xmatch(Profile *prof) (parser_regex.c:478), called from process_profile_rules (parser_regex.c:1238).
  • No DFA is built only for a pattern without globs when there is no alternate name, attachment or xattrs list (parser_regex.c:511-513).
  • Inputs: variables expanded and a path name copied to the attachment (parser_variable.c:58-78); alternates from aliases (parser_alias.c:201-208); the head from profile_base (parser_yacc.y:391).
  • xmatch_len is the smallest min_match_len() over the expression trees (aare_rules.cc:173-176).
  • Serialization: the DFA and then sd_write_uint32(buf, profile->xmatch_len) (parser_interface.c:496-501).
  • Kernel side: unpack_pdb(e, &profile->attach.xmatch, ...) and then the u32 into profile->attach.xmatch_len; a DFA without the length fails with missing xmatch len (policy_unpack.c:1174-1187).
  • The optional string attach is read by the kernel (policy_unpack.c:1171-1172) and not written by the parser.
  • struct aa_attachment { const char *xmatch_str; struct aa_policydb *xmatch; unsigned int xmatch_len; int xattr_count; char **xattrs; }; (policy.h:213-219).
  • To look at the DFA: apparmor_parser -Q -K -D dfa-states FILE (names from --help=dump).

14 find_attach: one loop, four registers for AppArmor developers

KERNEL: find_attach (domain.c:394) base.profiles, newest first count candidate candidate_len candidate_xattrs conflict NULL 0 0 false start binf /usr/bin/f* bin /usr/bin/* usr /usr/** foo /usr/bin/foo aa_dfa_leftmatch(xmatch, DFA_START, name, &count) 10 binf 10 0 false MAY_EXEC: match 10 binf 10 0 true == :469-475 6 binf 10 0 true skip :439-440 12 foo 12 0 false cleared :483 candidate_len = max(count, attach->xmatch_len) :481 !candidate || conflict: return NULL (*info set on conflict) else: return the label of aa_get_newest_profile(candidate) callers: profile_transition (unconfined), x_to_label (AA_X_NAME; AA_X_CHILD: profile->base.profiles)
find_attach visits the profiles binf, bin, usr and foo; a table shows count, candidate, candidate_len, candidate_xattrs and conflict after each visit, ending with foo, 12, no conflict.

find_attach (linux:security/apparmor/domain.c:394-506) returns the best match or NULL on no match or conflict. aa_dfa_leftmatch (match.c:816) supplies count; aa_xattrs_match (domain.c:313) supplies the tie-breaker and runs outside the RCU read lock, restarting the walk if the namespace revision changed. The counts are worked out from the code, not measured.

Here's the search itself. find_attach takes a list head: the namespace's profiles, or the current profile's children for cx. For each profile with an xmatch DFA it calls aa_dfa_leftmatch, which returns the final state and a count: the characters consumed before the walk re-entered a recent state, tracked in a thirty-two entry history. No exec permission in the final state means no match. Now watch the registers, reading the code. binf counts ten and becomes the candidate. bin also counts ten with equal xattrs, so conflict is set. usr counts six and is skipped. Then foo arrives with twelve: it replaces the candidate and clears the conflict. After the loop, no candidate or a conflict returns NULL.

Details and sources

for AppArmor developers for security researchers

Details

Read from the kernel; the counts in the narration are worked out from the code, not measured.

  • static struct aa_label *find_attach(const struct path *path, struct aa_ns *ns, struct list_head *head, const char *name, const char **info) (domain.c:394-396).
  • The registers: candidate, candidate_len, candidate_xattrs, conflict (domain.c:398-400).
  • Per profile: aa_dfa_leftmatch(attach->xmatch->dfa, attach->xmatch->start[AA_CLASS_XMATCH], name, &count), then perms->allow & MAY_EXEC (domain.c:431-436).
  • Skip: if (count < candidate_len) continue; (domain.c:439-440). Tie: count == candidate_len && ret <= candidate_xattrs (domain.c:469-475). Replace: candidate_len = max(count, attach->xmatch_len) (domain.c:480-483).
  • xattrs are read outside the RCU read lock, and the walk restarts if ns->revision changed (domain.c:443-455).
  • A profile without an xmatch DFA matches only by strcmp(profile->base.name, name) and then wins at once (domain.c:485-491).
  • End: if (!candidate || conflict) returns NULL, with *info = CONFLICTING_ATTACH_STR for a conflict (domain.c:495-499).
  • Visiting order: profiles are added at the head of the list with list_add_rcu, so the newest is visited first (policy.c:164).
  • The count: aa_dfa_leftmatch (match.c:816-824), is_loop (match.c:720-739), WB_HISTORY_SIZE 32 (match.h:154).

15 Seeing which profile attached

CHECKING THE RESULT foo (pid 4242) $ cat /proc/4242/attr/current foo (enforce) label, then mode; "unconfined" has no mode $ ps -Z $ aa-status the same label, for many processes $ cat /sys/kernel/security/apparmor/policy/profiles/<name>/attach <unknown> for every profile that has an attachment $ aa-status 0 processes are unconfined but have a profile defined. names against paths: misses named profiles, globs ... operation="exec" info="conflicting profile attachments" ... ... name="/usr/bin/foo" ... audit log: an unconfined exec hit a tie loaded the profile after foo started? restart foo: attachment happens only at exec
Terminal panels for checking the result: /proc/4242/attr/current, ps -Z and aa-status, the apparmorfs attach file that prints unknown, the aa-status count of unconfined processes that have a profile, and the conflict record in the audit log.

/proc/PID/attr/current holds label (mode) or unconfined. policy/profiles/<name>/attach shows <unknown> for profiles with an attachment. Known limitation: aa-status's "unconfined but have a profile defined" finds only path-named profiles without globs. A profile loaded after a process started does not attach to it.

To see what the kernel chose, read the task's current attribute in proc. You get the label with the mode in brackets, or the single word unconfined. ps -Z and aa-status show the same thing for many processes. Two things can mislead you. The attach file in apparmorfs prints unknown for every profile that has an attachment, because the parser doesn't send the attachment text. And the count in aa-status of unconfined processes that have a profile defined compares profile names with executable paths, so it misses named profiles and globs. If foo is unconfined and you expected otherwise, check two things: a conflict record in the audit log, and whether the profile was loaded before foo started.

Details and sources

Details

  • cat /proc/PID/attr/current or /proc/PID/attr/apparmor/current. The kernel answers current, prev (the label saved by change_hat) and exec (a pending on-exec target) (lsm.c:835-840).
  • The text is the label with its mode, foo (enforce), or unconfined (procattr.c:52-54).
  • ps -Z prints the same label per process; the aa-exec man page shows firefox//&unconfined (unconfined) in its LABEL column (aa-exec.pod:114-118).
  • aa-status reads current for every process with aa_getprocattr(pid, "current", &profile, &mode) (aa_status.c:427).
  • Known limitation: the line N processes are unconfined but have a profile defined. (aa_status.c:763) compares profile names with the path of the executable, strcmp(profiles[i].name, real_exe) (aa_status.c:468-474). It misses named profiles and glob attachments.
  • /sys/kernel/security/apparmor/policy/profiles/NAME.N/attach (apparmorfs.c:2050-2051) prints <unknown> for a profile with an attachment (apparmorfs.c:1364-1367), because the parser does not send the attachment text.
  • For a tie: search the log for info="conflicting profile attachments"; under px only the kernel log has it (dmesg, journalctl -k).
  • From C: int aa_gettaskcon(pid_t target, char **label, char **mode);.

16 Where to go from here

ROADS attachment score, highest wins, tie = no winner the profile head syn-profile-name syn-xattrs syn-flags-other syn-alias syn-builtin-variables exec rules syn-exec-modes syn-named-transitions how it is built and run re-pipeline k-exec namespaces stacking each namespace has its own search px -> &name: the attached profile plus name
The attachment topic in the centre with roads to the profile head topics, the exec rule topics, the compiler pipeline and kernel exec hook, and the namespaces and stacking decks.

Next: the profile head (syn-profile-name, syn-xattrs), exec rules (syn-exec-modes, syn-named-transitions), the kernel's exec hook (k-exec), then namespaces and stacking.

That's attachment: a score for each candidate, the highest wins, a tie means no winner, and what follows depends on who called exec. From here, the profile head topics cover names, xattrs, flags, aliases and variables one at a time. The exec mode topics cover px, cx and their fallbacks. If you want the machinery, follow a pattern through the compiler, or the exec hook in the kernel. And this deck's two neighbours go further: namespaces give each container its own set of candidates, and stacking lets an exec add a second profile to the one that attaches.

Details and sources

Details

  • The rule in one line, by the kernel code: each candidate gets a count from the left match of the executed path; the highest count wins; equal counts are decided by the number of matched xattrs; equal on both is a conflict and no profile is returned.
  • What follows a conflict or no match depends on the caller: unconfined stays unconfined, px and cx deny, pix and pux fall back.
  • Tables for all of this (scores, overlaps, outcomes, messages, known discrepancies) are in the reference under this deck.
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). Kernel behaviour was not run on a kernel; rows marked "tested" are asserted by xattrs_profile.sh.

Read more

Kernel behaviour on this page was worked out by reading the code at the commits above. It was not run on a kernel, except where a row says "tested", which means a regression test in the AppArmor tree asserts it.

The profile head

[profile] NAME [ATTACHMENT] [xattrs=(...)] [flags=(...)] { rules }
  • NAME identifies the profile in rules, in /proc/PID/attr/current and in logs. ATTACHMENT is the pattern compared with the path of the executable at exec. The order attachment, xattrs=, flags= is fixed.
  • The keyword profile is required unless the name starts with /.
SpellingNameAttachment
profile foo /usr/bin/foo { }foo/usr/bin/foo
/usr/bin/foo { } or profile /usr/bin/foo { }/usr/bin/foocopied from the name (deprecated spelling)
profile foo { }foonone: not picked by the search at exec
  • A quoted attachment with a space is accepted: profile foo "/usr/bin/my app" { }.
  • For a child profile named with a path, the attachment is the child's own name (the text after the last //).
  • A name that is not a path but contains a glob, such as profile foo* { }, has no attachment variable, yet a pattern is still built from the name. Such a pattern matches no absolute path unless it starts with a wildcard: profile ** { } matches every path.
  • The full syntax of the head is in syn-profile-name.

Scores for /usr/bin/foo

Worked out from the kernel code; not measured on a kernel. The score is the number of leading characters of the executed path that the pattern consumes before the match first returns to a state it was recently in.

AttachmentScoreWhy
/usr/bin/foo12every character is literal
/usr/bin/fo?12? takes one character and does not repeat
/usr/bin/fo*11eleven literals; the * starts repeating at once
/usr/bin/f*10ten literals
/usr/bin/*10nine literals plus the first character the * takes
/usr/**6five literals plus the first character the ** takes
/usr/*/foo6as above; the same pattern scores 10 for /usr/b/foo because a glob that takes exactly one character does not repeat
/**2one literal plus one
  • The score depends on the path that was run, not only on the pattern.
  • The man page apparmor_xattrs(7) says the priority is "determined by the length of the path". The code uses the count above, which agrees with that wording in common cases but not in all.

Overlapping profiles

An unconfined task executes /usr/bin/foo.

Profiles loadedScoresResultBasis
/usr/bin/foo and /usr/bin/*12, 10the exact one, in either load orderderived
/usr/bin/* and /usr/**10, 6/usr/bin/*; for /usr/lib/x/foo only /usr/** matchesderived
/usr/bin/* and /usr/bin/f*10, 10conflict: no profile, the task stays unconfinedderived
two names with the attachment /usr/bin/foo12, 12conflict; the parser rejects duplicate names, not duplicate attachmentsderived
/usr/bin/foo and /usr/bin/foo xattrs=(user.foo=hello)12, 12without the xattr on the file the plain one; with it the one that lists ittested: xattrs_profile.sh "xattrs break path length ties"
DIR/* xattrs=(user.foo=hello) and DIR/filelower, higherthe exact path, with or without the xattrtested: xattrs_profile.sh "longer paths have higher priority than xattrs"
/usr/bin/*, /usr/bin/f* and /usr/bin/foo10, 10, 12the exact one; a higher score clears the tie in any orderderived

The glob tie in row three is what the counting gives. It is recorded as a known discrepancy with what profile authors expect, not as a statement of the intended design.

What happens without a winner

Task's profileExec ruleNo attachment matchesTwo attachments tie
unconfined, or a profile with flags=(unconfined)none neededkeeps its label; no recordkeeps its label; an audit record is forced with info="conflicting profile attachments"
confinedpx / cxEACCES, info="profile transition not found"the same record; the conflict text goes only to the kernel log
confined, complain modepx / cxlearning profile <profile>//null-<path>the same
confinedpix / cixkeeps the current profile, info="ix fallback"keeps the current profile; forced record with info="conflicting profile attachments - ix fallback"
confinedpux / cuxthe namespace's unconfined profile, info="ux fallback"unconfined; info="conflicting profile attachments - ux fallback" is set; record not forced, written only if the rule audits
confinedpx -> name and the name is not loadedas the confined rows above, by fallbacknot applicable
confinedno rule for the pathEACCES, or a learning profile in complain modenot applicable
  • The ix fallback and ux fallback strings are the info value the kernel sets. Whether a record is written for them depends on the rule's auditing.
  • An on-exec request (aa-exec -p NAME, aa_change_onexec()) is tested before any exec rule and overrides it.
  • Exec modes and fallbacks: syn-exec-modes. Named targets: syn-named-transitions.

Known discrepancies:

  • apparmor.d(5) says "If the heuristic can not determine a winner between multiple matches the exec will be denied." In the code that holds only for px and cx without a fallback.
  • Under px the audit record cannot tell a tie from a missing profile. The kernel log can, in a rate-limited line: AppArmor: profile_transition (from profile launcher) audit info "conflicting profile attachments" dropped on missing transition. The code comments acknowledge the limitation.

xattrs conditions

  • Forms: xattrs=(name=value ...); a bare name means any value. Values are globs.
  • Every listed xattr is required. A file with extra, unlisted xattrs still matches (tested: xattrs_profile.sh).
  • Order of comparison: the path score first; among equal scores the profile with more matched xattrs wins; equal on both is a conflict.
  • Binary values such as security.ima cannot be matched reliably.
  • Hats cannot use xattrs=.
  • Features needed: domain/attach_conditions/xattr in both the kernel and the profile's ABI, and policy/outofband in the kernel. The profile file needs abi <abi/3.0>, or newer: a file without an abi rule gets the parser's default ABI, which has no xattr attachment. If a feature is missing the parser drops the condition (warning only with --warn=rule-not-enforced) and loads the profile, which then attaches by path alone and is broader than written.
  • profile foo xattrs=(user.a=b) { } is accepted; with no attachment, its pattern is the string foo, which no absolute path matches.
  • Every form: syn-xattrs.

Disconnected and deleted executables

When the kernel cannot build an absolute path for the executable, the exec of a confined task fails and the record carries one of:

infoWhen
Failed name lookup - disconnected paththe file is on a mount outside the task's mount namespace, or on an internal mount
Failed name lookup - deleted entrythe file was deleted and the profile does not mediate deleted files
Failed name lookup - name too longthe path does not fit the buffer
Failed name lookupany other naming error
  • flags=(attach_disconnected) makes a disconnected name absolute; flags=(attach_disconnected.path=/prefix) also puts the prefix in front. The prefix must begin with /.
  • The flag that counts is on the profile confining the task that calls execve, because that profile's settings build the name. It is not a property of the profile that might attach. Its name refers to attaching the path to a root.
  • An unconfined task keeps its label on a naming error; no profile attaches, whatever its attachment says (derived).
  • With attach_disconnected.path=/dis, a disconnected usr/bin/foo is looked up as /dis/usr/bin/foo in the current profile's exec rules and, for px, in the search (regression test: attach_disconnected.sh).
  • The other flags: syn-flags-other.

Aliases and variables

  • alias /usr/ -> /opt/x/, adds /opt/x/bin/foo as a second attachment of profile foo /usr/bin/foo. The original still matches.
  • The alias test is a prefix test on the pattern text, not on matched paths: an attachment /us*/bin/foo is not aliased by /usr/. See syn-alias.
  • @{exec_path} and @{attach_path} both expand to the attachment pattern, globs included, not to the path that was executed. profile bin /usr/bin/* { @{exec_path} r, } grants read on everything /usr/bin/* matches.
  • The variable holds only the attachment text; an alias still rewrites the resulting rule like any other file rule. With alias /usr/ -> /opt/x/,, @{exec_path} r, in profile foo /usr/bin/foo is compiled as /usr/bin/foo r, and /opt/x/bin/foo r,. Unlike @{profile_name} their value is not escaped.
  • Without an attachment they are undefined: profile foo { @{attach_path} r, } fails with Failed to find declaration for: @{attach_path} (the message names the variable that was used). A child profile without an attachment does not inherit the parent's value. They cannot be used in the attachment itself.
  • apparmor.d(5) describes @{exec_path} as possibly a kernel variable; at this commit the parser substitutes the attachment text. See syn-builtin-variables.

Looking at the result

WhereWhat it shows
/proc/PID/attr/current, /proc/PID/attr/apparmor/currentlabel (mode), for example foo (enforce), or unconfined
/proc/PID/attr/execa pending on-exec target
/proc/PID/attr/prevthe label saved by change_hat
ps -Zthe label per process
aa-statusprocesses per profile and mode, read from current
/sys/kernel/security/apparmor/profilesevery loaded profile with its mode
/sys/kernel/security/apparmor/policy/profiles/<name>/attach<unknown> for a profile with an attachment, the profile name otherwise; the parser does not send the attachment text
  • Known limitation: the aa-status count "processes are unconfined but have a profile defined" compares profile names with executable paths, so it finds only path-named profiles without globs.
  • A profile loaded after a process started does not attach to it: attachment is decided only at exec.
  • No sample of the conflict record exists in the trees; only its operation="exec", info= and name= fields are certain.

Parser errors and warnings

MessageWhen
Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'.a name without the profile keyword that is not a path
Profile attachment must begin with a '/' or variable.the attachment is neither a path nor a variable
syntax error, unexpected TOK_CONDLISTID, expecting TOK_OPENflags= written before xattrs=
profile id: invalid conditional group peer=()peer=(...) after the attachment; any other name gives syntax error, unexpected TOK_CONDID, expecting TOK_OPEN
hat profiles can't use xattrs matchesxattrs= on a hat
The use of file paths as profile names is deprecated. See man apparmor.d for more informationa path as the profile name; warning class deprecated, shown only with --warn=deprecated
xattr attachment conditional ignoredwarning, shown only with --warn=rule-not-enforced or --warn=all: the kernel or the profile's ABI lacks xattr attachment (a file with no abi rule is in that case); the profile loads without the condition
attach_disconnected path must begin with a /attach_disconnected.path= with a relative path
Failed to find declaration for: @{attach_path}@{attach_path} in a profile without an attachment (@{exec_path} in the message when that variable was used)
Invalid profile name 'NAME' - bad regular expressionthe attachment or name is not a valid pattern

Kernel messages

TextWhereMeaning
conflicting profile attachmentsaudit info=two best matches tied; unconfined exec
conflicting profile attachments - ix fallbackaudit info=tie under pix / cix; the task kept its profile
conflicting profile attachments - ux fallbackaudit info=tie under pux / cux; record not forced, written only if the rule audits
profile transition not foundaudit info=px / cx found no profile, or found a tie
ix fallback, ux fallbackaudit info=no match; the fallback was used
no new privsaudit info=, error EPERMthe new label is not a subset under no-new-privs
AppArmor: profile_transition (from profile P) audit info "..." dropped on missing transitionkernel log, rate-limitedthe info text replaced by profile transition not found
AppArmor: find_attach (from profile P) audit info "..." droppedkernel log, rate-limitedan earlier info text overwritten during a fallback

for AppArmor developers

Code map

Parser, in call order:

FunctionWhereRole
profile_baseparser/parser_yacc.y:391-459$1 name, $2 attachment, condition list, flags
process_profile_variablesparser/parser_variable.c:137-178expands variables; copies a path name into prof->attachment (:58-78); defines @{attach_path} and @{exec_path}
replace_profile_aliasesparser/parser_alias.c:200-208process_name (:159-191) pushes alternates on prof->altnames
process_profile_name_xmatchparser/parser_regex.c:478-623one AA_MAY_EXEC rule per name, xattr tail (:548-607), create_dfablob; no DFA only for a Basic pattern with no altname, attachment or xattrs (:511)
min_match_lenparser/libapparmor_re/expr-tree.h:343, aare_rules.cc:162-177the value written as xmatch_len
sd_serialize_profileparser/parser_interface.c:495-501writes the aadfa blob and the u32 xmatch_len after the name; "xattrs" at :458-478

Kernel:

FunctionWhereRole
apparmor_bprm_creds_for_execlinux:security/apparmor/domain.c:985-1105the exec hook; on-exec first, else one profile_transition per profile of the label
profile_transitiondomain.c:665-796names the path with the current profile's path flags; find_attach if unconfined, else the exec rule and x_to_label
find_attachdomain.c:394-506the search: candidate, candidate_len, candidate_xattrs, conflict
aa_dfa_leftmatch, is_looplinux:security/apparmor/match.c:816-824, 719-739the count, with a history of WB_HISTORY_SIZE (32) states
aa_xattrs_matchdomain.c:313-375number of matched xattrs or a negative error; runs outside the RCU read lock
x_to_label, x_table_lookupdomain.c:574-663, 523-559AA_X_NAME searches (children with AA_X_CHILD), AA_X_TABLE looks up by name, then the ix / ux fallbacks
aa_path_namelinux:security/apparmor/path.c:201-221builds the name and sets the Failed name lookup strings
unpack_pdb into struct aa_attachmentlinux:security/apparmor/policy_unpack.c:1174-1196, include/policy.h:213-219xmatch, xmatch_len, xattrs[]
  • Callers of find_attach: profile_transition with profile->ns->base.profiles (domain.c:698-699) and x_to_label with profile->base.profiles or ns->base.profiles (:603-611). Profiles are added at the list head (policy.c:164), so the newest is visited first.
  • A profile without an xmatch DFA matches only by strcmp(profile->base.name, name) and then wins at once (domain.c:485-492). With the current parser every profile that has an attachment has a DFA, so this branch is for blobs from older parsers.
  • The walk drops the RCU lock to read xattrs and restarts if the namespace revision changed (domain.c:443-455).
  • The parser does not write the optional "attach" string (policy_unpack.c:1172), which is why apparmorfs prints <unknown> (apparmorfs.c:1358-1368).

for AppArmor developers

Known discrepancies

These are on the AppArmor bug sweep list; none is presented as intended design.

  • xmatch_len stops at the first *, **, ? or [^x]. Observed with apparmor_parser 6.0.0~alpha2 (836052d21): /usr/bin/?oo 10, /usr/bin/[^a]oo 10, /usr/bin/[ab]oo 12, /usr/bin/*foo 9. The cause is NotCharSetNode::contains_oob() (parser/libapparmor_re/expr-tree.h:746-754), which reads as inverted next to its comment.
  • find_attach stores candidate_len = max(count, attach->xmatch_len) (domain.c:481) but compares later profiles by their raw count (:439-440, :469). With the lengths the parser emits today xmatch_len does not exceed the count of a matching path, so the result does not change; the asymmetry is latent.
  • The kernel-doc of find_attach (domain.c:385-388) says exact matches are preferred and then the greatest xmatch_len. The code prefers the greatest left-match count.
  • The forced audit record for conflicting profile attachments - ux fallback sits behind a proxy comparison (domain.c:730-737) that a ux fallback does not appear to satisfy; not confirmed by a run.
  • The header comment of find_attach still calls it the search "for unconfined processes" (domain.c:378); px and cx use it too.

Roads from here

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

PREAMBLE AND REUSE

PROFILE HEAD

IN THE KERNEL

THE DFA ENGINE · libapparmor_re