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
- Profile mode flags — the flags list and the mode word these flags sit beside
01 The switches beside the mode
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
EACCESunless the profile has the connect flag, and the leading/is removed from the name (path.c:48-72). The reason in the log isinfo="Failed name lookup - disconnected path"(path.c:208-212). - With
attach_disconnectedthe 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.
Read more
- apparmor.d(5), Flags, apparmor.d(5), Audit Mode, apparmor.d(5), Misc modes
- AppArmor wiki: profileflags
- Attachment: disconnected paths at exec. Profile modes: the mode word of the same list.
for AppArmor developers for security researchers
In the code
- Every accepted word is a branch of
flagvals::init(profile.h:211-263).
02 Words, pairs and name=value
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=VALUEis one word of the list: no blanks around=.- Either-or pairs:
attach_disconnectedorno_attach_disconnected;chroot_relativeornamespace_relative;chroot_attachorchroot_no_attach;mediate_deletedordelegate_deleted. Writing both sides givesProfile flag X conflicts with Y. ERROR CODEis "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
- apparmor.d(5), Flags
- AppArmor wiki: profileflags
- Profile modes: how the list itself is written.
for AppArmor developers for security researchers
In the code
- The list grammar: parser_yacc.y:600-629.
flagvals::init: bare words withstrcmp, thename=forms withstrncmpon the prefix, each marked "TODO: make this a proper parse" (profile.h:211-263).- Pair conflicts in
flagvals::merge(profile.h:314-329).
03 A path the kernel cannot connect
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 isEACCESand 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 asinfo=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 nameddisconnected(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_disconnectedstates 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.
Read more
for AppArmor developers for security researchers
In the code
attach_disconnectedsetsPATH_ATTACH; the.path=form also storesdisconnected_path(profile.h:231-242).- The string is written without a feature check: "added in 4.13, unfortunately there is no features flag" (parser_interface.c:503-507).
PATH_ATTACHis packed aspath_flags0x4 (parser_interface.c:536-537), the kernel'sPATH_CONNECT_PATH(path.h:20).
04 Three questions before a rule is tried
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_relativethe path is resolved against the task's root directory,current->fs, with__d_path(); otherwise withd_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_attachconnects only whenchroot_relativeis 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
ENOENTunless one of the two deleted flags is set (path.c:160-164). The reason isFailed name lookup - deleted entry(path.c:209-210). - The kernel's flag values:
PATH_CONNECT_PATH0x4,PATH_CHROOT_REL0x8,PATH_CHROOT_NSCONNECT0x10,PATH_DELEGATE_DELETED0x10000,PATH_MEDIATE_DELETED0x20000 (path.h:17-26). - When the loaded profile has no
path_flagsfield at all, the kernel usesPATH_MEDIATE_DELETEDas the default (policy_unpack.c:1246-1252). - The manual documents
mediate_deletedandchroot_relative(apparmor.d.pod:788-789, apparmor.d.pod:809-810).namespace_relative,chroot_attach,chroot_no_attachanddelegate_deletedare 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.
Read more
for AppArmor developers for security researchers
In the code
- Parser bits: profile.h:223-238, defined at parser.h:219-227.
- Packing:
chroot_relative0x8,mediate_deleted0x10000,attach_disconnected0x4,chroot_attach0x10,attach_disconnected.ipc0x20; the field is written only if some path flag was parsed (parser_interface.c:530-545).mediate_deletedis sent as 0x10000, which the kernel namesPATH_DELEGATE_DELETED; the kernel tests both deleted bits together. - Conflicts: profile.h:314-329.
05 Log everything, choose the signal
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 toAUDIT_ALL(policy_unpack.c:1238-1241).- With
AUDIT_ALLevery 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 withapparmor="AUDIT"(audit.c:206-210) and denials that adenyrule had quieted are logged again. - The system-wide switch is
/sys/module/apparmor/parameters/audit(lsm.c:1974-1976) with the valuesnormal,quiet_denied,quiet.allowed,quiet,noquiet,all(audit.c:20-27). kill.signal=NAME: an optional number namedkill; a value outside 1 to 35 fails the load withprofile kill.signal invalid value(policy_unpack.c:1202-1207). The default isSIGKILL(policy.c:412) and the signal is sent when aKILLEDrecord is written (audit.c:221-231).- Names for
kill.signal=are lower case withoutsig:hup,int,quit,term,usr1and the rest of the table at signal.cc:42-78. debug: the kernel marks the profile's label, andAA_DEBUG_LABELmessages are printed for marked labels only, and only when the kernel's debug setting/sys/module/apparmor/parameters/debugselects 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).
Read more
for AppArmor developers for security researchers
In the code
audit = 1,flags |= DEBUG1,signal = find_signal_mapping(...)(profile.h:216-222, profile.h:243-247).killis written only whenfeatures_supports_flag_signal; then structflags{bits, mode, audit} (parser_interface.c:514-528).
06 Accepted, then 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:
interruptibleneedsdomain/interruptible,kill.signal=needsdomain/kill.signal,error=needspolicy/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 theabiline of the file, for exampleabi <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 isWarning 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 withapparmor_parser --warn=rule-not-enforced;--Werror=rule-not-enforcedmakes the parser exit with status 1 instead. - Only the first such warning of a profile is printed.
- The kernel lists
kill.signalanddisconnected.pathunder/sys/kernel/security/apparmor/features/domain/. It has nointerruptiblethere and nopolicy/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.0file as the kernel features, and loaded nothing into a kernel. - A fourth gate has no warning: the path of
attach_disconnected.ipc=PATHis dropped silently withoutdomain/disconnected.ipc(parser_interface.c:509-512).
Read more
07 The flags on the wire for AppArmor developers for security researchers
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_profilewarns about the gated values and clearsINTERRUPTIBLE;signalanderrorstay in the parse data (profile.cc:91-112).- Order written by the serializer (parser_interface.c:503-545): string
disconnected(no feature check), stringdisconnected_ipc, u32kill, u32error(each only when its feature is supported), structflags{u32 bits, u32 mode, u32 audit}, then u32path_flagsonlyif (profile->flags.path). - Flag bits:
HAT1,DEBUG12,DEBUG24,INTERRUPTIBLE8 (profile.h:133-139). - The parser's internal path bits (parser.h:219-227) differ from the packed ones. Packed:
PATH_ATTACH0x4,PATH_CHROOT_REL0x8,PATH_CHROOT_NSATTACH0x10,PATH_IPC_ATTACH0x20,PATH_MEDIATE_DELETED0x10000.PATH_NS_REL,PATH_DELEGATE_DELETED,PATH_NO_ATTACHandPATH_CHROOT_NO_ATTACHpack no bit but still makeflags.pathnon-zero. - The kernel,
unpack_profile(policy_unpack.c:1198-1252): optionaldisconnected, optionalkill(range check 1 toMAXMAPPED_SIG), structflags, optionalpath_flags. It does not readdisconnected_ipcorerror. - The default
PATH_MEDIATE_DELETEDis set only in theelsebranch, whenpath_flagsis absent (policy_unpack.c:1246-1252). A profile with onlynamespace_relativetherefore loads withpath_flags0. - Kernel flag names and values: path.h:17-26.
08 Opposites, capitals and a missing 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 caseHUP.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 /forflags=(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.sdis described as a conflict test, misspellsnamepace_relativeand so fails withInvalid profile flaginstead (flags_bad10.sd:7).
Read more
- apparmor.d(5), Misc modes
- apparmor_parser(8), OPTIONS
- Profile modes: the mistakes of the list itself.
for AppArmor developers for security researchers
In the code
- Messages: unknown signal (profile.h:247), unknown error code (profile.h:251), invalid flag (profile.h:261), conflicts in
flagvals::merge(profile.h:314-370). - The prefix path is checked in
process_variable_in_attach_disconnected, during variable expansion after parsing (parser_variable.c:42-56). find_error_code_mappingusesstrcasecmp(profile.h:115-122).
09 Aliasing, and a default that goes missing for security researchers
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_disconnecteda 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 isdata/report.txtand a real/data/report.txtthen 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=/outsideputs 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_flagsfield 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 withflags=(no_attach_disconnected)contains the stringpath_flags, the binary of the same profile without flags does not. - The kernel sets
PATH_MEDIATE_DELETEDonly 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_DELETEDthemselves (file.c:297-298); exec, link and mount use the profile'spath_flagsalone (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
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=VALUEis 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
| Spelling | What it does | Needs feature | Mainline Linux 7.4 |
|---|---|---|---|
audit | logs every mediated request of the profile, allowed ones too, and logs denials that rules had quieted | none | acted on |
debug | marks the profile for kernel debug messages, printed only when kernel debugging is on | none | acted on |
interruptible | documented as "Enables interrupts for prompt upcall to userspace" | domain/interruptible | not advertised |
kill.signal=NAME | the signal sent when the profile kills a task; does not select kill mode | domain/kill.signal | acted on |
error=ERRNO | documented as changing the error code returned on a denial | policy/profile/error | not advertised |
attach_disconnected | a path that does not connect to the root gets a leading / and is matched | none | acted on |
attach_disconnected.path=PATH | as above, with PATH put in front of the name | none | acted on |
attach_disconnected.ipc | documented as attach_disconnected limited to IPC namespaces | none | not advertised |
attach_disconnected.ipc=PATH | as above, with a prefix path | domain/disconnected.ipc for the path | not advertised |
no_attach_disconnected | states the default: a disconnected path fails name lookup | none | default behaviour |
mediate_deleted | a 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) | none | acted on |
delegate_deleted | the other word of the pair; this parser packs no bit for it | none | see Known discrepancies |
chroot_relative | names files relative to the task's chroot | none | acted on |
namespace_relative | states the default: names relative to the mount namespace root | none | default behaviour |
chroot_attach | with chroot_relative: connects a path outside the chroot but inside the task's mount namespace; no effect alone | none | acted on |
chroot_no_attach | states the default of that pair | none | default behaviour |
- Pairs:
attach_disconnectedorno_attach_disconnected;chroot_relativeornamespace_relative;chroot_attachorchroot_no_attach;mediate_deletedordelegate_deleted. - Deleted files: the test is at linux:security/apparmor/path.c:160-164; file permission checks add
PATH_DELEGATE_DELETEDthemselves (linux:security/apparmor/file.c:297-298, 511); a profile loaded without a path flags word getsPATH_MEDIATE_DELETED(linux:security/apparmor/policy_unpack.c:1246-1252). PATHmust 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,emtandexistsare 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=epermis accepted (5.0.2). - Numbers are not accepted:
error=13is 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).
| Flag | Feature | Warning when dropped | Mainline Linux 7.4 advertises it |
|---|---|---|---|
interruptible | domain/interruptible | flag interruptible not supported. Ignoring | no |
kill.signal=NAME | domain/kill.signal | kill.signal not supported. Ignoring | yes |
error=ERRNO | policy/profile/error | error flag not supported. Ignoring | no |
attach_disconnected.ipc=PATH | domain/disconnected.ipc | no warning | no |
- 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
--Werrorfor that class the parser exits with status 1. - Format:
Warning from profile NAME (FILE): MESSAGE. - Tree runs: a file without an
abiline andkill.signal=termprinted "kill.signal not supported. Ignoring"; withabi <abi/5.0>,the flag was kept anderror=EPERMprinted "error flag not supported. Ignoring". - What your kernel lists: adm-features.
Errors
| Message | Cause |
|---|---|
Invalid profile flag: %s. | a word that is neither a mode nor a value of this page |
Profile flag chroot_relative conflicts with namespace_relative | both words of the pair |
Profile flag mediate_deleted conflicts with delegate_deleted | both words of the pair |
Profile flag attach_disconnected conflicts with no_attach_disconnected | both words of the pair |
Profile flag attach_disconnected.ipc conflicts with no_attach_disconnected | the ipc form with the negative word |
Profile flag chroot_attach conflicts with chroot_no_attach | both 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:
| Message | Where it appears |
|---|---|
Failed name lookup - disconnected path | info= of a log line: the path does not connect and the flag is absent |
Failed name lookup - deleted entry | info= of a log line: a deleted file could not be named |
profile kill.signal invalid value | at 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_deletedis sent as the bit that mainline Linux 7.4 namesPATH_DELEGATE_DELETED. The kernel's code tests both deleted bits together, so the result is the same today.kill.signal=acceptsrtmin+N,emtandexists, and sends AppArmor's own signal numbering. The kernel's code refuses values above 35 at load, sokill.signal=rtmin+1compiles 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 ofattach_disconnected.ipc=PATHis 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. debugwas 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.
| Spelling | Parser state (parser/profile.h) | Packed | |
|---|---|---|---|
audit | audit = 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=NAME | signal = N (243-247) | u32 named kill, if supported | |
error=ERRNO | error = N (248-251) | u32 named error, if supported | |
attach_disconnected | `path \ | = PATH_ATTACH` (231-232) | path_flags 0x4 |
attach_disconnected.path=PATH | PATH_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=PATH | PATH_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-227and differ from the packed values. - Kernel names:
linux:security/apparmor/include/path.h:17-26(PATH_CONNECT_PATH0x4,PATH_CHROOT_REL0x8,PATH_CHROOT_NSCONNECT0x10,PATH_DELEGATE_DELETED0x10000,PATH_MEDIATE_DELETED0x20000). - Parsing and conflicts:
flagvals::initatparser/profile.h:211-263,mergeatparser/profile.h:304-370. - The gate:
Profile::post_parse_profileatparser/profile.cc:91-110warns and clearsINTERRUPTIBLE;killanderrorare left in the parse data and skipped by the serializer when unsupported (parser/parser_interface.c:514-522). Feature lookups atparser/parser_main.c:1111-1122. - Warning plumbing:
common_warn_onceatparser/parser_common.c:169-187; default classes atparser/parser.h:77-78. - Prefix path checks:
parser/parser_variable.c:42-56. - Kernel:
unpack_profileatlinux:security/apparmor/policy_unpack.c:1198-1252;path_flags5.0.2 dump offlags=(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.sdis described as a conflict test but misspellsnamepace_relativeand fails with "Invalid profile flag"; the description offlags_bad13.sdspeaks of the debug flag while the file testschroot_attach, chroot_no_attach.
Roads from here
START HERE
- The profile language at a glance — back to the whole profile on one page
ATTACHMENT, NAMESPACES, STACKING
- Profile attachment — disconnected paths at exec
PREAMBLE AND REUSE
- The abi rule and the abi files — the abi line that decides which flags are kept
PROFILE HEAD
- Profile mode flags — the mode values of the same list
- Extended attribute conditions — another head part that depends on a kernel feature
QUALIFIERS
- The audit qualifier — audit on single rules instead of the whole profile
RUNNING THE PARSER
- Kernel features and the policy ABI — what your kernel advertises
- Running apparmor_parser (no slides yet) — the warn options that make dropped flags visible
IN THE KERNEL
- Unpacking and verifying policy (no slides yet) — how the kernel reads the flags of a profile