The prompt qualifier
ask before allowing for application developers
prompt marks permissions for which a user-space agent should be asked. The parser compiles and packs them. Mainline Linux 7.4 unpacks the prompt permissions and does not act on them so there the access is refused like any permission that is not allowed.
On the map: qualifiers
▶ Watch this deck — 7 scenes, ~5 min
Worth seeing first
- allow and deny — allow and deny, the two words prompt shares a seat with
01 Neither yes nor no: ask
prompt RULE, marks permissions to be decided by a user-space agent. The kernel unpacks them and does not act on them.
Should demo be able to read your documents? Sometimes the honest answer is: it depends. Ask the user when it happens. The profile language has a word for that. Prompt sits in the same seat as allow and deny, and the idea is that the kernel pauses the access and asks an agent in user space. Here's the catch, and you need it before you write the rule. The kernel loads prompt permissions and does nothing with them. Asking needs a kernel that carries extra patches. This deck shows what the parser does, and what the kernel does.
Details and sources
Details
promptis a qualifier in the access type seat of a rule, whereallowanddenygo. The example ruleprompt @{HOME}/Documents/** r,is line 29 of the map's example profile fordemo.- Intended meaning: the permission is neither granted nor refused by the profile; a user-space agent is asked when the access happens. The agent on the slide is drawn dashed and unnamed because neither source tree read for this map contains code that delivers such a request.
- The kernel (commit 97d73c825): the permission set has a
promptfield (perms.h:78); it is read from the loaded policy and no access decision reads it (lib.c:425-464). This was read from the kernel source, not observed on a running kernel. - The parser (AppArmor 836052d21) compiles prompt rules without a warning whatever the kernel supports.
for AppArmor developers for security researchers
Code
- Grammar:
TOK_PROMPTinopt_rule_mode, parser_yacc.y:700-703; keyword table parser_misc.c:102.
Read more
- The qualifier list of the manual page: apparmor.d(5), Rule Qualifiers
- The notification interface behind prompting, a development interface that is not in the kernel: AppArmor wiki: prompt-v3-interface
- Kernels that act on prompt rules: upstream-and-ubuntu
- The other two access types: syn-allow-deny
02 The third word for the third seat
[priority=N] [audit] prompt [owner|other] RULE,. One access type per rule: allow, deny or prompt.
Prompt takes the access type seat. So a rule has allow, or deny, or prompt, and only one of them. Audit goes before it and owner after it, as usual. You can also put it in front of a block. There's no simple test file for prompt in the tree. This block comes from the parser's equality tests, which check that a prompt block and three separate prompt rules compile to the same policy. And if you look in the manual's grammar, the access type line lists only allow and deny, though the block examples there do use prompt.
Details and sources
Details
- Form:
[priority=N] [audit] prompt [owner|other] RULE,andprompt { RULES }. The order of the qualifiers is fixed. - One access type per rule:
allow,denyorprompt. Two of them on one rule is a syntax error (run with the tree's parser at 836052d21). profile t { prompt /foo r, audit prompt signal, prompt capability chown, }is accepted (run with the tree's parser; nothing was loaded into a kernel). See the reference below before usingprompton capability rules.- No file under
parser/tst/simple_tests/uses a prompt rule. The block on the slide is from the equality tests, which check that/t { prompt { /foo r, audit /bar w, owner /baz rw, } }and/t { prompt /foo r, audit prompt /bar w, prompt owner /baz rw, }compile to the same binary policy: equality.sh:1443-1447. - Known discrepancy with the manual: apparmor.d(5) gives
ACCESS TYPE = ( 'allow' | 'deny' )(apparmor.d.pod:198) and usespromptonly in block examples (apparmor.d.pod:2691, apparmor.d.pod:2700).
for AppArmor developers for security researchers
Code
opt_rule_modeand the seat order: parser_yacc.y:700-711; keywordprompt: parser_misc.c:102.
Read more
- The manual page on qualifiers: apparmor.d(5), Rule Qualifiers and apparmor.d(5), Qualifier Blocks
- The four qualifier seats: syn-allow-deny
- Blocks: syn-qualifier-blocks
auditin front of an access type: syn-audit
03 Prompt gives way to allow and to deny
At equal priority a permission goes to deny, else allow, else prompt. A prompt rule with higher priority overrides both.
Prompt is the weakest of the three access types. Take a prompt rule for read and write on your documents. Alone, it marks both permissions as ask. Now add a plain allow for read on the same files. Read is simply allowed, and there's nothing left to ask. Write stays a prompt permission. Add a deny for a subdirectory, and there both are denied, quietly. So prompt fills the gap between what you allow outright and what you forbid. And if you want the question to stand even though a broader allow exists, give the prompt rule a higher priority.
Details and sources
Details
- The decision is made per permission of one name. At equal priority a permission goes to a deny rule, else to an allow rule, else to a prompt rule. Rule order in the file has no effect.
- Parser dumps behind the slide (
-D dfa-states-initial, format(allow/deny//prompt/audit/quiet);ris0x10004,wwith append0x2800a,rw0x3800e):
| Rules | State | Basis |
|---|---|---|
prompt /d r, | (0x 0/0//10004/0/0) | tree's parser at 836052d21 |
prompt /a rw, /a r, | (0x 10004/0//2800a/0/0): read allowed, write and append prompt | tree's parser at 836052d21 |
prompt /a rw, deny /a w, | (0x 0/2800a//10004/0/2800a): write denied and quiet, read prompt | tree's parser at 836052d21 |
priority=1 prompt /a rw, /a r, | (0x 0/0//3800e/0/0): read and write prompt | tree's parser at 836052d21 |
- The slide's paths (
@{HOME}/Documents/**,private/) are the same rule shapes with the example profile's names; the lamps for them are derived from the scoring and the dumps above, not from a dump of those exact rules. - A plain
denyalso marks the permissions quiet, so the refusal is not logged: syn-allow-deny. - What "ask" means at run time depends on the kernel; the kernel refuses such a request (next slide).
for AppArmor developers for security researchers
Code
- Per-bit score
priority*4plus 3 for deny, 2 for an exact exec match, 1 for allow, 0 for prompt: hfa.cc:1536-1554; prompt bits collected at hfa.cc:1649-1650.
Read more
- The manual page on priority: apparmor.d(5), priority
- The qualifiers on the wiki: AppArmor wiki: rule prefixes and modes
- Scoring and
priority=N: syn-priority - How the masks are merged per state: re-perms
04 What the kernel does with it
The kernel unpacks and validates the prompt field and no decision path reads it. By the kernel source, the access is refused and logged as a normal denial.
Follow the rule into the kernel. The parser compiles the prompt permission into its own set, next to allow, and packs it. The kernel unpacks it, checks that it doesn't overlap allow or deny, and keeps it. Then demo opens the document. The decision code looks at allow, and read isn't there. Nothing consults the prompt set. So, going by the kernel source, the open fails and you get an ordinary denied record. On this kernel a prompt rule behaves like no rule at all. And unlike a deny, it isn't silent: the refusal is logged.
Details and sources
Details
All kernel statements here are for the kernel (commit 97d73c825) and come from reading security/apparmor/. Nothing was run on a kernel.
struct aa_permshas apromptmember: perms.h:78.- Unpack: the
promptword of each permission entry is read at policy_unpack.c:916. - Validation: a profile is rejected if
promptoverlapsallowordeny, or ifcomplainoverlapsprompt: policy_unpack.c:1524-1527. - Accumulation when permission sets are merged: perms.h:118, perms.h:145.
- Decision:
aa_check_permscomputesdenied = request & (~perms->allow | perms->deny)and does not readprompt: lib.c:425-464. The file path does the same inaa_audit_file: file.c:95-154. - Result, by that code: in enforce mode the request fails with
EACCESand anapparmor="DENIED"record, as for any permission that is not allowed. The record on the slide is shortened; the fields kept are in the kernel's order. - Complain mode: derived from the same code, not run. A prompt bit is a bit missing from allow, so the request is permitted and logged as
ALLOWED. - The features file advertises
promptamong the permission table fields (apparmorfs.c:2631); that describes the table layout, not prompting.
Read more
- Which kernel gained which feature, with separate tables for upstream, SUSE and Ubuntu kernels: AppArmor wiki: Kernel feature matrix
- The notification interface, not in the kernel: AppArmor wiki: prompt-v3-interface
- Listeners and the life of a notification: AppArmor wiki: kernel development guide, notifications
- Kernels that do act on prompt rules: upstream-and-ubuntu
- How the kernel reads a profile: k-unpack
- Reading denial records: adm-denials
05 PromptMatchFlag, the third accept word and --prompt-compat for AppArmor developers for security researchers
PromptMatchFlag scores priority*4 + 0 (parser/libapparmor_re/hfa.cc:1552-1554); the bits are packed as the prompt field (policy_compat.cc). --prompt-compat=flag sets PACKED_MODE_USER.
A prompt rule becomes a PromptMatchFlag node. In the per-bit scoring it gets priority*4 + 0, below allow and deny. That's the ranking you saw. Its bits collect in the state's prompt word, and map_perms_to_accept emits them as the third accept word. The table builders write the prompt field; the file ones also mask it against allow and deny. Without a permission table, the third word is computed and thrown away. The --prompt-compat option is a separate knob. Its only reader is in parser policy, where flag mode marks a profile that uses prompt rules as user mode. The kernel unpacks and validates the field, and nothing consumes it.
Details and sources
for AppArmor developers for security researchers
Details
- Node:
rule_mode_t::PROMPTselectsPromptMatchFlag(aare_rules.h:85-89); the class is expr-tree.h:1199-1205. - Score in
pri_update_perm:priority << 2, plus 3 forDenyMatchFlag, 2 for an exact match on exec bits, 1 for allow, 0 for prompt: hfa.cc:1536-1554. Bits go toperms.prompt, audit bits toperms.audit: hfa.cc:1649-1650. map_perms_to_accept(accept1, accept2, accept3): allow,PACK_AUDIT_CTL(audit, quiet), prompt: hfa.h:132-138.- The table builders fill
prompt(policy_compat.cc:166-237: lines 166, 182, 207, 237); the two file builders also mask it with~(perms.allow | perms.deny)(lines 172, 188). Written bysd_serialize_perm: parser_interface.c:355. - Without a permission table (
kernel_supports_permstable32_version < 2) the third accept word is computed into a local and dropped, so the rule carries nothing: chfa.cc:129-136. - A profile is recorded as using prompt rules through
prefix_rule_t::uses_prompt(rule.h:374-377) andblock_rules::uses_prompt_rules(block_rules.cc:23-36). --prompt-compat=permsv2|default|ignore|flag: parser_main.c:892-905.--print-prompt-compatprintsPrompt compat mode:and the mode set by a--prompt-compatoption earlier on the command line; with none it printsUnknown prompt compat mode '0'(run with the tree's parser), because the default is chosen after the options are read (parser_main.c:1787-1790): parser_main.c:907-910, parser_common.c:214-229. Default selection, best supported of permsv2, flag, ignore: parser_common.c:189-212.- The only reader of the mode: in
flagmode a profile that uses prompt rules getsprofile_mode::PROMPT(parser_policy.c:161-162), packed as mode 4,PACKED_MODE_USER(policy_unpack.h:40, policy_unpack.c:1233-1234). ignoredoes not strip prompt permissions:--prompt-compat=ignore,--prompt-compat=permsv2and no option give the same binary forprompt /a r,, andflagdiffers from them in the mode word (run with the tree's parser).--prompt-compat=defaultselectsignorewith the abi/5.0 feature set, because it is evaluated before the features are known. Whether that is intended was not determined. The option is not in apparmor_parser(8).- The kernel: unpack policy_unpack.c:916; validation policy_unpack.c:1524-1527; user mode sets
perms->prompt |= ~(perms->allow | perms->deny)at lib.c:371-372. No decision path reads the field. Read from source, not run.
Read more
- How permissions are encoded on accept states: AppArmor wiki: TechnicalDoc_HFA_permissions
- The kernel side of notifications and prompting: AppArmor wiki: kernel development guide, notifications
- Permission words per state: re-perms
- The kernel side of unpacking: k-unpack
- The
promptprofile mode: syn-flags-modes
06 What to check before relying on prompt
prompt conflicts with allow and deny on the same rule or block ("conflicting mode prefix"). The parser does not warn when the kernel will not act on prompt rules.
There's very little the parser can tell you here. A prompt block around a deny rule is refused, and so are two access types on one rule. Beyond that it compiles prompt rules without comment, even for a kernel that won't ask. So the mistake to avoid is an assumption: the profile loaded, so somebody will be asked. On the kernel nobody is, and the access is denied. The second thing to check is overlap. An allow for the same permission wins, and then the prompt never comes up.
Details and sources
Details
prompt { deny /foo r, }is rejected withconflicting mode prefix(run with the tree's parser at 836052d21). The same message is given for an explicitallowinside apromptblock.prompt deny /x r,is rejected withsyntax error, unexpected TOK_DENY, expecting TOK_ID or TOK_MODE or TOK_SET_VAR(run with the tree's parser).- Full form of a parse error:
AppArmor parser error for FILE in profile FILE at line N: MESSAGE. - No warning exists for compiling prompt rules for a kernel that will not act on them (by reading the parser source). On the kernel the access is then refused and logged; see the previous slides.
- Overlap: at equal priority an allow rule for the same permission and name wins, so nothing remains in the prompt set for it.
priority=Non the prompt rule changes that: syn-priority. - Known discrepancy, confirmed with the tree's parser:
prompt capability chown,compiles to the same binary ascapability chown,, soprompt capability X,is stored as an allowed capability. Do not useprompton capability rules.
for AppArmor developers for security researchers
Code
- Conflict check in
prefix_rule_t::add_prefix: rule.h:409-416. - Capability rules distinguish only deny; prompt falls into the allow branch: block_rules.cc:143-152.
for security researchers
Attack surface
prompt capability X,andprompt { capability X, }fail open: they compile to the same binary ascapability X,, so the capability is granted on any kernel, with no message (run with the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel; block_rules.cc:143-152).- The parser prints no warning when a profile with
promptrules is compiled for a kernel that does not prompt. On the kernel a prompt permission is a permission that is not allowed: refused in enforce mode, permitted and logged as ALLOWED in complain mode (file.c:246-247; read from the kernel source, not observed on a running kernel). - Where a kernel does act on prompt permissions (mainline Linux does not), the decision moves to an agent in user space, which then belongs to the attack surface. See upstream-and-ubuntu.
--prompt-compat=flagmarks a profile that uses prompt rules with the user (prompt) profile mode instead;ignoreandpermsv2give the same binary as no option (same run).
Read more
- Which kernel gained which feature: AppArmor wiki: Kernel feature matrix
- The notification interface a prompting kernel offers: AppArmor wiki: prompt-v3-interface
- Kernels that act on prompt rules: upstream-and-ubuntu
- Reading denial records: adm-denials
07 Where to go from here
Next: syn-priority, syn-allow-deny, re-perms, k-unpack. Kernels that act on prompt rules: upstream-and-ubuntu.
So prompt is real syntax with a real place in the compiled policy, and a feature that depends on your kernel. If you came here from allow and deny, priority is the natural next stop: it's how a prompt rule can outrank an allow. Audit and qualifier blocks combine with prompt the way they do with the other two. To watch the prompt field travel into the kernel, follow the permissions deck and then the unpack deck. And for which kernels do ask, the upstream and Ubuntu deck is the place.
Details and sources
Details
promptis the third access type. The parser at AppArmor 836052d21 compiles and packs it; the kernel unpacks it and does not act on it (read from source, not run).- Which kernels deliver prompt requests to user space is outside both trees read for this deck.
Read more
- apparmor.d(5), Rule Qualifiers: the manual page on qualifiers
- AppArmor wiki: prompt-v3-interface: the notification interface, a development interface that is not in the kernel
- AppArmor wiki: kernel development guide, notifications: listeners, message life cycle, caching
- syn-allow-deny: the two access types that outrank prompt
- syn-priority: how a prompt rule can win a permission
- syn-audit:
audit prompt - syn-qualifier-blocks:
prompt { ... } - syn-flags-modes: the
promptprofile mode - re-perms and k-unpack: the prompt field on its way into the kernel
- upstream-and-ubuntu: which kernels act on prompt rules
- syntax-map: every kind of line on one page
Read more
Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the fragment (-Q -K --skip-kernel-load --warn=all), with nothing loaded into a kernel; "code" means the parser or kernel source was read, not run. Nothing here was observed on a running kernel. Kernel statements are for mainline Linux 7.4. What kernels with additional patches do with prompt rules: upstream-and-ubuntu.
Grammar
RULE LINE: [priority=N] [audit] prompt [owner|other] RULE ,
BLOCK: [audit] prompt [owner|other] { RULES }
priority=Nis not allowed in front of a block:priority is not allowed on rule blocks(tree).prompttakes the access type seat; a rule has at most one ofallow,deny,prompt(tree).- The parser accepts it on file rules and on other rule classes:
profile t { prompt /foo r, audit prompt signal, prompt capability chown, }is accepted (tree). For capability rules see "Known discrepancies and gaps". - No file in
parser/tst/simple_tests/uses a prompt rule.parser/tst/equality.sh:1445-1447checks that/t { prompt { /foo r, audit /bar w, owner /baz rw, } }equals/t { prompt /foo r, audit prompt /bar w, prompt owner /baz rw, }.
Ranking
Per permission of one name, at equal priority: deny, then allow, then prompt. Scoring and priority=N: syn-priority.
| Rules | Result | Basis |
|---|---|---|
prompt /d r, | read is prompt | tree |
prompt /a rw, and /a r, | read allowed; write and append prompt | tree |
priority=1 prompt /a rw, and /a r, | read, write and append prompt; nothing allowed | tree |
prompt /a rw, and deny /a w, | write and append denied and quiet; read prompt | tree |
What the kernel receives
- Each entry of the permission table has a
promptfield next toallow,deny,auditandquiet. A permission is in at most one of allow and prompt, because each bit goes to one kind of rule; the file table builders also mask the field with allow and deny (code). - This needs a permission table. For a kernel without one the prompt bits are computed and dropped: the rule then grants nothing and carries nothing (code).
- Mainline Linux 7.4 rejects a profile in which
promptoverlapsallowordeny, orcomplainoverlapsprompt(code; linux:security/apparmor/policy_unpack.c:1524-1527).
What mainline Linux 7.4 does
Read from linux 97d73c825 (7.4-rc2), security/apparmor/; not run.
| Step | What happens | Where |
|---|---|---|
| unpack | the prompt word of each entry is read | linux:security/apparmor/policy_unpack.c:916 |
| validate | overlap with allow, deny or complain rejects the profile | linux:security/apparmor/policy_unpack.c:1524-1527 |
| accumulate | merged into combined permission sets, minus allow and deny | linux:security/apparmor/include/perms.h:118, 145 |
| user mode | a profile in user mode gets prompt for everything not allowed or denied | linux:security/apparmor/lib.c:371-372 |
| decide | aa_check_perms and aa_audit_file read allow, deny, audit, quiet and hide; not prompt | linux:security/apparmor/lib.c:425-464, file.c:95-154 |
Result: a prompt permission is a permission that is not in allow. In enforce mode the request is refused with EACCES and logged as DENIED. In complain mode it is permitted and logged as ALLOWED (derived from the same code). No question is put to user space.
Parser options
| Option | Effect |
|---|---|
--prompt-compat=permsv2 | select the permsv2 mode |
--prompt-compat=flag | a profile that uses prompt rules is given the prompt profile mode, packed as kernel mode 4 (user) |
--prompt-compat=ignore | select the ignore mode; this does not remove prompt permissions from the output and produces the same binary as permsv2 (tree) |
--prompt-compat=default | meant as the best supported of permsv2 (needs permission table version 2 or later), flag (needs a permission table), ignore. Evaluated while options are read, before the kernel features are known: with the abi/5.0 feature set it selects ignore (tree). With no option the parser picks the best supported mode later |
--print-prompt-compat | prints Prompt compat mode: and the mode set so far on stderr, then exits; without an earlier --prompt-compat it prints Unknown prompt compat mode '0' (tree) |
The print rows and the ignore, permsv2 and flag comparison were run with the tree's parser; the rest is from the code (parser/parser_main.c:892-911, 1769-1790, parser/parser_common.c:189-229). Neither option is in apparmor_parser(8). The prompt profile mode itself: syn-flags-modes.
Errors and warnings
A parse error is printed as AppArmor parser error for FILE in profile FILE at line N: MESSAGE (tree).
| Message | Cause |
|---|---|
conflicting mode prefix | a rule's explicit access type against its block's, as in prompt { deny /foo r, } (tree) |
syntax error, unexpected TOK_DENY, expecting TOK_ID or TOK_MODE or TOK_SET_VAR | prompt deny /x r,: one access type per rule (tree) |
%s: Invalid --prompt-compat option '%s' | an unknown value for --prompt-compat; the parser exits with status 1 (code) |
There is no warning for compiling prompt rules for a kernel that will not act on them (code).
Known discrepancies and gaps
- Known discrepancy:
prompt capability X,is stored as an allowed capability; only deny is distinguished for capabilities (code, parser/block_rules.cc:143-152; tree:prompt capability chown,compiles to the same binary ascapability chown,). Do not useprompton capability rules. - Known discrepancy with the manual: apparmor.d(5) omits
promptfromACCESS TYPE(parser/apparmor.d.pod:198) and uses it only in block examples (2691, 2700);--prompt-compatis not documented. - Not determined: whether
prompthas any representation in the legacy network table. - Not determined: whether
--prompt-compat=ignoreis meant to strip prompt permissions; no code does. - Outside both trees: how a kernel with user-space prompting uses the prompt mask and the audit bits of prompt rules. See upstream-and-ubuntu.
for AppArmor developers for security researchers
Code map
| Step | Where |
|---|---|
grammar: TOK_PROMPT in opt_rule_mode | parser/parser_yacc.y:703; keyword parser/parser_misc.c:102 |
prefix_rule_t::uses_prompt | parser/rule.h:374-377 |
| conflict check, "conflicting mode prefix" | parser/rule.h:409-416 |
block_rules::uses_prompt_rules | parser/block_rules.cc:23-36, 617-618 |
PromptMatchFlag | parser/libapparmor_re/expr-tree.h:1199-1205; chosen in aare_rules.h:87-88 |
pri_update_perm: score priority*4 + 0 for prompt; perms.prompt, perms.audit | parser/libapparmor_re/hfa.cc:1536-1554, 1649-1650 |
map_perms_to_accept: third accept word | parser/libapparmor_re/hfa.h:132-138 |
the table builders fill perms.prompt | parser/libapparmor_re/policy_compat.cc:166, 182, 207, 237 |
the two file builders mask it: perms.prompt &= ~(perms.allow or perms.deny) | parser/libapparmor_re/policy_compat.cc:172, 188 |
| third word dropped without a permission table | parser/libapparmor_re/chfa.cc:129-136, 160-163 |
sd_serialize_perm | parser/parser_interface.c:355 |
prompt_compat_mode, options | parser/parser_main.c:203-204, 892-910, 1787-1790; parser/parser_common.c:189-229 |
profile_mode::PROMPT in flag mode | parser/parser_policy.c:161-162 |
PACKED_MODE_USER (Linux 7.4) | linux:security/apparmor/include/policy_unpack.h:40, policy_unpack.c:1233-1234 |
unpack_perm, validation (Linux 7.4) | linux:security/apparmor/policy_unpack.c:916, 1524-1527 |
aa_compute_profile_perms user-mode line (Linux 7.4) | linux:security/apparmor/lib.c:371-372 |
Dump format (-D dfa-states-initial): (allow/deny//prompt/audit/quiet) in hex; the doubled / is a known defect of the dump. Bits per half: x 0x1, w 0x2, r 0x4, a 0x8; the other half is shifted left by 14.
| Rules | State | Basis |
|---|---|---|
prompt /d r, | (0x 0/0//10004/0/0) | tree |
prompt /a rw, /a r, | (0x 10004/0//2800a/0/0) | tree |
priority=1 prompt /a rw, /a r, | (0x 0/0//3800e/0/0) | tree |
prompt /a rw, deny /a w, | (0x 0/2800a//10004/0/2800a) | tree |
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
- Upstream and Ubuntu kernels — which kernels act on prompt rules
PROFILE HEAD
- Profile mode flags — the prompt profile mode
QUALIFIERS
- allow and deny — the two access types that outrank prompt
- Rule priority — how a prompt rule can win a permission
- The audit qualifier — audit prompt
- Qualifier blocks — prompt in front of a block
IN THE KERNEL
- Unpacking and verifying policy (no slides yet) — where the kernel reads the prompt field
THE DFA ENGINE · libapparmor_re
- Permissions in the DFA — the prompt mask in the permission table