Choosing abstractions

for general-purpose apps for application developers for administrators for security researchers

What the shipped abstractions grant and which ones a command-line tool or a daemon or a desktop program needs. Covers base and the two name lookup abstractions and the ones with sensitive side grants. Also the deny-only private-files pair and the .d extension directories and how aa-logprof proposes includes.

On the map: general-purpose apps

▶ Watch this deck — 11 scenes, ~8 min

Worth seeing first

Part of journeys

01 Which include lines does my program need?

CHOOSING ABSTRACTIONS profile lsblk /usr/bin/lsblk { include <abstractions/base> include <abstractions/consoles> include <abstractions/nameservice-strict> ... /etc/apparmor.d/abstractions/ 130 files base consoles nameservice nameservice-strict user-tmp ssl_certs ssl_keys fonts gtk gnome kde audio dbus-session-strict private-files-strict ... base consoles nameservice-strict base 122 nameservice 49 consoles 27 nameservice-strict 14 ssl_certs 10 include lines in the shipped profiles this deck: what the common ones grant, and which to pick
The lsblk profile with three include lines, pointing at base, consoles and nameservice-strict in a listing of the abstractions directory, which holds 130 files. Below, how often the common abstractions are included in the shipped profiles.

profiles/apparmor.d/abstractions/ holds 130 abstractions. base appears in 122 include lines of the shipped profiles, nameservice in 49, consoles in 27, nameservice-strict in 14.

You've got a new profile with base in it, and a program that needs more. The abstractions directory holds a hundred and thirty files. Which ones are for you? Look at lsblk, a small command-line tool. It takes three: base, consoles, and the strict name lookup one. That's typical. Across the shipped profiles, base is included a hundred and twenty-two times, nameservice forty-nine, consoles twenty-seven. Each of those names hides a list of rules. This deck opens the common ones, so you know what a line gives you before you add it. It's for profile authors, and for administrators who extend what they wrote.

Details and sources

Details

  • The abstractions directory of the tree, profiles/apparmor.d/abstractions/, holds 130 files at the top level, 5 more under apparmor_api/ and 11 under ubuntu-browsers.d/. On an installed system they are under /etc/apparmor.d/abstractions/.
  • The lsblk profile includes base, consoles and nameservice-strict (lsblk:16-18).
  • Usage counts are grep counts of include <abstractions/NAME> lines over profiles/apparmor.d/ outside abstractions/, at AppArmor 836052d21: 198 profile files at the top level plus apache2.d/phpsysinfo. base 122 lines, nameservice 49, consoles 27, nameservice-strict 14, ssl_certs 10, user-tmp 9, private-files-strict 9.
  • One file can hold several profiles and child profiles, so the lines are counted, not the files: 102 of the 198 top-level files name base at least once, and 96 do not mention it.
  • The counts describe the tree. A distribution can ship more profiles or fewer.

02 What one include line does

include <abstractions/NAME> abi <abi/5.0>, include <tunables/global> profile lsblk /usr/bin/lsblk { include <abstractions/base> } abstractions/base abi <abi/5.0>, include <abstractions/crypto> /dev/log w, @{PROC}/meminfo r, ... include if exists <abstractions/base.d> pasted include <abstractions/base> the same file again in this profile: skipped include <tunables/global> variables come from your preamble $ apparmor_parser -p /etc/apparmor.d/lsblk ##included <abstractions/base> ##included <abstractions/crypto> a marker before each file's text Could not open 'abstractions/nonexistent' an error, unless you wrote include if exists
A profile with one include line on the left and the text of abstractions/base on the right. The text is pasted in place of the include line; a second include of the same file is skipped; variables come from the profile's tunables line. Below, apparmor_parser -p prints markers for each included file, and a missing file is an error.

Includes are pasted as text, once per profile. Variables come from the including profile's include <tunables/global>. apparmor_parser -p prints the expanded profile with ##included <...> markers.

An include line isn't a call. It's a paste. The parser reads the file's text into your profile at that spot. Includes nest: base pulls in crypto. And a file that was already pulled into this profile is skipped the second time, so naming an abstraction twice costs nothing. An abstraction has no preamble of its own, so the @{PROC} and @{pid} variables it uses come from your tunables line. To see the result, run the parser with -p. And a wrong name stops the compile.

Details and sources

Details

  • include <abstractions/NAME> looks the file up in the parser's include path; #include <...> is the older spelling of the same rule.
  • The text of the file is read in place of the line. Includes nest: base includes crypto (base:15), which includes openssl and upki.
  • When the name is a directory, every file in it is read.
  • A missing file stops the compile unless the line says include if exists. Run with the parser built from the AppArmor tree at 836052d21, include <abstractions/nonexistent> on line 4 of a file gives: AppArmor parser error for /work/a1.sd in profile /work/a1.sd at line 4: Could not open 'abstractions/nonexistent'.
  • A file is included once per profile; a second include of it in the same profile is skipped, and -p prints ##skipped duplicate include <...> there. A child profile keeps its own list, so it can include base again and gets the rules.
  • An abstraction has no preamble. The variables it uses (@{HOME}, @{PROC}, @{run}, @{etc_ro}, @{multiarch}) must be defined by the including profile, normally with include <tunables/global>.
  • Every shipped abstraction starts with abi <abi/5.0>,. The first abi declaration the parser reads, the one in your profile, stays in force. When an included file declares a different one, the compile still succeeds; the parser prints ... features abi 'abi/5.0' differs from policy declared feature abi, using the features abi declared in policy, and only when run with --warn=abi or --warn=all (run with the tree's parser on a profile that declared abi <abi/4.0>,).
  • apparmor_parser -p (--preprocess) prints the profile with every include expanded and a ##included <...> line before each file's text. The two marker lines on the slide show the format and the nesting of base and crypto; they are not a capture of a run on lsblk.

for AppArmor developers

Code

03 base: what every program gets

abstractions/base any program ld.so /usr/lib/** r **.so* mr locale, zoneinfo, gconv /dev/log w, journal sockets /dev/null /dev/zero /dev/urandom /proc/meminfo, stat, cpuinfo /proc/PID/{maps,auxv,status} what glibc reads ptrace (readby), signal (receive) peer=unconfined, unix peer=(label=@{profile_name}), not only files <abstractions/crypto> openssl, upki your binary /etc/passwd network /tmp, terminals not in base: your next includes
A program in the centre and what abstractions/base grants around it: the loader and libraries, locale data, logging sockets, null and random devices, a few proc files, ptrace, signal and unix rules, and the crypto abstraction. Not granted: the program's own binary, /etc/passwd, network, /tmp and terminals.

base grants the loader and libraries, logging sockets, locale data, a few /proc and /sys files, and ptrace, signal and unix rules. It includes crypto. It grants no executable path, no /etc/passwd, no network, no /tmp and no terminal devices.

Base is the one include nearly every profile has, so it's worth five minutes. It lets a program load its libraries, read locale and time zone data, write to syslog and the journal, use /dev/null and the random devices, and read the handful of proc files that glibc looks at. It also carries rules that aren't about files: being traced, receiving signals from unconfined processes, talking over unix sockets to its own profile. And it includes crypto, so the OpenSSL configuration comes along. What it doesn't give you: your own executable, the password file, any network, temp files or a terminal. Those are your next includes.

Details and sources

Details

abstractions/base by group, at AppArmor 836052d21:

GroupRulesLines
Nested includeinclude <abstractions/crypto>, which includes openssl and upkibase:15
Logging/dev/log w, and the journal sockets @{run}/systemd/journal/{dev-log,socket} w,, stdout rw,base:25, base:43-49
Random devices/dev/random r, /dev/urandom r,base:26-27
Locale, time zones, gconvread access to the locale, zoneinfo and gconv treesbase:32-55
Loader@{etc_ro}/ld.so.cache mr, ld.so.conf, ld.so.preload, the ld-*.so loaders with mrbase:62-71
Libraries/{usr/,}lib{,32,64}/** r, and **.so* mr,; the same under lib/@{multiarch}/base:74-77
Null devices/dev/null rw, /dev/zero rw, /dev/full rw,base:87-92
procfs and sysfs@{PROC}/meminfo, stat, cpuinfo, filesystems, five files under @{PROC}/sys/, @{PROC}/@{pid}/{maps,auxv,status}, CPU and hugepage files under @{sys}; all rbase:95-128
ptraceptrace (readby), ptrace (tracedby), ptrace (read) peer=@{profile_name},base:134-142
signalsignal (receive) peer=unconfined, signal peer=@{profile_name}, signal (receive, send) set=("exists"),base:145-151
unixunix peer=(label=@{profile_name}), unix (receive) peer=(label=unconfined), unix (create), unix (getattr, getopt, setopt, shutdown),base:154-163
eCryptfsowner @{HOME}/.Private/** mrixwlk, owner @{HOMEDIRS}/.ecryptfs/*/.Private/** mrixwlk,base:176-180
Site additionsinclude if exists <abstractions/base.d>base:184
  • A profile that contains only include <abstractions/base> adds 94 non-comment lines to the expanded text (-p run with the parser built from the tree; the profile's own two lines are not counted, the repeated abi lines are).
  • base has no capability rule, no network rule and no rule with x except the ix in the two eCryptfs rules.
  • Not granted: the program's own executable (the usual line is @{exec_path} mr,), /etc/passwd (a name lookup abstraction), any network rule, /tmp (user-tmp), terminal devices (consoles).
  • The slide writes /proc/PID/... for @{PROC}/@{pid}/....

for security researchers

Attack surface

  • The three ptrace rules reach every profile with base. ptrace (readby), and ptrace (tracedby), have no peer condition: whether another task may read or trace this one is then decided by that task's own policy. ptrace (read) peer=@{profile_name}, lets the program read tasks of its own profile through /proc.
  • signal (receive) peer=unconfined, and unix (receive) peer=(label=unconfined), open the profile to unconfined peers.
  • @{PROC}/@{pid}/{maps,auxv,status} r, has no owner. For another task's maps and auxv the ptrace check still applies; status is world-readable in the kernel unless procfs is mounted with hidepid (linux:fs/proc/base.c:728). Read from the code, not run.
  • The eCryptfs rules give ix together with w on files the user owns under ~/.Private/: a place where a confined program that can write can also execute, under the same profile.

04 nameservice or nameservice-strict

getpwuid() NEEDS WHICH ONE? nameservice-strict @{etc_ro}/passwd r, @{etc_ro}/group r, @{etc_ro}/hosts r, @{etc_ro}/nsswitch.conf r, @{etc_ro}/resolv.conf r, and six more files under /etc include <abstractions/nss-systemd> resolver files under @{run} 30 lines expanded nameservice include <abstractions/nameservice-strict> nis ldapclient winbind likewise mdns kerberosclient authd 7 includes network inet stream, and 3 more network netlink raw, capability net_bind_service, nis /etc/{,krb5/}krb5.keytab rk, kerberosclient /etc/ldap.secret r, ldapclient 142 lines expanded lsblk, hostname, iotop-c: strict. curl, ping, dnsmasq: full.
Two abstractions side by side. nameservice-strict: the lookup files under /etc, nss-systemd and resolver files, 30 expanded lines. nameservice: includes the strict one, seven back-end abstractions, network rules, capability net_bind_service and read access to the Kerberos keytab and the LDAP secret, 142 expanded lines.

nameservice-strict: lookup files and resolver configuration (30 expanded lines). nameservice: that plus NIS, LDAP, winbind, Kerberos and mDNS back ends, network inet/inet6 stream/dgram, network netlink raw, capability net_bind_service and read access to /etc/krb5.keytab and /etc/ldap.secret (142 lines).

Your program calls getpwuid and gets a denial on the password file. Two abstractions fix it. The strict one grants the lookup files, the resolver configuration and the systemd user database sockets: thirty lines once expanded. The other one includes the strict one, and then every back end glibc might load: NIS, LDAP, winbind, Kerberos, mDNS. With them come TCP and UDP sockets, a netlink socket, the capability to bind low ports, and read access to the Kerberos keytab and the LDAP secret. A hundred and forty-two lines. If your program only looks up a user name, take the strict one. Fourteen include lines in the shipped profiles already do.

Details and sources

Details

  • nameservice-strict (nameservice-strict:11-38): r on @{etc_ro}/default/nss, gai.conf, group, host.conf, hosts, nsswitch.conf, passwd, protocols, resolv.conf, services; the extrausers and nscd copies of passwd and group; @{run}/nscd/db* r,; and it includes nss-systemd, which gives rw on the sockets @{run}/systemd/userdb/io.systemd.*. It has no network rule and no rule that maps a library.
  • /etc/resolv.conf is often a symlink into @{run}, so the strict file also lists @{run}/{NetworkManager,connman,netconfig,resolvconf}/resolv.conf and the two systemd-resolved files (nameservice-strict:34-38). See Symlinks: rules see through them.
  • nameservice includes nameservice-strict (nameservice:15) and adds:
Comes withRuleLine
nameservicenetwork inet stream, network inet6 stream, network inet dgram, network inet6 dgram,nameservice:92-95
nameservicenetwork netlink raw, ("Netlink raw needed for nscd")nameservice:99
nameservice/var/lib/sss/pipes/nss rw, (sssd)nameservice:25
nameservicenscd sockets rw, @{run}/nscd/db* mix,nameservice:35-40
nameservicelibnss_*.so* mr,nameservice:48-49
nameservice@{run}/avahi-daemon/socket rw,nameservice:52
nameservicea dbus send to systemd for dynamic usersnameservice:84-89
nameservice@{PROC}/@{pid}/net/route r,nameservice:103
niscapability net_bind_service,nis:16
kerberosclient/etc/{,krb5/}krb5.keytab rk, and /tmp/krb5cc* r,kerberosclient:30, kerberosclient:45
ldapclient/etc/ldap.secret r,; it also includes ssl_certsldapclient:15, ldapclient:26
winbindrw on the winbindd pipeswinbind:15-17
mdns@{run}/mdnsd w,mdns:16
authd@{run}/authd.sock rw,authd:5
  • The seven includes are at nameservice:62-80: nis, ldapclient, winbind, likewise, mdns, kerberosclient, authd.
  • 30 and 142 are the non-comment lines the include adds to the -p output of the parser built from the tree, for a profile with only that include; the profile's own two lines are not counted, repeated abi lines are.
  • Shipped users: nameservice-strict in 14 include lines, among them lsblk:18, hostname:21 and iotop-c:8; nameservice in 49, among them curl:17, bin.ping:18 and usr.sbin.dnsmasq:20.
  • A file rule only removes AppArmor's objection. The keytab and the LDAP secret keep their owner and mode, so a program that does not run as root is normally still refused by the ordinary permission check.

05 Three kits: a tool, a daemon, a desktop program

KITS lsblk (command line) base consoles nameservice-strict dovecot-lmtp (daemon) base nameservice dovecot-common ssl_certs ssl_keys 22 dovecot profiles share it transmission-gtk (desktop) transmission-common dbus-session-strict dconf dri-enumerate gnome gtk vulkan gnome gnome includes base fonts gtk X freedesktop.org xdg-desktop user-tmp wayland opengl vulkan 357 lines user-tmp: owner /tmp/** rwkl opengl, vulkan: GPU devices X and wayland: both sockets one desktop line is convenient and broad; toolkit pieces are longer and narrower
The include lists of three shipped profiles: lsblk, a command-line tool, with three abstractions; dovecot-lmtp, a daemon, with five including the family abstraction dovecot-common; transmission-gtk, a desktop program, with seven. The gnome abstraction itself includes ten others and expands to 357 lines.

CLI: base, consoles, nameservice-strict. Daemon: base, a name lookup abstraction, the family abstraction, ssl_certs (and ssl_keys for servers). GUI: toolkit, display, fonts, dbus-session-strict, or gnome / kde, which include most of them (357 and 279 expanded lines).

Three kinds of program, three kits. A command-line tool: base, consoles for the terminal, and a name lookup abstraction. A daemon from a known family: base, nameservice, and the family's own abstraction. Dovecot's LMTP server takes dovecot-common, which twenty-two dovecot profiles share, plus ssl_certs and ssl_keys. A desktop program: here you choose. The gnome abstraction is one line that pulls in ten others: fonts, GTK, X and Wayland, temp files, OpenGL and Vulkan. Three hundred and fifty-seven lines in all. Or you pick the pieces yourself. For a general-purpose app the one-liner is a fair trade, as long as you know temp files and GPU access came with it.

Details and sources

Details

  • The three lists are the include lines of shipped profiles: lsblk (lsblk:16-18), dovecot-lmtp (usr.lib.dovecot.lmtp:18-22) and transmission-gtk (transmission:58-65). The slide leaves out include <abstractions/ and >.
  • dovecot-common is included by 22 profile files: the 21 usr.lib.dovecot.* files and usr.sbin.dovecot (grep). It carries capability setgid, (dovecot-common:14). Other dovecot workers take fewer lines; usr.lib.dovecot.imap-login has only base and dovecot-common.
  • gnome includes base, fonts, gtk, X, freedesktop.org, xdg-desktop, user-tmp, wayland, opengl and vulkan (gnome:15-24) and expands to 359 non-comment lines; kde includes base, fonts, X, freedesktop.org, xdg-desktop, user-tmp and qt5 (kde:14-20) and expands to 281 (-p runs with the parser built from the tree).
  • What comes along with gnome: owner /tmp/** rwkl, from user-tmp (user-tmp:21); /dev/dri/** rw, through opengl, vulkan, mesa and dri-common; the X11 sockets from X and owner @{run}/user/*/wayland-[0-9]* rw, from wayland; rw on the XDG base directories themselves from xdg-desktop.
  • Among the files directly under profiles/apparmor.d, only transmission includes gnome and none includes kde; X is in 3 include lines, fonts in 5, vulkan in 3 (grep). The larger desktop profiles are under profiles/apparmor/profiles/extras/.

Inventory by kit (the complete tables are in the reference below):

KitAbstractions
Command lineconsoles, terminfo, user-tmp, user-manpages, gnupg, apparmor_api/*
Daemonauthentication, wutmp, libpam-systemd, hosts_access, mysql, cups-client, web-data; family abstractions apache2-common, dovecot-common, postfix-common, frr, samba
TLSssl_certs for clients (10 include lines), ssl_keys for servers that read private keys (3); openssl is redundant where base is included, because base includes crypto, which includes openssl
DesktopX, wayland, gtk, qt5, qt6, gnome, kde, fonts, freedesktop.org, xdg-desktop, dconf, dri-common, mesa, nvidia, opengl, vulkan, video, audio
D-Busdbus-strict and dbus-session-strict (socket and handshake), dbus and dbus-session (the whole bus)
Interpretersbash, perl, python, ruby, php
  • The family abstractions carry capabilities and wide network rules written for that family's own binaries: postfix-common has capability setuid, setgid, sys_chroot (postfix-common:17-19), frr has six capabilities and a bare network, (frr:18-24).

06 Narrow names, wide grants

READ BEFORE YOU INCLUDE authentication @{etc_ro}/shadow r, ssl_keys /etc/ssl/** r, private keys included dbus dbus-session dbus bus=system, dbus bus=session, every method of every service user-tmp owner /tmp/** rwkl, l = hard links bash @{HOME}/.bash_history rw, no owner audio /dev/snd/* rw, @{PROC}/asound/** rw, ubuntu-helpers profile sanitized_helper { /** rwkl, network inet, ... } its own header: "Use at your own risk"
A table of abstractions and the wide rule each one carries: authentication reads /etc/shadow, ssl_keys reads all of /etc/ssl, dbus and dbus-session allow the whole bus, user-tmp has the link permission on /tmp, bash reads and writes the history file without owner, audio opens every sound device, and ubuntu-helpers defines the sanitized_helper profile with read and write on everything.

authentication: /etc/shadow r. ssl_keys: /etc/ssl/** r. dbus, dbus-session: the whole bus. user-tmp: l on /tmp/**. ubuntu-helpers: a sanitized_helper profile with /** rwkl,.

Most abstractions do what the name says. A few do a lot more, and they're worth knowing by heart. Authentication lets the program read the shadow file. ssl_keys is all of /etc/ssl, private keys included, where a TLS client only needs ssl_certs. The dbus abstraction without strict in its name is the whole bus. User-tmp includes the link letter. Bash gives read and write on the history file, with no owner. Audio is every sound device. And ubuntu-helpers defines a helper profile that can read and write almost everything. Its own header says: use at your own risk.

Details and sources

Details

The rows of the slide, and the rest of the list:

AbstractionRuleLine
authentication@{etc_ro}/shadow r, and @{etc_ro}/gshadow r,; also unix_chkpwd Px, and six nested includesauthentication:23-24, authentication:36
ssl_keys/etc/ssl/** r, ("Just include the whole /etc/ssl directory if we should have access to private keys too"), plus ACME, dehydrated and certbot private keysssl_keys:19
dbusdbus bus=system,dbus:18
dbus-sessiondbus bus=session, and /usr/bin/dbus-launch ix,dbus-session:18-19
dbus-accessibilitydbus bus=accessibility,dbus-accessibility:18
user-tmpowner /tmp/** rwkl, owner /var/tmp/** rwkl, owner @{HOME}/tmp/** rwkl,user-tmp:15-22
bash@{HOME}/.bash_history rw, without owner; ls and dircolors with mixbash:18, bash:45-46
audiorw on the legacy device names, /dev/snd/* rw, /dev/sound/* rw, @{PROC}/asound/** rw,audio:16-39
nameservicenetwork rules, capability net_bind_service, through nis, the Kerberos keytab, the LDAP secretsee the nameservice scene
apache2-common/**/.htaccess r,apache2-common:32
user-write, user-downloadowner @{HOME}/[^.]* rwl,: every non-hidden entry at the top of the home directoryuser-write:20, user-download:20
web-data@{HOME}/public_html/** r, without ownerweb-data:20-21
baseowner @{HOME}/.Private/** mrixwlk, (eCryptfs, with ix)base:177

Abstractions that carry capabilities:

AbstractionCapabilitiesLine
nisnet_bind_servicenis:16
nvidiaipc_locknvidia:7
ubuntu-konsolesys_ptraceubuntu-konsole:10
dovecot-commonsetgiddovecot-common:14
postfix-commonsetuid, setgid, sys_chrootpostfix-common:17-19
frrnet_bind_service, chown, setgid, setuid, dac_override, dac_read_search, and a bare network,frr:18-24

ubuntu-helpers defines a profile instead of adding rules (ubuntu-helpers:36):

  • profile sanitized_helper has network inet, network inet6, network unix, (ubuntu-helpers:42-44), dbus,, Pixr on everything in the bin and lib directories, PUxr on browser sandboxes, /usr/bin/snap ux, and / r, /** rwkl, (ubuntu-helpers:93).
  • Two deny rules follow: audit deny owner /**/* m, and audit deny owner /**/*.py* r, (ubuntu-helpers:97-98).
  • The header (ubuntu-helpers:1-32) calls it "an open profile that blacklists certain known dangerous files", says "This does not work for root owned processes, because of the way we use owner matching", and ends "Use at your own risk."
  • The ubuntu-browsers, ubuntu-email, ubuntu-media-players and similar abstractions send helpers there with Cx -> sanitized_helper,. No profile directly under profiles/apparmor.d uses them at this commit (grep).
  • Known discrepancy: the header says the abstraction "must only be included once" to avoid parser errors about multiple definitions. With the parser built from the tree at 836052d21 a profile that includes it twice compiles; the second include is skipped.
  • Known discrepancy: ruby names only Ruby 1.8 and 1.9 directories (ruby:14-23). Not checked against an installed Ruby.
  • Known discrepancy: audio has no PipeWire rule (grep). Not checked on a system.

for security researchers

Attack surface

  • An abstraction's breadth is inherited by every profile that includes it. In the shipped profiles that is 122 include lines for base, 49 for nameservice, 9 for user-tmp.
  • Side grants to look for first when auditing a profile, in the output of apparmor_parser -p: - capability net_bind_service, (from nis, through nameservice); - /etc/{,krb5/}krb5.keytab rk, and /etc/ldap.secret r, (through nameservice): AppArmor stops objecting, the files' own modes still apply; - l on owner /tmp/** rwkl, (user-tmp): the program may create hard links in /tmp to files it owns; - dbus bus=system, or dbus bus=session, without conditions: every service on that bus is reachable, and what a service then does for the caller happens outside this profile; - ix together with w under ~/.Private/ (base); - @{HOME}/.bash_history rw, and @{HOME}/public_html/** r, without owner: other users' files match when the ordinary permission check lets them through; - Cx -> sanitized_helper,: the child profile is close to unconfined for a non-root user, with /** rwkl,, three network families and Pixr on the bin directories. Its two deny rules use owner, which is why the header says it does not work for root.
  • What happens at exec time when a profile has Cx -> sanitized_helper, and no sanitized_helper child was not determined; such a profile compiles with the tree's parser.

07 private-files: abstractions that take away

DENY-ONLY ABSTRACTIONS @{HOME} owner file rw @{HOME}/**, curl: include <abstractions/private-files-strict> .ssh/ .gnupg/ .aws/ .mozilla/ keyrings, chromium, ... audit deny @{HOME}/.ssh/{,**} mrwkl, no allow rules in the file audit: logged deny: wins over allow l: no links created there either deny @{HOME}/.*rc mrk, audit deny @{HOME}/.*rc wl, private-files, included by the strict one every hidden file ending in rc owner @{HOME}/.ssh/config r, still denied priority=1 owner file r @{HOME}/.curlrc, priority 1 outranks priority 0 rules, deny included a deny list protects the names on it, nothing else
The home directory as a band that curl's owner rule covers, with denied cut-outs for .ssh, .gnupg, .aws and .mozilla from private-files-strict. Below, an audit deny rule, the two rules for hidden files ending in rc from private-files, an ordinary allow rule that stays denied, and curl's own rule with priority 1.

private-files-strict adds audit deny ... mrwkl on ~/.ssh, ~/.gnupg, ~/.aws, browser profiles and keyrings; it includes private-files. A deny cannot be overridden by an allow of the same priority.

Curl may read and write anything you own under home. Your SSH keys are under home. That's what private-files-strict is for. It has no allow rules at all, only denies: SSH, GnuPG, AWS credentials, browser profiles, keyrings. Deny beats allow, so the big owner rule has holes exactly there. Two things follow. You can't include it and then allow one of those paths in the ordinary way; the deny still wins. The way out is a rule with a higher priority, and curl's profile carries one on its own dot file. And a deny list only covers the names somebody thought of.

Details and sources

Details

  • private-files-strict includes private-files (private-files-strict:7) and adds audit deny ... mrwkl on @{HOME}/.aws/, .gnupg/, .ssh/, .gnome2_private/, .gnome2/keyrings/, @{run}/user/[0-9]*/keyring**, .mozilla/, .config/chromium/, .config/evolution/, .evolution/, Thunderbird, KMail and KWallet data, each as DIR/{,**}, and audit deny ... w on a few parent directories (private-files-strict:10-27).
  • private-files has three groups: - history and editor backup files, denied without audit: deny @{HOME}/.*history mrwkl, and seven more. The comment gives the reason: "don't audit files under $HOME otherwise get a lot of false positives when reading contents of directories" (private-files:7-16); - places from which files get executed: audit deny ... wl on @{HOME}/bin/, .config/autostart/, .config/upstart/, .init/, the KDE Autostart/ and env/ directories, .local/share/thumbnailers/ and .pki/nssdb/ (private-files:19-30); - shell start-up files: deny @{HOME}/.*rc mrk, with audit deny @{HOME}/.*rc wl,, and the same pair for .bash*, .inputrc, .{,z}profile*, .{,z}log{in,out} and .zshenv (private-files:33-49).
  • Neither file contains an allow rule. audit deny writes a log record for each refused access; plain deny refuses silently.
  • The mask mrwkl includes l, so the profile also may not create a link in those directories.
  • private-files-strict is in 9 include lines of the shipped profiles, among them curl (curl:18).
  • Within one priority level, deny rules have precedence over allow rules. The tree's local/README says so and gives the remedy: "To override them, you have to specify an allow rule with a higher priority" (local/README:25-28). A browser profile therefore cannot include private-files-strict and read ~/.mozilla with an ordinary rule.
  • curl's two priority=1 rules (curl:27-28) are for @{HOME}/.curlrc and @{HOME}/.config/curlrc. Read as text, the name .curlrc matches the pattern of deny @{HOME}/.*rc mrk,, and .config/curlrc matches no deny rule in either file. The profile's comment only says "allow reading configuration files from $HOME", and the commit that added the rules has no message body, so which deny, if any, the author had in mind is not recorded. The compiled result for .curlrc was not queried.
  • Complain mode does not switch these off: in the kernel a plain deny rule still blocks, silently, in a complain-mode profile (read from the code, not run).
  • Known discrepancy: for audit deny rules in a complain-mode profile the kernel code reads as allowing the access; the question is open. Test deny rules in enforce mode.

for security researchers

Attack surface

  • The two files are a list of names. A secret stored under a name that is not on it (a Git credentials file, a cloud tool's configuration directory) is covered by whatever allow rule the profile has for the home directory.
  • audit deny @{HOME}/.config/ w, is a rule for the directory itself, not for what is below it.
  • The deny rules are matched against the path the program uses. A hard link to a denied file under another name is another path; see Hard links and name-based rules.
  • The plain deny rules for history and start-up files leave no log record, so probing for them is silent.

08 Site changes: NAME.d and local/

TWO PLACES FOR YOUR OWN RULES /etc/apparmor.d/abstractions/base include if exists <abstractions/base.d> $ cat abstractions/base.d/site /opt/site/lib/** mr, curl ping lsblk dnsmasq ... every profile with base one file, every profile $ cat local/lsblk /srv/images/*.img r, profile lsblk { ... include if exists <local/lsblk> one profile $ sudo apparmor_parser -r /etc/apparmor.d/lsblk the shipped files stay untouched, so package updates do not fight you
Two places for site rules. A file in abstractions/base.d is read by the base abstraction and so reaches every profile that includes base. A file local/lsblk is read only by the lsblk profile. The profile is then reloaded with apparmor_parser -r.

abstractions/NAME.d/ extends an abstraction for all profiles that include it. local/PROFILE extends one profile. Both are read through include if exists; reload with apparmor_parser -r.

Your site keeps libraries under /opt, and half your profiles deny them. Don't edit base. Nearly every abstraction ends with an include if exists line for a directory named after it. Drop a file with your rule into base.d, and every profile that includes base gets it the next time it's reloaded. That's powerful, so think about how many profiles that is. When only one program needs something, use its local file instead: the shipped profiles end with an include if exists for a file under local, named after the profile. Then reload the profile.

Details and sources

Details

  • base ends with include if exists <abstractions/base.d> (base:184). base.d is a directory: every file in it is read. The same line, with the abstraction's own name, ends every top-level abstraction except two.
  • The exceptions: ubuntu-browsers has no include line at all, and ubuntu-helpers has include if exists <local/ubuntu-helpers> inside the profile it defines (ubuntu-helpers:39). The files under apparmor_api/ and ubuntu-browsers.d/ have no extension line either; ubuntu-browsers.d/ is a directory of separate abstractions, not the extension directory of ubuntu-browsers.
  • The tree ships no NAME.d directory. Whether a distribution ships files there was not determined.
  • local/PROFILE: all 198 profile files directly under profiles/apparmor.d contain an include if exists <local/...> line (grep), for example lsblk:58. The tree's local/README:1 describes the convention.
  • The paths /opt/site/lib/ and /srv/images/ and the file name site are illustrations.
  • A file in NAME.d is pasted into every including profile like the abstraction itself. A deny rule placed there cannot be undone by an ordinary allow rule of any profile that includes the abstraction.
  • apparmor_parser -r replaces the loaded profile with the newly compiled one. How a changed include file is noticed, and what the policy cache does with it, is the subject of Loading policy into the kernel and The policy cache.

for security researchers

Attack surface

  • /etc/apparmor.d/abstractions/base.d/ is a single place that widens every profile with base: 122 include lines in the shipped profiles. A file there is not part of any package's profile, so a review of the shipped profile text does not show it.
  • The same holds for every other NAME.d and for local/PROFILE. The policy of a machine is the apparmor_parser -p output on that machine.
  • Who may write under /etc/apparmor.d, and who may load the result, is the question of Who can change policy.

09 How aa-logprof suggests an abstraction

FROM A LOG RECORD TO include <...> apparmor="ALLOWED" operation="open" profile="demo" name="/etc/ssl/certs/ca-certificates.crt" ... requested_mask="r" denied_mask="r" fsuid=1000 ouid=0 /etc/ssl/certs/ca-certificates.crt r every loaded abstraction is asked base openssl ssl_certs ssl_keys frr ssl_certs ssl_keys a rule covers it no rule covers it [1 - include <abstractions/ssl_certs>] 2 - include <abstractions/ssl_keys> 3 - /etc/ssl/certs/ca-certificates.crt r, already included # LOGPROF-SUGGEST: no no ranking: the narrow one and the broad one, side by side $ sudo aa-logprof --no-abstraction offers paths only new profiles: base, plus bash, perl, python or ruby when the program is a script
A log record for a read of the certificate bundle is compared with every abstraction. base is already in the profile and skipped, openssl has no rule that covers the path, ssl_certs and ssl_keys each have one, frr carries a LOGPROF-SUGGEST no comment. The menu lists the two includes and then the path. aa-logprof --no-abstraction offers paths only.

aa-logprof proposes an abstraction when one of its rules covers the logged event. # LOGPROF-SUGGEST: no in an abstraction stops that. --no-abstraction turns proposals off. New profiles start with abstractions/base, plus the interpreter's abstraction for scripts.

Where do the include suggestions in aa-logprof come from? The tool loads every abstraction, and for each log record it asks each one: do you have a rule that covers this? Any that says yes goes on the menu, above the path. It skips what your profile already includes, and abstractions with a comment saying LOGPROF-SUGGEST: no, like the FRR one. There's no ranking: ssl_certs, which is what a client needs, sits next to ssl_keys, which opens all of /etc/ssl. If you'd rather see only paths, start the tool with the --no-abstraction option. And a brand new profile always starts with base.

Details and sources

Details

  • The log record is built for the slide: the field layout is that of the fixture libraries/libapparmor/testsuite/test_multi/syslog_datetime_01.in, the values (profile demo, the path, the ids) are illustrative. The menu is rendered from the tool's code, not captured from a session.
  • An abstraction is proposed for an event when all of this holds: the profile does not include it already; it is not under local/; it is a file under abstractions/ of the profile directory, or it is listed in custom_includes in logprof.conf; and one of its rules of that rule type covers the event.
  • The proposals are listed first, as include <abstractions/NAME>, sorted by name; the path and its globbed forms follow. The first option is preselected.
  • Nothing ranks proposals by breadth. For a read of /etc/ssl/certs/ca-certificates.crt the rules that cover it are /etc/{,libre}ssl/certs/{,**} r, in ssl_certs (ssl_certs:17) and /etc/ssl/** r, in ssl_keys (ssl_keys:19). Checked by running the rule classes of the tree's Python module over every top-level abstraction; a full aa-logprof session was not run.
  • An event that the profile, or any abstraction it includes (nested ones too), already covers is not asked about at all. That is why base does not appear on the menu, and why a read of /etc/ssl/openssl.cnf raises no question in a profile with base: base includes crypto, which includes openssl.
  • # LOGPROF-SUGGEST: is a comment line in an abstraction. Absent or empty: always eligible. no: never proposed. Anything else is a space-separated list of regular expressions matched against the profile name. Shipped uses, all no: frr:2, frr-snmp:2, transmission-common:2. On the slide frr stands for these; it has no rule for the certificate bundle either.
  • --no-abstraction exists on aa-genprof and aa-logprof ("Do not use any abstractions in profiles"). It removes the proposals from the menu; a new profile still gets base.
  • A new profile gets include <abstractions/base> if that file exists; otherwise the tool prints WARNING: Can't find abstractions/base, therefore not adding it to the new profile. For a script, the interpreter on the #! line decides one more abstraction: bash, dash, sh give abstractions/bash; perl gives perl; python, python2, python3, python3.N give python; ruby and rubyN.N give ruby. Other interpreters (node, lua, php) get only base.
  • Known discrepancy: the tools' matcher does not expand variables. With the tree's Python module, the rule @{etc_ro}/passwd r, does not cover a logged read of /etc/passwd. Abstractions written with @{etc_ro}, @{PROC}, @{HOME} or @{run} may therefore neither be proposed nor be recognised as already granting an access, so the tool can ask about a path the policy already allows. Checked at the level of the rule classes; a full aa-logprof session was not run.

for AppArmor developers

Code

10 Reviewing a profile: the includes are the policy for security researchers

THE INCLUDE GRAPH profile curl /usr/bin/curl { include <abstractions/base> include <abstractions/nameservice> ... four more what the file shows abstractions/base abstractions/nameservice 122 include lines 49 include lines one edit lands in all of them /etc/apparmor.d/abstractions/base.d/* if it exists pasted into every profile with base at its next compile $ apparmor_parser -p /etc/apparmor.d/curl on the machine, not in the tree search the expanded profile for capability net_bind_service, /etc/{,krb5/}krb5.keytab rk, owner /tmp/** rwkl, dbus bus=session, owner @{HOME}/.Private/** mrixwlk, /usr/bin/NAME Cx -> sanitized_helper,
The curl profile file with its include lines; base and nameservice are shared by 122 and 49 include lines of the shipped profiles; a directory abstractions/base.d on the installed system feeds into base. Below, the rules to search for first in the expanded profile, and the command apparmor_parser -p.

One abstraction is shared by many profiles, and abstractions/NAME.d/ on the installed system adds to it. Review the output of apparmor_parser -p on the machine, and search it for capability, krb5.keytab, rwkl, dbus bus=, ix and sanitized_helper.

You're reviewing a profile. The file shows six include lines. The policy is a few hundred rules somebody else wrote. So treat the includes as a graph. Base is included a hundred and twenty-two times in the shipped profiles, nameservice forty-nine: one edit to either lands in all of them. And the edit doesn't have to touch the file. Base ends by reading a directory called base.d, if it exists, and its contents are pasted into every profile with base at the next compile. So expand the profile on the machine, and search for the side grants first: the capability, the keytab, the link letter, the whole bus, the helper profile.

Details and sources

Details

  • curl's profile has six abstraction includes (curl:15-22): base, consoles, nameservice, private-files-strict, ssl_certs, user-tmp.
  • Fan-in, as grep counts of include lines over profiles/apparmor.d/ outside abstractions/ at AppArmor 836052d21: base 122, nameservice 49, consoles 27, nameservice-strict 14, ssl_certs 10, user-tmp 9, private-files-strict 9. Abstractions include each other as well: gnome pulls in ten, nameservice eight.
  • include if exists <abstractions/base.d> is the last line of base (base:184); all top-level abstractions except ubuntu-browsers and ubuntu-helpers have the same line for their own name. The tree ships no such directory, so anything found there on a machine was added by the distribution or the administrator.
  • An include is a text paste at compile time. A changed abstraction or a new file in NAME.d takes effect for a profile when that profile is compiled and loaded again; see Loading policy into the kernel and The policy cache for when that happens.
  • The rules in the search list and where they come from:
RuleAbstractionLine
capability net_bind_service,nis, included by nameservicenis:16
/etc/{,krb5/}krb5.keytab rk,kerberosclient, included by nameservice and authenticationkerberosclient:30
/etc/ldap.secret r,ldapclient, included by nameserviceldapclient:15
owner /tmp/** rwkl,user-tmp, also through gnome and kdeuser-tmp:21
dbus bus=session, dbus bus=system,dbus-session, dbusdbus-session:19, dbus:18
owner @{HOME}/.Private/** mrixwlk,basebase:177
/usr/bin/NAME Cx -> sanitized_helper,ubuntu-browsers, ubuntu-email and the other ubuntu-* listsubuntu-browsers:11-25
  • apparmor_parser -p prints the profile with every include expanded and does not load anything.
  • This scene describes policy text. Nothing in it was run against a kernel.

Attack surface

  • A reviewer who reads only the profile file misses most of the policy; a reviewer who reads only the tree misses NAME.d and local/ on the machine.
  • Write access to one abstraction, or to its .d directory, is write access to the policy of every profile that includes it. For base that is nearly every confined program.
  • A deny rule in an abstraction is inherited the same way and cannot be undone by an ordinary allow rule in the profile, so the fan-in works for tightening as well.
  • The helper profile sanitized_helper is defined inside an abstraction (ubuntu-helpers). A profile that includes it and has Cx -> sanitized_helper, rules gives a taken-over program a child profile with /** rwkl, and three network families. What happens at exec time when the child is missing was not determined.

11 Where to go from here

ROADS choosing abstractions base + lookup + what you use read before you include prac-general-purpose the style built from them prac-privileged when to use the strict variants syn-include include and if exists syn-abstractions-tunables where the files live dbus-mediation what the dbus ones control ut-logprof the tool that proposes includes prac-sys-proc /proc and /sys rules
Choosing abstractions in the centre with roads to prac-general-purpose, prac-privileged, syn-include, syn-abstractions-tunables, dbus-mediation, ut-logprof and prac-sys-proc.

Next: prac-general-purpose, prac-privileged, syn-include, syn-abstractions-tunables, dbus-mediation, ut-logprof, prac-sys-proc.

So: base, one name lookup abstraction, then only what your program uses. And print the expanded profile before you trust it. The general-purpose apps deck shows the profile style that's built this way, on curl. The security-sensitive programs deck shows why precise profiles prefer the strict variants. Include syntax, abstractions and tunables, D-Bus, aa-logprof, and rules for proc and sys each have a deck of their own.

Details and sources

Details

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run with -p or -Q on a profile, with nothing loaded into a kernel; "code" means the source of the parser, the tools or mainline Linux 7.4 was read, not run; "grep" is a count over profiles/apparmor.d/ at that commit. File names without a directory are under profiles/apparmor.d/abstractions/. Nothing here was observed on a running kernel.

Inventory by purpose

.d means the file ends with include if exists <abstractions/NAME.d>. "Users" are include lines in the shipped profiles outside abstractions/ (grep).

Start-up

NamePurposeNotable grantsIncludes.dUsers
basewhat a dynamically linked program needs to start, log and be signalledloader and libraries mr, /dev/log w, journal sockets, locale data, /dev/null rw, procfs and sysfs files, ptrace, signal and unix rules, eCryptfs mrixwlkcryptoyes122
cryptogcrypt, gnutls and crypto-policies configuration@{PROC}/sys/crypto/* r,openssl, upkiyesthrough base
opensslOpenSSL configuration/etc/ssl/openssl.cnf r, and engine directoriesyes3, redundant with base
upkiupki configuration and cache/etc/upki/config.toml r, /var/cache/upki/** r,yesthrough base

Name lookup

NamePurposeNotable grantsIncludes.dUsers
nameservice-strictusers, groups and hosts from files; resolver configurationten files under @{etc_ro}, extrausers and nscd copies, resolver files under @{run}nss-systemdyes14
nss-systemdsystemd user databaserw on @{run}/systemd/userdb/io.systemd.*yesthrough the above
nameserviceevery lookup back endnetwork inet/inet6 stream/dgram, network netlink raw, sssd pipe, nscd and avahi sockets, libnss_*.so* mrnameservice-strict, nis, ldapclient, winbind, likewise, mdns, kerberosclient, authdyes49
nisNIScapability net_bind_service,yesthrough nameservice
ldapclientLDAP/etc/ldap.secret r,ssl_certsyesthrough nameservice
kerberosclientKerberos/etc/{,krb5/}krb5.keytab rk, /tmp/krb5cc* r,yesthrough nameservice
winbind, likewise, mdns, authdwinbind pipes, likewise, mdnsd, authd socketrw on the daemon's pipes or socketyesthrough nameservice

Command-line tools

NamePurposeNotable grants.d
consolesterminal devices/dev/console rw, /dev/tty rw, /dev/pts/[0-9]* rw, /dev/pts/ r,yes
terminfoterminfo databasesryes
user-tmptemporary filesowner /tmp/** rwkl, /tmp/ rw, and the same for /var/tmp and @{HOME}/tmpyes
user-manpagesman pages and groff temp filesr, temp filesyes
groffgroff toolsmrix on the groff binariesyes
gnupgGnuPG filesnamed files under @{HOME}/.gnupg/, including secring.gpg ryes
aspell, enchantspelling dictionariesenchant includes aspellyes
libnuma, golang, psi-read, psi-read-pollsmall procfs and sysfs setssee the /proc and /sys tableyes
altslibalternativesincludes baseyes
apparmor_api/introspect, examine, change_profile, find_mountpoint, is_enabledfiles a program using libapparmor needschange_profile includes introspect; is_enabled includes find_mountpointno

Daemons and families

NamePurposeNotable grants.d
authenticationPAM@{etc_ro}/shadow r, gshadow r, pam_*.so mr, unix_chkpwd Px,; includes kerberosclient, nis, winbind, likewise, smbpass, p11-kityes
wutmplogin recordsrwk on wtmp, btmp, lastlog, @{run}/utmpyes
libpam-systemdlogind sessionsdbus send for CreateSession, ReleaseSession; includes dbus-strictyes
hosts_accesstcp wrappers/etc/hosts.allow, /etc/hosts.denyyes
mysqlMySQL clientsocket and charsetsyes
cups-clientCUPS client@{run}/cups/cups.sock rw,yes
web-datadocument rootsread-only, including @{HOME}/public_html/** r, without owneryes
apache2-commonApache familyincludes nameservice; /**/.htaccess r,; @{PROC}/@{pid}/attr/{apparmor/,}current rw, for change_hatyes
dovecot-commonDovecot family (22 profile files)capability setgid,yes
postfix-commonPostfix familycapability setuid, setgid, sys_chrootyes
frr, frr-snmpFRR family (18 profiles)network, and six capabilities; # LOGPROF-SUGGEST: noyes
samba, samba-rpcd, smbpassSamba family/var/lib/samba/** rwk,yes
transmission-commonTransmission family162 rule lines; # LOGPROF-SUGGEST: noyes
php, php5, php-workerPHPconfiguration, modules, session files rwlkyes

Crypto and TLS

NamePurposeNotable grantsUsers
ssl_certsCA bundles and public certificatesread-only10
ssl_keysprivate keys/etc/ssl/** r, and ACME, dehydrated, letsencrypt and certbot private keys3
p11-kitPKCS#11 modulesmodule configuration, *.so mr, the keyring's pkcs11 socket rw

A TLS client needs ssl_certs. ssl_keys is for servers that read their private key.

Interpreters

NameNotable grants
bash@{HOME}/.bashrc, .profile, .bash_profile r; @{HOME}/.bash_history rw, (no owner); /{usr/,}bin/ls mix, /usr/bin/dircolors mix,; @{HOMEDIRS} r,
perl/usr/bin/perl rmix,, module trees r, **.so* mr
pythoninterpreter binaries r (no execute), standard library and site-packages, owner @{HOME}/.cache/Python/** rw,
ruby/usr/lib{,32,64}/ruby/1.[89]{.[0-9],}/... only
phpsee daemons
golangcgroup CPU quota files

Desktop and graphics

NameNotable grantsIncludes
XXauthority files owner ... r, /tmp/.X11-unix/* rw, and the abstract X sockets, deny /var/cache/libx11/compose/* wlk,dri-common
waylandowner @{run}/user/*/wayland-[0-9]* rw,
gtkthemes and settings, owner @{HOME}/.Xauthority r, owner @{HOME}/.xsession-errors w,
qt5, qt6plugin and QML trees mr; write variants qt5-settings-write, qt6-settings-write, qt5-compose-cache-write, qt6-compose-cache-write
gnomeGTK module trees mr, @{PROC}/@{pid}/mounts r,base, fonts, gtk, X, freedesktop.org, xdg-desktop, user-tmp, wayland, opengl, vulkan
kdeKDE configuration; opt-in write sets kde-globals-write, kde-icon-cache-write, kde-language-write, recent-documents-write, trashbase, fonts, X, freedesktop.org, xdg-desktop, user-tmp, qt5
fontssystem fonts r, owner @{HOME}/.{,cache/}fontconfig/** mrwkl,
freedesktop.orgapplications, icons, mime databases r; recently-used.xbel* rw
xdg-desktoprw on the XDG base directories themselves, not their contents
dconfowner @{run}/user/*/dconf/user rw,, database r
dri-common, dri-enumerate, mesa/dev/dri/** rw,, shader cache rwmesa includes both dri files
nvidiacapability ipc_lock, /dev/nvidia* rw
opengl, vulkanmesa, nvidia
video/dev/video[0-9]* rw,
audiorw on OSS and ALSA devices, @{PROC}/asound/** rw,, PulseAudio cookie, socket and shm
ibus, fcitx, fcitx-strict, mozcinput methods

D-Bus

NameGrants
dbus-strict@{run}/dbus/system_bus_socket rw, and the six handshake calls to org.freedesktop.DBus
dbusdbus-strict plus dbus bus=system,
dbus-session-strictthe session socket owner @{run}/user/[0-9]*/bus rw,, abstract @/tmp/dbus-*, machine-id
dbus-sessionadds /usr/bin/dbus-launch ix, and dbus bus=session,
dbus-accessibility-strict, dbus-accessibilitythe accessibility bus; the non-strict one has dbus bus=accessibility,
dbus-network-manager-strictnamed NetworkManager read calls

Users: dbus-session-strict 6 profile files, dbus-strict 2, dbus 2. What these rules control, and who enforces them, is in D-Bus mediation.

Opening other programs

NameWhat it is
xdg-open, gio-open, gvfs-open, exo-open, kde-open5meant for a child profile. The header shows the pattern /usr/bin/xdg-open rPx -> foo//xdg-open, with profile foo//xdg-open { include <abstractions/xdg-open> }. xdg-open expands to 776 lines (tree).
ubuntu-browsers, ubuntu-console-browsers, ubuntu-email, ubuntu-console-email, ubuntu-media-players, ubuntu-bittorrent-clients, ubuntu-feed-readerslists of /usr/bin/NAME Cx -> sanitized_helper,; the including profile must also include ubuntu-helpers
ubuntu-helpersdefines profile sanitized_helper
ubuntu-gnome-terminal, ubuntu-xterm, ubuntu-konsoleix on the terminal emulator; ubuntu-konsole has capability sys_ptrace,
ubuntu-browsers.d/*building blocks for browser profiles; user-files includes private-files, java includes private-files-strict
snap_browsersdefines profile snap_browsers with child profiles

Deny-only

NameRulesUsers
private-filesdeny on history and backup files; audit deny ... wl on ~/bin, autostart and plugin directories; deny ... mrk and audit deny ... wl on shell start-up files, including @{HOME}/.*rcthrough the strict one and ubuntu-browsers.d/user-files
private-files-strictincludes private-files; audit deny ... mrwkl on .aws, .gnupg, .ssh, keyrings, .mozilla, Chromium, Evolution, Thunderbird, KMail, KWallet9

Expanded sizes

Non-comment lines that the include adds to the -p output of a profile that contains only this include (tree). The profile's own two lines (profile t { and }) are not counted; repeated abi lines are.

AbstractionLines
nameservice-strict30
base94
nameservice142
kde279
gnome357
xdg-open776

Side grants to know

AbstractionRuleFile and line
authentication@{etc_ro}/shadow r, @{etc_ro}/gshadow r,authentication:23-24
ssl_keys/etc/ssl/** r,ssl_keys:19
dbusdbus bus=system,dbus:18
dbus-sessiondbus bus=session, /usr/bin/dbus-launch ix,dbus-session:18-19
dbus-accessibilitydbus bus=accessibility,dbus-accessibility:18
user-tmpowner /tmp/** rwkl, (with l)user-tmp:21
bash@{HOME}/.bash_history rw, without ownerbash:18
audio/dev/snd/* rw, @{PROC}/asound/** rw,audio:36-39
nameservicenetwork inet stream, and three more; network netlink raw,nameservice:92-99
nis (through nameservice)capability net_bind_service,nis:16
kerberosclient (through nameservice)/etc/{,krb5/}krb5.keytab rk, /tmp/krb5cc* r,kerberosclient:30,45
ldapclient (through nameservice)/etc/ldap.secret r,ldapclient:15
apache2-common/**/.htaccess r,apache2-common:32
user-write, user-downloadowner @{HOME}/[^.]* rwl,user-write:20, user-download:20
web-data@{HOME}/public_html/** r, without ownerweb-data:20-21
baseowner @{HOME}/.Private/** mrixwlk,base:177
nvidiacapability ipc_lock,nvidia:7
ubuntu-konsolecapability sys_ptrace,ubuntu-konsole:10
dovecot-commoncapability setgid,dovecot-common:14
postfix-commoncapability setuid, setgid, sys_chroot,postfix-common:17-19
frrsix capabilities and network,frr:18-24
ubuntu-helpersprofile sanitized_helper with /** rwkl,, network inet, inet6, unix,, dbus,, Pixr on bin and lib directories, PUxr on browser sandboxes, /usr/bin/snap ux,; then audit deny owner /**/* m, and audit deny owner /**/*.py* r,ubuntu-helpers:36-98

The header of ubuntu-helpers says the profile "does not work for root owned processes, because of the way we use owner matching" and ends "Use at your own risk."

/proc and /sys rules that abstractions already carry

All r unless noted.

AbstractionRulesLines
base@{PROC}/sys/kernel/version, ngroups_max, cap_last_cap; @{PROC}/sys/crypto/fips_enabled; @{PROC}/sys/vm/overcommit_memory; @{PROC}/meminfo, stat, cpuinfo, filesystems; @{PROC}/@{pid}/{maps,auxv,status}; @{sys}/devices/system/cpu/, online, possible; transparent hugepage enabled, hpage_pmd_sizebase:95-128
crypto@{PROC}/sys/crypto/fips_enabled, @{PROC}/sys/crypto/*crypto:24,27
nameservice@{PROC}/@{pid}/net/psched, ipv6_route, routenameservice:55,102-103
nss-systemd@{PROC}/sys/kernel/random/boot_idnss-systemd:30
bash@{PROC}/@{pid}/mounts, @{PROC}/filesystemsbash:37-38
gnome@{PROC}/@{pid}/mountsgnome:82
golangowner @{PROC}/@{pid}/mountinfo, owner @{PROC}/@{pid}/cgroup, cgroup CPU quota filesgolang:5-8
audio@{PROC}/asound/** rw,audio:39
nvidia@{PROC}/interrupts, @{PROC}/modules, @{PROC}/driver/nvidia/paramsnvidia:20-23
mesa@{sys}/devices/@{pci_bus}/**/{revision,config}mesa:17
apparmor_api/find_mountpoint@{PROC}/@{pids}/mountsfind_mountpoint:16
psi-read, psi-read-poll@{PROC}/pressure/{cpu,memory,io}, r and rwline 6 of each

base's @{PROC}/@{pid}/{maps,auxv,status} r, has no owner. For another task's maps and auxv the ptrace check still applies; status is world-readable unless procfs is mounted with hidepid (code). More in Writing rules for /sys and /proc.

Extension points

PlaceReachesRead through
/etc/apparmor.d/abstractions/NAME.d/*every profile that includes NAMEinclude if exists <abstractions/NAME.d> at the end of NAME
/etc/apparmor.d/local/PROFILEone profileinclude if exists <local/PROFILE> at the end of the profile
  • Exceptions without a .d line: ubuntu-browsers (no include line), ubuntu-helpers (include if exists <local/ubuntu-helpers> inside its profile), and the files under apparmor_api/ and ubuntu-browsers.d/.
  • The tree ships no NAME.d directory. All 198 profile files directly under profiles/apparmor.d have a local/ include (grep).
  • A deny rule in NAME.d cannot be undone by an ordinary allow rule of an including profile.

Include mechanics and messages

TextMeaning
include <abstractions/NAME>search the include path; #include <...> is the older spelling
include if exists <...>no error when the file or directory is missing
include <DIR>every file in the directory is read
AppArmor parser error for FILE in profile FILE at line N: Could not open 'abstractions/nonexistent'a missing include without if exists (tree)
... features abi 'abi/5.0' differs from policy declared feature abi, using the features abi declared in policyan included file declares another abi than the profile; printed only with --warn=abi or --warn=all; the compile succeeds (tree)
##included <abstractions/NAME>marker in -p output before an included file's text
##skipped duplicate include <...>marker in -p output where a file was already included in this profile
##failed include <...>marker in -p output for a file that could not be opened (code)
  • A file is included once per profile; child profiles have their own list (code, tree).
  • An abstraction has no preamble: its variables come from the including profile's include <tunables/global>.

How the tools choose

  • New profile (aa-genprof, aa-autodep): include <abstractions/base>; if the file is missing, WARNING: Can't find abstractions/base, therefore not adding it to the new profile.
  • Scripts: the interpreter on the #! line adds one abstraction, r on the script and ix on the interpreter.
InterpreterAbstraction
bash, dash, shabstractions/bash
perlabstractions/perl
python, python2, python3, python3.Nabstractions/python
ruby, rubyN.Nabstractions/ruby
anything else (node, lua, php)none
  • Suggestions: for each logged event, every loaded abstraction is proposed that is not already included, is not under local/, is under abstractions/ or listed in custom_includes of logprof.conf, and has a rule covering the event. Proposals come first in the menu, sorted by name, without ranking by breadth.
  • An event already covered by the profile or its includes, nested ones too, is not asked about.
  • # LOGPROF-SUGGEST: in an abstraction: absent or empty, always eligible; no, never proposed; otherwise regular expressions matched against the profile name. Shipped: frr, frr-snmp, transmission-common, all no.
  • --no-abstraction (aa-genprof, aa-logprof) removes the proposals; new profiles still get base.

Known discrepancies

None of these is intended behaviour to rely on.

  • aa-logprof and variables: the tools' matcher does not expand variables, so @{etc_ro}/passwd r, does not cover a logged /etc/passwd. Abstractions written with @{etc_ro}, @{PROC}, @{HOME}, @{run} may neither be proposed nor recognised as already granting the access. Checked with the rule classes of the tree's Python module; a full aa-logprof session was not run.
  • ubuntu-helpers header: says a second include causes parser errors about multiple definitions. With the tree's parser the duplicate is skipped and the compile succeeds. Documentation only.
  • opengl header: line 2 reads # Vulkan access requirements. Documentation only.
  • ruby: covers only ruby/1.[89] directories, so the abstraction that aa-genprof adds for a Ruby script may grant nothing useful. Not verified against an installed Ruby.
  • audio reads PipeWire's client configuration (audio:89-91) but has no rule for a PipeWire socket. Not verified on a system.
  • audit deny in a complain-mode profile: the kernel code reads as allowing the access; open question. The private-files pair uses audit deny for most of its rules.
  • Not determined: what happens at exec time for Cx -> sanitized_helper, when the profile has no sanitized_helper child (such a profile compiles with -Q); whether distributions ship files in abstractions/*.d/.

for AppArmor developers

Code

WhatWhere
include path search, ##included markerparser/parser_lex.l:170-181
Could not open, if existsparser/parser_lex.l:192-197
text inclusion (buffer push), directory includesparser/parser_lex.l:207-216, :128
##skipped duplicate includeparser/parser_lex.l:223
duplicate checkparser/parser_include.c:165
per-profile include cacheparser/parser_yacc.y:396-397, :454-455
abi in a profile body; first declaration winsparser/parser_yacc.y:722, :1892-1903
default warning classesparser/parser.h:77-78
match_includes, valid_includeutils/apparmor/aa.py:1419-1459, :1463-1475
menu orderutils/apparmor/aa.py:1152-1156
is_known_ruleutils/apparmor/aa.py:2341-2351
loadincludesutils/apparmor/aa.py:2519-2534
interpreter mapping, new profileutils/apparmor/aa.py:372-381, :391-404
LOGPROF-SUGGESTutils/apparmor/regex.py:93, utils/apparmor/aa.py:2034-2038, utils/apparmor/profile_storage.py:83
--no-abstractionutils/aa-logprof:32, utils/aa-genprof:72, utils/apparmor/aa.py:284-286
variable gap in the matcherutils/apparmor/aare.py:49, :83, utils/apparmor/common.py:238-243

Roads from here

PREAMBLE AND REUSE

QUALIFIERS

IN PRACTICE · general-purpose apps

IN PRACTICE · security-sensitive programs

TOOLS · utils/

  • aa-logprof — the tool that proposes include lines

LIBAPPARMOR