Extended attribute conditions

attach by extended attribute for application developers for security researchers

The xattrs part of the profile head. A list of extended attributes that the executable must carry for the profile to attach. Every listed attribute is required and values are patterns. Without kernel and policy support the parser ignores the condition and the profile attaches by path alone.

On the map: profile head

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

01 The same path, but only the marked file

XATTRS CONDITIONS file /usr/bin/demo profile demo /usr/bin/demo xattrs=(user.demo=trusted) { profile demo no mark: not attached $ setfattr -n user.demo -v trusted /usr/bin/demo user.demo="trusted" marked: attached demo label: demo (enforce) the condition is part of the head, between the path and the flags
The file /usr/bin/demo and the profile demo with an xattrs condition: without the attribute the profile is not attached; after setfattr stores user.demo=trusted on the file, the profile attaches to the program.

xattrs=(user.demo=trusted) adds a condition to the attachment: the executable must have the extended attribute user.demo with the value trusted. Set it with setfattr -n user.demo -v trusted /usr/bin/demo.

A path tells you where a file is, not whether it's the file you meant. Suppose you want demo's profile only on the build you've approved. Extended attributes let you mark a file: a small name and value that the filesystem stores with it. An xattrs condition in the profile head says: attach only if the executable carries this mark. Same path, no mark, and the profile stays out of it. Set the attribute with setfattr, start demo again, and the profile attaches. This deck covers how to write the condition, what matching means, and the one way it can silently disappear.

Details and sources

Details

  • The manual: "AppArmor profiles can conditionally match files based on the presence and value of extended attributes in addition to file path" (apparmor_xattrs.pod:33-44).
  • Setting and reading the mark, from the same page: setfattr -n 'security.apparmor' -v 'trusted' /usr/bin/example-tool and getfattr --absolute-names -d -m - /usr/bin/example-tool (apparmor_xattrs.pod:53-59). The attribute name and value are arbitrary.
  • The kernel, read from the source and not run: the attributes are read at exec, in the hook bprm_creds_for_exec (lsm.c:1862), by aa_xattrs_match() with vfs_getxattr_alloc() on the executable (domain.c:313-370).
  • A kernel says that it can do this with the file /sys/kernel/security/apparmor/features/domain/attach_conditions/xattr (apparmorfs.c:2596-2599, apparmorfs.c:2610).
  • The AppArmor regression test asserts the behaviour on the slide: with the path matching and no attributes the task runs unconfined; with both attributes set to the listed values it runs under the profile (xattrs_profile.sh:51-59).

02 A list of name=value after the path

GRAMMAR NAME ATTACHMENT xattrs=( ) + identities=( ) flags=( ) { the profile head xattrs = ( ENTRY ) name = value or name any value, but present trusted "trusted" "stable/*" a pattern, like a path repeat: space, comma or new line between entries one group per head; the group may be empty
Syntax diagram: in the profile head the xattrs group sits after the attachment and before identities and flags; it is the word xattrs, an equals sign and a parenthesised list of entries; an entry is name=value or a bare name; the value is a pattern.

xattrs=( ENTRY ... ) with ENTRY = name=value or name. Values may be quoted and are patterns. One group per head, written after the attachment and before + identities=( ) and flags=( ).

The condition has one seat in the head: after the attachment path, before identities and flags. It's the word xattrs, an equals sign, and a list in parentheses. Each entry is an attribute name, then equals, then the value you expect. You can also write just the name, which means the attribute must exist, whatever it holds. The value can be quoted, and it's a pattern, with the same wildcards as a path. Entries are separated by spaces or commas, and the list can run over several lines.

Details and sources

Details

  • The manual's grammar: ATTACHMENT SPECIFICATION = [ PROFILE_EXEC_COND ] [ PROFILE XATTR CONDS ], PROFILE XATTR CONDS = [ 'xattrs=' ] '(' comma or white space separated list of PROFILE XATTR ')', PROFILE XATTR = extended attribute name '=' XATTR VALUE FILEGLOB (apparmor.d.pod:141-149).
  • The parser differs from that text in two ways. The word xattrs= is required: a bare ( ... ) in the head is a flags list. And an entry may be a bare name without =value, as in xattrs=(user.foo=bar myvalue) (ok_13.sd:5).
  • Position: after the attachment path, before + identities=( ) and flags=( ). One group per head.
  • Entries are separated by white space, commas or new lines. A list over several lines is in the manual's own example (apparmor_xattrs.pod:70-77).
  • A value is a word or a quoted string, and it is a pattern in the syntax of a path: "The xattrs value may also contain a path regex" (apparmor_xattrs.pod:46-51).
  • The simplest fixture: /usr/bin/xattrs-test xattrs=(myvalue=foo) { (ok_01.sd:5). xattrs=() with no entries is accepted by the parser built from the AppArmor tree.

Read more

for AppArmor developers for security researchers

In the code

03 One attribute, two attributes, a pattern

EXAMPLES profile demo /usr/bin/demo xattrs=(user.demo=trusted) { user.demo must be "trusted" profile demo /usr/bin/demo xattrs=(user.demo=trusted user.signed) { both must hold; user.signed is a bare name, so it only has to exist profile demo /usr/bin/* xattrs=(user.channel="stable/*") { the value is matched as a pattern; the path may be a glob too the names are whatever the file system stores; AppArmor gives them no meaning $ getfattr -d -m - /usr/bin/demo # file: usr/bin/demo user.demo="trusted" user.signed="yes" illustration, in the format of apparmor_xattrs(7)
Three profile heads: one xattrs entry with an exact value, two entries of which one is a bare name, and a quoted pattern value with a glob path; then getfattr listing the attributes stored on /usr/bin/demo.

xattrs=(user.demo=trusted user.signed) requires both attributes. A bare name requires presence only. A value such as "stable/*" is matched as a pattern. getfattr -d -m - FILE lists a file's attributes.

Three conditions you might write. The plain one: user.demo must be trusted. Add a second entry and both have to hold; here the second is a bare name, so that attribute only has to exist. The third uses a pattern as the value, "stable/*", and a glob as the path, so one profile covers every marked program in the directory. AppArmor attaches no meaning to the attribute names. They are whatever you or your packaging tools store on the file, and getfattr shows you what is there.

Details and sources

Details

  • One attribute: xattrs=(myvalue=foo) (ok_01.sd:5).
  • Two entries, the second a bare name: xattrs=(user.foo=bar myvalue) (ok_13.sd:5). A bare name is compiled as the pattern **: the attribute must exist, with any value.
  • A pattern as the value and a glob as the path, from the manual: profile trusted /usr/bin/* xattrs=(user.trust="tier/*") { (apparmor_xattrs.pod:46-51).
  • The manual: the attribute name and value "are arbitrary, and profiles can match based on the value of any attribute" (apparmor_xattrs.pod:43-44). AppArmor does not write or interpret them.
  • Tools: getfattr -d -m - FILE lists a file's attributes with their values, setfattr -n NAME -v VALUE FILE sets one (apparmor_xattrs.pod:53-59).
  • The regression test also covers values with wildcards, user.foo = hello/* and user.bar = * (xattrs_profile.sh:63-75).

for AppArmor developers for security researchers

In the code

  • if (!xattr_value) xattr_value = "**"; // Default to allowing any value. and the conversion of each value with convert_aaregex_to_pcre (parser_regex.c:556-586).

04 Every listed attribute must match

MATCHING xattrs=(user.demo=trusted user.signed) exec: the path matched, now the attributes file A user.demo="trusted" user.signed="yes" user.note="x" profile demo both match; the extra one is ignored file B user.demo="trusted" profile demo user.signed missing: not a candidate file C user.demo="beta" user.signed="yes" profile demo wrong value: not a candidate not a candidate: the search goes on with the other profiles; nothing is denied by this alone
A condition listing user.demo=trusted and user.signed checked against three files: one with both attributes and an extra one attaches; one missing user.signed and one with a different user.demo value are not candidates.

All listed attributes are required; a missing attribute or a value that does not match removes the profile from the candidates for that exec. Attributes not listed are ignored. How a profile with xattrs ranks against others is in the attachment deck.

What does matching mean exactly? When demo is started and the path fits, the kernel reads each attribute the profile lists from the file, and compares its value with the pattern. All of them have to match. A file with both marks and some unrelated third attribute is fine; extra attributes are ignored. A file with only one of the two marks is not a candidate for this profile. Neither is a file where a value differs. And not a candidate is all it means: the kernel carries on with the other profiles, and if a plainer profile for the same path exists, that one may attach instead.

Details and sources

Details

Kernel statements are read from the kernel source; the rows marked tested are asserted by the AppArmor regression test.

  • For a profile whose path pattern matched, aa_xattrs_match() walks the listed names in order and reads each one from the executable with vfs_getxattr_alloc() (domain.c:333-335).
  • An attribute that is present: its value must end in an accepting state, otherwise the result is -EINVAL (domain.c:336-354). A listed attribute that is missing gives -EINVAL as well, because the parser generates no optional entries (domain.c:357-369).
  • A negative result only skips this profile: "Fail matching if the xattrs don't match", then continue to the next profile in the list (domain.c:456-461).
  • Attributes that the profile does not list are never read.
  • Tested, with a profile listing user.foo=hello and user.bar=bye: no attributes, only one attribute, or a wrong value all leave the task unconfined; both values right attaches the profile; an extra user.spam changes nothing (xattrs_profile.sh:43-59).
  • The function returns the number of attributes matched. Among profiles with an equal path match the one with more matched attributes wins, and an exact tie is a conflict (domain.c:469-475).
  • The manual says priority "is determined by the length of the path, then the number of xattrs specified" (apparmor_xattrs.pod:61-63). The kernel compares a match score that is not always the length of the path; see attachment.

for AppArmor developers for security researchers

In the code

  • Before the value the kernel takes a null transition, "Check the xattr presence before value", then aa_dfa_match_len() over the value and aa_dfa_outofband_transition() to the next entry (domain.c:339-356).
  • The read happens outside the RCU section; the namespace revision is compared afterwards and the search restarts if policy changed (domain.c:442-455).
  • Parser side of the same tail: parser_regex.c:548-607.

05 When the condition is dropped

FEATURE GATE kernel features policy ABI both must include xattr attachment abi <abi/5.0>, profile demo /usr/bin/demo xattrs=(user.demo=trusted) { demo path + user.demo profile demo /usr/bin/demo xattrs=(user.demo=trusted) { the same head, no abi line demo path only Warning from profile demo (demo): xattr attachment conditional ignored $ apparmor_parser --warn=rule-not-enforced -r demo the warning is off by default; this turns it on unmarked /usr/bin/demo attaches to the unmarked file too
Two versions of a profile file run through the parser: with an abi 5.0 line the xattrs condition is kept; without an abi line the condition is ignored with a warning that is off by default, and the profile attaches by path alone, also to an unmarked file.

The condition needs domain/attach_conditions/xattr in both the kernel features and the policy ABI, and policy/outofband in the kernel features. Otherwise the parser prints "xattr attachment conditional ignored" (class rule-not-enforced, off by default) and the profile attaches by path alone. Checked with the source tree's parser, given the tree's abi/5.0 file as the kernel features.

Now the trap. Xattr attachment needs support on two sides: the kernel has to offer it, and the policy's ABI has to include it. If either is missing, the parser doesn't refuse the profile. It drops the condition and builds the attachment from the path alone. I ran both versions through the parser from the source tree. With the abi 5.0 line in the file, the condition is kept. Without an abi line, the parser prints "xattr attachment conditional ignored", and only if that warning class is turned on. What it builds then is a profile that attaches to every file at that path, marked or not. Broader than you wrote, not narrower.

Details and sources

Details

  • The parser keeps the condition only if (features_supports_domain_xattr && kernel_supports_oob); otherwise it warns, frees the list and builds the attachment from the path alone (parser_regex.c:548-553).
  • domain/attach_conditions/xattr must be in both the kernel features and the policy ABI (parser_main.c:1096-1098, parser_main.c:1000-1003).
  • policy/outofband is looked up in the kernel features (parser_main.c:1758-1759). At 836052d21 this is the only place that sets it; no lookup in the policy ABI was found for this one.
  • The warning is Warning from profile NAME (FILE): xattr attachment conditional ignored (parser_regex.c:472-476, parser_common.c:169-187). It is in the class rule-not-enforced, which is off by default: apparmor_parser --warn=rule-not-enforced or --warn=all. It is printed once per profile.
  • The tree's abi/5.0 file lists both features (5.0:11, 5.0:91), so abi <abi/5.0>, in the file keeps the condition.
  • The kernel has both: /sys/kernel/security/apparmor/features/domain/attach_conditions/xattr and /sys/kernel/security/apparmor/features/policy/outofband (apparmorfs.c:2596-2599, apparmorfs.c:2610, apparmorfs.c:2637).
  • Both runs on the slide used the parser built from the AppArmor tree with the tree's abi/5.0 file as the kernel features, no parser.conf, and loaded nothing into a kernel. A system whose parser.conf sets another default policy ABI may differ.

06 From the list to the attachment DFA for AppArmor developers for security researchers

PARSER AND KERNEL scanner xattrs=( -> TOK_CONDLISTID, then LIST_COND_MODE parser_lex.l:420-427, 524-549 grammar: opt_cond_list in profile_base; the group name must be "xattrs" parser_yacc.y:391, 434-439, 1268-1275 process_profile_name_xmatch path pattern oob value 1 oob value 2 parser_regex.c:548-607 one rule per prefix of the list; a bare name is compiled as ** sd_serialize_xattrs struct "xattrs": an array of the names parser_interface.c:458-478, 565 kernel: aa_xattrs_match vfs_getxattr_alloc() per name; DFA walk over the value mismatch = -EINVAL domain.c:313-370 the count of matched xattrs breaks ties (domain.c:469-474) opt_conds prepends: the list is stored in reverse source order; the DFA tail and the name array walk the same list, so they agree (parser_yacc.y:1262-1266)
Pipeline of an xattrs condition: the scanner, the grammar's opt_cond_list, process_profile_name_xmatch building a DFA tail of values separated by out-of-band transitions, sd_serialize_xattrs writing the names, and aa_xattrs_match in the kernel.

TOK_CONDLISTID → cond_list → DFA tail in process_profile_name_xmatch() (out-of-band transitions between values) → xattrs name array → aa_xattrs_match() with vfs_getxattr_alloc().

For developers. The scanner returns a condition list token for the word xattrs followed by equals and a parenthesis, and reads the entries in a mode of its own. The head rule accepts only the name xattrs for this group. In process_profile_name_xmatch the values become a tail on the attachment DFA: after the path pattern comes an out of band transition, then the first value, another out of band transition, the next value. The attribute names travel separately, as an array of strings. In the kernel, aa_xattrs_match fetches each named attribute and continues the DFA walk over its value. The number matched is kept for tie breaking.

Details and sources

for AppArmor developers for security researchers

Details

  • Scanner: (peer|xattrs)/{WS}*={WS}*\( returns TOK_CONDLISTID and enters EXTCONDLIST_MODE (parser_lex.l:420-427); entries are read in LIST_COND_MODE, values in LIST_COND_VAL or LIST_COND_PAREN_VAL (parser_lex.l:508-549).
  • Grammar: cond_list: TOK_CONDLISTID TOK_EQUALS TOK_OPENPAREN opt_conds TOK_CLOSEPAREN (parser_yacc.y:1261-1275); opt_conds prepends, so the stored list is in reverse source order. profile_base rejects any name but xattrs with profile id: invalid conditional group %s=() (parser_yacc.y:434-439).
  • process_profile_name_xmatch(Profile *prof): each value is prefixed with \x00 and converted; the tail has one rule per prefix of the list, x1 | x1 \x-1 x2 | x1 \x-1 x2 \x-1 x3 ..., the separators being out-of-band transitions (parser_regex.c:548-607).
  • A comment describes an optional form, {\x00{value_match},}\x-1; the parser does not generate it (parser_regex.c:576-580).
  • Names: sd_serialize_xattrs writes struct xattrs holding an array of strings, in the order of the same list (parser_interface.c:458-478, called at parser_interface.c:565).
  • The kernel: unpack_xattrs fills profile->attach.xattrs and xattr_count (policy_unpack.c:591-615); failure is failed to unpack profile xattrs (policy_unpack.c:1290-1293).
  • static int aa_xattrs_match(const struct path *path, const struct aa_profile *profile, aa_state_t state): out-of-band transition from the exec match, then per name vfs_getxattr_alloc(), aa_dfa_null_transition(), aa_dfa_match_len(), a check for MAY_EXEC, and another out-of-band transition. Returns the number matched or -EINVAL (domain.c:313-370).
  • The count is the tie-breaker in the attachment search (domain.c:442-475).

07 Wrong seat, wrong group, wrong profile

COMMON MISTAKES profile demo /usr/bin/demo flags=(complain) xattrs=(user.demo=trusted) { syntax error, unexpected TOK_CONDLISTID, expecting TOK_OPEN xattrs come before flags profile demo /usr/bin/demo xattrs=(user.demo=trusted) xattrs=(user.signed) { syntax error, unexpected TOK_CONDLISTID, expecting TOK_OPEN one group, several entries profile demo /usr/bin/demo peer=(user.demo=trusted) { profile id: invalid conditional group peer=() only xattrs fits this seat ^admin xattrs=(user.demo=trusted) { inside profile demo hat profiles can't use xattrs matches no xattrs on a hat a child profile may have an xattrs condition; a hat may not
Four rejected heads with the parser's message: xattrs after flags, two xattrs groups, a peer group in the head, and xattrs on a hat inside a profile.

"syntax error, unexpected TOK_CONDLISTID, expecting TOK_OPEN" means the group is after the flags or written twice. "hat profiles can't use xattrs matches" means the condition is on a hat inside a profile.

Four ways to get it wrong. Write the condition after the flags and you get a syntax error at the word xattrs; its seat is before them. A second xattrs group gives the same error: put all the entries in one list. Use another group name in that seat, peer for instance, and the parser says invalid conditional group. And a hat inside a profile can't carry the condition at all: the parser refuses it, and a note in its source says it isn't clear what such a match should do. A child profile can have one.

Details and sources

Details

  • syntax error, unexpected TOK_CONDLISTID, expecting TOK_OPEN: the group is written after the flags, as in flags=(complain) xattrs=(myvalue=foo) (bad_03.sd:5), or a second xattrs=( ) group follows the first.
  • profile id: invalid conditional group peer=(): a group other than xattrs in that seat (bad_01.sd:5). It is reported one line after the head.
  • hat profiles can't use xattrs matches: the condition is on a hat inside a profile (hats_01.sd:6). This message is not translated.
  • syntax error, unexpected TOK_VALUE, expecting TOK_CONDID or TOK_CLOSEPAREN for name=(a b): more than one value in parentheses.
  • A child profile may carry the condition: profile c /x xattrs=(...) { } inside a profile is accepted (parser 5.0.2).
  • Known discrepancy: a hat written at the top level of a file, ^a xattrs=(user.a=b) { }, is accepted (parser 5.0.2). What the kernel does with it was not determined.
  • The full form of a parser message is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.

for AppArmor developers for security researchers

In the code

08 Who can set the mark, and what a dropped condition gives away for security researchers

ATTACK SURFACE profile demo /usr/bin/demo xattrs=(user.demo=trusted) { who may set the mark user.* anyone who may write the file trusted.* CAP_SYS_ADMIN security.* CAP_SYS_ADMIN linux: fs/xattr.c:125-179 linux: security/commoncap.c:1025-1045 AppArmor in the kernel: no hook for setting an attribute; file rules do not guard the mark condition dropped by the parser demo path only unmarked /usr/bin/demo gets the profile meant for the marked build $ apparmor_parser --warn=rule-not-enforced -r demo off by default
A profile head with an xattrs condition; a table of who may set attributes in the user, trusted and security namespaces; a note that AppArmor in the kernel has no hook for setting attributes; and the dropped condition, after which an unmarked file at the path gets the profile meant for the marked build.

A user.* attribute can be set by anyone with write permission on the file; trusted.* and security.* need CAP_SYS_ADMIN. The kernel has no AppArmor hook for setting attributes. A dropped condition makes the profile attach to unmarked files at the path; --warn=rule-not-enforced shows it. Kernel statements are read from the code, not run.

Look at this condition the way an attacker would. The mark is only as good as the rules for setting it. A user.* attribute can be written by anyone who may write the file. trusted.* and security.* names need CAP_SYS_ADMIN. And the kernel has no AppArmor hook for setting an attribute, so a profile's file rules don't decide who may mark a file. Then the dropped condition. When the parser ignores it, the profile attaches by path alone, so whatever sits at that path gets the profile meant for the marked build, and no default warning says so. Run the parser with that warning turned on.

Details and sources

Details

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

  • Who may set an attribute is decided by the VFS and the capability module, by namespace of the attribute name (fs/xattr.c:125-179):
  • user.*: on a regular file, anyone who passes the ordinary write permission check on the inode;
  • trusted.*: only a task with CAP_SYS_ADMIN;
  • security.*: left to the filesystem and the security modules. The capability module asks for CAP_SYS_ADMIN in the user namespace of the filesystem, except for security.capability (security/commoncap.c:1025-1045).
  • AppArmor registers path and file hooks but none for setting or removing an extended attribute: the word xattr does not occur in its hook file, and the path hooks are listed at lsm.c:1796-1806. A profile's file rules therefore do not decide who may mark a file.
  • The mark is read at exec with vfs_getxattr_alloc() from the file being executed (domain.c:313-370).
  • The parser keeps the condition only when domain/attach_conditions/xattr is in the kernel features and the policy ABI and policy/outofband is in the kernel features; otherwise it frees the list and builds the attachment from the path alone (parser_regex.c:548-553).
  • The warning "xattr attachment conditional ignored" is in the class rule-not-enforced, off by default (parser_common.c:169-187). Seen with the parser built from the AppArmor tree at 836052d21 for a file without an abi line and --warn=all.
  • The manual's own example uses security.apparmor as the attribute name and says the name is arbitrary (apparmor_xattrs.pod:33-57).

09 Around xattrs

ROADS NAME ATTACHMENT xattrs=( ) + identities=( ) flags=( ) { which profile wins? attachment path first, then the number of matched xattrs is the condition kept? syn-abi the line that keeps it alive adm-features does your kernel support it? values, and the exec itself syn-globbing patterns in values k-exec the exec path in the kernel the neighbours in the head syn-profile-name before syn-identities after syn-hats no xattrs on hats syntax-map the whole profile
The profile head with the xattrs slot highlighted and roads to the attachment deck for ranking, syn-abi and adm-features for the feature check, syn-globbing and k-exec, and the neighbouring head decks syn-profile-name, syn-identities, syn-hats and syntax-map.

Ranking and ties: attachment. The feature check: syn-abi, adm-features. Value patterns: syn-globbing. Neighbours in the head: syn-profile-name, syn-identities, syn-hats.

The big question this deck left open is ranking: when two profiles fit the same file, one with xattrs and one without, which wins? The attachment deck answers it: the path counts first, and matched attributes break ties. If the dropped condition worried you, look at the abi deck, and at the features deck for administrators. The pattern syntax of values is the globbing deck's subject, and the exec deck shows where the kernel reads the attributes. The head's other parts, the name before and identities after, have decks of their own, and so do hats.

Details and sources

Details

  • xattrs=( NAME=VALUE ... ) after the attachment path: every listed attribute must be present on the executable and match; a bare name requires presence only.
  • A profile whose attributes do not match is skipped for that exec. Nothing is denied by that; another profile may attach, or none.
  • Without domain/attach_conditions/xattr and policy/outofband the parser drops the condition and the profile attaches by path alone. See it with apparmor_parser --warn=rule-not-enforced.
  • Check a kernel: /sys/kernel/security/apparmor/features/domain/attach_conditions/xattr (apparmorfs.c:2596-2599).
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825).

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the fragment, with the tree's abi/5.0 file as the kernel features and nothing loaded into a kernel; "5.0.2" means the released parser 5.0.2 was run; "code" means the kernel or parser source was read, not run; "tested" means a regression test in the AppArmor tree asserts it.

Grammar

HEAD:    [profile] NAME [ATTACHMENT] [XATTRS] [+ identities=( ... )] [flags=( ... )] {
XATTRS:  'xattrs' '=' '(' { ENTRY [','] } ')'
ENTRY:   NAME | NAME '=' VALUE | NAME '=' '(' VALUE ')'
  • VALUE is a word or a quoted string. It is a pattern in the same syntax as a path: see syn-globbing.
  • A bare NAME is compiled as the pattern **: the attribute must be present, with any value.
  • Position: after the attachment, before + identities=( ) and flags=( ). One group per head.
  • Entries are separated by white space, commas or new lines; the list may span several lines.
  • xattrs=() with no entries is accepted (tree).
  • A head without an attachment may carry the group: profile a xattrs=(user.a=b) { } is accepted (tree). What such a profile matches is in attachment.

Keywords

TokenMeaning
xattrsthe only group name accepted in this position of the head
=the only comparison; name in (...) is not accepted
white space, ,, new lineseparators between entries

Matching

At exec, for a profile whose path pattern matched, the kernel reads each listed attribute from the executable and matches its value against the pattern (code; the rows marked tested are asserted by tests/regression/apparmor/xattrs_profile.sh).

The file hasResultBasis
every listed attribute, each value matchingthe profile is a candidatetested
one listed attribute missingnot a candidatetested
one listed attribute with a value that does not matchnot a candidatetested
attributes that the profile does not listignoredtested
an attribute listed as a bare name, with any valuematchescode
  • "Not a candidate" removes this profile from the search for this exec. It denies nothing by itself; another profile may attach, or none.
  • Ranking: the path match is compared first; among equal path matches the profile with more matched attributes wins. See attachment.

Feature gating

NeedsWhereIf missing
domain/attach_conditions/xattrthe kernel features and the policy ABIthe condition is ignored
policy/outofbandthe kernel featuresthe condition is ignored
  • When the condition is ignored the parser builds the attachment from the path alone. The profile then attaches to every file its path matches, with or without the attributes: broader than written.
  • The warning is Warning from profile NAME (FILE): xattr attachment conditional ignored. It belongs to the class rule-not-enforced, which is off by default (--warn=rule-not-enforced or --warn=all turns it on), and is printed once per profile.
  • Run with the tree's parser: with abi <abi/5.0>, in the file the condition is kept and no warning is printed; without an abi line the warning above is printed. The runs used no parser.conf; a system whose parser.conf sets another default policy ABI may differ.
  • Mainline Linux 7.4 advertises both features (code).
  • The abi rule: syn-abi. Checking a kernel: adm-features.

Where the condition is allowed

WhereAllowedBasis
a top-level profileyestree
a child profile (profile c /x xattrs=(...) { } inside a profile)yestree
a hat inside a profile (^hat or hat)no: hat profiles can't use xattrs matchestree
a hat written at the top level of a fileaccepted by the parsertree; known discrepancy, see below

Hats: syn-hats.

Errors and warnings

MessageCause
syntax error, unexpected TOK_CONDLISTID, expecting TOK_OPENthe group is written after flags=( ), or a second xattrs=( ) group follows the first
profile id: invalid conditional group NAME=()a group other than xattrs in the head, such as peer=( ); reported one line after the head
hat profiles can't use xattrs matchesthe condition is on a hat inside a profile; this message is not translated
syntax error, unexpected TOK_VALUE, expecting TOK_CONDID or TOK_CLOSEPARENname=(a b): more than one value in parentheses
Lexer found unexpected character: '(' (0x28) in state: LIST_COND_MODEname in (b)
Warning from profile NAME (FILE): xattr attachment conditional ignoreda required feature is missing; see Feature gating
kernel: failed to unpack profile xattrsthe kernel could not read the list of names from the loaded policy (code)

Known discrepancies

  • A hat written at the top level of a file, ^a xattrs=(user.a=b) { } or hat a xattrs=(user.a=b) { }, is accepted, while the same line inside a profile is rejected. What the kernel does with such a hat was not determined.
  • apparmor_xattrs(7) says the priority of a profile "is determined by the length of the path, then the number of xattrs specified". The kernel compares a match score that is not always the length of the path; see attachment.

for AppArmor developers for security researchers

Code map

StepWhere
xattrs=( returns TOK_CONDLISTID; entries read in LIST_COND_MODE, commas skippedparser/parser_lex.l:420-427, 508-549
opt_cond_list in profile_base; only the name xattrs acceptedparser/parser_yacc.y:391, 434-439
entries: bare name, name=value; cond_listparser/parser_yacc.y:1196-1217, 1261-1275
hat checkparser/parser_yacc.y:490-504
feature test, warningparser/parser_regex.c:472-476, 549-553; parser/parser_main.c:1096-1098, 1758-1759; parser/parser_common.c:169-187
DFA tail in process_profile_name_xmatch(): one rule per prefix of the list, out-of-band transition between values, bare name as **parser/parser_regex.c:462-469, 548-607
names written as struct xattrs, an array of stringsparser/parser_interface.c:458-478, 565
kernel unpacks the nameslinux:security/apparmor/policy_unpack.c:591-615, 1290-1293
aa_xattrs_match(): vfs_getxattr_alloc() per name, DFA walk over the value, mismatch returns -EINVALlinux:security/apparmor/domain.c:313-370
count of matched attributes as tie-breakerlinux:security/apparmor/domain.c:442-474
kernel feature fileslinux:security/apparmor/apparmorfs.c:2596-2599, 2610, 2637
  • opt_conds prepends each entry (parser/parser_yacc.y:1262-1266), so the stored list is in reverse source order. The DFA tail and the name array are built by walking the same list, so they agree.
  • A parser comment describes an optional-attribute form; the parser does not generate it (parser/parser_regex.c:576-585).
  • Man page: parser/apparmor_xattrs.pod. Regression test: tests/regression/apparmor/xattrs_profile.sh. Parser fixtures: parser/tst/simple_tests/xattrs/.

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

PREAMBLE AND REUSE

PROFILE HEAD

PROFILE STRUCTURE

  • Hats — hats cannot carry an xattrs condition

RUNNING THE PARSER

IN THE KERNEL