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
- The profile name — the profile head, whose last part is the flags list
Part of journeys
- New to AppArmor, step 4 of 10 · previous: The profile name · next: Profile attachment
- Hardening a privileged program, step 8 of 11 · previous: The audit qualifier · next: Reading a denial
01 What happens when no rule allows it?
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 areenforce,complain,kill,unconfined,promptanddefault_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 asapparmor="..."areAUDIT,ALLOWED,DENIEDandKILLED(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/currentand/proc/<pid>/attr/apparmor/current(label.c:1563-1571).
Read more
- apparmor.d(5), Profile Mode
- apparmor(7), Complain mode
- apparmor.net: Profiles basics, modes
- Why AppArmor: the short version of the modes. Reading denials.
02 The flags list and its mode word
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 ')'andPROFILE 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 quotedflags=("complain"). - Spelling is compared exactly and case matters:
complain, notComplain;default_allowwith 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
- apparmor.d(5), Profile Mode and apparmor.d(5), Flags
- apparmor_parser(8), OPTIONS
- Other profile flags: every other value of the list. Identities: the head part written before it.
for AppArmor developers for security researchers
In the code
- Three
flagsproductions (empty, withflags =, bare parentheses) and theflagvalslist: parser_yacc.y:593-629. flagsis a keyword only when=follows (parser_lex.l:433-436); list values are read inLIST_VAL_MODE, where commas are skipped (parser_lex.l:479-488).str_to_modecompares withstrcmpagainstprofile_mode_table(profile.h:97-105, profile.cc:30-39).
03 Six words, five modes
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 ownunconfinedlabel is printed without a mode. - Reading it:
cat /proc/<pid>/attr/current, or from a programint aa_getcon(char **label, char **mode)andint 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 isunconfined. - The right-hand column of the slide is put together from this code. It was not captured from a running system.
Read more
for AppArmor developers for security researchers
In the code
profile_mode_packedrewritesDEFAULT_ALLOWtoUNCONFINEDand subtracts one;UNSPECIFIEDstays 0 (profile.h:48-87).
04 Complain still refuses what you deny
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 adenyrule still refuses. - For file rules the refusal is decided in
aa_audit_file: a plaindenyis quieted and returns the error before the complain conversion (file.c:142-149). Whether anaudit denyfile rule is still refused in complain mode is open (not run): its request is not quieted, reachesaa_audit, and there a complain-mode profile turns any error intoALLOWED(audit.c:206-212). - The record is of type
ALLOWEDonly when every refused permission is in the complain set (audit.c:143-152). - For an
ALLOWEDrecordaa_auditreturnscomplain_error(ad->error)(audit.c:233-234), which turnsEPERMandEACCESinto 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/modeset tocomplainhas the same effect on every profile (policy.h:40-48).
05 Kill mode: refuse and 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_auditalso turns aDENIEDrecord of a kill-mode profile intoKILLED(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
SIGKILLunless the policy sets another:profile->signal = SIGKILLwhen the profile is allocated (policy.c:412). kill.signal=NAMEarrives as an optional number namedkill. A value outside 1 to 35 fails the load withprofile 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 withoutsig(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.
Read more
- apparmor.d(5), Profile Mode and apparmor.d(5), Misc modes for
kill.signal. - Other profile flags:
kill.signal=in full. - Reading denials, how the kernel builds the record.
06 Unconfined, default_allow and prompt today
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 forunconfined, 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 isuser, 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 leavesDENIED(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
promptordefault_allowon a kernel that does not act on them.
Read more
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_profilechecks features forinterruptible,kill.signalanderroronly; no mode is checked (profile.cc:91-110).
07 How the mode is packed for AppArmor developers for security researchers
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:UNSPECIFIED0,ENFORCE1,COMPLAIN2,KILL3,UNCONFINED4,PROMPT5,DEFAULT_ALLOW6,CONFLICT7 (profile.h:48-58). The spellings are inprofile_mode_table(profile.cc:30-39).flagvals::init(const char *str)callsstr_to_modefirst; a word that is a mode setsmode(profile.h:211-220).merge_profile_mode(l, r)returnsCONFLICTfor two different specified modes (profile.h:66-73);flagvals::mergeraisesProfile flag '%s' conflicts with '%s'(profile.h:304-309).profile_mode_packed(mode)rewritesDEFAULT_ALLOWtoUNCONFINED, then returns the value minus one;UNSPECIFIEDgives 0 (profile.h:75-87).- The serializer writes struct
flagsas 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 withPROMPT(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 offlagsis compared withPACKED_MODE_ENFORCE0 toPACKED_MODE_USER4;FORCE_COMPLAIN_FLAGin the version wins over the number; anything else isgoto fail(policy_unpack.c:1209-1237, policy_unpack.h:36-40). COMPLAIN_MODE,USER_MODEandKILL_MODEare true for the profile's mode or for the globalaa_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
"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'forflags=(enforce, complain)(flags_bad30.sd:7); likewiseflags=(complain, kill)(flags_bad34.sd:7).Invalid profile flag: Complain.for a wrongly capitalised word; the fixture for an unknown word isflags=(capability)(flags_bad2.sd:7).syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUEforflags=()(flags_bad16.sd:6).syntax error, unexpected TOK_FLAGS, expecting TOK_OPENfor 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 flagsandfailed 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.
Read more
- apparmor.d(5), Profile Mode
- apparmor_parser(8), OPTIONS
- Other profile flags:
auditgoes in the same list.
for AppArmor developers for security researchers
In the code
- The conflict comes from
flagvals::merge(profile.h:304-309) throughmerge_profile_mode(profile.h:66-73); the invalid flag error is the last branch offlagvals::init(profile.h:261). - The empty list and the second list are grammar errors:
flagvalsneeds at least oneflagval, andprofile_basetakes oneflags(parser_yacc.y:593-629).
09 Three things to test before you trust a mode for security researchers
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_packedrewrites it to the value ofunconfinedunder 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 insecurity/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 plaindenyare in the quiet mask,aa_audit_fileclears them from the request and returns the error before the complain conversion (file.c:142-149). - Complain mode and
audit deny(open, not run): anaudit denyrule is not quieted, so the request reachesaa_auditwith typeAUDIT_APPARMOR_AUTO. There a complain-mode profile makes the recordALLOWED(audit.c:206-212) and the return value goes throughcomplain_error(), which turnsEACCESinto success (audit.c:233-234). If that reading is right, addingauditto adenyfile 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 adenyrule,flags=(prompt), andflags=(complain)with anaudit denyrule print no warning besides the missing-abi notice.
10 Around the modes
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_allowloads as unconfined andpromptas the mode the kernel namesuser. - Complain permits what the rules leave out and still refuses what a
denyrule 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. flagsis 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, notComplain;default_allowwith 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.
| Spelling | An access outside the rules | Log type | The kernel's name |
|---|---|---|---|
no mode, or enforce | refused | DENIED | enforce |
complain | permitted | ALLOWED | complain |
kill | refused, and the task is sent a signal (SIGKILL unless kill.signal= says otherwise) | KILLED | kill |
unconfined | not checked (file access returns early) | none | unconfined |
prompt | mainline Linux 7.4: refused, nobody is asked | DENIED | user |
default_allow | as unconfined: this parser loads it as unconfined | none | unconfined |
- The name is printed after the profile name, as in
demo (complain), in/proc/PID/attr/current. kill.signal=NAMEpicks 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.
promptas a qualifier on a single rule is a different construct: syn-prompt.
Complain mode in detail
| The access is | Result | Log |
|---|---|---|
| allowed by a rule | permitted | nothing, unless the rule is audited |
| not mentioned by any rule | permitted | apparmor="ALLOWED" |
matched by a deny rule | refused (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
denyrule is still enforced. - For file rules the refusal is decided in
aa_audit_file: a plaindenyis quieted and returns the error before the complain conversion (linux:security/apparmor/file.c:142-149). Whether anaudit denyfile rule is still refused in complain mode on mainline Linux 7.4 is open (not run): such a request is not quieted, goes on toaa_audit, and there a complain-mode profile turns the error into anALLOWEDrecord (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
| Message | When |
|---|---|
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_VALUE | an empty list, flags=() |
syntax error, unexpected TOK_FLAGS, expecting TOK_OPEN | a second list, flags=(complain) flags=(audit) |
| a syntax error | a misspelt keyword, flogs=(audit) (flags_bad14.sd:6) |
kernel: profile missing flags | the loaded policy has no flags struct |
kernel: failed to unpack profile flags | the flags struct is malformed or carries a mode number the kernel does not know |
- No warning exists for
promptordefault_allowon 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 forunconfined(parser/profile.h:75-87; a 5.0.2 dump offlags=(default_allow, audit, debug)shows mode 3), so the kernel's name for it isunconfined. 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
| Spelling | Parser enum | Packed u32 | Kernel mode | Kernel name |
|---|---|---|---|---|
| (no mode) | UNSPECIFIED 0 | 0 | APPARMOR_ENFORCE | enforce |
enforce | ENFORCE 1 | 0 | APPARMOR_ENFORCE | enforce |
complain | COMPLAIN 2 | 1 | APPARMOR_COMPLAIN | complain |
kill | KILL 3 | 2 | APPARMOR_KILL | kill |
unconfined | UNCONFINED 4 | 3 | APPARMOR_UNCONFINED + FLAG_UNCONFINED | unconfined |
prompt | PROMPT 5 | 4 | APPARMOR_USER | user |
default_allow | DEFAULT_ALLOW 6 | 3 | APPARMOR_UNCONFINED + FLAG_UNCONFINED | unconfined |
profile_mode_packedrewritesDEFAULT_ALLOWtoUNCONFINEDunder the comment "until dominance is fixed use unconfined mode for default_allow", then subtracts one;UNSPECIFIEDstays 0.- The kernel also sets
APPARMOR_COMPLAINwhen the version word carriesFORCE_COMPLAIN_FLAG, whatever the packed mode is. - With prompt rules and the prompt compatibility mode
FLAG, post-processing overwrites the declared mode withPROMPT.
for AppArmor developers for security researchers
Code map
| What | Where |
|---|---|
| grammar of the list | parser/parser_yacc.y:593-629 |
flags keyword, list values | parser/parser_lex.l:433-436, 479-488 |
profile_mode enum, merge_profile_mode, profile_mode_packed, str_to_mode | parser/profile.h:48-57, 66-73, 75-87, 97-105 |
profile_mode_table | parser/profile.cc:30-39 |
flagvals::init, invalid flag error | parser/profile.h:211-263 |
flagvals::merge, conflict error | parser/profile.h:304-309 |
| feature checks (none for modes) | parser/profile.cc:91-110 |
struct flags written | parser/parser_interface.c:524-528 |
| no "mediates class" entries for unconfined and default_allow | parser/parser_regex.c:1396-1398 |
| prompt compatibility overwrites the mode | parser/parser_policy.c:161-162 |
| force-complain | parser/parser_yacc.y:443-447, parser/parser_interface.c:670 |
| kernel reads the mode | linux:security/apparmor/policy_unpack.c:1209-1237 |
| packed mode constants | linux:security/apparmor/include/policy_unpack.h:36-40 |
| mode names | linux:security/apparmor/policy.c:94-100 |
COMPLAIN_MODE, KILL_MODE, USER_MODE | linux:security/apparmor/include/policy.h:40-48 |
aa_apply_modes_to_perms | linux:security/apparmor/lib.c:364-372 |
| audit type choice, signal, complain return | linux:security/apparmor/audit.c:143-150, 200-237 |
name (mode) label format | linux:security/apparmor/label.c:1564-1571 |
Roads from here
START HERE
- Why AppArmor — the same access in four modes on one slide
- Upstream and Ubuntu kernels — kernels where prompt is acted on
- The profile language at a glance — back to the whole profile on one page
PROFILE HEAD
- The other profile flags — the other values of the same list
- Profile identities — the head part written before the flags
QUALIFIERS
- allow and deny — deny rules and why complain does not lift them
- The prompt qualifier — prompt as a rule qualifier
RUNNING THE PARSER
- Reading a denial — read the ALLOWED and DENIED and KILLED lines
TOOLS · utils/
- Switching profile modes (no slides yet) — switch a profile between complain and enforce with the tools
IN THE KERNEL
- How a denial is logged (no slides yet) — how the kernel chooses the log type