The abi rule and the abi files

pinning the feature ABI for application developers for administrators for security researchers

The abi rule names the feature file a profile was written for and so freezes what its text means. A rule class is compiled only when that file and the kernel both have its entry. The first abi rule of a file counts and it must stand in the preamble. Without one the parser uses an option given on the command line or else an old built-in default. Seven files ship in abi/. With an older file userns and mqueue and io_uring rules are left out and unix rules are downgraded and by default nothing is printed. New profiles name abi/5.0.

On the map: preamble and reuse

▶ Watch this deck — 13 scenes, ~10 min

Worth seeing first

  • The preamble — the preamble, where the abi line stands
  • include — the file search in angle brackets that abi shares

Part of journeys

01 Why a profile names an ABI

WHY AN ABI LINE the abi line freezes what the text means an example: a future AppArmor 6 learns to mediate something new abi/5.0 cannot express it not checked: stays allowed abi/6.0 can express it; the text says nothing denied by default it has happened before: the same text, two abi lines abi <abi/3.0>, profile demo /usr/bin/demo { /etc/demo/** r, } abi <abi/5.0>, profile demo /usr/bin/demo { /etc/demo/** r, } user namespaces, io_uring sqpoll not checked: allowed user namespaces, io_uring sqpoll checked, no rule: denied on a kernel that mediates them: see "The file offers, the kernel decides"
The abi line freezes what the profile text means. An example of a future release: if AppArmor 6 learns to mediate something new, a profile that names abi/5.0 cannot express it, so it is not checked and stays allowed; under a future abi/6.0 the same text can express it and says nothing, so it is denied by default. The case that has happened: the same profile, with one file rule and no userns or io_uring rule, under two abi lines. With abi <abi/3.0>, user namespaces and io_uring sqpoll are not checked and are allowed. With abi <abi/5.0>, they are checked, there is no rule, and they are denied. This holds on a kernel that mediates them; the kernel's part is the scene The file offers, the kernel decides.

The abi line freezes what a profile's text means. What its abi file cannot express is not checked for the profile, so it stays allowed; under a newer file the same text denies whatever it does not allow.

Why does a profile name an abi file? So that an old profile keeps its old meaning: the line freezes what the text means. Suppose a future AppArmor 6 mediates something new. A profile naming abi/5.0 had no way to mention it. For that profile it isn't checked, and stays allowed. Under a future abi/6.0, the profile could allow it, but its text doesn't, so the default applies: deny. It's happened before. Take demo's profile with one file rule. Under abi/3.0, user namespaces and io_uring aren't checked. Under abi/5.0 they are, and they're denied. The kernel's part comes later.

Details and sources

Details

  • The principle is the manual's: "If the kernel supports a feature not supported by the policy then policy will be built so that the kernel does NOT enforce that feature" (apparmor.d.pod:2833-2834). A profile lists what is allowed and everything else of a checked class is denied, so a class that the profile's abi file cannot express has to be left unchecked for that profile, or every profile written before the class existed would start to deny it.
  • The top row is an example of a future release, not a statement about one. There is no abi/6.0 file in the tree, and nothing here says what a later AppArmor will mediate. abi/5.0 and abi/6.0 stand for "the file the profile was written for" and "a later file that has an entry for the new class".
  • The bottom row was run for this deck with the tree's parser (apparmor_parser -Q -K --skip-kernel-load -D rule-exprs, kernel feature set written from the kernel source, nothing loaded into a kernel). The profile is profile demo /usr/bin/demo { /etc/demo/** r, } with one abi line in front. With abi <abi/3.0>, its marker lines are \d2, \d7, \d32, \d10, \d9 and \d14. With abi <abi/5.0>, there are four more: \d21 (user namespaces), \d22 (io_uring), \d15 and \d15\0001 (unix sockets). Both runs print nothing and exit with status 0.
  • A marker makes the kernel check the class for the profile. A class that is checked and has no rule is denied: for creating a user namespace at task.c:388, for io_uring sqpoll and override_creds at lsm.c:638. Without the marker both hooks let the access through. The markers were printed by the parser; "allowed" and "denied" on the slide are taken from the kernel source and were not observed on a running kernel.
  • The abi rule is used at compile time only. It is not part of what the kernel receives.
  • "Allowed" means AppArmor does not check it for this profile. Other limits on user namespaces and io_uring (sysctls, capabilities, seccomp) are untouched.
  • "On a kernel that mediates them": the newer file only offers the class. It is checked when the kernel has the entry too, which the kernel source the map describes has for both. That half is the scene "The file offers, the kernel decides".
  • The third class in this run, unix sockets (\d15), is not on the slide: with abi/5.0 the profile's unix sockets are matched by unix rules. See the scene "Some rules stay, but say less".
  • What to do when you raise the line on an old profile is in the scene "Mistakes and what you see": add the rules the program needs and test in complain mode.

for AppArmor developers for security researchers

In the code

Read more

02 abi, a feature file, a comma

GRAMMAR abi <magic/path> "path" <kernel> <default> , abi <abi/5.0>, line 1 of demo's file: the comma is required, unlike include found like an include: the -I directories, then /etc/apparmor.d /etc/apparmor.d/abi/ 3.0 4.0 4.0-ip 5.0 5.0-interface kernel-5.4-vanilla ... opened as written abi "/etc/apparmor.d/abi/5.0", not a file: the kernel's own feature set not a file: the parser's built-in default, the same as writing no abi rule
Syntax diagram: the keyword abi, then one of a magic path in angle brackets, a quoted path, the special name <kernel> or the special name <default>, then a comma. A magic path is found like an include; the shipped feature files are in /etc/apparmor.d/abi: 3.0, 4.0, 4.0-ip, 5.0, 5.0-interface, kernel-5.4-vanilla and more. A quoted path is opened as written, for example abi "/etc/apparmor.d/abi/5.0". <kernel> is the kernel's own feature set and <default> is the parser's built-in default. The comma is required, unlike include.

abi <abi/5.0>, or abi "path",. <kernel> and <default> are special names. The comma is required.

The rule looks like an include with a different keyword, and one important difference: it ends with a comma. After the word abi comes a file name. In angle brackets it's searched for the way includes are, and the shipped feature files live in a directory called abi. In quotes it's opened as written. Two names in angle brackets aren't files at all. Kernel means the kernel's own feature set, and default means the parser's built-in set. The manual warns against kernel in shipped profiles, because the profile's meaning would change with every new kernel.

Details and sources

Details

  • The manual's grammar: ABI = ( 'abi' ) ( ABS PATH | MAGIC PATH | '<kernel>' | '<default>' ) ',' (apparmor.d.pod:120).
  • Shipped feature files in profiles/apparmor.d/abi/: 3.0, 4.0, 4.0-ip, 5.0, 5.0-interface, kernel-5.4-outoftree-network, kernel-5.4-vanilla.
  • A magic path is searched for like an include: the -I directories, then the base directory. See include.
  • A bare path is accepted like the quoted form: abi simple_tests/includes/abi/4.19 , (abi/ok_16.sd, a test the parser is expected to accept). The quoted form is that of the neighbouring tests in that directory, for example abi "simple_tests/includes/abi/4.19", (abi/ok_1.sd). The quoted line on the slide, abi "/etc/apparmor.d/abi/5.0",, was run with the tree's parser for this deck with the path of the feature file in the test image (/src/apparmor/profiles/apparmor.d/abi/5.0) in place of /etc/apparmor.d/abi/5.0: with a userns, rule and --warn=all it prints nothing and exits with status 0.
  • <kernel>: "should never be used in shipped policy as it can cause system breakage when a new kernel is installed". "The special abi default is equivalent to not specifying an ABI" (apparmor.d.pod:2840-2844).
  • Only the angle-bracket form is special: abi "kernel", opens a file called kernel (derived).
  • Recorded in the research notes, with --warn=all and a profile holding userns,: abi <kernel>, prints nothing; abi <default>, prints userns rules not enforced.
  • In the runs behind this scene and the scenes "Two feature sets, and what is in both", "Who decides the policy ABI" and "Left out without a word" the kernel's feature set was the tree's abi/5.0 file, given to the parser as an option; no running kernel was consulted. The scenes on the files, from "Seven files, and you name one" on, use a kernel feature set written from the kernel source.
  • Known discrepancy: apparmor_parser(8) describes -b and -I in terms that do not match the code.

for AppArmor developers for security researchers

In the code

03 Two feature sets, and what is in both

POLICY ABI AND KERNEL ABI policy ABI from the abi rule kernel ABI from the kernel compiled abi <abi/3.0>, profile demo /usr/bin/demo { userns, /x r, } a different profile: the research run userns $ apparmor_parser -Q --warn=all demo Warning from profile demo (...): userns rules not enforced abi <abi/4.0>, in line 1 instead: no output abi/3.0: 4401 bytes abi/4.0: 4481 bytes the compiled profile really differs left out is not an error: exit status 0 both times
Two overlapping sets: the policy ABI, from the abi rule, and the kernel ABI, from the kernel; only what is in both is compiled. A research profile has abi <abi/3.0>, and a userns rule; userns is in the kernel's set only. With --warn=all the parser prints Warning from profile demo: userns rules not enforced. With abi <abi/4.0>, there is no output and userns is compiled. The compiled profile is 4401 bytes with abi/3.0 and 4481 bytes with abi/4.0. Exit status 0 both times.

A rule class is compiled only if the policy ABI and the kernel ABI both have it. With abi/3.0, userns, is left out.

The parser works with two feature sets. The policy ABI is what your abi rule names. The kernel ABI is what the kernel says it can do. A kind of rule is compiled only if it's in both. Here's a small profile with a user namespace rule, and abi/3.0 as its policy ABI. That set knows nothing of user namespaces, so the rule is left out, and only if you ask for all warnings does the parser say so. Name abi/4.0 and the rule is compiled. You can see it in the size of the result: eighty bytes more.

Details and sources

Details

  • Recorded in the research notes, with --warn=all: the profile on the slide with abi <abi/3.0>, prints Warning from profile demo (/work/ab1.sd): userns rules not enforced, and -S writes 4401 bytes. With abi <abi/4.0>, there is no output and -S writes 4481 bytes. Both were run again for this deck with the same result for the warning. /work/ab1.sd is the scratch name of the file; the slide shows (...).
  • Without --warn=all the first run prints nothing and exits with status 0. The warning classes for left-out rules are off by default: see Running apparmor_parser.
  • In these runs the kernel's feature set was the tree's abi/5.0 file, given with --kernel-features, not a running kernel. That set has user namespace mediation.
  • The kernel publishes its own feature set under /sys/kernel/security/apparmor/features: see Kernel features and the policy ABI.
  • What the kernel then does with a profile depends only on what was compiled in (apparmor.d.pod:2829-2838).
  • The research profile replaces demo's file here because demo's file names abi/5.0, with which nothing is left out.

for AppArmor developers for security researchers

In the code

04 Who decides the policy ABI

THE ORDER --override-policy-abi FILE the first abi rule in the preamble --policy-features FILE the built-in default abi <abi/3.0>, --override-policy-abi .../abi/4.0 userns compiled the option replaces the file's rule abi <abi/3.0>, --policy-features .../abi/4.0 userns rules not enforced the rule wins over the pin no abi rule, --policy-features .../abi/4.0 userns compiled no abi rule, no option File '...' missing feature abi, falling back to default policy feature abi userns rules not enforced top to bottom: the first that applies decides the same file can be compiled with a different policy ABI: look at the command line as well as at line 1
A ladder of four sources, top to bottom: --override-policy-abi FILE, the first abi rule in the preamble, --policy-features FILE, the built-in default. Recorded runs with a userns rule: abi/3.0 in the file with an override to abi/4.0 compiles userns; abi/3.0 in the file with a pinned abi/4.0 prints userns rules not enforced; no abi rule with a pinned abi/4.0 compiles userns; no abi rule and no option prints the missing feature abi warning and userns rules not enforced. The first source that applies decides, so the command line matters as well as the first line of the file.

Override option, then the file's first abi rule, then the pinned set, then the built-in default. Warnings of class abi are off by default.

Where does the policy ABI come from? There's a fixed order. At the top, an option on the parser's command line that overrides whatever the file says. Then the first abi rule in the file's preamble. Then a second option, which pins a feature set, but only for files that have no abi rule. And at the bottom, a default built into the parser, which is old and lacks newer features. The first of these that applies decides the policy ABI for the whole file. So when a rule goes missing, check how the parser was started as well as what the file says.

Details and sources

Details

  • All runs are recorded in the research notes and use the profile with userns, of the scene before, with --warn=all.
  • abi <abi/3.0>, with --override-policy-abi /src/apparmor/profiles/apparmor.d/abi/4.0: no userns warning.
  • abi <abi/3.0>, with --policy-features .../abi/4.0: userns rules not enforced.
  • No abi rule, with --policy-features .../abi/4.0: no warning at all.
  • No abi rule and no option: Warning ... File '/work/ab3.sd' missing feature abi, falling back to default policy feature abi, then Warning from profile demo (/work/ab3.sd): userns rules not enforced.
  • Not on this slide (it is a row of the scene "Mistakes and what you see"): two rules, abi <abi/3.0>, then abi <abi/4.0>,: Warning from /work/ab4.sd (/work/ab4.sd line 2): ... /work/ab4.sd features abi 'abi/4.0' differs from policy declared feature abi, using the features abi declared in policy, then userns rules not enforced. In the other order the same warning names abi/3.0 and userns is compiled. The same rule twice draws no warning.
  • The slide shortens paths to .... The file names under /work/ are scratch names.
  • --policy-features is also spelled --compile-features; -M and -m set it together with the kernel features. The options accept '<kernel>' as a value.
  • Both warnings of class abi are off by default; --warn=abi or --warn=all turns them on.
  • The policy ABI is settled once per file, when the first profile begins, and reset for the next file.
  • Recorded for an abi rule inside a profile body with no abi rule in the preamble (--warn=all): the missing-abi warning for line 1, then the "differs" warning for the body's line, then userns rules not enforced.
  • Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect.
  • Known discrepancy: Without an abi rule, xattrs= is dropped silently and change_profile -> &x is refused "by the kernel".

for AppArmor developers for security researchers

In the code

05 Seven files, and you name one

THE ABI FILES abi <abi/5.0>, profile demo /usr/bin/demo { /etc/demo/** r, 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, } demo's profile from here on: one rule of every kind /etc/apparmor.d/abi/ kernel-5.4-vanilla kernel-5.4-outoftree-network 3.0 4.0 4.0-ip 5.0 5.0-interface each file is a list of what a kernel can mediate, frozen at an AppArmor release 5.0 almost all of it is compiled ? an older file: some of these three rules are left out, and nothing is printed
Demo's profile from here on: the line abi <abi/5.0>, and one rule of every kind, among them network, unix, dbus, signal, ptrace, mount, mqueue, userns and io_uring. The directory /etc/apparmor.d/abi/ holds seven files: kernel-5.4-vanilla, kernel-5.4-outoftree-network, 3.0, 4.0, 4.0-ip, 5.0 and 5.0-interface. Each file is a list of what a kernel can mediate. The abi line names the file 5.0. With an older file such as 3.0 or 4.0, the mqueue, userns and io_uring rules are compiled or left out depending on the file.

The abi rule names one of seven feature files in /etc/apparmor.d/abi/. Which one you name decides which rule classes of the profile are compiled.

Demo's profile starts with an abi line. From here on the profile has grown: it now has one rule of every kind, so you can watch what that line does to each. The name in the line is a real file. It's one of seven that ship in a directory called abi. Each one is a plain list of what a kernel can mediate, frozen at some AppArmor release. Name abi/5.0, and almost all of demo's profile is compiled. Name an older file, and some of these rules quietly stop counting. So let's go through the files, and find the line you should write.

Details and sources

Details

  • The seven files are in profiles/apparmor.d/abi/ of the tree and are installed as /etc/apparmor.d/abi/: 3.0, 4.0, 4.0-ip, 5.0, 5.0-interface, kernel-5.4-outoftree-network, kernel-5.4-vanilla. There is no 6.0 file.
  • A feature file has the same text form as what the kernel publishes under /sys/kernel/security/apparmor/features: a directory becomes name {...} and a file becomes name {content} (features.c:53). The format is in Kernel features and the policy ABI.
  • The profile on the slide is not the running example of the neighbouring decks, and not the two-rule profile of the scene "Two feature sets, and what is in both". The running example has only file rules, which no abi file changes. This is the profile of the research notes, the same program with one rule per rule class:
abi <abi/5.0>,
profile demo /usr/bin/demo {
  /etc/demo/** r,
  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,
}
  • "Almost all": with abi <abi/5.0>, and the kernel's feature set, one rule of this profile is left out, the mqueue rule. The run is in the scene "The same profile under 3.0, 4.0 and 5.0".
  • Only abi/5.0 is named by shipped policy: under profiles/apparmor.d 345 lines are abi <abi/5.0>, (210 in column 0, 135 indented: 134 in abstractions and one in apache2.d/phpsysinfo) and 111 under profiles/apparmor/profiles/extras. No other file is named.
  • aa-genprof and aa-autodep write abi <abi/5.0>, into a new profile (aa.py:516-517), and the tree's build fails for a shipped abstraction (profiles/Makefile:171-176) or profile (profiles/Makefile:190-195) without it.
  • The number in the file name is the AppArmor release whose policy the list was frozen for. It is not a kernel version and not the parser's version.

Read more

06 Each file adds to the one before

OLDEST TO NEWEST kernel-5.4- vanilla kernel-5.4- outoftree- network these two are for parser.conf, not for an abi rule file mount signal ptrace capability + dbus + network (old) + unix (old) 3.0 AppArmor 3.0 + network 4.0 AppArmor 4.0 + userns + mqueue 5.0 AppArmor 5.0 + unix (full) + io_uring + ip= port= + three flags 4.0-ip = 4.0 + ip= port= 5.0-interface = 5.0 + interface=
The files in a line from oldest to newest. kernel-5.4-vanilla has file, mount, signal, ptrace and capability. kernel-5.4-outoftree-network adds dbus and the old network and unix mediation. Both are for parser.conf, not for an abi rule. 3.0, for AppArmor 3.0, adds network rules. 4.0, for AppArmor 4.0, adds userns and mqueue. 5.0, for AppArmor 5.0, adds full unix rules, io_uring, ip= and port=, and three profile flags. Two side files: 4.0-ip is 4.0 plus ip= and port=, and 5.0-interface is 5.0 plus interface=.

3.0, 4.0 and 5.0 each add rule classes. 4.0-ip and 5.0-interface add one feature to a numbered file. The two kernel-5.4 files are for parser.conf.

Line the files up by age. The two with kernel-5.4 in their names describe old kernels. They're for the parser's configuration file, to pin profiles that have no abi line, not for you to name. The second adds dbus and an older kind of network mediation. Then three numbered files, one per major AppArmor release. First, abi/3.0: network rules. Next, abi/4.0: user namespaces and message queues. Last, abi/5.0: full unix socket rules, io_uring, addresses and ports, and three profile flags. The two side files are a numbered file plus one thing: addresses and ports, or network interfaces.

Details and sources

Details

  • The chips are rule classes and syntax as a profile author writes them. The feature paths behind them are in the table "Feature by file" below the deck.
  • kernel-5.4-vanilla to kernel-5.4-outoftree-network: adds dbus, network (the old table of address families) and network/af_unix (unix rules in the old encoding).
  • kernel-5.4-outoftree-network to 3.0: adds network_v8 (network rules) and perfmon and bpf in caps/mask.
  • 3.0 to 4.0: adds ipc/posix_mqueue (mqueue rules for POSIX queues) and namespaces/mask with userns_create (userns rules); also mctp in the address family masks and checkpoint_restore in caps/mask.
  • 4.0 to 4.0-ip: one entry, network_v8/af_inet (ip= and port= on network inet and inet6 rules).
  • 4.0-ip to 5.0: adds network_v9 with af_unix (unix rules in the current encoding), io_uring, and domain/interruptible, domain/kill.signal and domain/disconnected.ipc. These are the "three flags" of the slide: interruptible, kill.signal= and attach_disconnected.ipc=.
  • 5.0 to 5.0-interface: adds network_v9_skb with iface (interface= on network rules).
  • Commits and first releases: the two kernel-5.4 files, 398bb20df, release 3.0.0; 3.0, 730db1760, release 3.0.0; 4.0, f1b4da2f6, release 4.0.0; 4.0-ip and 5.0, d688f93a4 and aecf78014, release 5.0.0; 5.0-interface, dc761781e, first in 6.0.0~alpha1 (6.0.0 is not released at the commit the map describes). So 4.0-ip is newer than 4.0 in one entry only, and it arrived with release 5.0.0.
  • Which kernel each numbered file was captured from is not recorded in the tree.
  • The two kernel-5.4 files are offered by the parser's configuration file as commented lines: #policy-features=/etc/apparmor.d/abi/kernel-5.4-vanilla and #policy-features=/etc/apparmor.d/abi/kernel-5.4-outoftree-network (parser.conf:77-81). They pin profiles that have no abi rule.
  • Known discrepancy: The kernel-5.4 abi files have a stray closing brace, so their file, domain and policy entries are not found. Each file has one closing brace more than opening ones: in kernel-5.4-vanilla it follows the mount entry (kernel-5.4-vanilla:31; the file has no network block), in kernel-5.4-outoftree-network it follows the network block (kernel-5.4-outoftree-network:39). The file, domain and policy entries after it are in the text and are not found by the lookup. Among them are domain/attach_conditions/xattr (the xattrs= attachment condition) and domain/stack (& targets): both files have the two entries in their text, and the lookup finds them from 3.0 on, which has the same entries in the same order and no extra brace. The slide does not list them as something 3.0 adds.

07 The same profile under 3.0, 4.0 and 5.0

COMPILE IT THREE TIMES $ apparmor_parser -Q -K --warn=all demo abi <abi/3.0>, abi <abi/4.0>, abi <abi/5.0>, downgrading … unix socket rule userns rules not enforced io_uring rules not enforced mqueue … rules not enforced downgrading … unix socket rule userns compiled io_uring rules not enforced mqueue … rules not enforced unix compiled in full userns compiled io_uring compiled mqueue … rules not enforced the last line stays under every file: that one is the kernel's doing, two scenes on $ apparmor_parser -Q -K demo; echo $? 0 no output, in all three left out is not denied: that kind of access is not checked for demo
The command apparmor_parser -Q -K --warn=all demo, run three times with a different first line. With abi <abi/3.0>, four warnings: downgrading extended network unix socket rule to generic network rule, userns rules not enforced, io_uring rules not enforced, mqueue type=posix rules not enforced. With abi <abi/4.0>, the userns rule is compiled and the other three warnings remain. With abi <abi/5.0>, the unix, userns and io_uring rules are compiled and only the mqueue warning remains; that one is the kernel's doing. With apparmor_parser -Q -K demo, without --warn=all, there is no output and exit status 0 in all three. A rule that is left out is not denied: that access is not checked for demo.

An older abi file leaves userns, mqueue and io_uring rules out. -K --warn=all says so; the default output does not, and without -K a cached profile is not compiled again.

Here's demo's profile compiled three times. Only the first line changes. Under abi/3.0 the parser tells you four things, if you ask for all warnings: the unix rule was downgraded, and the user namespace, io_uring and message queue rules are not enforced. Under abi/4.0, the user namespace rule is in. Under abi/5.0, so are io_uring and the full unix rule. One line stays in every column; that's the kernel's doing, two scenes on. Leave that option off, and all three compile with no output and exit status zero. And a rule that's left out isn't denied: that access just isn't checked.

Details and sources

Details

  • The three runs were recorded in the research notes and run again for this deck with the tree's parser: apparmor_parser -Q -K --skip-kernel-load --warn=all on the profile of the scene "Seven files, and you name one", with nothing loaded into a kernel. The slide leaves out --skip-kernel-load and the kernel feature set. The kernel feature set of the runs is a file written from the feature tables of the kernel source (apparmorfs.c:2684, net.c:24), given with --kernel-features; it is not a running kernel.
  • Full output with abi <abi/3.0>,, exit status 0. Every line begins Warning from profile demo (FILE): :
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
  • With abi <abi/4.0>,, exit status 0:
downgrading extended network unix socket rule to generic network rule
mqueue type=posix rules not enforced
io_uring rules not enforced
  • With abi <abi/5.0>,, exit status 0: mqueue type=posix rules not enforced. The slide orders the lines by rule class so that a class keeps its row, and shortens two of them with an ellipsis.
  • Without --warn=all: no output and exit status 0 (run for all three abi lines).
  • Why -K: reading the cache is on by default and -Q does not turn it off. When the cache has an entry for the profile that is newer than the file, the parser takes the compiled profile from it and skips the compile, which is where these warnings are printed. Run for this deck with a cache directory that survives between runs: -Q -W --cache-loc DIR --warn=all on the abi <abi/3.0>, profile prints the four warnings and writes the cache; then -Q --cache-loc DIR --warn=all --show-cache prints Cache hit: DIR/fd0f5cfe.0/demo-3.0.sd and no warning, exit status 0; with -K (or -T, --skip-read-cache) it prints Cache miss and the four warnings again. A profile that is installed and loaded is normally in the cache, so without -K the check says nothing exactly there.
  • Sizes of the compiled profile (-S): 5961 bytes with abi/3.0, 6049 with abi/4.0, 6337 with abi/5.0.
  • The two warning classes are rule-not-enforced and rule-downgraded. Both are off by default (parser_main.c:281-282); --warn=rule-not-enforced --warn=rule-downgraded turns on just these two.
  • Not affected by any of the seven files: file rules, capability and rlimit rules. signal, ptrace and mount are in all seven files. dbus is in every file but kernel-5.4-vanilla; who enforces dbus rules is in D-Bus mediation.
  • The manual: "If the kernel supports a feature not supported by the policy then policy will be built so that the kernel does NOT enforce that feature" (apparmor.d.pod:2833-2834). "Not checked" on the slide restates that sentence and the parser's marker rules; it was not observed on a running kernel.
  • That these warnings are off by default is a deliberate default, not a known discrepancy.
  • Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path. So "not checked" does not hold for the mqueue rule of this profile: the rule is left out in all three columns, and the queue is still refused, by the file check and not by the mqueue class. Observed on Debian 13 and Debian sid, with and without an mqueue rule: mq_open fails with error 13 and the log has apparmor="DENIED" operation="open" class="file" info="Failed name lookup - disconnected path". The record is in Kernel features and the policy ABI.
  • Known discrepancy: Kernel: dbus rules of a profile compiled without network_v9 unix support are not consulted, so profiles that pin abi/3.0 or abi/4.0 get no dbus mediation. This one was found by reading the code and has not been run on a kernel.

for AppArmor developers for security researchers

In the code

Read more

08 Some rules stay, but say less

DOWNGRADED unix (connect) type=stream peer=(addr=@demo), compiled under abi/5.0 unix stream connect peer addr=@demo compiled under abi/4.0 network unix stream (connect) any address with --warn=all: downgrading extended network unix socket rule to generic network rule network inet tcp ip=127.0.0.1 port=8080, a kernel with the af_inet entry inet stream 127.0.0.1:8080 this kernel, whichever abi file network inet stream any address, any port no warning, also with --warn=all
Two rules and what each is compiled to. The rule unix (connect) type=stream peer=(addr=@demo), is compiled under abi/5.0 as a unix stream connect rule with the peer address @demo. Under abi/4.0, on the upstream kernel, it is compiled as network unix stream with the connect permission, for any address, and with --warn=all the parser prints: downgrading extended network unix socket rule to generic network rule. The rule network inet tcp ip=127.0.0.1 port=8080, is compiled on a kernel with the af_inet entry as inet stream 127.0.0.1:8080. On this kernel, whichever abi file is named, it is compiled as network inet stream, for any address and any port, with no warning, also with --warn=all.

Under abi/4.0 a unix rule becomes a network unix rule. ip= and port= are compiled only where the abi file and the kernel both have af_inet; otherwise the rule covers the whole family.

Left out is one outcome. The other is quieter. Demo's unix rule allows connecting to one named socket. Under abi/5.0, that's what gets compiled. Under abi/4.0, on the upstream kernel, the parser can't express the address. So it compiles a plain network rule for unix stream sockets: connect, to anything. It tells you, if you ask. The inet rule with an address and a port has a twist. It needs an entry called af_inet, in the file and in the kernel. This kernel doesn't have it. Whichever file you name, the rule becomes all inet stream sockets. And here there's no warning at all.

Details and sources

Details

  • The texts inside the four boxes are readable paraphrases of the compiled rules (derived). The dump lines behind them, recorded in the research notes with -D rule-exprs and the kernel feature set written from the kernel source, and run again for this deck: - abi/5.0, the unix rule: rule: \x0f\x00\x01\x00\x01...*\x00[^\000]*\x00\x01\x00demo\x00[^\000]* with permission (0x40/0). The peer address demo is in the rule. Also present under abi/5.0: rule: \x0f\x00\x01\x00\x01 with (0x40/0), the generic unix stream connect rule, which the parser always adds beside the full one; the kernel does not use it for a unix socket when class 15 is mediated (af_unix.c:406, policy.h:360). - abi/4.0 (also abi/3.0 and abi/4.0-ip), the unix rule: only rule: \x0e\x00\x01\x00\x01 with (0x40/0): family unix, type stream, the connect permission, no address. - the inet rule with ip= and port=, every abi file: rule: \x0f\x00\x02\x00\x01 (\x0e before abi/5.0) with (0x1fc076/0), the same line as the rule network inet stream, above it in the profile.
  • The box "a kernel with the af_inet entry" was recorded with the tree's abi/5.0-interface file as a stand-in kernel feature set and abi/4.0-ip or abi/5.0 in the profile: the dump then has a line containing \x01\x00\x1f\x90\x01\x7f\x00\x00\x01\x00 (port 0x1f90 is 8080, the address is 127.0.0.1). It was not observed on a running kernel. Which kernels have the entry is in Upstream and Ubuntu kernels.
  • "The upstream kernel" in the narration is the kernel source tree the map describes; "this kernel" on the slide is the same. Why abi/3.0 and abi/4.0 downgrade the unix rule on it: they name network/af_unix, the kernel names network_v9/af_unix, and a feature must be in both sets.
  • The downgrade warning is in the class rule-downgraded, which is off by default.
  • An allow rule is downgraded. A deny rule cannot be. Run for this deck: deny unix (connect) type=stream peer=(addr=@demo), under abi <abi/4.0>, prints deny unix socket rule not enforced, can't be downgraded to generic network rule with --warn=all, and the dump has no network rule; exit status 0.
  • ip= and port= need network_v8/af_inet or network_v9/af_inet in both sets. abi/4.0-ip, abi/5.0 and abi/5.0-interface have the first; no shipped file has the second; the kernel's tables have neither (net.c:24).
  • interface= needs network_v9_skb/iface, which only abi/5.0-interface has. Recorded with the stand-in kernel set that has it: with abi/5.0, network send interface=eth0, compiles without eth0, exit status 0, and --warn=all prints nothing.
  • A third downgrade exists for change_profile safe rules: downgrading change_profile safe rule to unsafe due to lack of necessary kernel support (from the code).
  • Known discrepancy: inet conditionals are dropped silently when the kernel has no af_inet, so deny rules get wider.
  • Known discrepancy: deny unix rules are dropped when the kernel lacks fine-grained unix mediation, even where the downgrade would be exact.

for AppArmor developers for security researchers

In the code

09 The file offers, the kernel decides

BOTH MUST HAVE IT abi/5.0 the policy ABI: an offer the kernel the kernel ABI network_v9 network_v9 io_uring io_uring userns_create userns_create posix_mqueue - af_inet - interruptible - unix rules compiled io_uring compiled userns compiled mqueue type=posix rules not enforced ip= and port= not compiled, no message the flag is ignored abi/4.0-ip = abi/4.0: 6049 bytes abi/5.0-interface = abi/5.0: 6337 bytes on this kernel kernels with more entries: the deck on upstream and Ubuntu kernels
Two lists side by side: the file abi/5.0, the policy ABI, with the entries network_v9, io_uring, userns_create, posix_mqueue, af_inet and interruptible; and the kernel, the kernel ABI, with network_v9, io_uring and userns_create only. Where both have the entry the rule class is compiled: unix rules, io_uring and userns. posix_mqueue is missing in the kernel: mqueue type=posix rules not enforced. af_inet and interruptible are missing too: ip= and port= are not compiled, and the flag is ignored. On this kernel abi/4.0-ip compiles to the same 6049 bytes as abi/4.0, and abi/5.0-interface to the same 6337 bytes as abi/5.0. Kernels with more entries are in the deck on upstream and Ubuntu kernels.

A rule class is compiled when the abi file and the kernel both have its entry. On this kernel 4.0-ip compiles to the same bytes as 4.0, and 5.0-interface to the same bytes as 5.0.

The abi file is only half the decision. The parser also has the kernel's feature list, and a rule class is compiled only when both have its entry. So the abi/5.0 file is an offer: full unix rules, io_uring and user namespaces. The kernel has all three, and they're compiled. It also offers message queues; this kernel has no such entry: the line you saw in every column. Addresses and ports, the interruptible flag and interfaces go the same way. So the side files buy you nothing here: each compiles to the same bytes as its numbered file. Some distribution kernels have these entries; that's another deck.

Details and sources

Details

  • The entry names on the slide are shortened to their last component. In full: network_v9/af_unix (fine-grained unix rules), io_uring, namespaces/mask/userns_create, ipc/posix_mqueue, network_v8/af_inet, domain/interruptible.
  • "The kernel" is the kernel source tree the map describes. Its feature tables: the top level (apparmorfs.c:2684) has no network and no ipc; domain (apparmorfs.c:2600) has no interruptible and no disconnected.ipc; network_v8 and network_v9 (net.c:24) have no af_inet. The runs used a feature file written from these tables, not a running kernel.
  • What the parser looks up in abi/5.0 and the kernel's tables do not have: network, network/af_unix, network_v8/af_inet, ipc/posix_mqueue, domain/interruptible, domain/disconnected.ipc.
  • "Interfaces go the same way": interface= needs network_v9_skb/iface. abi/5.0 does not offer it; only abi/5.0-interface does, and the kernel's tables have no network_v9_skb. So that side file changes nothing on this kernel.
  • Recorded in the research notes: the profile of the scene "Seven files, and you name one" with abi <abi/4.0-ip>, gives the same -D rule-exprs dump and the same 6049 bytes as with abi <abi/4.0>,; with abi <abi/5.0-interface>, the same dump and the same 6337 bytes as with abi <abi/5.0>,.
  • Recorded: flags=(interruptible) with abi <abi/5.0>, prints flag interruptible not supported. Ignoring under --warn=all.
  • On an older kernel the same profile with abi <abi/5.0>, needs no change: the classes that kernel lacks are left out. Recorded with the tree's abi/4.0 file as a stand-in for an older kernel: io_uring rules not enforced. With the tree's abi/3.0 as the stand-in: mqueue type=posix rules not enforced, userns rules not enforced, io_uring rules not enforced.
  • The file must exist on the system. A package older than release 5.0 has no abi/5.0 file, and the parser then stops with Could not open 'abi/5.0' (derived from the releases in which the files arrived; not run on an older package).
  • The manual: "the compile may downgrade the rule with the feature to something the kernel supports, drop the rule completely, or fail the compile" (apparmor.d.pod:2835-2838).
  • Which distribution kernel has which entry is not stated here: see 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 missing ipc/posix_mqueue entry means the mqueue rule is left out; it does not mean the queue is open to the profile. Observed on Debian 13 and Debian sid, with and without an mqueue rule: mq_open fails with error 13 and the log has apparmor="DENIED" operation="open" class="file" info="Failed name lookup - disconnected path". See Kernel features and the policy ABI.
  • Known discrepancy: abi/5.0-interface turns on packet rules for every network rule. Recorded with the tree's abi/5.0-interface file as a stand-in kernel feature set: the profile of the scene "Seven files, and you name one", which has no interface=, has 67 rule: lines with abi <abi/5.0>, and 149 with abi <abi/5.0-interface>,. What a kernel with that entry does with the extra rules is not determined.
  • Known discrepancy: attach_disconnected.ipc is dropped without a warning and its bit is written anyway.

10 Left out without a word for security researchers

WHAT IS NOT ENFORCED as written abi <abi/3.0>, userns, /x r, as compiled /x r no user namespace mediation $ apparmor_parser -Q demo; echo $? 0 no output demo unshare(CLONE_NEWUSER) the kernel this profile carries nothing for the kernel to check it against abi <abi/3.0>, deny userns, the same result: a deny rule of a left-out class is left out too no abi rule: the built-in default a pinned set on the command line an override on the command line each can lower the policy ABI for a file without touching its rules --warn=all shows it; -D rule-exprs shows what was compiled
A profile as written, with abi <abi/3.0>, a userns rule and a file rule, and as compiled, with the file rule only and no user namespace mediation. apparmor_parser -Q prints nothing and exits with status 0. When demo calls unshare(CLONE_NEWUSER) the profile carries nothing for the kernel to check it against. A deny userns rule is left out in the same way. No abi rule, a pinned set or an override on the command line can each lower the policy ABI for a file without touching its rules. --warn=all shows it and -D rule-exprs shows what was compiled.

A rule class missing from the policy ABI is left out silently: exit status 0, no message unless --warn=all.

The abi rule is the one line in a profile that can switch whole kinds of mediation off. If the policy ABI lacks a feature, rules of that kind are left out. The parser's default reaction is silence and a zero exit status. And what a profile doesn't carry, the kernel doesn't check. A deny rule goes the same way. So does a file with no abi rule at all, which gets an old default, and so do feature sets chosen on the command line. So when you audit a profile, look at its first line, at how the parser is invoked, and at the compiled output.

Details and sources

for security researchers

Details

  • Recorded in the research notes and run again for this deck: the profile on the left, without --warn=all, prints nothing and exits with status 0. With --warn=all it prints userns rules not enforced. Recorded sizes of the compiled profile: 4401 bytes against 4481 with abi <abi/4.0>,.
  • The step with the kernel restates the manual's sentence that policy "will be built so that the kernel does NOT enforce that feature" (apparmor.d.pod:2829-2838). It is taken from the man page and the parser and was not run on a kernel.
  • The deny row was run with the tree's parser for this deck: abi <abi/3.0>, with deny userns, and /x r, exits with status 0 and no output; with --warn=all it prints Warning from profile demo (...): userns rules not enforced, and the -D rule-exprs dump has the attachment and /x only.
  • That the warning for rules that are not enforced is not in the default warning set is a deliberate default: the review notes list it under considered and rejected, not as a known discrepancy.
  • The manual on a missing abi rule: apparmor.d.pod:2846-2855.

for security researchers

Attack surface

  • Five things change which rule classes exist in the loaded profile, without a change to any rule and without a default warning: the preamble's abi rule; its absence; --policy-features, --compile-features, -M and -m; --override-policy-abi; and the abi file itself, which is found on the include search path, so a -I directory shadows /etc/apparmor.d/abi/.
  • The parser's configuration file can set options too: see Running apparmor_parser.
  • Known discrepancy: An abi rule accepts any readable file; a file without feature entries switches rule classes off silently. Recorded: abi <tunables/global>, with network inet stream, and signal send, exits with status 0 and no output; with --warn=all it prints network rules not enforced and signal rules not enforced; -S writes 3025 bytes against 4681 with abi <abi/4.0>,.
  • Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect.
  • Known discrepancy: Without an abi rule, xattrs= is dropped silently and change_profile -> &x is refused "by the kernel".

11 One global, twenty-four lookups, a marker per class for AppArmor developers for security researchers

IN THE PARSER scanner abi -> ABI_MODE <name> -> TOK_ID abi_features() "<kernel>", "<default>", or aa_features_new_from_file() the first one loaded: set a later one: compared, dropped policy_features set_supported_features() 24 paths, one switch each features_supports_io_uring = features_intersect( kernel_features, policy_features, "io_uring"); kernel_features io_uring_rule::gen_policy_re() switch off: warn once, return rule_result_t::NOT_SUPPORTED process_profile_policydb() switch on: the marker rule add_rule(mediates_io_uring, ...) RULE_MEDIATES(rules, AA_CLASS_IO_URING) no marker: the hook allows a missing entry means unchecked, not denied
The scanner switches to ABI_MODE on the keyword abi and returns one file name. abi_features handles the names <kernel> and <default> and otherwise loads the file with aa_features_new_from_file. The first set loaded becomes policy_features; a later one is compared and dropped. set_supported_features calls features_intersect with kernel_features and policy_features for 24 paths such as io_uring, and each call sets a switch such as features_supports_io_uring. io_uring_rule::gen_policy_re returns NOT_SUPPORTED when its switch is off. process_profile_policydb adds the marker rule mediates_io_uring when the switch is on. In the kernel, RULE_MEDIATES(rules, AA_CLASS_IO_URING) looks for the marker; with no marker the hook allows the access. A missing entry means unchecked, not denied.

parser_yacc.y:1884-1906 loads the file and 345-369 settles the policy ABI; parser_main.c:1030-1125 sets the switches; parser_regex.c:1392-1452 adds one marker per class, which the kernel's RULE_MEDIATES tests.

After the keyword, the scanner takes one file name. The grammar action calls abi_features, which loads the file. The first one loaded becomes the global policy_features; a later one is only compared. Once the preamble is reduced, set_supported_features calls features_intersect for twenty-four paths: is this in the kernel's set and in the policy's? Each answer sets a switch, which a rule class asks when it generates code. If it's off, the class returns not supported. Then each profile gets a marker rule for every class whose switch is on. The kernel looks for that marker before it checks the class. No marker, and the hook lets the access through. So a missing entry means unchecked, not denied.

Details and sources

for AppArmor developers for security researchers

Details

  • The production: parser_yacc.y:1052-1063. abi_features(): parser_yacc.y:1884-1906; the special names: parser_yacc.y:1846-1857; the lookup with search_path: parser_yacc.y:1858-1863.
  • The reduction of preamble that settles the policy ABI: parser_yacc.y:345-369.
  • The assignment on the slide is parser_main.c:1108-1110 joined on two lines.
  • features_intersect(a, b, str) is aa_features_supports(a, str) && aa_features_supports(b, str) (parser_main.c:1000-1003). set_supported_features() calls it for 24 paths (parser_main.c:1030-1125). The 24 paths, their switches and the files that have them are in the table "Feature by file" below the deck.
  • One more lookup there uses the kernel set only: mount/move_mount/detached (parser_main.c:1086-1087).
  • The lookup walks the text of the feature set, component by component (walk_one, features.c:361-444).
  • The rule class on the slide is io_uring.cc:113-125, shortened: warn_once() prints io_uring rules not enforced in the warning class rule-not-enforced.
  • The marker rules: process_profile_policydb(), parser_regex.c:1392-1452. One is added for every class whose switch is on, whether or not the profile has a rule of that class; profiles in unconfined or default-allow mode get only the user namespace marker.
  • The marker in a dump, recorded with -D rule-exprs, abi <abi/5.0>, and the kernel feature set written from the kernel source, is the line rule: \d22 -> \x16 priority=-1001 (0x4/0)< 0x4>. The other markers of that run: \d21 (user namespaces, priority -1001), and with priority 1001 \d2, \d7 (mount), \d32 (dbus), \d10 (signal), \d9 (ptrace), \d14, \d15 and \d15\0001 (network and unix). Class numbers: policydb.h:24-56.
  • The kernel side: RULE_MEDIATES returns the start state of the class in the profile's policy (policy.h:331). For io_uring the check is skipped and the hook returns 0 when that state is 0 (lsm.c:638). The same test: net.c:265, mount.c:254, ipc.c:93, task.c:388. Taken from the source; not observed on a running kernel. One class does not simply let the access through without its marker: for a tracer the kernel falls back to a CAP_SYS_PTRACE check (task.c:290). ptrace is in all seven files, so no abi line removes that marker.
  • caps/mask of an abi file only adds names to the parser's capability table (parser_yacc.y:365, parser_misc.c:407-435); it does not gate capability rules. Recorded: capability perfmon, under abi <abi/kernel-5.4-vanilla>,, whose caps/mask has no perfmon, compiles as itself.
  • The policy block of an abi file (versions, permstable32, set_load, state32, outofband) and the file entry are looked up in the kernel feature set only (parser_main.c:1743-1776).
  • Messages in the code: Could not open '%s': %m, fstat failed for '%s': %m, failed to find features abi '%s': %m, failed features abi not set but include cache skipped (parser_yacc.y:1870-1900; no input was found that prints the last one), Failed to setup default policy feature abi (parser_yacc.y:360).
  • Reset per file: parser_main.c:1264-1266.
  • The grammar also accepts the rule in a body: rules: rules abi_rule (parser_yacc.y:722; the tests abi/ok_20.sd and abi/ok_21.sd).
  • Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path. "Unchecked, not denied" describes a class whose hook tests the marker. Message queues are different: the kernel has no hook for the class at all, and opening a POSIX queue reaches the file-open check instead. Observed on Debian 13 and Debian sid, with and without an mqueue rule: mq_open fails with error 13 and the log has apparmor="DENIED" operation="open" class="file" info="Failed name lookup - disconnected path". See Kernel features and the policy ABI.
  • Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect.
  • Known discrepancy: An abi rule accepts any readable file; a file without feature entries switches rule classes off silently.
  • Known discrepancy: abi <DIRECTORY>, reports "failed to find features abi 'abi': Success".
  • Known discrepancy: The kernel-5.4 abi files have a stray closing brace, so their file, domain and policy entries are not found. Recorded: xattrs= on the profile head under abi <abi/kernel-5.4-vanilla>, prints xattr attachment conditional ignored with --warn=all, and the compiled profile is identical to the one without xattrs=; with the extra closing brace removed from a copy of the file there is no warning. The lookup returns false at a closing brace at depth 0 (features.c:401-406).
  • Known discrepancy: aa_features_supports(features, "policy/versions/v7") is false for a feature set that has policy/notify_versions. It applies where abi/5.0 or abi/5.0-interface is the kernel feature set, not where it is the policy ABI.
  • Known discrepancy: A capability known only from the policy ABI compiles as chown.

for security researchers

Attack surface

  • A lower abi file removes whole classes of mediation from a profile, with exit status 0 and no default message. Under abi/3.0, demo may create user namespaces and use io_uring whatever its rules say (from the parser's output and the marker mechanism; not run on a kernel).
  • ip=, port= and interface= are removed without a message in any warning class where the abi file or the kernel lacks the entry.
  • What to run on a profile you audit: apparmor_parser -Q -K --warn=all, and -D rule-exprs to see which \dN marker lines the profile carries. Without -K (or -T) a profile that is in the cache is not compiled again and no warning is printed.

12 Mistakes and what you see

MISTAKES abi <abi/nope>, Could not open 'abi/nope': No such file or directory also abi/5.0 where AppArmor is older than 5.0 abi <abi/5.0> no comma syntax error, unexpected TOK_VALUE, expecting TOK_END_OF_RULE profile demo { ... } abi <abi/5.0>, syntax error, unexpected TOK_ABI, expecting end of file (no abi rule at all) an old built-in default; no message unless --warn=all abi <abi/3.0>, then abi <abi/4.0>, the first one counts; no message unless --warn=abi abi <abi/3.0>, and userns, no output, exit status 0 --warn=all: userns rules not enforced network inet tcp ip=127.0.0.1 port=8080, no output, also with --warn=all; on this kernel compiled for any address and any port abi <abi/5.0>, # was abi/3.0 no output; user namespaces and io_uring are now checked, and denied without a rule write abi <abi/5.0>, first, and compile once with -K --warn=all
Eight mistakes and what the parser prints. abi <abi/nope>,: Could not open 'abi/nope': No such file or directory; the same for abi/5.0 where AppArmor is older than 5.0. abi <abi/5.0> without a comma: syntax error, unexpected TOK_VALUE, expecting TOK_END_OF_RULE. An abi rule after a profile: syntax error, unexpected TOK_ABI, expecting end of file. No abi rule at all: an old built-in default and no message unless --warn=all. Two different abi rules: the first counts and no message unless --warn=abi. abi <abi/3.0>, with a userns rule: no output and exit status 0; with --warn=all, userns rules not enforced. network inet tcp ip=127.0.0.1 port=8080 where the kernel cannot check addresses: no output, also with --warn=all, and the rule covers any address and any port. abi <abi/5.0>, in place of abi/3.0 on an old profile: no output; user namespaces and io_uring are now checked and denied without a rule. Advice: write abi <abi/5.0>, first and compile once with -K --warn=all.

A missing file, a missing comma and a misplaced abi rule are errors. The other mistakes print nothing by default. Start a new profile with abi <abi/5.0>, and compile once with -K --warn=all.

The loud mistakes first. A file that isn't there, or isn't installed where you ship: could not open. A missing comma, or an abi rule after a profile: a syntax error. The quiet ones print nothing. No abi rule: an old default. Two different abi rules: the first one counts. An old file with a newer rule: it compiles, and isn't enforced. An address and a port the kernel can't check: you get the whole family. Raise the line on an old profile, and user namespaces and io_uring, unchecked before, are denied: add rules, and test in complain mode. So start with abi/5.0, and compile once, skipping the cache, with all warnings on.

Details and sources

Details

  • The slide has eight rows. Rows 1 to 5 are about the rule and were run with the tree's abi/5.0 file as the kernel feature set; rows 6 to 8 are about the files and were run with a kernel feature set written from the kernel source. Nothing was loaded into a kernel.
  • Rows 1 to 3 are recorded in the research notes; rows 1 and 2 were run again with a profile for demo, and row 3 for the preamble deck. Each exits with status 1.
  • Row 1 in full: AppArmor parser error for /work/ab9.sd in profile /work/ab9.sd at line 1: Could not open 'abi/nope': No such file or directory.
  • Row 1, second line: the file abi/5.0 arrived with AppArmor 5.0.0 (commit aecf78014). A system with an older AppArmor has no such file, and the abi rule then fails as it does for any file that is not installed. That line of the slide is derived from that and from this run, which names a file the tree does not have: abi <abi/6.0>, gives AppArmor parser error for /work/demo-6.0.sd in profile /work/demo-6.0.sd at line 1: Could not open 'abi/6.0': No such file or directory, exit status 1 (/work/ is where the run kept the file). It was not run on an older package. An older kernel is a different matter and needs no change: see the scene "The file offers, the kernel decides".
  • Row 2 is reported at line 2, where the profile begins: syntax error, unexpected TOK_VALUE, expecting TOK_END_OF_RULE.
  • Not on the slide: abi abi/4.0, without angle brackets gives Could not open 'abi/4.0': No such file or directory. A bare name is opened as written and not searched for, so abi/4.0 is looked for in the working directory (recorded in the research notes and run again).
  • Row 4, recorded with --warn=all: Warning ... File '/work/ab3.sd' missing feature abi, falling back to default policy feature abi. Without that option nothing is printed.
  • Row 5, two rules abi <abi/3.0>, then abi <abi/4.0>, in one preamble, recorded in the research notes and run again for the review of this deck: nothing is printed by default, exit status 0. With --warn=abi: Warning from /work/ab4.sd (/work/ab4.sd line 2): ... /work/ab4.sd features abi 'abi/4.0' differs from policy declared feature abi, using the features abi declared in policy. The first rule counts: a userns, rule in that file is left out. In the other order the same warning names abi/3.0 and userns is compiled. The same rule twice draws no warning.
  • Rows 6 and 7 are the profile of the scene "Seven files, and you name one" with the abi line named, recorded in the research notes; row 6 was run again for this deck. The same pin also weakens a unix rule: under abi <abi/4.0>, the rule unix (connect) type=stream peer=(addr=@demo), prints nothing, and with --warn=all prints downgrading extended network unix socket rule to generic network rule (the scene "Some rules stay, but say less"). The slide shows one rule of that profile per row. The kernel feature set is the file written from the kernel source, as in the earlier scenes; exit status 0 in all of them.
  • Row 8, run for this deck with -D rule-exprs, kernel feature set as above. The profile is profile demo /usr/bin/demo { /etc/demo/** r, } with one abi line in front. With abi <abi/3.0>, its marker lines are \d2, \d7, \d32, \d10, \d9 and \d14. With abi <abi/5.0>, there are four more: \d21 (user namespaces), \d22 (io_uring), \d15 and \d15\0001 (unix sockets). Both runs print nothing and exit with status 0. A marker makes the kernel check the class, and a class that is checked and has no rule is denied: for user namespaces at task.c:388, for io_uring sqpoll and override_creds at lsm.c:638. So the program could create user namespaces and use io_uring under the old line, and cannot under the new one. The markers were printed by the parser; the denial is taken from the kernel source and was not observed on a running kernel. With \d15 the profile's unix sockets are also matched by unix rules.
  • What to do when you raise the line: add userns, and io_uring rules if the program needs them, and run the profile in complain mode first, where the new denials are logged and not enforced.
  • The last line: -K makes the parser compile the profile and not take it from the cache; without it a profile that is in the cache prints none of these warnings. The run is in the notes of the scene "The same profile under 3.0, 4.0 and 5.0". The result of --warn=all also depends on the kernel feature set of the machine where you run it, so run it on the oldest and the newest system you target.
  • The advice names the tree's current set. It is what all 210 shipped profile files that carry an abi rule in column 0 do.
  • Do not name the two kernel-5.4 files in an abi rule. They are meant for policy-features= in the parser's configuration file (parser.conf:77-81).
  • The two warning classes are rule-not-enforced and rule-downgraded, both off by default (parser_main.c:281-282). --warn=all turns on every class.
  • What you lose by naming an older file: - abi/4.0: io_uring rules; the flags interruptible, kill.signal= and attach_disconnected.ipc=; ip= and port=; and on this kernel fine-grained unix rules, which become network unix rules without an address or a peer. - abi/3.0: also userns and mqueue rules. - no abi rule: also network rules on this kernel, xattrs= and & targets.
  • What you risk by raising the line, in general: every class the newer file adds is checked for the profile as soon as the kernel has it, whether or not the profile has a rule for it. Row 8 is the case of abi/3.0 to abi/5.0.
  • abi/4.0-ip and abi/5.0-interface matter only on a kernel that has their extra entry. abi/5.0 already has the entry for ip= and port=.
  • The number in the file name is an AppArmor release, not a kernel version.
  • Parser tests that expect a failure: abi <includes/abi/4.19, (abi/bad_6.sd) and abi <>, (abi/bad_20.sd).
  • The abi rule is per file: a second profile file needs its own.
  • The file names under /work/ are scratch names of the runs.
  • Known discrepancy: abi <DIRECTORY>, reports "failed to find features abi 'abi': Success".
  • Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect. The indented abi <abi/5.0>, of the shipped abstractions does not stand in for an abi rule in your own preamble.
  • Known discrepancy: The kernel-5.4 abi files have a stray closing brace, so their file, domain and policy entries are not found. Recorded in the research notes for a profile with /etc/demo/** r, and change_profile -> &other,: under abi <abi/kernel-5.4-vanilla>, the compile fails with The current kernel does not support stacking of named transitions: &other, exit status 255; under abi <abi/3.0>, it compiles.
  • Known discrepancy: inet conditionals are dropped silently when the kernel has no af_inet, so deny rules get wider.
  • Known discrepancy: Without an abi rule, xattrs= is dropped silently and change_profile -> &x is refused "by the kernel".
  • Known discrepancy: Only the first "Ignoring" warning of a profile is printed.

for AppArmor developers for security researchers

In the code

13 From the abi line to the rules it switches on

ROADS abi <abi/5.0>, names the file /etc/apparmor.d/abi/5.0 adm-features what the kernel publishes adm-parser the options and --warn syn-unix syn-network-inet syn-userns syn-mqueue syn-io-uring syn-xattrs the rules these entries switch on upstream-and-ubuntu kernels with more entries lib-features re-blob sec-unmediated syntax-map the line to write: abi <abi/5.0>,
The line abi <abi/5.0>, in the centre; it names the file /etc/apparmor.d/abi/5.0. Roads on the left to adm-features, what the kernel publishes, and adm-parser, the options and --warn. On the right to syn-unix, syn-network-inet, syn-userns, syn-mqueue, syn-io-uring and syn-xattrs, the rules these entries switch on. Below to upstream-and-ubuntu, kernels with more entries, and to lib-features, re-blob, sec-unmediated and syntax-map. The line to write is abi <abi/5.0>,.

The abi rule names the policy ABI; an abi file offers rule classes and the kernel accepts what it has. New profiles name abi/5.0.

That's the abi rule and the files it names. The line freezes what your profile's text means. Each file is an offer of rule classes, and the kernel accepts what it can. What your kernel publishes, and how to compare it with a file, is the deck on kernel features. The options that override it are in the deck on running the parser. Each kind of rule you saw switch on and off has a deck too. And the kernels that have the entries this one lacks are in the deck on upstream and Ubuntu kernels. For your own profile, the line to write is abi/5.0.

Details and sources

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit 836052d21 (6.0.0~alpha2) was run on the profile (-Q -K --skip-kernel-load, with --warn=all where a warning is quoted and -D rule-exprs where a compiled rule is described), with nothing loaded into a kernel. The kernel feature set of the runs in the sections on the files ("Why an abi line", and "The files" to "Choosing a line") was a file written from the feature tables of the kernel source (apparmorfs.c:2684, net.c:24, capability.c:28), given with --kernel-features; it is not a running kernel. Rows marked "kernel with every entry" used the tree's abi/5.0-interface file as the kernel feature set instead, standing in for a kernel that has every entry the shipped files name. The runs in the sections on the rule ("Grammar" to "The abi line and a userns rule") used the tree's abi/5.0 file as the kernel feature set, also given with --kernel-features; that set has user namespace mediation. "code" means the parser source, or the kernel source, was read and not run; "derived" means the result was reasoned from that code. Nothing here was observed on a running kernel.

Why an abi line

The abi line freezes what the text of a profile means. A profile lists what is allowed, and whatever it does not list in a checked class is denied. A class that the profile's abi file has no entry for could not be written about when the profile was written, so the parser compiles the profile so that the class is not checked for it: the access stays allowed (the manual: "policy will be built so that the kernel does NOT enforce that feature", apparmor.d.pod:2833-2834). A newer abi file has the entry, and on a kernel that has it too the class is checked: the same text under the newer line denies what it does not allow. As an example of a future release: if AppArmor 6 mediated something new, a profile that names abi/5.0 would go on allowing it, and the same text under an abi/6.0 would deny it until a rule is added. There is no abi/6.0 file at this commit. The case that exists: a profile with one file rule has no marker for user namespaces, io_uring or unix sockets under abi <abi/3.0>, and has all three under abi <abi/5.0>, (tree); that a checked class without a rule is denied is from the kernel source (code). See "Choosing a line".

Grammar

ABI RULE:  'abi' ( <magic/path> | "path" | path | '<kernel>' | '<default>' ) ','
  • The comma is required (tree).
  • <magic/path> is searched for like an include: the -I directories, then the base directory (code). "path" and a bare path are opened as written (tree for the bare path that does not exist; the test abi/ok_16.sd).
  • <kernel> is the kernel's feature set; <default> is the parser's built-in default and is equivalent to writing no abi rule (code; tree for the userns, results below). Only the angle-bracket forms are special (derived).
  • The rule stands in the preamble. After the first profile it is a syntax error (tree). The first abi rule of a file counts.

Policy ABI and kernel ABI

The policy ABI is the feature set the abi rule names; the kernel ABI is the feature set of the kernel. A rule class is compiled only if both sets have its feature (code). apparmor.d(5): "If the kernel supports a feature not supported by the policy then policy will be built so that the kernel does NOT enforce that feature". A rule class the policy ABI lacks is left out; that is not an error and by default not a message (tree).

Which source decides

OrderSourceRecorded run (profile with userns,)
1--override-policy-abi FILEabi <abi/3.0>, in the file, override to abi/4.0: userns compiled
2the first abi rule of the fileabi <abi/3.0>, in the file, --policy-features .../abi/4.0: userns rules not enforced
3--policy-features FILE (also --compile-features, -M, -m)no abi rule, --policy-features .../abi/4.0: userns compiled, no warning
4the built-in defaultno abi rule, no option: the missing-abi warning and userns rules not enforced

All four are tree runs recorded in the research notes. Two different abi rules in one preamble: the first counts, and the second draws the "differs" warning (tree).

The abi line and a userns rule

First lineWith --warn=allWithoutSize of -S
abi <abi/3.0>,userns rules not enforcednothing, exit status 04401 bytes
abi <abi/4.0>,nothingnothing4481 bytes
noneFile '...' missing feature abi, falling back to default policy feature abi, then userns rules not enforcednothing4401 bytes
abi <kernel>,nothing: userns compilednot recordednot recorded
abi <default>,userns rules not enforcednot recordednot recorded

Tree runs recorded in the research notes.

The files

All seven are in /etc/apparmor.d/abi/ (profiles/apparmor.d/abi/ in the tree).

FileArrived withCommitWhat it isMeant for
kernel-5.4-vanillarelease 3.0.0398bb20dfthe features of a 5.4 kernel without extra patchespolicy-features= in parser.conf, to pin profiles that have no abi rule
kernel-5.4-outoftree-networkrelease 3.0.0398bb20dfthe same plus dbus and the old network and unix mediationpolicy-features= in parser.conf
3.0release 3.0.0730db1760adds network_v8an abi rule
4.0release 4.0.0f1b4da2f6adds POSIX message queues and user namespacesan abi rule
4.0-iprelease 5.0.0d688f93a44.0 plus one entry, network_v8/af_inetan abi rule, on a kernel that has the entry
5.0release 5.0.0aecf78014adds network_v9 with af_unix, io_uring and three profile flagsan abi rule; the one that shipped policy names
5.0-interface6.0.0~alpha1dc761781e5.0 plus network_v9_skban abi rule, on a kernel that has the entry
  • There is no 6.0 file at this commit.
  • Shipped policy names only abi/5.0: 345 lines under profiles/apparmor.d (210 in column 0, 135 indented: 134 in abstractions and one in apache2.d/phpsysinfo) and 111 under profiles/apparmor/profiles/extras. aa-genprof and aa-autodep write abi <abi/5.0>, into new profiles (code).
  • The number in a file name is the AppArmor release whose policy the list was frozen for. It is not a kernel version. Which kernel each numbered file was captured from is not recorded in the tree.
  • A feature file has the text form of what the kernel publishes under /sys/kernel/security/apparmor/features; see Kernel features and the policy ABI.

Feature by file

The rows are the 24 paths the parser looks up in the policy ABI and in the kernel feature set, then the two differences in caps/mask. A rule class is compiled only where the abi file named by the profile and the kernel both have the path. y present; - absent; (y) present in the text but not found by the lookup (see "In the code" for apparmor-developers and security-researchers). Column k-van is kernel-5.4-vanilla, k-oot is kernel-5.4-outoftree-network, 5.0-if is 5.0-interface, default is the parser's built-in default used when there is no abi rule, and kernel is the kernel source the map describes.

Feature pathSwitches onk-vank-oot3.04.04.0-ip5.05.0-ifdefaultkernel
mountmount, umount, remount, pivot_root rulesyyyyyyyyy
signalsignal rulesyyyyyyyyy
ptraceptrace rulesyyyyyyyyy
dbusdbus rules-yyyyyyyy
networkthe old table of address families-yyyyyyy-
network/af_unixunix rules, old encoding-yyyyyyy-
network_v8network rules--yyyyy-y
network_v8/af_inetip= and port=----yyy--
network_v9network rules, current encoding-----yy-y
network_v9/af_unixunix rules, current encoding-----yy-y
network_v9/af_inetip= and port=, current encoding---------
network_v9_skbpacket rules------y--
network_v9_skb/ifaceinterface=------y--
domain/attach_conditions/xattrxattrs= on the profile head(y)(y)yyyyy-y
domain/stack& targets; change_profile safe(y)(y)yyyyy(y)y
namespaces/mask/userns_createuserns rules---yyyy-y
ipc/posix_mqueuemqueue rules, POSIX queues---yyyy--
ipc/sysv_mqueuemqueue rules, System V queues---------
io_uringio_uring rules-----yy-y
domain/interruptibleflags=(interruptible)-----yy--
domain/kill.signalflags=(kill.signal=...)-----yy-y
domain/disconnected.ipcflags=(attach_disconnected.ipc=...)-----yy--
policy/profile/errorflags=(error=...)---------
domain/identitynames of identities---------
caps/mask has perfmon bpfnames only; does not gate capability rules--yyyyyyy
caps/mask has checkpoint_restorenames only---yyyy-y
  • The seven file columns were counted from the files in the tree; the kernel column from the kernel's tables (code); the default column is from the research notes.
  • File rules, capability and rlimit rules, change_profile without & and hats depend on no path: they are compiled under every file (tree for file rules and capability).
  • mount/move_mount/detached is looked up in the kernel set only. 5.0 and 5.0-interface have it and so does the kernel.

Entries that are in the files and are not looked up in a policy ABI (code): file/mask, rlimit/mask, query/..., capability, namespaces/profile, namespaces/pivot_root, namespaces/userns_create, caps/extended, domain/version, domain/change_*, domain/computed_longest_left, domain/post_nnp_subset, domain/fix_binfmt_elf_mmap, domain/unconfined_allowed_children, domain/disconnected.path, every af_mask, and the whole policy block. The policy block and file are looked up in the kernel feature set only.

What each step adds

From, toEntries addedRule classes or syntax this switches on
kernel-5.4-vanilla to kernel-5.4-outoftree-networkdbus/mask; network/af_mask, network/af_unixdbus rules; the old table of address families; unix rules in the old encoding
kernel-5.4-outoftree-network to 3.0network_v8/af_mask; perfmon bpf in caps/mask; the domain entries are foundnetwork rules; xattrs= on the profile head; & targets
3.0 to 4.0ipc/posix_mqueue; namespaces/mask = userns_create; mctp in the af_masks; checkpoint_restore in caps/maskmqueue rules for POSIX queues; userns rules
4.0 to 4.0-ipnetwork_v8/af_inetip= and port= on network inet and inet6 rules
4.0-ip to 5.0network_v9/af_mask, network_v9/af_unix; io_uring/mask; domain/interruptible, domain/kill.signal, domain/disconnected.ipc; mount/move_mountunix and network rules in the current encoding; io_uring rules; the flags interruptible, kill.signal=, attach_disconnected.ipc=
5.0 to 5.0-interfacenetwork_v9_skb with af_mask, iface, localout, postroute, rcv_skb, relabelinterface= on network rules; packet rules

Each step also adds entries that are not looked up in a policy ABI (in the policy block and elsewhere); they are left out of this table.

Rule class by abi line, on this kernel

The profile of the scene "Seven files, and you name one", one rule per row (tree). Every run exits with status 0. Messages appear only with --warn=all; the class is rule-not-enforced unless stated.

Ruleabi/3.0abi/4.0abi/5.0
/etc/demo/** r,compiledcompiledcompiled
capability net_bind_service,compiledcompiledcompiled
network inet stream,compiledcompiledcompiled
network inet tcp ip=127.0.0.1 port=8080,kept without ip= and port=; no messagethe samethe same
unix (connect) type=stream peer=(addr=@demo),downgraded to a network unix stream rule; downgrading extended network unix socket rule to generic network rule (class rule-downgraded)the samecompiled
dbus send bus=session path=/org/demo,compiledcompiledcompiled
signal send set=hup,compiledcompiledcompiled
ptrace read,compiledcompiledcompiled
mount fstype=tmpfs -> /mnt/demo/,compiledcompiledcompiled
mqueue (create) type=posix /demo,left out; mqueue type=posix rules not enforcedthe samethe same
userns,left out; userns rules not enforcedcompiledcompiled
io_uring sqpoll,left out; io_uring rules not enforcedleft out; io_uring rules not enforcedcompiled
size of -S5961 bytes6049 bytes6337 bytes
  • abi/4.0-ip gives the same output and the same 6049 bytes as abi/4.0; abi/5.0-interface the same output and the same 6337 bytes as abi/5.0 (tree).
  • Without --warn=all nothing is printed (tree, for abi/3.0).
  • Side runs (tree): xattrs=(user.demo=1) on the profile head is compiled under abi/3.0 (4585 bytes against 4513 without it); change_profile -> &other, compiles under abi/3.0; flags=(interruptible) under abi/5.0 prints flag interruptible not supported. Ignoring.
  • Kernel with every entry (tree): ip=127.0.0.1 port=8080 is compiled into the rule with abi/4.0-ip and abi/5.0, and is not with abi/4.0. network send interface=eth0, is compiled with the interface under abi/5.0-interface; under abi/5.0 it is compiled without it, exit status 0, no message.

The two kernel-5.4 files and a profile with no abi rule, same profile, same kernel feature set (tree):

First lineLeft out or changedSize of -S
abi <abi/kernel-5.4-vanilla>,both network rules, the unix rule, the dbus, mqueue, userns and io_uring rules5409 bytes
abi <abi/kernel-5.4-outoftree-network>,the same without the dbus rule5721 bytes
no abi rulethe same as the line above, after File 'FILE' missing feature abi, falling back to default policy feature abi5721 bytes

The messages of these runs: network rules not enforced (three times), extended network unix socket rules not enforced, dbus rules not enforced (vanilla only), mqueue type=posix rules not enforced, userns rules not enforced, io_uring rules not enforced, and profile demo network rules not enforced.

When the kernel lacks the entry

The switch is the intersection, so the result is the same whether the abi file or the kernel lacks the path. apparmor.d(5): "the compile may downgrade the rule with the feature to something the kernel supports, drop the rule completely, or fail the compile".

Rule class or syntaxEntryResult when absent on either sideMessage and classBasis
networknetwork_v8 or network_v9left outnetwork rules not enforced (rule-not-enforced)tree
network ... ip= port=network_v8/af_inet or network_v9/af_inetkept as a family and type rulenonetree
network ... interface=network_v9_skb/ifacekept without the interfacenonetree
unixnetwork_v9/af_unix or network/af_unixallow rules become network unix rulesdowngrading extended network unix socket rule to generic network rule (rule-downgraded); with no network entry at all extended network unix socket rules not enforcedtree
deny unixthe sameleft outdeny unix socket rule not enforced, can't be downgraded to generic network rule (rule-not-enforced)tree
dbusdbusleft outdbus rules not enforcedtree
signal, ptracesignal, ptraceleft outsignal rules not enforced, ptrace rules not enforcedcode
mountmountleft outnot recordedcode
mqueueipc/posix_mqueue, ipc/sysv_mqueueleft outmqueue type=posix rules not enforced, mqueue type=sysv rules not enforcedtree
usernsnamespaces/mask/userns_createleft outuserns rules not enforcedtree
io_uringio_uringleft outio_uring rules not enforcedtree
xattrs= on the headdomain/attach_conditions/xattrcondition removed; the profile attaches by path alonexattr attachment conditional ignored (rule-not-enforced)tree
change_profile -> &x, & targetsdomain/stackthe compile fails, exit status 255The current kernel does not support stacking of named transitions: &xtree
change_profile safe ...domain/stackcompiled as unsafedowngrading change_profile safe rule to unsafe due to lack of necessary kernel support (rule-downgraded)code
flags=(interruptible)domain/interruptibleflag clearedflag interruptible not supported. Ignoringtree
flags=(kill.signal=...)domain/kill.signalnot writtenkill.signal not supported. Ignoringtree
flags=(attach_disconnected.ipc=...)domain/disconnected.ipcsee the known discrepancy belownonecode

The profile of the scene "Seven files, and you name one" with abi <abi/5.0>, against three kernel feature sets (tree, --warn=all):

Kernel feature setWarnings
written from the kernel sourcemqueue type=posix rules not enforced
the tree's abi/4.0 file, standing in for an older kernelio_uring rules not enforced
the tree's abi/3.0 file, standing in for an older kernelmqueue type=posix rules not enforced, userns rules not enforced, io_uring rules not enforced

Kernels that have the entries this one lacks: Upstream and Ubuntu kernels.

Choosing a line

  • Write abi <abi/5.0>, as the first line of a new profile file. It is what every shipped profile has and what aa-genprof writes.
  • Compile once with apparmor_parser -Q -K --warn=all FILE (or --warn=rule-not-enforced --warn=rule-downgraded) on the oldest and the newest system you target. Without the warning option a rule that is left out prints nothing and the exit status is 0. Without -K a profile that is already in the cache is not compiled again and no warning is printed (tree: after a run with -W, -Q --warn=all --show-cache prints Cache hit and no warning; with -K or -T the warnings are back).
  • What you lose with an older line. abi/4.0: io_uring rules; the flags interruptible, kill.signal= and attach_disconnected.ipc=; ip= and port=; and on this kernel fine-grained unix rules, which become network unix rules without an address or a peer. abi/3.0: also userns and mqueue rules. No abi rule: also network rules on this kernel, xattrs= and & targets. A class that is left out is not denied: it is not checked for the profile (POSIX message queues are the exception; see the known discrepancies below).
  • What you risk by raising the line. Every class the newer file adds is checked for the profile as soon as the kernel has it, whether or not the profile has a rule for it. A profile moved from abi/3.0 to abi/5.0 without new rules no longer lets the program create user namespaces or use io_uring sqpoll and override_creds, and its unix sockets are matched by unix rules. Basis: a profile with one file rule has no \d21, \d22 or \d15 marker line under abi/3.0 and has all three under abi/5.0 (tree); that a checked class without a rule is denied is from the kernel source (code), not from a running kernel. Raise the line, add the rules the program needs, then test in complain mode.
  • abi/4.0-ip and abi/5.0-interface are for kernels that have network_v8/af_inet or network_v9_skb. On this kernel they compile to the same bytes as 4.0 and 5.0. abi/5.0 already has af_inet. An ip=, port= or interface= in a profile that may run where the entry is missing gives a rule for the whole family and type, with no message.
  • An older kernel needs no change to the profile: with abi/5.0 the classes that kernel lacks are left out. The file must be installed: without it the parser stops with Could not open 'abi/5.0' (derived: a package older than release 5.0 does not ship the file).
  • Do not name the two kernel-5.4 files in an abi rule. They are meant for policy-features= in parser.conf.
  • If you pin profiles with one of the two kernel-5.4 files in parser.conf, or name one in an abi rule, the xattrs= attachment condition is removed and the profile attaches by path alone; --warn=all prints xattr attachment conditional ignored (tree). A profile with a & target fails to compile.

Warnings and errors

MessageClass, defaultCauseBasis
Could not open 'NAME': No such file or directoryerror, exit status 1the file named by the abi rule was not found or is not installed; abi/5.0 on a system older than AppArmor 5.0 is the same case (derived)tree
syntax error, unexpected TOK_VALUE, expecting TOK_END_OF_RULEerrorno commatree
syntax error, unexpected TOK_ABI, expecting end of fileerroran abi rule after a profiletree
File 'FILE' missing feature abi, falling back to default policy feature abiwarning abi, offno abi rule and no optiontree
features abi 'NAME' differs from policy declared feature abi, using the features abi declared in policywarning abi, offa later abi rule that differs from the firsttree
userns rules not enforced, io_uring rules not enforced, mqueue type=posix rules not enforced, dbus rules not enforced, network rules not enforcedwarning rule-not-enforced, offthe abi file or the kernel lacks the entry of the classtree
extended network unix socket rules not enforcedwarning rule-not-enforced, offno unix entry and no network entrytree
downgrading extended network unix socket rule to generic network rulewarning rule-downgraded, offno unix entry in both sets; a network entry in bothtree
xattr attachment conditional ignoredwarning rule-not-enforced, offdomain/attach_conditions/xattr not foundtree
flag interruptible not supported. Ignoringwarning, offdomain/interruptible missing on either sidetree
The current kernel does not support stacking of named transitions: NAMEerror, exit status 255domain/stack not foundtree
noneip=, port= or interface= without its entrytree
fstat failed for '%s': %m, failed to find features abi '%s': %m, Failed to setup default policy feature abierrornot produced in the runscode

for security researchers

Attack surface

  • The policy ABI decides which rule classes exist in the compiled profile. It can be lowered without touching a rule: by the abi rule, by its absence, by --policy-features and its other spellings, by --override-policy-abi, and by which file the name in the abi rule resolves to on the include search path.
  • None of these prints a message by default; the exit status is 0.
  • Allow rules and deny rules of a left-out class are both left out (tree for userns, and deny userns,).
  • A lower abi file removes whole classes of mediation from a profile with exit status 0 and no default message. Under abi/3.0, the program may create user namespaces and use io_uring whatever its rules say (derived from the parser's output and the marker rules; not run on a kernel).
  • ip=, port= and interface= are removed without a message in any warning class where the abi file or the kernel lacks the entry. A deny rule with such a condition then covers the whole family and type.
  • The two kernel-5.4 files, named in an abi rule or pinned in parser.conf, remove the xattrs= attachment condition: the profile attaches by path alone.
  • What to run: apparmor_parser -Q -K --warn=all (without -K or -T a cached profile is not compiled again and prints no warning), and -D rule-exprs to see which \dN marker lines a profile carries.

for AppArmor developers for security researchers

In the code

  • Production and scanner mode: parser_yacc.y:1052-1063, parser_lex.l:893-895, parser_lex.l:911-916.
  • abi_features(): parser_yacc.y:1884-1906; the order of sources: parser_yacc.y:346-369; the built-in default: default_features.c:127.
  • The kernel publishes its feature set in apparmorfs (apparmorfs.c:2684); libapparmor reads it (features.c:591-594).
  • The options: parser_main.c:669-740.
  • set_supported_features(): parser_main.c:1030-1125. features_intersect(): parser_main.c:1000-1003. The lookup used from the kernel set only: parser_main.c:1086-1087 and parser_main.c:1743-1776.
  • The lookup itself (walk_one): features.c:361-444.
  • The marker rules, one per class whose switch is on: parser_regex.c:1392-1452. Class numbers: policydb.h:24-56. In the -D rule-exprs dump they are the \dN lines with priority=1001 (-1001 for user namespaces and io_uring).
  • The kernel's tables: apparmorfs.c:2684 (top level), apparmorfs.c:2600 (domain), net.c:24 (network_v8, network_v9). The kernel tests a class with RULE_MEDIATES (policy.h:331), for example net.c:265, mount.c:254, ipc.c:93, lsm.c:638.
  • caps/mask of an abi file adds names to the capability table only (parser_yacc.y:365, parser_misc.c:407-435).
  • The cache hit that skips the compile and its warnings: parser_main.c:1367-1372. The warning classes: parser_main.c:281-282. The built-in default: default_features.c:127-200.
  • Known discrepancy: a POSIX message queue on a kernel without mqueue mediation is refused as a file with a disconnected path. "Left out" and "not checked" on this page are about the rule class. For POSIX message queues the access itself is still refused, by the file check. Observed on Debian 13 and Debian sid, with and without an mqueue rule: mq_open fails with error 13 and the log has apparmor="DENIED" operation="open" class="file" info="Failed name lookup - disconnected path". See Kernel features and the policy ABI.
  • Known discrepancy: apparmor_parser(8) describes -b and -I in terms that do not match the code.
  • Known discrepancy: An abi rule accepts any readable file; a file without feature entries switches rule classes off silently. Recorded: abi <tunables/global>, with network inet stream, and signal send,: exit status 0, no output; with --warn=all, network rules not enforced and signal rules not enforced; -S writes 3025 bytes against 4681 with abi <abi/4.0>,.
  • Known discrepancy: abi <DIRECTORY>, reports "failed to find features abi 'abi': Success". Recorded for abi <abi>,.
  • Known discrepancy: An abi rule inside a profile body or an abstraction is accepted and has no effect. Recorded: with no abi rule in the preamble and abi <abi/4.0>, in the body, the missing-abi warning, the "differs" warning and userns rules not enforced.
  • Known discrepancy: The kernel-5.4 abi files have a stray closing brace, so their file, domain and policy entries are not found. kernel-5.4-vanilla line 31 (after the mount entry; the file has no network block) and kernel-5.4-outoftree-network line 39 (after the network block) are a closing brace without an opening one; the file, domain and policy entries follow it, and the lookup returns false at a closing brace at depth 0 (features.c:401-406). These are the (y) cells of the table. Recorded: xattrs=(user.demo=1) under abi <abi/kernel-5.4-vanilla>, prints xattr attachment conditional ignored and the compiled profile is identical to the one without xattrs=; with --policy-features naming a copy of the file without line 31 there is no warning; change_profile -> &other, under the same abi line fails with the stacking message, exit status 255, and compiles under abi <abi/3.0>,.
  • Known discrepancy: abi/5.0-interface turns on packet rules for every network rule. Recorded with the tree's abi/5.0-interface file as the kernel feature set: the profile of the scene "Seven files, and you name one", which has no interface=, has 67 rule: lines with abi <abi/5.0>, and 149 with abi <abi/5.0-interface>,; 81 of them are packet rules for the two inet rules and the unix rule. What a kernel with that entry does with them is not determined.
  • Known discrepancy: aa_features_supports(features, "policy/versions/v7") is false for a feature set that has policy/notify_versions. It applies where abi/5.0 or abi/5.0-interface is the kernel feature set, not where it is the policy ABI.
  • Known discrepancy: inet conditionals are dropped silently when the kernel has no af_inet, so deny rules get wider.
  • Known discrepancy: deny unix rules are dropped when the kernel lacks fine-grained unix mediation, even where the downgrade would be exact.
  • Known discrepancy: Kernel: dbus rules of a profile compiled without network_v9 unix support are not consulted, so profiles that pin abi/3.0 or abi/4.0 get no dbus mediation. Found by reading the code; not run on a kernel.
  • Known discrepancy: A capability known only from the policy ABI compiles as chown.
  • Known discrepancy: Two "not enforced" warnings are printed for rules that are compiled.
  • Known discrepancy: Only the first "Ignoring" warning of a profile is printed.
  • Known discrepancy: attach_disconnected.ipc is dropped without a warning and its bit is written anyway.
  • Known discrepancy: Without an abi rule, xattrs= is dropped silently and change_profile -> &x is refused "by the kernel".

Roads from here

START HERE

PREAMBLE AND REUSE

PROFILE HEAD

RULE CLASSES

SECURITY · threat model and limits

RUNNING THE PARSER

LIBAPPARMOR

THE DFA ENGINE · libapparmor_re