The other profile flags

attach_disconnected… for application developers for administrators for security researchers

The values of the flags list that are not modes. attach_disconnected and the other flags that change how the kernel names a file. audit and debug. kill.signal and error and interruptible which depend on kernel features and are dropped with an Ignoring warning when the feature is missing.

On the map: profile head

▶ Watch this deck — 10 scenes, ~8 min

Worth seeing first

01 The switches beside the mode

THE OTHER FLAGS profile demo /usr/bin/demo flags=(complain, attach_disconnected) { demo a file handed over by another program data/report.txt no leading / info="Failed name lookup - disconnected path" without the flag: no rule is tried with attach_disconnected /data/report.txt demo's rules sixteen values that are not modes four jobs: path naming, logging, the kill signal, newer kernel features
The head of the demo profile with attach_disconnected highlighted; demo holds a file whose name has no leading slash, which fails name lookup without the flag and becomes /data/report.txt with it.

Besides the mode, flags=( ) holds switches for path naming, logging, the kill signal and a few features of newer kernels. attach_disconnected lets the kernel name a file it cannot connect to the root. The path here is an illustration; the behaviour is read from the kernel code.

Demo's profile has a second word in its flags, next to complain: attach_disconnected. Here's the problem it solves. Another program hands demo an open file, and that file lives on a mount demo can't see. The kernel tries to work out the file's path, so it can try your rules, and comes up with a name that has no beginning. Without the flag, on the kernel, that's a failed name lookup, and it happens before any of your rules is looked at. With the flag, the kernel puts a slash in front and carries on. That's one switch. There are sixteen values in this family, and they do four kinds of job.

Details and sources

Details

All kernel statements are read from the kernel source and were not run.

  • Before a file rule is tried the kernel turns the open file into a path with aa_path_name(). On failure the request is audited with the reason and refused; no rule is consulted (file.c:156-180).
  • A path that does not connect to the expected root fails with EACCES unless the profile has the connect flag, and the leading / is removed from the name (path.c:48-72). The reason in the log is info="Failed name lookup - disconnected path" (path.c:208-212).
  • With attach_disconnected the kernel puts / in front of the name and continues (path.c:62-68).
  • The manual lists these values under "Audit Mode" and "Misc modes" (apparmor.d.pod:772-826) and in the grammar line PROFILE FLAGS (apparmor.d.pod:159-162). The parser accepts sixteen; five of them are missing from the manual: namespace_relative, chroot_attach, chroot_no_attach, delegate_deleted, no_attach_disconnected.
  • The path on the slide is an illustration.

for AppArmor developers for security researchers

In the code

02 Words, pairs and name=value

GRAMMAR flags= ( VALUE ) , same list as the mode, any order path naming: either-or pairs attach_disconnected | no_attach_disconnected chroot_relative | namespace_relative chroot_attach | chroot_no_attach mediate_deleted | delegate_deleted path naming: name=value attach_disconnected.path=PATH attach_disconnected.ipc attach_disconnected.ipc=PATH logging audit debug kill kill.signal=NAME need a kernel feature interruptible error=ERRNO also kept only with the feature: kill.signal=NAME attach_disconnected.ipc=PATH
The flags list as a syntax diagram, and the sixteen values that are not modes sorted into four groups: path naming, logging, kill and values that need a kernel feature.

Sixteen values: audit, debug, interruptible, kill.signal=NAME, error=ERRNO, attach_disconnected, attach_disconnected.path=PATH, attach_disconnected.ipc, attach_disconnected.ipc=PATH, no_attach_disconnected, mediate_deleted, delegate_deleted, chroot_relative, namespace_relative, chroot_attach, chroot_no_attach.

These values live in the same parentheses as the mode, in any order. They come in three shapes. Either-or pairs, where the two words are opposites and writing both is an error: attach_disconnected or no_attach_disconnected, chroot_relative or namespace_relative, and two more. Values with an equals sign and no spaces around it, such as the prefix path you can give to attach_disconnected. And bare words, like audit and debug. Sort them by job and there are four groups: path naming, logging, the kill signal, which is kill.signal=NAME, and a handful that only do something when the kernel has the matching feature.

Details and sources

Details

  • The manual's grammar: PROFILE FLAGS = PROFILE MODE | AUDIT_MODE | 'mediate_deleted' | 'attach_disconnected' | 'attach_disconnected.path='ABS PATH | 'chroot_relative' | 'attach_disconnected.ipc' | 'attach_disconnected.ipc='ABS PATH | 'debug' | 'interruptible' | 'kill.signal='SIGNAL | 'error='ERROR CODE (apparmor.d.pod:157-168).
  • NAME=VALUE is one word of the list: no blanks around =.
  • Either-or pairs: attach_disconnected or no_attach_disconnected; chroot_relative or namespace_relative; chroot_attach or chroot_no_attach; mediate_deleted or delegate_deleted. Writing both sides gives Profile flag X conflicts with Y.
  • ERROR CODE is "case insensitive error code name starting with 'E'" (apparmor.d.pod:164).
  • Fixtures: flags=(audit, attach_disconnected) (flags_ok5.sd:14), flags=(attach_disconnected.path=/foo) (flags_ok_disconnected_path1.sd:7), flags=(kill.signal=quit, kill) (flags_ok43.sd:7).
  • Signal names for kill.signal=: signal.cc:42-78.

Read more

for AppArmor developers for security researchers

In the code

03 A path the kernel cannot connect

DISCONNECTED PATHS data/report.txt what the kernel can work out the kernel: name the file without the flag Failed name lookup - disconnected path before any rule is tried flags=(attach_disconnected) /data/report.txt demo's rules the manual: attach_disconnected "is unsafe and can result in aliasing" flags=(attach_disconnected.path=/outside) /outside/data/report.txt demo's rules a rule only for disconnected files /outside/data/** r,
One disconnected name, data/report.txt, in three lanes: without the flag name lookup fails; with attach_disconnected it becomes /data/report.txt; with attach_disconnected.path=/outside it becomes /outside/data/report.txt.

Without the flag a disconnected path fails with "Failed name lookup - disconnected path". attach_disconnected prefixes /. attach_disconnected.path=/outside prefixes /outside, so rules can tell disconnected files apart. no_attach_disconnected states the default. Read from the kernel code, not run.

Three versions of the same moment. The kernel has an open file and needs its path, and the path doesn't reach the root. With no flag, the kernel ends it there: failed name lookup, disconnected path. With attach_disconnected, the kernel puts a slash in front and matches that name against demo's rules. The manual calls that unsafe: it can result in aliasing. The made-up name can be the same as a real file's, so a rule for one also covers the other. The third version helps with that. Give the flag a path, and disconnected files appear under that prefix, where you can write rules just for them.

Details and sources

Details

All kernel statements are read from the kernel source and were not run.

  • disconnect(): without the connect flag the result is EACCES and a name without leading /; with it the kernel prepends / if missing and then the profile's prefix string, if it has one (path.c:48-72).
  • The failure reason is Failed name lookup - disconnected path (path.c:211-212); it is logged as info= and the request is refused before any rule is tried (file.c:169-177).
  • attach_disconnected.path=PATH: the prefix is loaded as an optional string named disconnected (policy_unpack.c:1198-1200). The kernel shows support with /sys/kernel/security/apparmor/features/domain/disconnected.path (apparmorfs.c:2611).
  • The parser expands variables in PATH, filters repeated slashes, requires a leading / and removes trailing slashes (parser_variable.c:42-56).
  • The manual: "WARNING this mode is unsafe and can result in aliasing and access to objects that should not be allowed. Its intent is a debug and policy development tool" (apparmor.d.pod:791-799).
  • no_attach_disconnected states the default.
  • Fixtures: flags_ok5.sd:7, flags_ok_disconnected_path1.sd:7.
  • The same name lookup, with the profile's path flags, runs for the executable at exec (domain.c:684); see attachment.

for AppArmor developers for security researchers

In the code

04 Three questions before a rule is tried

PATH NAMING FLAGS open file rules relative towhich root? namespace_relative default: the root of the mount namespace chroot_relative the task's chroot does it connectto that root? attach_disconnected connect anyway chroot_attach with chroot_relative: connect if inside the mount namespace disconnected path was the filedeleted? mediate_deleted delegate_deleted named only with one of these in effect; normally one is Failed name lookup - deleted entry
A pipeline from an open file through three kernel questions to the rules: relative to which root, does it connect to that root, was the file deleted; under each question the flags that change its answer; a deleted file is named only with one of the two deleted flags in effect.

chroot_relative names files from the task's chroot instead of the mount namespace root. chroot_attach only has an effect together with chroot_relative. A file deleted while still open is named only with mediate_deleted or delegate_deleted in effect; otherwise the kernel's code fails with "Failed name lookup - deleted entry". no_attach_disconnected, namespace_relative and chroot_no_attach only spell out the defaults. Writing both words of a pair is an error.

The flag attach_disconnected is one of a small family. Before any rule is tried, the kernel has to turn an open file into a path, and the code of the kernel answers three questions on the way. First, relative to which root: normally the root of the whole mount namespace, or with chroot_relative, the task's own chroot. Second, does the file connect to that root at all? That's where attach_disconnected and chroot_attach step in. Third, has the file been deleted while it's still open? Then it can only be named when one of two flags is in effect, mediate_deleted or delegate_deleted. Normally one is. Without them, the lookup fails with deleted entry.

Details and sources

Details

All kernel statements are read from the kernel source and were not run.

  • Which root: with chroot_relative the path is resolved against the task's root directory, current->fs, with __d_path(); otherwise with d_absolute_path(), and a mount outside the task's mount namespace counts as not connected (path.c:118-128).
  • Connected or not: handled by disconnect() (path.c:48-72). chroot_attach connects only when chroot_relative is set as well and the mount belongs to the task's mount namespace (path.c:35, path.c:53-55).
  • Deleted while open: an unlinked file that still has an inode fails with ENOENT unless one of the two deleted flags is set (path.c:160-164). The reason is Failed name lookup - deleted entry (path.c:209-210).
  • The kernel's flag values: PATH_CONNECT_PATH 0x4, PATH_CHROOT_REL 0x8, PATH_CHROOT_NSCONNECT 0x10, PATH_DELEGATE_DELETED 0x10000, PATH_MEDIATE_DELETED 0x20000 (path.h:17-26).
  • When the loaded profile has no path_flags field at all, the kernel uses PATH_MEDIATE_DELETED as the default (policy_unpack.c:1246-1252).
  • The manual documents mediate_deleted and chroot_relative (apparmor.d.pod:788-789, apparmor.d.pod:809-810). namespace_relative, chroot_attach, chroot_no_attach and delegate_deleted are accepted by the parser and not in the manual.
  • Pair errors: Profile flag chroot_relative conflicts with namespace_relative, Profile flag mediate_deleted conflicts with delegate_deleted, Profile flag chroot_attach conflicts with chroot_no_attach.

for AppArmor developers for security researchers

In the code

  • Parser bits: profile.h:223-238, defined at parser.h:219-227.
  • Packing: chroot_relative 0x8, mediate_deleted 0x10000, attach_disconnected 0x4, chroot_attach 0x10, attach_disconnected.ipc 0x20; the field is written only if some path flag was parsed (parser_interface.c:530-545). mediate_deleted is sent as 0x10000, which the kernel names PATH_DELEGATE_DELETED; the kernel tests both deleted bits together.
  • Conflicts: profile.h:314-329.

05 Log everything, choose the signal

AUDIT AND KILL.SIGNAL flags=(audit) demo /etc/demo/demo.conf apparmor="AUDIT" operation="open" profile="demo" name="/etc/demo/demo.conf" allowed, and logged anyway denials that rules had silenced are logged too works with any mode flags=(kill, kill.signal=term) demo ~/.ssh/id_rsa kernel SIGTERM instead of SIGKILL term hup int quit ... kill.signal= alone does not select kill mode: the word kill is still needed debug: kernel debug messages for this profile, only when kernel debugging is on
Left: with flags=(audit) an allowed read of demo.conf is logged as AUDIT. Right: with flags=(kill, kill.signal=term) a refused access makes the kernel send SIGTERM instead of SIGKILL.

audit logs every mediated request of the profile (apparmor="AUDIT" for allowed ones) and un-silences quieted denials. kill.signal=term makes kill mode send that signal. debug enables kernel debug output for the profile's label when kernel debugging is on. The log line is assembled from the kernel's audit type names, not captured.

Two flags tune the profile's reaction. Audit turns on logging for everything the profile mediates. Demo reads its own config file, a rule allows it, and normally you hear nothing. With audit in the flags, the code of the kernel logs that read too, marked audit, and denials that a rule had told the kernel to keep quiet about show up again. It works with any mode. Kill dot signal belongs with kill mode: it replaces SIGKILL with the signal you name, in lower case and without the sig. It doesn't switch kill mode on. You still need the word kill.

Details and sources

Details

All kernel statements are read from the kernel source and were not run.

  • audit: sent as the third number of the flags structure; non-zero sets the profile's audit mode to AUDIT_ALL (policy_unpack.c:1238-1241).
  • With AUDIT_ALL every permission is put in the audit set and the quiet set is emptied, on each check (lib.c:374-380). Allowed requests are then logged with apparmor="AUDIT" (audit.c:206-210) and denials that a deny rule had quieted are logged again.
  • The system-wide switch is /sys/module/apparmor/parameters/audit (lsm.c:1974-1976) with the values normal, quiet_denied, quiet.allowed, quiet, noquiet, all (audit.c:20-27).
  • kill.signal=NAME: an optional number named kill; a value outside 1 to 35 fails the load with profile kill.signal invalid value (policy_unpack.c:1202-1207). The default is SIGKILL (policy.c:412) and the signal is sent when a KILLED record is written (audit.c:221-231).
  • Names for kill.signal= are lower case without sig: hup, int, quit, term, usr1 and the rest of the table at signal.cc:42-78.
  • debug: the kernel marks the profile's label, and AA_DEBUG_LABEL messages are printed for marked labels only, and only when the kernel's debug setting /sys/module/apparmor/parameters/debug selects that message group (policy_unpack.c:1218-1221, lib.h:42-51, lsm.c:1969-1971).
  • The manual: audit "causes all actions whether allowed or denied to be logged"; debug "should never appear in policy except when trying to debug kernel or policy problems"; kill.signal "changes the signal that will be sent by AppArmor when in kill mode or a kill rule has been violated" (apparmor.d.pod:779-780, apparmor.d.pod:812-821).
  • Fixtures: flags=(complain audit) (flags_ok16.sd:7), flags=(kill.signal=quit, kill) (flags_ok43.sd:7).

for AppArmor developers for security researchers

In the code

06 Accepted, then dropped

FEATURE GATE kill.signal=term interruptible error=EPERM feature present? kernel features abi <abi/5.0>, the abi line of the file both must list it run 1: no abi line in the file kill.signal=term dropped Warning from profile demo (demo): kill.signal not supported. Ignoring run 2: abi <abi/5.0>, in the file kill.signal=term kept error=EPERM dropped Warning from profile demo (demo): error flag not supported. Ignoring $ apparmor_parser --warn=rule-not-enforced -r demo without this option the flags are dropped silently the kernel: kill.signal yes; interruptible, error: no
Three flags pass a gate that asks whether both the kernel features and the abi line list the feature; without an abi line kill.signal is dropped with an Ignoring warning, with abi 5.0 it is kept and error=EPERM is dropped.

kill.signal=, interruptible and error= need domain/kill.signal, domain/interruptible and policy/profile/error in both the kernel features and the policy ABI. Otherwise: "... not supported. Ignoring", shown only with --warn=rule-not-enforced. Both cases were run with the tree's parser, without loading into a kernel. The kernel advertises only kill.signal of the three.

Some flags need a kernel that knows them. The parser accepts the word, then checks: do the kernel features list it, and does the abi line of the file list it too? If either says no, the flag is dropped and the profile is compiled without it. Here are two runs of the parser from the source tree. A file with no abi line and kill.signal: dropped. Add the abi 5.0 line and it's kept, while error=EPERM is still dropped. The parser does warn, not supported, ignoring, but only if you ask for that class of warning. By default you see nothing.

Details and sources

Details

  • The three gated flags and their features: interruptible needs domain/interruptible, kill.signal= needs domain/kill.signal, error= needs policy/profile/error (parser_main.c:1111-1119).
  • A feature counts only when it is in both lists, the kernel features and the policy ABI: aa_features_supports(a, str) && aa_features_supports(b, str) (parser_main.c:1000-1003). The policy ABI is the abi line of the file, for example abi <abi/5.0>,.
  • The warnings: flag interruptible not supported. Ignoring, kill.signal not supported. Ignoring, error flag not supported. Ignoring (profile.cc:91-110). The printed form is Warning from profile NAME (FILE): MESSAGE (parser_common.c:169-187).
  • They belong to the warning class rule-not-enforced (parser_main.c:281), which is not in the default set (parser.h:77-78). Turn it on with apparmor_parser --warn=rule-not-enforced; --Werror=rule-not-enforced makes the parser exit with status 1 instead.
  • Only the first such warning of a profile is printed.
  • The kernel lists kill.signal and disconnected.path under /sys/kernel/security/apparmor/features/domain/. It has no interruptible there and no policy/profile/error (apparmorfs.c:2600-2647).
  • Both runs on the slide used the parser built from the AppArmor tree at 836052d21 with the tree's abi/5.0 file as the kernel features, and loaded nothing into a kernel.
  • A fourth gate has no warning: the path of attach_disconnected.ipc=PATH is dropped silently without domain/disconnected.ipc (parser_interface.c:509-512).

07 The flags on the wire for AppArmor developers for security researchers

PARSER AND KERNEL flagvals::init, merge profile.h:211-263, 304-370 Profile::post_parse_profile warns "Ignoring"; clears INTERRUPTIBLE profile.cc:91-110 optional fieldsparser_interface.c:503-522 string "disconnected" string "disconnected_ipc" u32 "kill" u32 "error" the last three: only when the feature is supported struct "flags" { u32 bits, u32 mode, u32 audit } bits: HAT 1, DEBUG1 2, INTERRUPTIBLE 8 524-528 u32 "path_flags" optional 530-545 0x4 attach_disconnected 0x8 chroot_relative 0x10 chroot_attach 0x20 attach_disconnected.ipc 0x10000 mediate_deleted unpack_profilelinux: policy_unpack.c:1198-1252 no path_flags field -> path_flags = PATH_MEDIATE_DELETED field present -> value as sent path_flags is written whenever any path flag was parsed, even if no bit is set
The parser functions that handle flag values, the record they produce (four optional fields, the flags struct, an optional path_flags word) and how unpack_profile in the kernel treats a missing path_flags field.

Fields in order: disconnected, disconnected_ipc, kill, error (all optional), struct flags {bits, mode, audit}, optional path_flags. Four values pack no bit: namespace_relative, delegate_deleted, no_attach_disconnected, chroot_no_attach.

On the parser side, the init function of flagvals reads each value, and merge combines them and raises the conflicts. Then post_parse_profile warns about the gated values. The serializer writes up to four optional fields first: the two disconnected strings, and the kill and error numbers, the last three only when their feature is supported. Then the flags struct of three words: bits, mode, audit. Last comes path_flags, written only if some path flag was parsed. Now the kernel side, in the kernel. Its default, PATH_MEDIATE_DELETED, is applied only when that field is absent. So a flag that packs no bit still changes what the kernel ends up with.

Details and sources

for AppArmor developers for security researchers

Details

  • flagvals::init(const char *str) parses one value (profile.h:211-263); flagvals::merge(const flagvals &rhs) combines two and raises the conflicts (profile.h:304-370).
  • Profile::post_parse_profile warns about the gated values and clears INTERRUPTIBLE; signal and error stay in the parse data (profile.cc:91-112).
  • Order written by the serializer (parser_interface.c:503-545): string disconnected (no feature check), string disconnected_ipc, u32 kill, u32 error (each only when its feature is supported), struct flags {u32 bits, u32 mode, u32 audit}, then u32 path_flags only if (profile->flags.path).
  • Flag bits: HAT 1, DEBUG1 2, DEBUG2 4, INTERRUPTIBLE 8 (profile.h:133-139).
  • The parser's internal path bits (parser.h:219-227) differ from the packed ones. Packed: PATH_ATTACH 0x4, PATH_CHROOT_REL 0x8, PATH_CHROOT_NSATTACH 0x10, PATH_IPC_ATTACH 0x20, PATH_MEDIATE_DELETED 0x10000. PATH_NS_REL, PATH_DELEGATE_DELETED, PATH_NO_ATTACH and PATH_CHROOT_NO_ATTACH pack no bit but still make flags.path non-zero.
  • The kernel, unpack_profile (policy_unpack.c:1198-1252): optional disconnected, optional kill (range check 1 to MAXMAPPED_SIG), struct flags, optional path_flags. It does not read disconnected_ipc or error.
  • The default PATH_MEDIATE_DELETED is set only in the else branch, when path_flags is absent (policy_unpack.c:1246-1252). A profile with only namespace_relative therefore loads with path_flags 0.
  • Kernel flag names and values: path.h:17-26.

08 Opposites, capitals and a missing slash

COMMON MISTAKES flags=(attach_disconnected, no_attach_disconnected) Profile flag attach_disconnected conflicts with no_attach_disconnected flags=(kill.signal=HUP) unknown signal specified for kill.signal='HUP' lower case: hup flags=(kill.signal=hup, kill.signal=term) Profile flag kill.signal set to conflicting values: '1' and '15' flags=(error=13) unknown error code specified for error='13' a name: error=EACCES flags=(attach_disconnected.path=outside) attach_disconnected path must begin with a / reported after the profile body, not at the head
Five rejected flags lists with the parser message for each: a pair conflict, an upper-case signal name, two different kill.signal values, a numeric error code and a prefix path without a leading slash.

Pair conflicts read "Profile flag X conflicts with Y". kill.signal= takes lower-case names without sig; error= takes errno names, not numbers. "attach_disconnected path must begin with a /" is reported after the profile body. All five messages come from runs of the tree's parser.

The mistakes here are easy to read once you know the pattern. Two words of the same pair in one list: the parser says which flag conflicts with which. A signal name in capitals: unknown signal, because the names are lower case. The same value flag twice with different values: conflicting values, and for signals it prints the numbers, not the names you wrote. Error wants a name such as EACCES, not a number. And a prefix path without its leading slash is refused, though the line number in that message points past the head of the profile, not at it.

Details and sources

Details

  • Messages, from runs of the parser built from the AppArmor tree at 836052d21. The full form is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.
  • Profile flag attach_disconnected conflicts with no_attach_disconnected (flags_bad12.sd:7).
  • unknown signal specified for kill.signal='foo' (flags_bad68.sd:7); the same for upper case HUP.
  • Profile flag kill.signal set to conflicting values: '%d' and '%d': the numbers are printed, not the names.
  • unknown error code specified for error='13' (flags_bad87.sd:5).
  • attach_disconnected path must begin with a / for flags=(attach_disconnected.path=foo) (flags_bad_disconnected_path1.sd:7). It is reported after the profile body has been read, so the line number is not the head's line.
  • error= takes errno names of the machine that built the parser; the lookup ignores case (apparmor.d.pod:164).
  • Two different prefix paths give Profile flag attach_disconnected set to conflicting values: '%s' and '%s'; the same text is printed for two .ipc= paths.
  • A stale fixture: flags_bad10.sd is described as a conflict test, misspells namepace_relative and so fails with Invalid profile flag instead (flags_bad10.sd:7).

Read more

for AppArmor developers for security researchers

In the code

09 Aliasing, and a default that goes missing for security researchers

ATTACK SURFACE data/report.txt (other mount) /data/report.txt (real file) /data/report.txt flags=(attach_disconnected) /data/** r, one rule, two objects flags=(attach_disconnected.path=/outside) /outside/data/report.txt kept apart flags=(no_attach_disconnected) a flag that only spells out a default parser: writes a path_flags word the kernel, unpack_profile path_flags absent: PATH_MEDIATE_DELETED present: the default is not applied Failed name lookup - deleted entry exec, link and mount on a deleted file the kernel half is read from the code; it has not been run on a kernel
Top: a disconnected file and a real file both end up with the name /data/report.txt and match one rule; the prefix form keeps them apart. Bottom: a head with only no_attach_disconnected makes the parser write a path_flags word, the kernel then skips its default for deleted files, and exec, link and mount on a deleted file fail name lookup.

attach_disconnected gives a disconnected file the name of a path under /, so a rule can match two different objects; attach_disconnected.path= separates them. Any path flag makes the parser write path_flags (run with the tree's parser), and the kernel sets its deleted-file default only when that field is absent (read from the code, not run on a kernel).

Two things for a researcher. First, aliasing. With attach_disconnected, a file from a mount the task can't see gets a name that starts at the root. If a real file has the same name, one rule covers both, and whoever hands demo the descriptor picks the object. The prefix form keeps the two apart. Second, a lost default. Write any path flag, even one that only spells out a default, and the parser sends a path_flags word. The kernel applies its default for deleted files only when that word is absent. By its code, exec, link and mount on a deleted file then fail the name lookup. That hasn't been run on a kernel.

Details and sources

Details

All kernel statements are read from the kernel source and were not run.

  • Aliasing: with attach_disconnected a path that does not connect to the task's root gets a leading / and is matched like any other name (path.c:48-72). A file from another mount whose partial name is data/report.txt and a real /data/report.txt then match the same rules. The manual: "WARNING this mode is unsafe and can result in aliasing and access to objects that should not be allowed" (apparmor.d.pod:791-795).
  • attach_disconnected.path=/outside puts the prefix in front of disconnected names only, so rules under /outside/ cover them and no connected file has such a name unless that directory exists.
  • The lost default: the parser writes the path_flags field whenever any path flag was parsed, including the four that pack no bit (parser_interface.c:530-545). Run with the parser built from the AppArmor tree at 836052d21: the binary of a profile with flags=(no_attach_disconnected) contains the string path_flags, the binary of the same profile without flags does not.
  • The kernel sets PATH_MEDIATE_DELETED only when the field is absent; on the other branch it ORs in a label flag that cannot be that bit (policy_unpack.c:1246-1252).
  • A deleted file that still has an inode cannot be named without one of the deleted bits (path.c:160-164). File permission checks add PATH_DELEGATE_DELETED themselves (file.c:297-298); exec, link and mount use the profile's path_flags alone (domain.c:684, file.c:346-353, mount.c:214-221).
  • The failure is a refusal with info="Failed name lookup - deleted entry", so this reading fails closed. Whether it shows on a running system was not tested; it is recorded as a discrepancy between parser and kernel in the reference below.

10 Around the other flags

ROADS path naming attachmentdisconnected paths at exec logging syn-auditaudit on one rule kill syn-flags-modesthe kill mode need a kernel feature syn-abi adm-features adm-parser--warn options the other flags k-unpackthe kernel reading the flags syn-xattrsanother gated head part syntax-mapthe whole profile
The four groups of flags, each with the decks that continue its subject: attachment, syn-audit, syn-flags-modes, syn-abi with adm-features and adm-parser, and below them k-unpack, syn-xattrs and syntax-map.

Disconnected paths at exec: attachment. Audit per rule: syn-audit. Kill mode: syn-flags-modes. The feature gate: syn-abi, adm-features, adm-parser. The kernel side: k-unpack.

From here the roads follow the four groups. Disconnected paths matter most at exec, and the attachment deck has that story. Audit also exists as a qualifier on single rules, which is usually what you want before you turn it on for a whole profile. The kill signal belongs to kill mode, in the deck on modes. The feature gate is the business of the abi deck, and of the features and parser decks for administrators. And if you want to see the kernel read these fields, the unpack deck is the place.

Details and sources

Details

  • Four groups of values beside the mode: path naming, logging (audit, debug), the kill signal (kill.signal=NAME) and values gated by kernel features (interruptible, kill.signal=, error=).
  • A path flag changes how the kernel names a file before any rule is tried; the name lookup is in path.c:202-212 of the kernel.
  • A gated value that the kernel features or the policy ABI do not list is dropped with a warning that is off by default: apparmor_parser --warn=rule-not-enforced.
  • Kernel behaviour in this deck was read from the source and not run. Parser results come from the parser built from the AppArmor tree.
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825).

Read more

Parser results on this page marked "tree" come from running the parser of the source tree without loading into a kernel; in those runs the "kernel features" were the tree's abi/5.0 file. Results marked "5.0.2" come from the released parser. Kernel behaviour was read from the kernel's code and not run.

Grammar

flags=( VALUE [,] VALUE ... )
VALUE = WORD | NAME=VALUE
  • The list is the one described in syn-flags-modes: the same parentheses hold the mode and the values of this page, in any order.
  • NAME=VALUE is one word: no blanks around the =. Values may be quoted.
  • One mode at most, plus any number of other values.
  • Of each either-or pair at most one side may be written.

Every value

SpellingWhat it doesNeeds featureMainline Linux 7.4
auditlogs every mediated request of the profile, allowed ones too, and logs denials that rules had quietednoneacted on
debugmarks the profile for kernel debug messages, printed only when kernel debugging is onnoneacted on
interruptibledocumented as "Enables interrupts for prompt upcall to userspace"domain/interruptiblenot advertised
kill.signal=NAMEthe signal sent when the profile kills a task; does not select kill modedomain/kill.signalacted on
error=ERRNOdocumented as changing the error code returned on a denialpolicy/profile/errornot advertised
attach_disconnecteda path that does not connect to the root gets a leading / and is matchednoneacted on
attach_disconnected.path=PATHas above, with PATH put in front of the namenoneacted on
attach_disconnected.ipcdocumented as attach_disconnected limited to IPC namespacesnonenot advertised
attach_disconnected.ipc=PATHas above, with a prefix pathdomain/disconnected.ipc for the pathnot advertised
no_attach_disconnectedstates the default: a disconnected path fails name lookupnonedefault behaviour
mediate_deleteda file that was deleted while still open is named and mediated; without either deleted flag mainline Linux 7.4 fails the lookup with "Failed name lookup - deleted entry" for exec, link and mount (file permission checks always name the file)noneacted on
delegate_deletedthe other word of the pair; this parser packs no bit for itnonesee Known discrepancies
chroot_relativenames files relative to the task's chrootnoneacted on
namespace_relativestates the default: names relative to the mount namespace rootnonedefault behaviour
chroot_attachwith chroot_relative: connects a path outside the chroot but inside the task's mount namespace; no effect alonenoneacted on
chroot_no_attachstates the default of that pairnonedefault behaviour
  • Pairs: attach_disconnected or no_attach_disconnected; chroot_relative or namespace_relative; chroot_attach or chroot_no_attach; mediate_deleted or delegate_deleted.
  • Deleted files: the test is at linux:security/apparmor/path.c:160-164; file permission checks add PATH_DELEGATE_DELETED themselves (linux:security/apparmor/file.c:297-298, 511); a profile loaded without a path flags word gets PATH_MEDIATE_DELETED (linux:security/apparmor/policy_unpack.c:1246-1252).
  • PATH must begin with /. Variables are expanded, repeated slashes are filtered and trailing slashes removed.
  • The man page warns that attach_disconnected "is unsafe and can result in aliasing and access to objects that should not be allowed".

kill.signal names

Lower case, without sig:

hup int quit ill trap abrt bus fpe kill usr1 segv usr2 pipe alrm term
stkflt chld cont stop stp tstp ttin ttou urg xcpu xfsz vtalrm prof winch
io poll pwr sys emt exists rtmin+N
  • The kernel's code accepts values 1 to 35 and fails the load otherwise with "profile kill.signal invalid value".
  • rtmin+N, emt and exists are accepted by the parser; see Known discrepancies.

error names

  • The errno names of the machine that built the parser, such as EPERM, EACCES, ENOENT.
  • The lookup ignores case: error=eperm is accepted (5.0.2).
  • Numbers are not accepted: error=13 is an error.

The feature gate

A gated value is kept only when the feature is listed both in the kernel features and in the policy ABI (the abi line of the file, see syn-abi).

FlagFeatureWarning when droppedMainline Linux 7.4 advertises it
interruptibledomain/interruptibleflag interruptible not supported. Ignoringno
kill.signal=NAMEdomain/kill.signalkill.signal not supported. Ignoringyes
error=ERRNOpolicy/profile/errorerror flag not supported. Ignoringno
attach_disconnected.ipc=PATHdomain/disconnected.ipcno warningno
  • The warnings belong to the class rule-not-enforced, which is not in the default set. Ask for it with --warn=rule-not-enforced; see adm-parser.
  • With --Werror for that class the parser exits with status 1.
  • Format: Warning from profile NAME (FILE): MESSAGE.
  • Tree runs: a file without an abi line and kill.signal=term printed "kill.signal not supported. Ignoring"; with abi <abi/5.0>, the flag was kept and error=EPERM printed "error flag not supported. Ignoring".
  • What your kernel lists: adm-features.

Errors

MessageCause
Invalid profile flag: %s.a word that is neither a mode nor a value of this page
Profile flag chroot_relative conflicts with namespace_relativeboth words of the pair
Profile flag mediate_deleted conflicts with delegate_deletedboth words of the pair
Profile flag attach_disconnected conflicts with no_attach_disconnectedboth words of the pair
Profile flag attach_disconnected.ipc conflicts with no_attach_disconnectedthe ipc form with the negative word
Profile flag chroot_attach conflicts with chroot_no_attachboth words of the pair
Profile flag attach_disconnected set to conflicting values: '%s' and '%s'two different prefix paths; also printed for two .ipc= paths
Profile flag kill.signal set to conflicting values: '%d' and '%d'two different signals; the numbers are printed, not the names
Profile flag error set to conflicting values: '%s' and '%s'two different error names
unknown signal specified for kill.signal='%s'a name not in the list, for example upper case HUP
unknown error code specified for error='%s'a number or an unknown name
attach_disconnected path must begin with a /a prefix path without leading /; reported after the profile body, so the line number is not the head's line

Kernel messages, from the code of mainline Linux 7.4:

MessageWhere it appears
Failed name lookup - disconnected pathinfo= of a log line: the path does not connect and the flag is absent
Failed name lookup - deleted entryinfo= of a log line: a deleted file could not be named
profile kill.signal invalid valueat load: a kill value outside 1 to 35

Known discrepancies

Each of these is a known discrepancy between what is written and what the code does, recorded while researching this page. None is a statement of intended design.

  • Only the first "Ignoring" warning of a profile is printed. A profile with two unsupported gated flags reports one of them (reproduced with the tree's parser).
  • Writing any path flag, including the four that pack no bit (namespace_relative, delegate_deleted, no_attach_disconnected, chroot_no_attach), makes the parser send the path flags word, and the kernel's code applies its default handling of deleted files only when that word is absent.
  • mediate_deleted is sent as the bit that mainline Linux 7.4 names PATH_DELEGATE_DELETED. The kernel's code tests both deleted bits together, so the result is the same today.
  • kill.signal= accepts rtmin+N, emt and exists, and sends AppArmor's own signal numbering. The kernel's code refuses values above 35 at load, so kill.signal=rtmin+1 compiles and then cannot load on a kernel with the feature. Not run on a kernel.
  • attach_disconnected.ipc: the bit is sent without a feature check, and the path of attach_disconnected.ipc=PATH is dropped without any warning.
  • The man page apparmor.d(5) omits five accepted values: namespace_relative, chroot_attach, chroot_no_attach, delegate_deleted, no_attach_disconnected.
  • debug was written as 0 by the 5.0.2 parser and is written as a bit by the tree's parser.

for AppArmor developers for security researchers

Packed layout and code map

Fields in the order written by parser/parser_interface.c:503-545: string disconnected, string disconnected_ipc, u32 kill, u32 error (all optional), struct flags {u32 bits, u32 mode, u32 audit}, optional u32 path_flags.

SpellingParser state (parser/profile.h)Packed
auditaudit = 1 (221-222)third u32 of flags = 1
debug`flags \= DEBUG1` (216-218)bit 2 of the first u32 of flags
interruptible`flags \= INTERRUPTIBLE` (252-253)bit 8 of the first u32 of flags
kill.signal=NAMEsignal = N (243-247)u32 named kill, if supported
error=ERRNOerror = N (248-251)u32 named error, if supported
attach_disconnected`path \= PATH_ATTACH` (231-232)path_flags 0x4
attach_disconnected.path=PATHPATH_ATTACH and disconnected_path (239-242)0x4 and string disconnected, no feature check
attach_disconnected.ipc`path \= PATH_IPC_ATTACH` (254-255)path_flags 0x20
attach_disconnected.ipc=PATHPATH_IPC_ATTACH and disconnected_ipc (256-259)0x20, and string disconnected_ipc if supported
no_attach_disconnected`path \= PATH_NO_ATTACH` (233-234)nothing
mediate_deleted`path \= PATH_MEDIATE_DELETED` (227-228)path_flags 0x10000
delegate_deleted`path \= PATH_DELEGATE_DELETED` (229-230)nothing
chroot_relative`path \= PATH_CHROOT_REL` (223-224)path_flags 0x8
namespace_relative`path \= PATH_NS_REL` (225-226)nothing
chroot_attach`path \= PATH_CHROOT_NSATTACH` (235-236)path_flags 0x10
chroot_no_attach`path \= PATH_CHROOT_NO_ATTACH` (237-238)nothing
  • The parser's internal path bits are at parser/parser.h:219-227 and differ from the packed values.
  • Kernel names: linux:security/apparmor/include/path.h:17-26 (PATH_CONNECT_PATH 0x4, PATH_CHROOT_REL 0x8, PATH_CHROOT_NSCONNECT 0x10, PATH_DELEGATE_DELETED 0x10000, PATH_MEDIATE_DELETED 0x20000).
  • Parsing and conflicts: flagvals::init at parser/profile.h:211-263, merge at parser/profile.h:304-370.
  • The gate: Profile::post_parse_profile at parser/profile.cc:91-110 warns and clears INTERRUPTIBLE; kill and error are left in the parse data and skipped by the serializer when unsupported (parser/parser_interface.c:514-522). Feature lookups at parser/parser_main.c:1111-1122.
  • Warning plumbing: common_warn_once at parser/parser_common.c:169-187; default classes at parser/parser.h:77-78.
  • Prefix path checks: parser/parser_variable.c:42-56.
  • Kernel: unpack_profile at linux:security/apparmor/policy_unpack.c:1198-1252; path_flags 5.0.2 dump of flags=(delegate_deleted) has the field with value 0. Naming: linux:security/apparmor/path.c:35, 48-72, 118-128, 160-164, 209-212. Audit and kill: linux:security/apparmor/lib.c:374-380, linux:security/apparmor/audit.c:206-231. Advertised features: linux:security/apparmor/apparmorfs.c:2596-2647.
  • Stale fixtures: flags_bad10.sd is described as a conflict test but misspells namepace_relative and fails with "Invalid profile flag"; the description of flags_bad13.sd speaks of the debug flag while the file tests chroot_attach, chroot_no_attach.

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

PREAMBLE AND REUSE

PROFILE HEAD

QUALIFIERS

RUNNING THE PARSER

IN THE KERNEL