Kernel features and the policy ABI
kernel vs policy for application developers for administrators
The kernel publishes what its AppArmor can enforce as a directory of feature files. aa-features-abi prints that directory as the text an abi file has. The parser compiles a kind of rule only when the kernel's set and the policy's set both have it and by default prints nothing when a rule is left out. Two options and one parser.conf line choose the sets. The cache directory is named after the kernel's set.
On the map: running the parser
▶ Watch this deck — 9 scenes, ~7 min
Worth seeing first
- The abi rule and the abi files — the abi rule and the idea of two feature sets
Part of journeys
- Network, IPC and privileges, step 14 of 14 · previous: Upstream and Ubuntu kernels
01 Accepted, and not enforced
A rule the kernel cannot enforce is left out with exit status 0 and no message unless you ask. This deck shows where the kernel publishes its feature set, how to print it, how to choose the two sets and how to see what was left out.
Here's a profile with twelve rules, one of each kind. Compile it, and the parser says nothing. Exit status zero. Ask for every warning, and one line appears: message queue rules are not enforced. The rule was fine. This kernel has no message queue mediation, so the parser left it out, quietly. Whether a kind of rule is compiled depends on two feature lists: the kernel's, and the one the policy was written for. The deck on the abi rule explains why. Here's the administrator's side: where the kernel publishes its list, the tool that prints it, the options that choose the lists, and how to see what's left out.
Details and sources
Details
- Run in a Debian sid guest (kernel 7.3.4, whose 49 feature files are the entries of the kernel source the map describes less one,
network_v8/sctp, which no rule on these slides needs) with the parser built from the AppArmor tree,--config-file=/dev/null -K, the kernel features read from the running kernel. - The profile is the twelve-rule profile of the research notes, named
demo-all: a file rule,capability net_bind_service,,network inet stream,,network inet tcp ip=127.0.0.1 port=8080,,unix (connect) type=stream peer=(addr=@demo),,dbus send bus=session path=/org/demo,,signal send set=hup,,ptrace read,,mount fstype=tmpfs -> /mnt/demo/,,mqueue (create) type=posix /demo,,userns,,io_uring sqpoll,. The slide shows four of them. apparmor_parser -Q -K demo-all.sdprinted nothing and exited with status 0. With--warn=allit printedWarning from profile demo-all (demo-all.sd): mqueue type=posix rules not enforcedand exited with status 0.-Qcompiles without loading;-Kskips the cache, without which a cached profile is not compiled again and prints no warning. The slide shortens the file name.- A profile with an mqueue rule also loads without a message:
apparmor_parser -aof a profile withmqueue (create, open, read, write, delete) type=posix /demo-ok,exited with status 0 in the same guest. - "Left out" means the compiled profile carries nothing for that kind of rule, so the kernel does not consult the profile for it. An allow rule and a
denyrule are left out alike. - Left out does not mean that the access is open. In the same guest
mq_open("/demo-ok", O_CREAT|O_RDWR)under that profile failed with "Permission denied", and so did every other queue name, with and without an mqueue rule. The kernel logged a file record:apparmor="DENIED" operation="open" class="file" info="Failed name lookup - disconnected path" error=-13 profile="demo-mq" name="demo-ok" pid=1455 comm="python3" requested_mask="wrc" denied_mask="wrc" fsuid=0 ouid=0. The queue is opened as a file on a mount that is attached nowhere, and file mediation refuses a path it cannot resolve. Debian 13 logged the same. See Reading a denial; what kernels with message queue mediation do is in Upstream and Ubuntu kernels. - Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path.
- The two sets and the rule that a class needs its entry in both are the scene "Two feature sets, and what is in both" of The abi rule and the abi files.
for AppArmor developers for security researchers
In the code
set_supported_features(): parser_main.c:1030-1125. The two warning classes are not in the default set: parser.h:77-78, parser_main.c:281-282.
02 What the kernel publishes
/sys/kernel/security/apparmor/features holds one file per fact: 49 files on the test kernel. A missing entry, such as ipc, means rules of that kind are left out. Left out is not open: this kernel still refuses the message queue, as a file with a disconnected path.
The kernel publishes its list as a directory called features, in the AppArmor part of securityfs. Fourteen directories and one file at the top, one per area: file, mount, signal and so on. Inside, each file is one fact. Under namespaces, the mask file says userns_create: user namespace rules. Under network_v9, af_unix says yes: fine-grained unix socket rules. The mount mask lists mount, umount and pivot root. Forty-nine files on our test kernel. What isn't there matters as much. There's no ipc directory: that's the reason for the message queue line. Left out doesn't mean open, though: this kernel still refuses that queue, as a file with a disconnected path.
Details and sources
Details
- The list was read in a Debian sid guest (kernel 7.3.4): every file under the directory with its content, 49 files. They are the entries of the feature tables of the kernel source the map describes, with policy compression configured in, less one: that source also has
network_v8/sctp(net.c:24-36), which makes 50. Thelsoutput on the slide is that list's top level, wrapped over two lines. - All 49, with their values:
capability0xffffff;caps/extendedyes;caps/mask(the capability names);dbus/maskacquire send receive;domain/attach_conditions/xattr,domain/change_hat,domain/change_hatv,domain/change_onexec,domain/change_profile,domain/computed_longest_left,domain/disconnected.path,domain/fix_binfmt_elf_mmap,domain/kill.signal,domain/post_nnp_subset,domain/stack,domain/unconfined_allowed_childrenyes;domain/version1.2;file/maskcreate read write exec append mmap_exec link lock;io_uring/masksqpoll override_creds;mount/maskmount umount pivot_root;mount/move_mountdetached;namespaces/maskuserns_create;namespaces/pivot_rootno;namespaces/profileyes;network_v8/af_maskandnetwork_v9/af_mask(the address family names);network_v8/tcp-fast-open,network_v9/tcp-fast-open,network_v9/af_unixyes;policy/compressed_load,policy/diff-encode,policy/extended_policy_header,policy/set_loadyes;policy/outofband0x000001;policy/permstable32(13 words);policy/permstable32_version0x000003;policy/state320x000001;policy/unconfined_restrictions/change_profileyes;policy/versions/v5tov9yes;ptrace/maskread trace;query/label/data,query/label/multi_transactionyes;query/label/permsallow deny audit quiet;rlimit/mask(the limit names);signal/mask(the signal names). - Not there, and looked for by the parser:
ipc/posix_mqueue(mqueue rules),network_v8/af_inet(ip=andport=),networkandnetwork/af_unix(the older network and unix mediation),network_v9_skb(interface=),domain/interruptible,domain/disconnected.ipc. - No
ipcentry means mqueue rules are left out of every profile compiled for this kernel. It does not mean message queues are open to confined programs: in the same guest, opening a POSIX message queue under a profile was refused, with and without an mqueue rule, and the record on the slide was logged in full asapparmor="DENIED" operation="open" class="file" info="Failed name lookup - disconnected path" error=-13 profile="demo-mq" name="demo-ok" pid=1455 comm="python3" requested_mask="wrc" denied_mask="wrc" fsuid=0 ouid=0. - Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path.
- An entry says the kernel has the code. A class is enforced for a profile only when the profile was compiled with rules for it.
dbus/maskis published by the kernel, although D-Bus rules are enforced by the bus daemon: see D-Bus mediation.- The files are readable by every user. Other kernels publish other lists: see Upstream and Ubuntu kernels.
for AppArmor developers for security researchers
In the code
- The tables: apparmorfs.c:2579-2701, the network entries net.c:24-36. The two entries that depend on
CONFIG_SECURITY_APPARMOR_COMPRESSED_POLICY: apparmorfs.c:2642-2645. - The paths the parser looks up are listed in the reference of The abi rule and the abi files.
03 aa-features-abi: the directory as one text
aa-features-abi -x prints the kernel's feature set as text; -w FILE saves it. An abi file has the same form, so the two can be compared with diff.
You don't have to walk the directory. The aa-features-abi tool does it. With -x it extracts the running kernel's features and prints them as one text: a name, an opening brace, then the value or the nested names, and a closing brace. A hundred and sixteen lines here. With -w it writes the text to a file instead. That text should look familiar: it's the form of the abi files under /etc/apparmor.d. An abi file is a feature list that somebody saved and gave a name. So you can save your kernel's list, carry it to another machine, or compare it with abi/5.0 using diff.
Details and sources
Details
- Run in a Debian sid guest (kernel 7.3.4) with the tool built from the AppArmor tree:
aa-features-abi -x -w FILEexited with status 0 and wrote 116 lines (2482 bytes); the first nine are the ones on the slide, with the capability list shortened. The distribution's ownaa-features-abi -xprinted the same bytes. - Usage:
aa-features-abi [OPTIONS] <SOURCE> [OUTPUT OPTIONS]. Source:-x,--extract(the running kernel) or-f F,--file=F(a file). Output:--stdout(the default) or-w F,--write=F. Options:-d,--debug;-v,--verbose;-h,--help.-xtogether with-fis refused:options --extract and --file are mutually exclusive. -freads a feature file and writes it out again, which checks that the file can be parsed.- The text form: a directory becomes
name {followed by its entries and a}line; a file becomesname {followed by its content, with}on the next line. - The
diffon the slide was made between the saved text of the guest's kernel and theabi/5.0file of the AppArmor tree; the two lines shown are two of its lines. Only inabi/5.0:disconnected.ipc,interruptible, theipcblock,userns_create {pciu&, thenetworkblock,af_inet,metadata_tagging_version, thenotifyblocks, andio_uringandusernsunderunconfined_restrictions. Only in the kernel:tcp-fast-open,compressed_load,diff-encode,extended_policy_header. - Not every difference matters: the parser asks for 24 paths and the capability list, and ignores the rest of a policy feature file. Which path switches on which kind of rule is in the reference of The abi rule and the abi files.
- A feature text can be at most 8192 bytes; the five kernels looked at had 1960 to 3249.
for AppArmor developers for security researchers
In the code
- Options and messages: aa_features_abi.c:50-66, aa_features_abi.c:115-124, aa_features_abi.c:173.
- The directory walk that produces the text, and the size limit: features.c:202-262, features.c:57.
04 Compiling for another kernel
--kernel-features FILE replaces the running kernel's feature set with a file, to compile policy for another kernel. It changes what the parser assumes, not what a kernel can do.
By default the parser takes the kernel's list from the running kernel. With the --kernel-features option you replace it with a file. That's for compiling policy somewhere else: a build machine, a container image, a test. We saved our test kernel's list, took it to a machine without an AppArmor kernel, and the parser gave the same warning and the same bytes. Give it an older list, and more is left out: here user namespace and io_uring rules go as well. One caution. The option changes what the parser assumes, not what the kernel can do. So give it the list of the kernel the policy will run on.
Details and sources
Details
- The first command was run with the tree's parser in a container on a host whose kernel has no part in the run (
-Q -K --skip-kernel-load), with the feature text saved from the Debian sid guest as the file. It printedWarning from profile demo-all (/work/demo-all.sd): mqueue type=posix rules not enforced, and-Swrote 1037 bytes. In the guest itself, with the features read from the running kernel, the warning and the 1037 bytes were the same. The slide shortens the file names and the warning prefix. - The second command was run in the guest, with the
abi/3.0file of the AppArmor tree as the kernel set (the slide writes the installed path). Output, in full:Warning from profile demo-all (demo-all.sd): mqueue type=posix rules not enforced,... userns rules not enforced,... io_uring rules not enforced, exit status 0. The same three lines came out on every kernel tried, because the file replaced the kernel's set. - Without the option the parser reads
/sys/kernel/security/apparmor/features. - The kernel's set decides more than which rules are compiled: the format of the compiled profile (policy version, the form of the permission tables, compression) and the name of the cache directory follow it too. See The binary policy format and the scene "A new kernel, a new cache directory".
- A file that cannot be read:
Failed to load kernel features from 'FILE': ..., exit status 1 (from the source, not run). -M FILE(--features-file) and-m STRING(--match-string) set the kernel's set and pin the policy's set to the same value in one step.- Whether a kernel refuses a profile compiled for a larger feature set than it has was not tried.
- Known discrepancy: apparmor_parser(8) gives
/etc/apparmor.d/cache/.featuresas the default of-M; the parser reads the running kernel when no option is given.
for AppArmor developers for security researchers
In the code
- The option: parser_main.c:697-706. The default, the running kernel: parser_main.c:1726-1740, features.c:584-594.
-mand-M: parser_main.c:669-696.
05 The policy's list, from the command line
For profiles without an abi rule, --policy-features names the policy set: a file or <kernel>. --override-policy-abi also replaces the set of profiles that have an abi rule.
The other list belongs to the policy. A profile names it with its abi rule. But plenty of profiles have no abi rule. Then the parser falls back to an old built-in list and leaves out a lot: network, unix, message queue, user namespace and io_uring rules. For those profiles there's the --policy-features option. It takes a file, or the word kernel in angle brackets: whatever the running kernel has. With that, only the message queue line remains. It doesn't touch profiles with an abi rule. For that there's the --override-policy-abi option: it beats the rule in the file. Use it knowingly: the author chose that line.
Details and sources
Details
- Run in a Debian sid guest (kernel 7.3.4, whose 49 feature files are the entries of the kernel source the map describes less one,
network_v8/sctp, which no rule on these slides needs) with the parser built from the AppArmor tree,--config-file=/dev/null -K, the kernel features read from the running kernel. The profile is the twelve-rule profile with its first line removed; all runs had-Q --warn=alland exit status 0. The slide writes the installed path of the abi file; the runs used the copy from the AppArmor tree. - No option:
Warning from demo-all-noabi.sd (demo-all-noabi.sd line 1): .../apparmor_parser: File 'demo-all-noabi.sd' missing feature abi, falling back to default policy feature abi, thennetwork rules not enforced(three times),extended network unix socket rules not enforced,mqueue type=posix rules not enforced,userns rules not enforced,io_uring rules not enforced, and a lineprofile demo-all network rules not enforced. - Without
--warn=allthe same file prints nothing: the "missing feature abi" warning belongs to the warning classabi, which is off by default (run with the tree's parser outside a guest). --policy-features FILEwithabi/3.0:downgrading extended network unix socket rule to generic network rule,mqueue type=posix rules not enforced,userns rules not enforced,io_uring rules not enforced.--policy-features "<kernel>":mqueue type=posix rules not enforcedonly. The word must reach the parser with its angle brackets, so quote it in a shell. It always means the running kernel, also when--kernel-featuresnames a file: on a machine without an AppArmor kernel the tree's parser stopped withFailed to load kernel features into the policy-features abi: No such file or directory, exit status 1 (run with the tree's parser outside a guest).--override-policy-abi FILEwithabi/3.0, on the profile that hasabi <abi/5.0>,: the same four lines as--policy-featureswithabi/3.0on the profile without the rule. It also accepts<kernel>.--compile-featuresis the older name of--policy-features.- The manual:
--policy-features"does not override feature ABI rules";--override-policy-abidoes. - A file that cannot be read:
Failed to load policy-features from 'FILE': ..., exit status 1 (from the source, not run). - The order of all the sources of the policy set, and what the built-in default lacks, is the scene "Who decides the policy ABI" of The abi rule and the abi files.
- Known discrepancy: Two "not enforced" warnings are printed for rules that are compiled.
for AppArmor developers for security researchers
In the code
- The two options: parser_main.c:707-740; their names: parser_main.c:196-200.
06 parser.conf: a pin for the whole system
policy-features=FILE in /etc/apparmor/parser.conf pins every profile without an abi rule. Debian ships such a line, Ubuntu none. A profile's own abi rule wins over the pin.
Options on a command line are forgotten. The parser's config file isn't: every long option can go into parser.conf, one per line. A policy features line there pins every profile without an abi rule to one list, on every load, including at boot. The shipped file has two examples, commented out. What do real systems do? The Debian systems we looked at ship a pin, to a file of their own. The Ubuntu ones ship none. So the same profile without an abi rule can mean different things on the two. And a profile with an abi rule isn't affected: its own line wins over the pin.
Details and sources
Details
- The config file is read before the command line, on every run of the parser, so also when policy is loaded at boot.
--config-file FILEnames another file;--print-config-fileprints which one is used. - The shipped file has the two commented lines
#policy-features=/etc/apparmor.d/abi/kernel-5.4-vanillaand#policy-features=/etc/apparmor.d/abi/kernel-5.4-outoftree-network, and says that only one should be used at a time. It also has#warn=no-abi, to switch the abi warnings off without a pin. - Run with the tree's parser outside a guest (kernel set: the tree's
abi/5.0file,--warn=all): with a config file holdingpolicy-features=.../abi/3.0, the twelve-rule profile without an abi rule printedmqueue type=posix rules not enforced,userns rules not enforcedandio_uring rules not enforced, and no "missing feature abi" line. The same profile withabi <abi/5.0>,printed nothing: the abi rule won over the pin. Withpolicy-features=.../abi/5.0andwarn=allboth in the config file, the profile without an abi rule printed nothing. - What distributions ship was read in guests:
/etc/apparmor/parser.confon Debian 13 and Debian sid has one line that is not a comment,policy-features=/usr/share/apparmor-features/features. On Ubuntu 24.04, 26.04 and 26.10 every line is a comment. The content of Debian's features file was not examined. - Without a pin and without an abi rule a profile gets the parser's built-in default set: see the scene "The policy's list, from the command line" for what that leaves out.
- A later
policy-features=line replaces an earlier one. - Other keys of the file are in parser.conf, warnings and debug flags.
for AppArmor developers for security researchers
Attack surface
- The file changes which mediation classes every profile without an abi rule gets, on every load and without a message. Who can write it can weaken policy without touching a profile. See Who can change policy.
for AppArmor developers for security researchers
In the code
- The shipped file: parser.conf:65-81. Reading it: parser_main.c:967-981, parser_main.c:1820. A later value replaces the earlier: parser_main.c:707-723.
07 Seeing what was left out
-Q -K --warn=all lists what was left out or downgraded (without -K a cached profile is not compiled again and prints nothing); -D rule-exprs shows what was compiled; --Werror with the warning enabled fails the compile. ip= and port= conditions are dropped with no message.
So how do you find out what your profiles lost? By default you don't: no message, exit status zero. Three things help. --warn=all, with -Q so nothing is loaded and -K to skip the cache, prints a line for each kind of rule left out or downgraded. The rule expression dump shows what was compiled: for our twelve rules, twenty-four lines on one kernel and sixty-seven on another. And --Werror, with the same warning switched on, turns a left-out rule into a failed compile: what a build wants. A gap remains: address and port conditions the kernel can't check go without any message.
Details and sources
Details
- Run in a Debian sid guest (kernel 7.3.4, whose 49 feature files are the entries of the kernel source the map describes less one,
network_v8/sctp, which no rule on these slides needs) with the parser built from the AppArmor tree,--config-file=/dev/null -K, the kernel features read from the running kernel. The slide shortens file names and writes...forapparmor_parser. apparmor_parser -Q -K demo-all.sd: no output, exit status 0. With--warn=all:Warning from profile demo-all (demo-all.sd): mqueue type=posix rules not enforced, exit status 0.- Why
-K: the warnings are printed while a profile is compiled. Reading the cache is on by default and-Qdoes not turn it off, so for a profile that has a fresh cache entry, which is the normal state of the files in/etc/apparmor.d, the parser takes the compiled profile from the cache and prints no warning.-K(--skip-cache) or-T(--skip-read-cache) makes it compile.-Dand-Sskip reading the cache by themselves. See The policy cache. - The two warning classes are
rule-not-enforced("warn if a rule is not enforced") andrule-downgraded("warn if a rule is downgraded to a lesser but still enforcing rule"). Neither is in the default set.--help=warnlists all classes;--warn=allswitches every class on, so it prints other warnings too. A linewarn=rule-not-enforcedin parser.conf makes it permanent. -D rule-exprsprints onerule:line per compiled rule. For the twelve-rule profile withabi <abi/5.0>,: 24 lines in the Debian sid guest. "Another kernel" is the Ubuntu 26.04 guest (kernel 7.0), where the same command gave 67 and--warn=allprinted nothing; Ubuntu 24.04 gave 66 and Debian 13 gave 19. See Upstream and Ubuntu kernels.- The
--Werrorrun was made with the tree's parser outside a guest, with the feature text saved from the Debian sid guest as the kernel set. With--warn=rule-not-enforced --Werror=rule-not-enforcedit printedWarning converted to Error from profile demo-all (/work/demo-all.sd): mqueue type=posix rules not enforcedand exited with status 1. - Known discrepancy:
--Werror=rule-not-enforcedwithout--warn=rule-not-enforcedexits with status 1 and prints nothing. Seen in the same run without the--warnoption, and with a bare--Werror. - What prints nothing even with
--warn=all, recorded in the research notes with the tree's parser:ip=andport=on a network rule when the kernel has nonetwork_v8/af_inet(the rule is kept as a family and type rule),interface=withoutnetwork_v9_skb/iface, and the flagattach_disconnected.ipc. - Known discrepancy: inet conditionals are dropped silently when the kernel has no
af_inet, sodenyrules get wider. Seen on the running Debian sid kernel: withnetwork inet stream,anddeny network (connect) inet stream peer=(ip=127.0.0.1 port=25),a connect to port 22 was refused as well as one to port 25. - Known discrepancy:
attach_disconnected.ipcis dropped without a warning and its bit is written anyway. - Known discrepancy: Only the first "Ignoring" warning of a profile is printed.
- A kind of rule that was left out leaves no audit record of its own class at run time: the kernel does not consult the profile for it. That does not make the access open. On this kernel a POSIX message queue is still refused, and the record is a file record with
info="Failed name lookup - disconnected path". See the scene "What the kernel publishes" and Reading a denial. - Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path.
for AppArmor developers for security researchers
In the code
- The classes: parser_main.c:281-282; the default set: parser.h:77-78. The warning that is printed once per profile, and its exit under
--Werror: parser_common.c:169-186.
08 A new kernel, a new cache directory
The cache directory is named after a hash of the kernel's feature text. A kernel with a different feature set gets a new directory and every profile is compiled again. --print-cache-dir prints the one in use.
One more place where the kernel's list shows up: the cache. The parser keeps compiled profiles in a directory named after a hash of the kernel's feature text. Five kernels, five different names. A compiled profile is only right for the list it was compiled against, so a kernel with a different list gets a directory of its own. For you it explains two things. After a kernel upgrade that changes the list, the first load is slower, because every profile is compiled again. And the old directory stays behind, ready if you boot the old kernel. To see which one is in use, there's the --print-cache-dir option.
Details and sources
Details
apparmor_parser --print-cache-dirwas run with the distribution's parser in five guests. Debian 13 (kernel 6.12.116):/var/cache/apparmor/979b3ac6.0. Ubuntu 24.04 (6.8.0-147):b8ec2925.0. Ubuntu 26.04 (7.0.0-43):f6da0254.0. Debian sid (7.3.4):48da56f3.0. Ubuntu 26.10 (7.3.0-10):0bd21c56.0. "Another 7.3" on the slide is the Ubuntu 26.10 kernel: the same kernel version as Debian sid's with a different feature set. Each guest's/var/cache/apparmor/held exactly that one directory.- The tree's parser, run outside a guest with
--kernel-featuresnaming the feature text saved from the Debian sid guest, printed/var/cache/apparmor/48da56f3.0as well: the name depends on the feature text and on nothing else of the machine. - The name is the hash as eight hexadecimal digits, a dot and a number. The number is 0 unless two different feature texts have the same hash; then the next free number is used.
- Two kernel versions with the same feature text share a directory. The feature text is the kernel's set, whether read from the running kernel or given with
--kernel-features. The policy set does not enter the name. - "Every profile is compiled again" follows from the new directory being empty; it was not timed. Whether old directories are ever removed is a matter of the distribution's packaging and was not examined.
- How the cache decides that an entry is fresh, and the options that control it, are in The policy cache.
for AppArmor developers for security researchers
In the code
- The directory name: policy_cache.c:249-297. The hash, a 32-bit MurmurHash3 of the text: features.c:255-270. The option: parser_main.c:1128-1150.
09 From the feature files to the rules they switch on
The feature directory, aa-features-abi, --kernel-features, --policy-features, parser.conf and --warn=all. Roads: the abi rule, the parser and its config, the cache, other kernels.
That's the administrator's side of features. The kernel publishes its list as a directory, and aa-features-abi prints it as text. Then the --kernel-features option and the --policy-features option replace the two lists, and parser.conf pins the policy's list. Nothing is printed when a rule is left out, unless you ask with --warn=all. From here: the deck on the abi rule, for the line inside a profile and the shipped files. Running the parser, its config file and the cache have their own decks. Upstream and Ubuntu kernels compares the lists of different kernels. And reading a denial covers the rules that made it in.
Details and sources
Read more
- The abi rule and the abi files.
- Running apparmor_parser, parser.conf, warnings and debug flags, The policy cache.
- Upstream and Ubuntu kernels, Reading a denial.
- The features API, apparmorfs, The binary policy format.
- apparmor_parser(8), --kernel-features, apparmor_parser(8), --policy-features, aa-features-abi(1), wiki: apparmorpolicyfeaturesABI.
Read more
Basis of the statements on this page: "guest" means the command was run in a disposable virtual machine with the parser and aa-features-abi built from the AppArmor commit 836052d21 (--config-file=/dev/null -K, kernel features read from the running kernel unless an option says otherwise). The main guest is Debian sid with kernel 7.3.4, whose 49 feature files are the entries of the feature tables of the kernel source the map describes less one (network_v8/sctp). "tree" means the tree's parser was run without a kernel (-Q -K --skip-kernel-load), with the kernel set named. "source" means read and not run. The abi rule, the shipped abi files and the table of which entry switches on which kind of rule are in The abi rule and the abi files and are not repeated here.
The feature directory
/sys/kernel/security/apparmor/features, readable by every user. Top level on the kernel: capability (a file) and the directories caps, dbus, domain, file, io_uring, mount, namespaces, network_v8, network_v9, policy, ptrace, query, rlimit, signal.
| Entry | Value (guest) | What it switches on |
|---|---|---|
file/mask | create read write exec append mmap_exec link lock | file rules (always compiled) |
network_v8, network_v9 | directories | network rules |
network_v9/af_unix | yes | fine-grained unix rules |
mount/mask | mount umount pivot_root | mount, umount and pivot_root rules |
mount/move_mount | detached | read from the kernel set only |
signal/mask, ptrace/mask | the signal names; read trace | signal and ptrace rules |
dbus/mask | acquire send receive | dbus rules are compiled (the bus daemon enforces them) |
namespaces/mask | userns_create | userns rules |
io_uring/mask | sqpoll override_creds | io_uring rules |
domain/stack | yes | stacking (& targets) |
domain/attach_conditions/xattr | yes | xattrs= on a profile |
domain/kill.signal | yes | flags=(kill.signal=...) |
caps/mask | the capability names | which capability names are known |
policy/versions/v5 to v9, policy/permstable32, policy/permstable32_version, policy/state32, policy/outofband, policy/set_load, policy/diff-encode, policy/compressed_load, policy/extended_policy_header | yes or a number | the format of the compiled profile |
policy/unconfined_restrictions/change_profile | yes | |
query/label/* | the query interface | |
not present: ipc/posix_mqueue, network_v8/af_inet, network, network/af_unix, network_v9_skb, domain/interruptible, domain/disconnected.ipc | mqueue rules; ip= and port=; the older network and unix mediation; interface=; two profile flags |
aa-features-abi
aa-features-abi [OPTIONS] <SOURCE> [OUTPUT OPTIONS]
SOURCE: -x, --extract the running kernel
-f F, --file=F a feature file
OUTPUT: --stdout the default
-w F, --write=F a file
OPTIONS: -d, --debug -v, --verbose -h, --help
Guest: -x -w FILE wrote 116 lines. -x with -f: options --extract and --file are mutually exclusive (source). The text form: name {content and } for a file, name { ... } for a directory.
Options that set the feature sets
| Option | Sets | Value | Beats an abi rule |
|---|---|---|---|
| (none) | kernel set: the running kernel. Policy set: the file's abi rule, else the built-in default | ||
--kernel-features FILE | the kernel set | a feature file | not applicable |
--policy-features FILE (older name --compile-features) | the policy set of files without an abi rule | a file or <kernel> | no |
--override-policy-abi FILE | the policy set of every file | a file or <kernel> | yes |
-M FILE, --features-file FILE | both: the kernel set, and the policy set as with --policy-features | a file | no |
-m STRING, --match-string STRING | both, from a string | feature text | no |
policy-features=FILE in parser.conf | as --policy-features, on every run | no |
Guest, the twelve-rule profile, -Q -K --warn=all:
| Profile and option | Output (prefix left out) |
|---|---|
with abi <abi/5.0>, | mqueue type=posix rules not enforced |
with it, --kernel-features abi/3.0 | mqueue, userns and io_uring rules not enforced |
with it, --override-policy-abi abi/3.0 | downgrading extended network unix socket rule to generic network rule; mqueue, userns, io_uring not enforced |
| without an abi rule | File '...' missing feature abi, falling back to default policy feature abi; network (three lines), extended network unix socket rules not enforced, mqueue, userns, io_uring not enforced |
without, --policy-features "<kernel>" | mqueue type=posix rules not enforced |
without, --policy-features abi/3.0 | the unix rule downgraded; mqueue, userns, io_uring not enforced |
Every run exits with status 0. Without --warn=all none prints anything (tree).
parser.conf
/etc/apparmor/parser.conf: every long option as name=value or name, one per line, read before the command line. --config-file FILE names another file.
| System (guest) | Active lines |
|---|---|
| the shipped file of the tree | none; two commented policy-features= examples |
| Debian 13, Debian sid | policy-features=/usr/share/apparmor-features/features |
| Ubuntu 24.04, 26.04, 26.10 | none |
Tree: a pin to abi/3.0 removes the "missing feature abi" warning of a profile without an abi rule and leaves mqueue, userns and io_uring rules out; a profile with abi <abi/5.0>, is compiled against abi/5.0 whatever the pin says.
Seeing what was left out
| Command | Shows |
|---|---|
apparmor_parser -Q -K --warn=all FILE | one line per kind of rule left out or downgraded, per profile; also every other warning. Without -K (or -T) a profile with a fresh cache entry is not compiled again and prints nothing |
--warn=rule-not-enforced, --warn=rule-downgraded | only these two classes |
apparmor_parser -Q -D rule-exprs FILE | the compiled rules, one rule: line each |
-K --warn=rule-not-enforced --Werror=rule-not-enforced | exit status 1 and Warning converted to Error ... |
apparmor_parser --help=warn | the warning classes |
Known discrepancies: --Werror=rule-not-enforced without --warn=rule-not-enforced exits with status 1 and prints nothing; inet conditionals are dropped silently when the kernel has no af_inet, so deny rules get wider; attach_disconnected.ipc is dropped without a warning and its bit is written anyway; Two "not enforced" warnings are printed for rules that are compiled; Only the first "Ignoring" warning of a profile is printed.
The same profile on five kernels
The twelve-rule profile with abi <abi/5.0>,, compiled in each guest by the tree's parser with -Q -K --warn=all. Which kernel has which entry, and why, is Upstream and Ubuntu kernels.
| Guest kernel | Feature files | Warnings | rule: lines | Cache directory |
|---|---|---|---|---|
| Debian 13, 6.12.116 | 38 | unix rule downgraded; dbus and mqueue rules not enforced | 19 | 979b3ac6.0 |
| Ubuntu 24.04, 6.8.0-147 | 51 | none | 66 | b8ec2925.0 |
| Ubuntu 26.04, 7.0.0-43 | 67 | none | 67 | f6da0254.0 |
| Debian sid, 7.3.4 | 49 | mqueue rules not enforced | 24 | 48da56f3.0 |
| Ubuntu 26.10, 7.3.0-10 | 68 | none | 67 | 0bd21c56.0 |
The cache directory
<cache location>/<hash>.<n>: the hash is eight hexadecimal digits computed from the kernel set's text; n is 0 unless two texts collide. apparmor_parser --print-cache-dir prints it. Tree: with --kernel-features naming the text saved from the Debian sid guest, the name is the guest's, 48da56f3.0.
for AppArmor developers for security researchers
In the code
- Kernel tables: apparmorfs.c:2579-2701, net.c:24-36.
- Reading a feature set and turning a directory into text: features.c:202-262, features.c:584-594.
- Parser options: parser_main.c:669-740; the switches computed from the two sets: parser_main.c:1030-1125; values read from the kernel set only: parser_main.c:1726-1776.
- Config file: parser_main.c:967-981; the shipped file parser.conf:65-81.
- Warnings: parser_main.c:281-283, parser.h:77-78, parser_common.c:169-186.
- Cache directory: policy_cache.c:249-297.
for security researchers
Attack surface
- Three things outside any profile change which kinds of rule exist in loaded policy, with exit status 0 and no default message: the kernel's feature set (a kernel without an entry),
parser.conf(policy-features=), and the options given by whatever loads policy at boot. - A
denyrule is left out like any other rule of its kind. - A kind of rule that was left out produces no audit record of its own class at run time. The access is not always open: Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path.
Roads from here
START HERE
- Upstream and Ubuntu kernels — kernels with more entries than this one
PREAMBLE AND REUSE
- The abi rule and the abi files — the abi rule and the shipped abi files
RUNNING THE PARSER
- Running apparmor_parser (no slides yet) — every option of the parser
- parser.conf, warnings and debug flags (no slides yet) — parser.conf and the warning classes
- The policy cache (no slides yet) — the cache that is keyed by the kernel feature set
- Reading a denial — reading the records of the rules that are enforced
LIBAPPARMOR
- The features API (no slides yet) — the API that reads feature sets
IN THE KERNEL
- apparmorfs (no slides yet) — the filesystem the feature files live in
THE DFA ENGINE · libapparmor_re
- The binary policy format — the feature set changes the encoding