Profile mode flags

enforce, complain, kill… for application developers for administrators for security researchers

The profile modes enforce and complain and kill and unconfined and prompt and default_allow. How to write the flags list and which name the kernel reports for each mode. Complain still refuses what a deny rule denies. Two modes in one list are an error.

On the map: profile head

▶ Watch this deck — 10 scenes, ~8 min

Worth seeing first

Part of journeys

01 What happens when no rule allows it?

PROFILE MODES demo /home/user/.ssh/id_rsa open() no rule allows it profile demo /usr/bin/demo flags=(complain) { the mode decides refuse allow and log refuse and signal one word in the head, six spellings: this deck the keywords, the list, the kernel's names, the surprises
A profile head with the flag complain highlighted; below it demo opens an SSH key that no rule allows, the kernel sits on the access, and three possible outcomes hang under it: refuse, allow and log, refuse and signal.

The mode is a value in the flags=( ) list of the profile head. It decides what happens to an access that the rules neither allow nor deny.

Demo has a bug, and it tries to open your SSH key. Nothing in its profile allows that. What happens next isn't decided by any rule. It's decided by one word in the head of the profile: the mode. On the kernel, the kernel can refuse the access. It can let it through and write it down. Or it can refuse and send the process a signal. You saw the short version at the start of the map. This deck is the full one: every mode keyword, how to write the list it sits in, what the kernel calls each mode, and a few surprises along the way.

Details and sources

Details

  • The mode is one value of the flags=( ) list in the profile head. The six mode words are enforce, complain, kill, unconfined, prompt and default_allow (apparmor.d.pod:157-166).
  • The kernel, read from the source and not run: the mode is applied to the computed permissions on each check by aa_apply_modes_to_perms (lib.c:364-372). Kill mode marks every permission that is not allowed; complain mode marks every permission that is neither allowed nor denied.
  • The record type follows from those marks in aa_select_audit_type (audit.c:143-152). The names that appear in the log as apparmor="..." are AUDIT, ALLOWED, DENIED and KILLED (audit.c:29-38).
  • In kill mode the task is sent the profile's signal after the record is written (audit.c:221-231).
  • The mode of a running task is printed after the profile name, as in demo (complain), in /proc/<pid>/attr/current and /proc/<pid>/attr/apparmor/current (label.c:1563-1571).

02 The flags list and its mode word

GRAMMAR NAME ATTACHMENT xattrs=( ) + identities=( ) flags=( ) { flags= ( VALUE ) optional one or more, separated by spaces or commas enforce complain kill unconfined prompt default_allow the mode words at most one of these none means enforce other values, any number audit, attach_disconnected, ... next deck: syn-flags-other profile demo /usr/bin/demo flags=(complain) { profile demo /usr/bin/demo (complain) { the same thing
Syntax diagram: the flags list is the last slot of the profile head; it is an optional flags= prefix, an opening parenthesis, one or more values and a closing parenthesis; six of the values are mode words, at most one per list; two heads with and without the prefix mean the same.

flags=( VALUE ... ) or ( VALUE ... ), last in the head, one list only, at least one value. Mode values: enforce, complain, kill, unconfined, prompt, default_allow. No mode value means enforce.

The flags are the last thing in the head, just before the brace. It's a list in parentheses, usually written with flags= in front, though the bare parentheses work too. Values are separated by spaces or commas. Six of the possible values are modes: enforce, complain, kill, unconfined, prompt and default_allow. A list may hold one of them, or none, and none means enforce. Everything else you can put in that list is a switch of another kind, and those have the next deck to themselves. Spelling is exact: lower case, underscore and all. So these two heads say the same thing.

Details and sources

Details

  • The manual's grammar: PROFILE FLAG CONDS = [ 'flags=' ] '(' comma or white space separated list of PROFILE FLAGS ')' and PROFILE MODE = 'enforce' | 'complain' | 'kill' | 'default_allow' | 'unconfined' | 'prompt' (apparmor.d.pod:157-166).
  • The list is the last part of the head, directly before {. A head takes one list and the list needs at least one value.
  • Values are separated by white space, commas or both. Parser 5.0.2 also accepts flags=(complain,,audit), flags = ( complain ) and the quoted flags=("complain").
  • Spelling is compared exactly and case matters: complain, not Complain; default_allow with an underscore.
  • A list without a mode word loads as enforce: the number sent to the kernel is 0 both for no mode and for enforce.
  • Fixtures from the parser's tests: flags=(complain) (flags_ok.sd:7), the bare form (audit,debug) (flags_ok19.sd:7), a mode beside another value, flags=(enforce audit) (flags_ok15.sd:7).
  • To check a head without loading anything: apparmor_parser -Q -K FILE (-Q, --skip-kernel-load, -K, --skip-cache).

Read more

for AppArmor developers for security researchers

In the code

03 Six words, five modes

WHAT THE KERNEL REPORTS you write a process shows (nothing) enforce demo (enforce) complain demo (complain) kill demo (kill) unconfined demo (unconfined) default_allow default_allow is loaded exactly like unconfined prompt demo (user) the kernel's name for prompt is "user" $ cat /proc/1234/attr/current where the name is printed (worked out from the code)
Seven spellings on the left, nothing, enforce, complain, kill, unconfined, default_allow and prompt, joined to five reported modes on the right: enforce, complain, kill, unconfined and user. default_allow joins unconfined and prompt joins user.

No mode and enforce load as enforce. default_allow loads as unconfined. prompt loads as the mode the kernel names user. The mode is shown after the profile name, as in demo (complain). The right-hand column is put together from the kernel code, not captured from a running system.

Here's what the kernel makes of each word, by its code. Write nothing, or write enforce, and the profile is in enforce mode; once loaded, the two are the same thing. Complain is complain, kill is kill, unconfined is unconfined. Now the two that surprise people. default_allow isn't a mode of its own in the kernel: this parser loads it exactly as unconfined, and that's the name the kernel has for it. And prompt arrives under a different name: the kernel calls that mode user. So six words, seven if you count silence, and five modes. The name is shown after the profile name, wherever a process's confinement is printed.

Details and sources

Details

  • The kernel reads the mode as a number: 0 enforce, 1 complain, 2 kill, 3 unconfined, 4 user; any other number fails the load with failed to unpack profile flags (policy_unpack.c:1213-1237, constants at policy_unpack.h:36-40).
  • The kernel's names for the five modes: enforce, complain, kill, unconfined, user (policy.c:94-100).
  • Where the name is shown: the label is formatted as NAME (MODE), or :NS:NAME (MODE) with a namespace (label.c:1563-1571). The namespace's own unconfined label is printed without a mode.
  • Reading it: cat /proc/<pid>/attr/current, or from a program int aa_getcon(char **label, char **mode) and int aa_gettaskcon(pid_t target, char **label, char **mode) (apparmor.h:110-111).
  • There is also a system-wide mode, /sys/module/apparmor/parameters/mode, readable and writable by root only, which takes the same five names (lsm.c:1947-1949, lsm.c:2229-2247). A profile behaves as complain, kill or user when its own mode or the system-wide mode says so (policy.h:40-48).
  • The manual on default_allow: such profiles "may be be reported as being in enforce mode or allow mode" (apparmor.d.pod:734-745). With the parser at 836052d21 the kernel's name for it is unconfined.
  • The right-hand column of the slide is put together from this code. It was not captured from a running system.

for AppArmor developers for security researchers

In the code

  • profile_mode_packed rewrites DEFAULT_ALLOW to UNCONFINED and subtracts one; UNSPECIFIED stays 0 (profile.h:48-87).

04 Complain still refuses what you deny

COMPLAIN MODE profile demo /usr/bin/demo flags=(complain) { /etc/demo/** r, deny /proc/sys/** w, demo /etc/demo/demo.conf read allowed by a rule: nothing special demo /home/user/.ssh/id_rsa read apparmor="ALLOWED" no rule: let through and logged demo /proc/sys/kernel/hostname write denied by a rule: still refused complain is "log what is missing", not "allow everything"
A complain-mode profile with one allow rule and one deny rule, and three accesses by demo: a read the rule allows goes through, a read no rule mentions goes through and is logged as ALLOWED, and a write matched by the deny rule is refused.

In complain mode an access that no rule allows or denies is permitted and logged with apparmor="ALLOWED". An access matched by a deny rule is still refused. This is what the kernel code says for a plain deny, and the manual agrees.

Complain mode is how you learn what a program needs: run it, read the log, add rules. But look closely at what it lets through. A read that a rule allows is simply allowed. A read that no rule mentions goes through too, and the kernel logs it as allowed, so you can see what was missing. The third case is the one people get wrong. If the profile has a deny rule, and demo does the denied thing, complain mode doesn't help it: by the code of the kernel the access is refused, just as in enforce. Complain fills in what you left out. It doesn't overrule what you wrote.

Details and sources

Details

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

  • In complain mode the kernel adds to the complain set every permission that is neither allowed nor denied: perms->complain |= ~(perms->allow | perms->deny) (lib.c:369-370). A permission in the deny set is not added, so a deny rule still refuses.
  • For file rules the refusal is decided in aa_audit_file: a plain deny is quieted and returns the error before the complain conversion (file.c:142-149). Whether an audit deny file rule is still refused in complain mode is open (not run): its request is not quieted, reaches aa_audit, and there a complain-mode profile turns any error into ALLOWED (audit.c:206-212).
  • The record is of type ALLOWED only when every refused permission is in the complain set (audit.c:143-152).
  • For an ALLOWED record aa_audit returns complain_error(ad->error) (audit.c:233-234), which turns EPERM and EACCES into success and passes every other error on (audit.h:206-211).
  • The manual: "Complain mode will only convert implicit denials to ALLOWED", and the compiler may strip explicit denials with -O filter-deny (apparmor.d.pod:604-616). It lists further cases that complain mode does not turn into an allow (apparmor.d.pod:618-731); those were not checked against the kernel here.
  • apparmor_parser -C (--Complain) forces complain mode at load time (apparmor_parser.pod:168). For policy ABIs newer than 5 this travels in the policy version word, and the kernel then loads the profile as complain whatever the head says (policy_unpack.c:1224-1225, policy_compat.h:18).
  • The system-wide mode /sys/module/apparmor/parameters/mode set to complain has the same effect on every profile (policy.h:40-48).

05 Kill mode: refuse and signal

KILL MODE profile demo /usr/bin/demo flags=(kill) { demo /home/user/.ssh/id_rsa open() refused what the log line looks like apparmor="KILLED" operation="open" ... profile="demo" name="/home/user/.ssh/id_rsa" ... the kernel SIGKILL by default flags=(kill, kill.signal=term) another signal: see the other flags (syn-flags-other) kill.signal picks the signal; the word kill selects the mode
A profile with flags=(kill); demo opens the SSH key, the access is cut, the log line says KILLED, and the kernel sends SIGKILL back to demo. A second flag, kill.signal, can choose another signal.

flags=(kill): by the kernel code, a refused access is logged with apparmor="KILLED" and the task is sent a signal, SIGKILL by default. kill.signal=NAME chooses another signal; it does not select kill mode by itself. The log line is put together from the kernel's type names, not copied from a log.

Kill mode is enforce with a consequence. Demo reaches for the key, the kernel refuses, and the log line says killed instead of denied. Then, going by the code of the kernel, it sends the process a signal. By default that's SIGKILL, so demo is gone before it can try anything else. This is for programs where one forbidden access means something is badly wrong, and you'd rather lose the process than let it carry on. The signal can be changed with a separate flag, kill.signal, which you'll find in the next deck. That flag picks the signal; it's still the word kill that selects the mode.

Details and sources

Details

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

  • In kill mode every permission that is not allowed is marked: perms->kill = ~perms->allow (lib.c:367-368).
  • A refused request that touches a marked permission gets the record type KILLED (audit.c:147-148); aa_audit also turns a DENIED record of a kill-mode profile into KILLED (audit.c:221-222).
  • After the record is written the kernel calls send_sig_info(profile->signal, SEND_SIG_NOINFO, ...). The target is the task named in the audit data if there is one, otherwise the current task (audit.c:228-231).
  • The signal is SIGKILL unless the policy sets another: profile->signal = SIGKILL when the profile is allocated (policy.c:412).
  • kill.signal=NAME arrives as 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).
  • A kernel says that it supports the flag with the file /sys/kernel/security/apparmor/features/domain/kill.signal (apparmorfs.c:2612).
  • Fixtures: flags=(kill) (flags_ok13.sd:7), flags=(kill, kill.signal=trap) (flags_ok46.sd:7). Signal names are lower case without sig (signal.cc:42-78).
  • The log line on the slide is assembled from the kernel's type names. It was not copied from a log.

06 Unconfined, default_allow and prompt today

ON THE KERNEL flags=(unconfined) demo .ssh/id_rsa demo (unconfined) not checked, not logged the manual: "should only be used for debugging" flags=(default_allow) demo .ssh/id_rsa demo (unconfined) same as the row above: loaded as unconfined the manual describes it differently flags=(prompt) demo kernel .ssh/id_rsa demo (user) user-space agent nobody is asked prompt on the kernel works out to: refused, as in enforce read from the kernel's code; kernels with the prompting patches differ
Three rows with the same access by demo to the SSH key. With flags=(unconfined) it is not checked. With flags=(default_allow) the outcome is the same. With flags=(prompt) no user-space agent is asked and the access is refused.

unconfined: tasks are treated as unconfined. default_allow: loaded as unconfined by this parser, which is not what the manual describes. prompt: the kernel has no code that asks user space, so an access outside the rules works out to refused. All three rows are read from the code, not run. Distribution kernels with prompting behave differently.

Three modes do less than their names promise, at least on the kernel. Unconfined gives the process a profile name and then doesn't check this access; the manual itself says it's for debugging. default_allow sounds like allow by default, but honour my deny rules. With this parser it's loaded as unconfined, full stop, so for an access like this one your rules aren't consulted. And prompt is meant to ask a helper program what to do about an access the rules don't cover. That kernel marks such accesses and then asks nobody. Reading the kernel's code, the access works out to refused, as in enforce.

Details and sources

Details

All three rows are read from the kernel source and of the parser. None was run on a kernel.

  • unconfined: the kernel sets the profile's mode to unconfined and also marks its label as unconfined (policy_unpack.c:1230-1232). The file permission check returns success at once for such a profile: if (profile_unconfined(profile)) return 0; (file.c:263-264, policy.h:316). Which other checks still apply was not determined.
  • default_allow: the parser at 836052d21 sends the same mode number as for unconfined, so everything above applies. The manual describes something else: "similar to unconfined but allows for allow and deny rules, specifying audit, and domain transitions" (apparmor.d.pod:734-745).
  • prompt: the kernel's name is user, commented "modified complain mode to userspace" (policy.h:76). In this mode the permissions outside the rules are marked for prompting: perms->prompt |= ~(perms->allow | perms->deny) (lib.c:371-372).
  • Nothing in security/apparmor/ of the kernel reads that mark to ask user space or to decide; the record type is chosen from the kill and complain marks only, which leaves DENIED (audit.c:143-152).
  • The manual on prompt: "send an up call to userspace ... If userspace does not respond then the access will be denied" (apparmor.d.pod:765-768). That describes kernels that carry the prompting patches.
  • The manual on unconfined: "should not be used under regular deployment but can be useful during debugging" (apparmor.d.pod:747-763).
  • The parser prints no warning for prompt or default_allow on a kernel that does not act on them.

for AppArmor developers for security researchers

In the code

  • profile_mode_packed: "until dominance is fixed use unconfined mode for default_allow" (profile.h:75-87).
  • Profile::post_parse_profile checks features for interruptible, kill.signal and error only; no mode is checked (profile.cc:91-110).

07 How the mode is packed for AppArmor developers for security researchers

PARSER AND KERNEL flagvals::init(str) profile.h:211-220 str_to_mode() over profile_mode_table flagvals::merge profile.h:304-309 two modes: "Profile flag ... conflicts with ..." profile_mode_packed() profile.h:75-87 DEFAULT_ALLOW -> UNCONFINED; none, ENFORCE -> 0 struct "flags" parser_interface.c:524-528 u32 flag bits u32 mode u32 audit unpack_profile() policy_unpack.c:1222-1237 0 APPARMOR_ENFORCE 1 APPARMOR_COMPLAIN 2 APPARMOR_KILL 3 APPARMOR_UNCONFINED + FLAG_UNCONFINED 4 APPARMOR_USER else: "failed to unpack profile flags" no mode is gated on a kernel feature in the parser: prompt goes to any kernel post_parse_profile checks only interruptible, kill.signal, error (profile.cc:91-110) prompt rules + prompt compat mode FLAG: the mode becomes PROMPT (parser_policy.c:161-162)
Pipeline: flagvals::init looks the word up, merge detects two modes, profile_mode_packed maps the enum to a number, the number is the second u32 of the flags struct, and unpack_profile in the kernel maps 0 to 4 onto its five modes.

flagvals::init → merge → profile_mode_packed() → second u32 of struct flags → unpack_profile(): 0 enforce, 1 complain, 2 kill, 3 unconfined, 4 user. With prompt rules and the prompt compatibility mode FLAG, post-processing overwrites the declared mode with PROMPT (parser/parser_policy.c:161-162).

Each word in the list goes through flagvals init, which looks it up in the profile mode table with str_to_mode. Merge combines the values, and raises the conflict error when two modes meet. profile_mode_packed turns the parser's enum into the number for the kernel, and this is where default_allow is rewritten to unconfined, under a comment that says until dominance is fixed. The number is written as the second u32 of the flags struct. In the kernel, unpack_profile tests it: zero to four, and anything else fails the load. None of the modes is checked against kernel features, so prompt is sent to any kernel.

Details and sources

for AppArmor developers for security researchers

Details

  • enum class profile_mode: UNSPECIFIED 0, ENFORCE 1, COMPLAIN 2, KILL 3, UNCONFINED 4, PROMPT 5, DEFAULT_ALLOW 6, CONFLICT 7 (profile.h:48-58). The spellings are in profile_mode_table (profile.cc:30-39).
  • flagvals::init(const char *str) calls str_to_mode first; a word that is a mode sets mode (profile.h:211-220).
  • merge_profile_mode(l, r) returns CONFLICT for two different specified modes (profile.h:66-73); flagvals::merge raises Profile flag '%s' conflicts with '%s' (profile.h:304-309).
  • profile_mode_packed(mode) rewrites DEFAULT_ALLOW to UNCONFINED, then returns the value minus one; UNSPECIFIED gives 0 (profile.h:75-87).
  • The serializer writes struct flags as three u32: flag bits, profile_mode_packed(profile->flags.mode), audit (parser_interface.c:524-528).
  • With prompt rules and the prompt compatibility mode FLAG, post-processing overwrites the declared mode with PROMPT (parser_policy.c:161-162).
  • Force-complain sets the mode in the head only for kernel ABI 5 (parser_yacc.y:443-447); otherwise it is part of ENCODE_VERSION (parser_interface.c:670-671).
  • The kernel, unpack_profile: the second u32 of flags is compared with PACKED_MODE_ENFORCE 0 to PACKED_MODE_USER 4; FORCE_COMPLAIN_FLAG in the version wins over the number; anything else is goto fail (policy_unpack.c:1209-1237, policy_unpack.h:36-40).
  • COMPLAIN_MODE, USER_MODE and KILL_MODE are true for the profile's mode or for the global aa_g_profile_mode (policy.h:40-48).
  • No mode is checked against kernel features (profile.cc:91-110).

08 One mode per list, spelled exactly

COMMON MISTAKES flags=(complain, kill) Profile flag 'complain' conflicts with 'kill' flags=(enforce, complain) Profile flag 'enforce' conflicts with 'complain' writing the default counts as a mode flags=(Complain) Invalid profile flag: Complain. flags=() syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUE flags=(complain) flags=(audit) syntax error, unexpected TOK_FLAGS, expecting TOK_OPEN one list: flags=(complain, audit)
Five wrong flags lists and the parser's message for each: two modes conflict, enforce with complain conflicts, a capitalised mode is an invalid flag, an empty list is a syntax error, and a second list is a syntax error.

"Profile flag 'A' conflicts with 'B'" means two mode words in one list. "Invalid profile flag: X." means an unknown or wrongly capitalised value. A head takes one flags list and the list cannot be empty. All five messages are what the parser built from the tree prints.

Here's what goes wrong in practice. Two modes in one list is an error, and the message names both. That's true even for enforce and complain together, although enforce is what you get by writing nothing: once you write it, it counts. A capital letter or a typo gives invalid profile flag, with the word you wrote. An empty list is a syntax error, so delete the list instead of emptying it. And there's one list per head. If you want complain and audit, they go in the same parentheses.

Details and sources

Details

  • Messages, as printed by 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 'enforce' conflicts with 'complain' for flags=(enforce, complain) (flags_bad30.sd:7); likewise flags=(complain, kill) (flags_bad34.sd:7).
  • Invalid profile flag: Complain. for a wrongly capitalised word; the fixture for an unknown word is flags=(capability) (flags_bad2.sd:7).
  • syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUE for flags=() (flags_bad16.sd:6).
  • syntax error, unexpected TOK_FLAGS, expecting TOK_OPEN for a second list, flags=(complain) flags=(audit).
  • flags=(default_allow, unconfined) is a conflict too, although both load as the same mode (flags_bad72.sd:6).
  • A repeated mode, flags=(complain complain), is accepted (parser 5.0.2).
  • The kernel has two load-time messages of its own: profile missing flags and failed to unpack profile flags, the second also for a mode number it does not know (policy_unpack.c:1209-1237).
  • To try a head without loading it: apparmor_parser -Q -K FILE.

for AppArmor developers for security researchers

In the code

  • The conflict comes from flagvals::merge (profile.h:304-309) through merge_profile_mode (profile.h:66-73); the invalid flag error is the last branch of flagvals::init (profile.h:261).
  • The empty list and the second list are grammar errors: flagvals needs at least one flagval, and profile_base takes one flags (parser_yacc.y:593-629).

09 Three things to test before you trust a mode for security researchers

ATTACK SURFACE flags=(default_allow) deny /home/** r, demo (unconfined) a file access returns before any rule is looked at flags=(prompt) demo (user) nobody is asked; refused, as in enforce flags=(complain) deny /home/** r, refused a plain deny is quieted and stays refused flags=(complain) audit deny /home/** r, apparmor="ALLOWED" ? not quieted: goes on to aa_audit, where complain makes the error allowed open: read from the kernel code, not run on a kernel $ apparmor_parser -Q --warn=all demo no warning for any of the three (tree's parser)
Three rows. flags=(default_allow) with a deny rule is loaded as unconfined and the deny rule is not consulted for a file access. flags=(prompt) is loaded as user mode, nobody is asked and the access is refused. flags=(complain) with an audit deny rule: the request is not quieted and may be logged as ALLOWED; open, not run. The parser warns about none of them.

default_allow is loaded as unconfined. prompt on the kernel asks nobody and refuses what the rules do not cover. Whether an audit deny file rule is still refused in complain mode is open: the kernel code suggests it is not, and it has not been run. The tree's parser prints no warning for any of the three with --warn=all.

Three things to test from this deck. First, default_allow. The name suggests your deny rules still count. This parser loads it as unconfined, and for a file access the kernel returns before it looks at a rule. Second, prompt. On that kernel nobody is asked, and an access the rules don't cover is refused, as in enforce. Third, an open question. In complain mode a plain deny is still refused. But by the file code, an audit deny isn't quieted, and it reaches the step where complain mode turns the error into an allowed record. It hasn't been run, so treat it as a lead. The parser warns about none of the three.

Details and sources

Details

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

  • default_allow: profile_mode_packed rewrites it to the value of unconfined under the comment "until dominance is fixed use unconfined mode for default_allow" (profile.h:75-87). For a profile in unconfined mode the file permission check returns success before any rule is looked up (file.c:263-264). Which other checks still apply was not determined.
  • prompt: the permissions outside the rules are marked for prompting (lib.c:364-372); nothing in security/apparmor/ reads that mark to ask user space or to decide, so the access stays refused. Kernels with the prompting patches differ: upstream and Ubuntu kernels.
  • Complain mode and a plain deny: for a file request the denied bits of a plain deny are in the quiet mask, aa_audit_file clears them from the request and returns the error before the complain conversion (file.c:142-149).
  • Complain mode and audit deny (open, not run): an audit deny rule is not quieted, so the request reaches aa_audit with type AUDIT_APPARMOR_AUTO. There a complain-mode profile makes the record ALLOWED (audit.c:206-212) and the return value goes through complain_error(), which turns EACCES into success (audit.c:233-234). If that reading is right, adding audit to a deny file rule lifts the denial in complain mode. It needs a kernel run to confirm.
  • Run with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded): flags=(default_allow) with a deny rule, flags=(prompt), and flags=(complain) with an audit deny rule print no warning besides the missing-abi notice.

10 Around the modes

ROADS flags=(complain, attach_disconnected) syn-flags-other the other values of the list syn-allow-deny why a deny survives complain syn-prompt prompt on single rules ut-modes aa-complain and aa-enforce adm-denials ALLOWED, DENIED, KILLED lines k-audit how the log type is chosen why-apparmor four modes on one slide syn-identities the part before the flags syntax-map the whole profile on one page upstream-and-ubuntu kernels where prompt is acted on
Roads from the mode flags: syn-flags-other for the other values of the list, syn-allow-deny and syn-prompt, ut-modes and adm-denials, k-audit and why-apparmor, syn-identities, syntax-map and upstream-and-ubuntu.

Other values of the list: syn-flags-other. Deny rules: syn-allow-deny. Changing modes with tools: ut-modes. Reading the log: adm-denials. Kernels that act on prompt: upstream-and-ubuntu.

The mode is one value in that list; the other values are in the next deck. If the complain and deny slide made you curious, the allow and deny deck has the whole story, and prompt as a qualifier on single rules has a deck of its own. Administrators usually change modes with tools, not by editing the head: that's the modes deck in the utilities district. The denial decks show how to read the allowed, denied and killed lines this deck kept mentioning, and how the kernel picks between them. Or step back to the rest of the head, and the whole profile on one page.

Details and sources

Details

  • One mode word per flags=( ) list; none means enforce.
  • Six words, five kernel modes: default_allow loads as unconfined and prompt as the mode the kernel names user.
  • Complain permits what the rules leave out and still refuses what a deny rule denies.
  • Kernel behaviour in this deck was read from the kernel source and not run. Parser messages were produced by 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 messages on this page were produced by the parser built from the AppArmor tree, or by apparmor_parser 5.0.2 where a row says so. Kernel behaviour was worked out by reading the kernel's code at the commit above. It was not run on a kernel.

Grammar

flags: [ 'flags' '=' ] '(' VALUE { [','] VALUE } ')'
  • The flags list is the last part of the profile head, directly before {. A head takes one list.
  • flags is a keyword only when = follows it. The bare form ( VALUE ... ) means the same.
  • At least one value is required. Values are separated by white space, commas or both.
  • Comparison is exact and case-sensitive: complain, not Complain; default_allow with an underscore.
  • Also accepted (5.0.2): flags=(complain,,audit), flags = ( complain ), flags=("complain").
  • A list holds at most one mode value. With none, the profile is in enforce mode.
  • Every other value of the list: syn-flags-other.

Fixtures: flags=(complain) (parser/tst/simple_tests/profile/flags/flags_ok.sd:7), (audit,debug) (flags_ok19.sd:7), flags=(enforce audit) (flags_ok15.sd:7). The tree's parser also accepts profile demo /usr/bin/demo (complain) {.

Mode values

"Outside the rules" means an access that no rule allows and no deny rule denies. The last three columns are read from the kernel's code.

SpellingAn access outside the rulesLog typeThe kernel's name
no mode, or enforcerefusedDENIEDenforce
complainpermittedALLOWEDcomplain
killrefused, and the task is sent a signal (SIGKILL unless kill.signal= says otherwise)KILLEDkill
unconfinednot checked (file access returns early)noneunconfined
promptmainline Linux 7.4: refused, nobody is askedDENIEDuser
default_allowas unconfined: this parser loads it as unconfinednoneunconfined
  • The name is printed after the profile name, as in demo (complain), in /proc/PID/attr/current.
  • kill.signal=NAME picks the signal and does not select kill mode: see syn-flags-other.
  • Which checks mainline Linux 7.4 still applies to a profile in unconfined mode, beyond the early returns, was not determined.
  • prompt as a qualifier on a single rule is a different construct: syn-prompt.

Complain mode in detail

The access isResultLog
allowed by a rulepermittednothing, unless the rule is audited
not mentioned by any rulepermittedapparmor="ALLOWED"
matched by a deny rulerefused (for an audit deny file rule this is open, see below)depends on the deny rule: syn-allow-deny
  • The kernel adds to the complain set every permission that is neither allowed nor explicitly denied (linux:security/apparmor/lib.c:369-370). Denied permissions are not added, so a deny rule is still enforced.
  • For file rules the refusal is decided in aa_audit_file: a plain deny is quieted and returns the error before the complain conversion (linux:security/apparmor/file.c:142-149). Whether an audit deny file rule is still refused in complain mode on mainline Linux 7.4 is open (not run): such a request is not quieted, goes on to aa_audit, and there a complain-mode profile turns the error into an ALLOWED record (linux:security/apparmor/audit.c:206-212, 233-234).
  • The manual says the same, and adds that the compiler may strip explicit denials with -O filter-deny (parser/apparmor.d.pod:609-616).
  • The manual lists further cases that complain mode does not turn into an allow (parser/apparmor.d.pod:604-690). They were not checked against the kernel here.
  • A hat that does not exist is created as a learning profile in complain mode: syn-hats.
  • Switching a profile between complain and enforce with the tools: ut-modes.

The global mode

  • The kernel also has a system-wide mode. A profile behaves as complain, kill or user when either its own mode or the global mode says so (linux:security/apparmor/include/policy.h:40-48).
  • The parser's force-complain option sets the mode in the head only for kernel ABI 5. For newer ABIs it is encoded in the policy version word, and the kernel then loads the profile as complain whatever the head says.

Errors and warnings

MessageWhen
Profile flag 'A' conflicts with 'B'two mode values in one list: any pair, including enforce with another mode and default_allow with unconfined
Invalid profile flag: X.an unknown value or a wrongly capitalised one, for example flags=(Complain)
syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUEan empty list, flags=()
syntax error, unexpected TOK_FLAGS, expecting TOK_OPENa second list, flags=(complain) flags=(audit)
a syntax errora misspelt keyword, flogs=(audit) (flags_bad14.sd:6)
kernel: profile missing flagsthe loaded policy has no flags struct
kernel: failed to unpack profile flagsthe flags struct is malformed or carries a mode number the kernel does not know
  • No warning exists for prompt or default_allow on a kernel that does not act on them. No mode is checked against kernel features.
  • Fixtures: flags_bad2.sd:7 (invalid flag), flags_bad16.sd:6 (empty list), flags_bad30.sd:7 (enforce, complain), flags_bad34.sd:7 (complain, kill), flags_bad72.sd:6 (default_allow, unconfined), all under parser/tst/simple_tests/profile/flags/.

Known discrepancies

  • default_allow: the manual says the mode "allows for allow and deny rules, specifying audit, and domain transitions" and that such profiles "may be reported as being in enforce mode or allow mode" (parser/apparmor.d.pod:734-745). The parser at this commit packs the same value as for unconfined (parser/profile.h:75-87; a 5.0.2 dump of flags=(default_allow, audit, debug) shows mode 3), so the kernel's name for it is unconfined. The slides teach the code.
  • prompt: the manual says the mode sends "an up call to userspace" and "If userspace does not respond then the access will be denied" (parser/apparmor.d.pod:765-768). That describes kernels with the prompting patches. Mainline Linux 7.4 only marks the permissions; no code reads the mark to decide or to notify user space.
  • A repeated mode, flags=(complain complain), is accepted (5.0.2), although two different modes are an error.
  • flags=(default_allow, unconfined) is a conflict although both are packed as the same value.

for AppArmor developers for security researchers

Packed values

SpellingParser enumPacked u32Kernel modeKernel name
(no mode)UNSPECIFIED 00APPARMOR_ENFORCEenforce
enforceENFORCE 10APPARMOR_ENFORCEenforce
complainCOMPLAIN 21APPARMOR_COMPLAINcomplain
killKILL 32APPARMOR_KILLkill
unconfinedUNCONFINED 43APPARMOR_UNCONFINED + FLAG_UNCONFINEDunconfined
promptPROMPT 54APPARMOR_USERuser
default_allowDEFAULT_ALLOW 63APPARMOR_UNCONFINED + FLAG_UNCONFINEDunconfined
  • profile_mode_packed rewrites DEFAULT_ALLOW to UNCONFINED under the comment "until dominance is fixed use unconfined mode for default_allow", then subtracts one; UNSPECIFIED stays 0.
  • The kernel also sets APPARMOR_COMPLAIN when the version word carries FORCE_COMPLAIN_FLAG, whatever the packed mode is.
  • With prompt rules and the prompt compatibility mode FLAG, post-processing overwrites the declared mode with PROMPT.

for AppArmor developers for security researchers

Code map

WhatWhere
grammar of the listparser/parser_yacc.y:593-629
flags keyword, list valuesparser/parser_lex.l:433-436, 479-488
profile_mode enum, merge_profile_mode, profile_mode_packed, str_to_modeparser/profile.h:48-57, 66-73, 75-87, 97-105
profile_mode_tableparser/profile.cc:30-39
flagvals::init, invalid flag errorparser/profile.h:211-263
flagvals::merge, conflict errorparser/profile.h:304-309
feature checks (none for modes)parser/profile.cc:91-110
struct flags writtenparser/parser_interface.c:524-528
no "mediates class" entries for unconfined and default_allowparser/parser_regex.c:1396-1398
prompt compatibility overwrites the modeparser/parser_policy.c:161-162
force-complainparser/parser_yacc.y:443-447, parser/parser_interface.c:670
kernel reads the modelinux:security/apparmor/policy_unpack.c:1209-1237
packed mode constantslinux:security/apparmor/include/policy_unpack.h:36-40
mode nameslinux:security/apparmor/policy.c:94-100
COMPLAIN_MODE, KILL_MODE, USER_MODElinux:security/apparmor/include/policy.h:40-48
aa_apply_modes_to_permslinux:security/apparmor/lib.c:364-372
audit type choice, signal, complain returnlinux:security/apparmor/audit.c:143-150, 200-237
name (mode) label formatlinux:security/apparmor/label.c:1564-1571

Roads from here

START HERE

PROFILE HEAD

QUALIFIERS

RUNNING THE PARSER

TOOLS · utils/

IN THE KERNEL