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
- Profiles for general-purpose apps — the profile style built on these includes
- Abstractions and tunables — what an abstraction file is and where it lives
Part of journeys
- Write your first profile, step 10 of 12 · previous: Profiles for general-purpose apps · next: Generating a profile
01 Which include lines does my program need?
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 underubuntu-browsers.d/. On an installed system they are under/etc/apparmor.d/abstractions/. - The lsblk profile includes
base,consolesandnameservice-strict(lsblk:16-18). - Usage counts are grep counts of
include <abstractions/NAME>lines overprofiles/apparmor.d/outsideabstractions/, at AppArmor 836052d21: 198 profile files at the top level plusapache2.d/phpsysinfo.base122 lines,nameservice49,consoles27,nameservice-strict14,ssl_certs10,user-tmp9,private-files-strict9. - 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
baseat 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
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:
baseincludescrypto(base:15), which includesopensslandupki. - 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
includeof it in the same profile is skipped, and-pprints##skipped duplicate include <...>there. A child profile keeps its own list, so it can includebaseagain 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 withinclude <tunables/global>. - Every shipped abstraction starts with
abi <abi/5.0>,. The firstabideclaration 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=abior--warn=all(run with the tree's parser on a profile that declaredabi <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 ofbaseandcrypto; they are not a capture of a run on lsblk.
Read more
for AppArmor developers
Code
- The include rule in the lexer: search of the include path and the
##includedmarker (parser_lex.l:170-181),Could not openand theif existsexit (parser_lex.l:192-197), the buffer push that makes it a text paste (parser_lex.l:207), directories read file by file (parser_lex.l:208-216, callback at parser_lex.l:128), the##skipped duplicate includemarker (parser_lex.l:223). - The duplicate check: parser_include.c:165. The include cache is replaced when a profile starts (parser_yacc.y:396-397) and restored after it (parser_yacc.y:454-455).
abiinside a profile body is grammatical (parser_yacc.y:722); the first declaration wins and a different later one only warns (parser_yacc.y:1892-1903). Theabiwarning class is not among the default warnings (parser.h:77-78).
03 base: what every program gets
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:
| Group | Rules | Lines |
|---|---|---|
| Nested include | include <abstractions/crypto>, which includes openssl and upki | base: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, gconv | read access to the locale, zoneinfo and gconv trees | base:32-55 |
| Loader | @{etc_ro}/ld.so.cache mr, ld.so.conf, ld.so.preload, the ld-*.so loaders with mr | base: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 r | base:95-128 |
| ptrace | ptrace (readby), ptrace (tracedby), ptrace (read) peer=@{profile_name}, | base:134-142 |
| signal | signal (receive) peer=unconfined, signal peer=@{profile_name}, signal (receive, send) set=("exists"), | base:145-151 |
| unix | unix peer=(label=@{profile_name}), unix (receive) peer=(label=unconfined), unix (create), unix (getattr, getopt, setopt, shutdown), | base:154-163 |
| eCryptfs | owner @{HOME}/.Private/** mrixwlk, owner @{HOMEDIRS}/.ecryptfs/*/.Private/** mrixwlk, | base:176-180 |
| Site additions | include if exists <abstractions/base.d> | base:184 |
- A profile that contains only
include <abstractions/base>adds 94 non-comment lines to the expanded text (-prun with the parser built from the tree; the profile's own two lines are not counted, the repeatedabilines are). basehas no capability rule, no network rule and no rule withxexcept theixin the two eCryptfs rules.- Not granted: the program's own executable (the usual line is
@{exec_path} mr,),/etc/passwd(a name lookup abstraction), anynetworkrule,/tmp(user-tmp), terminal devices (consoles). - The slide writes
/proc/PID/...for@{PROC}/@{pid}/....
Read more
for security researchers
Attack surface
- The three ptrace rules reach every profile with
base.ptrace (readby),andptrace (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,andunix (receive) peer=(label=unconfined),open the profile to unconfined peers.@{PROC}/@{pid}/{maps,auxv,status} r,has noowner. For another task'smapsandauxvthe ptrace check still applies;statusis world-readable in the kernel unless procfs is mounted withhidepid(linux:fs/proc/base.c:728). Read from the code, not run.- The eCryptfs rules give
ixtogether withwon 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
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):ron@{etc_ro}/default/nss,gai.conf,group,host.conf,hosts,nsswitch.conf,passwd,protocols,resolv.conf,services; the extrausers and nscd copies ofpasswdandgroup;@{run}/nscd/db* r,; and it includesnss-systemd, which givesrwon the sockets@{run}/systemd/userdb/io.systemd.*. It has no network rule and no rule that maps a library./etc/resolv.confis often a symlink into@{run}, so the strict file also lists@{run}/{NetworkManager,connman,netconfig,resolvconf}/resolv.confand the two systemd-resolved files (nameservice-strict:34-38). See Symlinks: rules see through them.nameserviceincludesnameservice-strict(nameservice:15) and adds:
| Comes with | Rule | Line |
|---|---|---|
nameservice | network inet stream, network inet6 stream, network inet dgram, network inet6 dgram, | nameservice:92-95 |
nameservice | network netlink raw, ("Netlink raw needed for nscd") | nameservice:99 |
nameservice | /var/lib/sss/pipes/nss rw, (sssd) | nameservice:25 |
nameservice | nscd sockets rw, @{run}/nscd/db* mix, | nameservice:35-40 |
nameservice | libnss_*.so* mr, | nameservice:48-49 |
nameservice | @{run}/avahi-daemon/socket rw, | nameservice:52 |
nameservice | a dbus send to systemd for dynamic users | nameservice:84-89 |
nameservice | @{PROC}/@{pid}/net/route r, | nameservice:103 |
nis | capability 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_certs | ldapclient:15, ldapclient:26 |
winbind | rw on the winbindd pipes | winbind: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
-poutput of the parser built from the tree, for a profile with only that include; the profile's own two lines are not counted, repeatedabilines are. - Shipped users:
nameservice-strictin 14 include lines, among them lsblk:18, hostname:21 and iotop-c:8;nameservicein 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
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) andtransmission-gtk(transmission:58-65). The slide leaves outinclude <abstractions/and>. dovecot-commonis included by 22 profile files: the 21usr.lib.dovecot.*files andusr.sbin.dovecot(grep). It carriescapability setgid,(dovecot-common:14). Other dovecot workers take fewer lines;usr.lib.dovecot.imap-loginhas onlybaseanddovecot-common.gnomeincludesbase,fonts,gtk,X,freedesktop.org,xdg-desktop,user-tmp,wayland,openglandvulkan(gnome:15-24) and expands to 359 non-comment lines;kdeincludesbase,fonts,X,freedesktop.org,xdg-desktop,user-tmpandqt5(kde:14-20) and expands to 281 (-pruns with the parser built from the tree).- What comes along with
gnome:owner /tmp/** rwkl,fromuser-tmp(user-tmp:21);/dev/dri/** rw,throughopengl,vulkan,mesaanddri-common; the X11 sockets fromXandowner @{run}/user/*/wayland-[0-9]* rw,fromwayland;rwon the XDG base directories themselves fromxdg-desktop. - Among the files directly under
profiles/apparmor.d, onlytransmissionincludesgnomeand none includeskde;Xis in 3 include lines,fontsin 5,vulkanin 3 (grep). The larger desktop profiles are underprofiles/apparmor/profiles/extras/.
Inventory by kit (the complete tables are in the reference below):
| Kit | Abstractions |
|---|---|
| Command line | consoles, terminfo, user-tmp, user-manpages, gnupg, apparmor_api/* |
| Daemon | authentication, wutmp, libpam-systemd, hosts_access, mysql, cups-client, web-data; family abstractions apache2-common, dovecot-common, postfix-common, frr, samba |
| TLS | ssl_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 |
| Desktop | X, wayland, gtk, qt5, qt6, gnome, kde, fonts, freedesktop.org, xdg-desktop, dconf, dri-common, mesa, nvidia, opengl, vulkan, video, audio |
| D-Bus | dbus-strict and dbus-session-strict (socket and handshake), dbus and dbus-session (the whole bus) |
| Interpreters | bash, perl, python, ruby, php |
- The family abstractions carry capabilities and wide network rules written for that family's own binaries:
postfix-commonhascapability setuid, setgid, sys_chroot(postfix-common:17-19),frrhas six capabilities and a barenetwork,(frr:18-24).
06 Narrow names, wide grants
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:
| Abstraction | Rule | Line |
|---|---|---|
authentication | @{etc_ro}/shadow r, and @{etc_ro}/gshadow r,; also unix_chkpwd Px, and six nested includes | authentication: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 keys | ssl_keys:19 |
dbus | dbus bus=system, | dbus:18 |
dbus-session | dbus bus=session, and /usr/bin/dbus-launch ix, | dbus-session:18-19 |
dbus-accessibility | dbus bus=accessibility, | dbus-accessibility:18 |
user-tmp | owner /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 mix | bash:18, bash:45-46 |
audio | rw on the legacy device names, /dev/snd/* rw, /dev/sound/* rw, @{PROC}/asound/** rw, | audio:16-39 |
nameservice | network rules, capability net_bind_service, through nis, the Kerberos keytab, the LDAP secret | see the nameservice scene |
apache2-common | /**/.htaccess r, | apache2-common:32 |
user-write, user-download | owner @{HOME}/[^.]* rwl,: every non-hidden entry at the top of the home directory | user-write:20, user-download:20 |
web-data | @{HOME}/public_html/** r, without owner | web-data:20-21 |
base | owner @{HOME}/.Private/** mrixwlk, (eCryptfs, with ix) | base:177 |
Abstractions that carry capabilities:
| Abstraction | Capabilities | Line |
|---|---|---|
nis | net_bind_service | nis:16 |
nvidia | ipc_lock | nvidia:7 |
ubuntu-konsole | sys_ptrace | ubuntu-konsole:10 |
dovecot-common | setgid | dovecot-common:14 |
postfix-common | setuid, setgid, sys_chroot | postfix-common:17-19 |
frr | net_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_helperhasnetwork inet,network inet6,network unix,(ubuntu-helpers:42-44),dbus,,Pixron everything in the bin and lib directories,PUxron browser sandboxes,/usr/bin/snap ux,and/ r,/** rwkl,(ubuntu-helpers:93).- Two deny rules follow:
audit deny owner /**/* m,andaudit 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-playersand similar abstractions send helpers there withCx -> sanitized_helper,. No profile directly underprofiles/apparmor.duses 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:
rubynames only Ruby 1.8 and 1.9 directories (ruby:14-23). Not checked against an installed Ruby. - Known discrepancy:
audiohas no PipeWire rule (grep). Not checked on a system.
Read more
- apparmor.d(5): abstractions/authentication, apparmor.d(5): abstractions/user-tmp, apparmor.d(5): abstractions/bash, apparmor.d(5): abstractions/audio, apparmor.d(5): l - Link mode.
- wiki: sanitized_helper.
- Hard links and name-based rules: the
lin/tmp. D-Bus mediation. Exec modes. AppArmor's threat model.
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 fornameservice, 9 foruser-tmp. - Side grants to look for first when auditing a profile, in the output of
apparmor_parser -p: -capability net_bind_service,(fromnis, throughnameservice); -/etc/{,krb5/}krb5.keytab rk,and/etc/ldap.secret r,(throughnameservice): AppArmor stops objecting, the files' own modes still apply; -lonowner /tmp/** rwkl,(user-tmp): the program may create hard links in/tmpto files it owns; -dbus bus=system,ordbus bus=session,without conditions: every service on that bus is reachable, and what a service then does for the caller happens outside this profile; -ixtogether withwunder~/.Private/(base); -@{HOME}/.bash_history rw,and@{HOME}/public_html/** r,withoutowner: 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 andPixron the bin directories. Its two deny rules useowner, 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 nosanitized_helperchild was not determined; such a profile compiles with the tree's parser.
07 private-files: abstractions that take away
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-strictincludesprivate-files(private-files-strict:7) and addsaudit deny ... mrwklon@{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 asDIR/{,**}, andaudit deny ... won a few parent directories (private-files-strict:10-27).private-fileshas three groups: - history and editor backup files, denied withoutaudit: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 ... wlon@{HOME}/bin/,.config/autostart/,.config/upstart/,.init/, the KDEAutostart/andenv/directories,.local/share/thumbnailers/and.pki/nssdb/(private-files:19-30); - shell start-up files:deny @{HOME}/.*rc mrk,withaudit 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 denywrites a log record for each refused access; plaindenyrefuses silently. - The mask
mrwklincludesl, so the profile also may not create a link in those directories. private-files-strictis 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/READMEsays 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 includeprivate-files-strictand read~/.mozillawith an ordinary rule. - curl's two
priority=1rules (curl:27-28) are for@{HOME}/.curlrcand@{HOME}/.config/curlrc. Read as text, the name.curlrcmatches the pattern ofdeny @{HOME}/.*rc mrk,, and.config/curlrcmatches 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.curlrcwas not queried. - Complain mode does not switch these off: in the kernel a plain
denyrule still blocks, silently, in a complain-mode profile (read from the code, not run). - Known discrepancy: for
audit denyrules in a complain-mode profile the kernel code reads as allowing the access; the question is open. Test deny rules in enforce mode.
Read more
- apparmor.d(5): deny, apparmor.d(5): audit, apparmor.d(5): priority.
- allow and deny, The audit qualifier, Rule priority.
- Hard links and name-based rules: a deny matches names, not files.
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
denyrules for history and start-up files leave no log record, so probing for them is silent.
08 Site changes: NAME.d and local/
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
baseends withinclude if exists <abstractions/base.d>(base:184).base.dis 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-browsershas no include line at all, andubuntu-helpershasinclude if exists <local/ubuntu-helpers>inside the profile it defines (ubuntu-helpers:39). The files underapparmor_api/andubuntu-browsers.d/have no extension line either;ubuntu-browsers.d/is a directory of separate abstractions, not the extension directory ofubuntu-browsers. - The tree ships no
NAME.ddirectory. Whether a distribution ships files there was not determined. local/PROFILE: all 198 profile files directly underprofiles/apparmor.dcontain aninclude 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 namesiteare illustrations. - A file in
NAME.dis pasted into every including profile like the abstraction itself. Adenyrule placed there cannot be undone by an ordinary allow rule of any profile that includes the abstraction. apparmor_parser -rreplaces 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.
Read more
for security researchers
Attack surface
/etc/apparmor.d/abstractions/base.d/is a single place that widens every profile withbase: 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.dand forlocal/PROFILE. The policy of a machine is theapparmor_parser -poutput 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
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 (profiledemo, 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 underabstractions/of the profile directory, or it is listed incustom_includesinlogprof.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.crtthe rules that cover it are/etc/{,libre}ssl/certs/{,**} r,inssl_certs(ssl_certs:17) and/etc/ssl/** r,inssl_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
basedoes not appear on the menu, and why a read of/etc/ssl/openssl.cnfraises no question in a profile withbase:baseincludescrypto, which includesopenssl. # 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, allno: frr:2, frr-snmp:2, transmission-common:2. On the slidefrrstands for these; it has no rule for the certificate bundle either.--no-abstractionexists onaa-genprofandaa-logprof("Do not use any abstractions in profiles"). It removes the proposals from the menu; a new profile still getsbase.- A new profile gets
include <abstractions/base>if that file exists; otherwise the tool printsWARNING: 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,shgiveabstractions/bash;perlgivesperl;python,python2,python3,python3.Ngivepython;rubyandrubyN.Ngiveruby. Other interpreters (node, lua, php) get onlybase. - 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.
Read more
- aa-logprof(8), aa-genprof(8), logprof.conf(5).
- apparmor.net: Generate profiles with aa-genprof.
- aa-logprof, Generating a profile, Profiles for general-purpose apps: the question menu and its keys.
for AppArmor developers
Code
match_includes(aa.py:1419-1459): the loop over loaded include files, the already-included andlocal/skips, theis_coveredtest and thelogprof_suggesthandling.valid_include(aa.py:1463-1475).- The menu puts the proposals first (aa.py:1152-1156).
is_known_rule(aa.py:2341-2351) checks the profile and its includes recursively before any question. loadincludesreads every file undertunablesandabstractions(aa.py:2519-2534).- New profiles:
get_interpreter_and_abstraction(aa.py:372-381),create_new_profile(aa.py:391-404). LOGPROF-SUGGEST: the regex (regex.py:93), where it is read (aa.py:2034-2038), the empty default (profile_storage.py:83).--no-abstraction: aa-logprof:32, aa-genprof:72,disable_abstractions(aa.py:284-286).- The variable gap: aare.py:49 (
# self.variables = variables # XXX), aare.py:83, the brace rewriting at common.py:238-243; test-aare.py:239 is a test case with a@{PROC}/pattern; it expects no match against/foobar.
10 Reviewing a profile: the includes are the policy for security researchers
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/outsideabstractions/at AppArmor 836052d21:base122,nameservice49,consoles27,nameservice-strict14,ssl_certs10,user-tmp9,private-files-strict9. Abstractions include each other as well:gnomepulls in ten,nameserviceeight. include if exists <abstractions/base.d>is the last line ofbase(base:184); all top-level abstractions exceptubuntu-browsersandubuntu-helpershave 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.dtakes 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:
| Rule | Abstraction | Line |
|---|---|---|
capability net_bind_service, | nis, included by nameservice | nis:16 |
/etc/{,krb5/}krb5.keytab rk, | kerberosclient, included by nameservice and authentication | kerberosclient:30 |
/etc/ldap.secret r, | ldapclient, included by nameservice | ldapclient:15 |
owner /tmp/** rwkl, | user-tmp, also through gnome and kde | user-tmp:21 |
dbus bus=session, dbus bus=system, | dbus-session, dbus | dbus-session:19, dbus:18 |
owner @{HOME}/.Private/** mrixwlk, | base | base:177 |
/usr/bin/NAME Cx -> sanitized_helper, | ubuntu-browsers, ubuntu-email and the other ubuntu-* lists | ubuntu-browsers:11-25 |
apparmor_parser -pprints the profile with every include expanded and does not load anything.- This scene describes policy text. Nothing in it was run against a kernel.
Read more
- apparmor_parser(8): OPTIONS, apparmor.d(5): include mechanism.
- wiki: sanitized_helper, wiki: AbstractionsGuide.
- Who can change policy, AppArmor's threat model, What is not mediated.
- Profiles for general-purpose apps: what a taken-over curl keeps under its shipped profile.
Attack surface
- A reviewer who reads only the profile file misses most of the policy; a reviewer who reads only the tree misses
NAME.dandlocal/on the machine. - Write access to one abstraction, or to its
.ddirectory, is write access to the policy of every profile that includes it. Forbasethat is nearly every confined program. - A
denyrule 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_helperis defined inside an abstraction (ubuntu-helpers). A profile that includes it and hasCx -> 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
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
- Profiles for general-purpose apps: the short, broad profile style built from abstractions, followed on the shipped curl profile.
- Profiles for security-sensitive programs: the precise style, and why it picks
nameservice-strictand explicit paths. - include: the include rule,
if exists, quoted and angle-bracket paths. - Abstractions and tunables: where the files live and how the include path is searched.
- The abi rule: the
abiline every abstraction starts with. - allow and deny and Rule priority: why a deny in an abstraction cannot be undone by an ordinary allow rule.
- D-Bus mediation: what the
dbus*abstractions actually control, and who enforces it. - aa-logprof: every option and key of the tool that proposes include lines.
- Writing rules for /sys and /proc: the rules abstractions already carry there.
- For security researchers: Who can change policy and AppArmor's threat model.
- Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825).
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
| Name | Purpose | Notable grants | Includes | .d | Users |
|---|---|---|---|---|---|
base | what a dynamically linked program needs to start, log and be signalled | loader and libraries mr, /dev/log w, journal sockets, locale data, /dev/null rw, procfs and sysfs files, ptrace, signal and unix rules, eCryptfs mrixwlk | crypto | yes | 122 |
crypto | gcrypt, gnutls and crypto-policies configuration | @{PROC}/sys/crypto/* r, | openssl, upki | yes | through base |
openssl | OpenSSL configuration | /etc/ssl/openssl.cnf r, and engine directories | yes | 3, redundant with base | |
upki | upki configuration and cache | /etc/upki/config.toml r, /var/cache/upki/** r, | yes | through base |
Name lookup
| Name | Purpose | Notable grants | Includes | .d | Users |
|---|---|---|---|---|---|
nameservice-strict | users, groups and hosts from files; resolver configuration | ten files under @{etc_ro}, extrausers and nscd copies, resolver files under @{run} | nss-systemd | yes | 14 |
nss-systemd | systemd user database | rw on @{run}/systemd/userdb/io.systemd.* | yes | through the above | |
nameservice | every lookup back end | network inet/inet6 stream/dgram, network netlink raw, sssd pipe, nscd and avahi sockets, libnss_*.so* mr | nameservice-strict, nis, ldapclient, winbind, likewise, mdns, kerberosclient, authd | yes | 49 |
nis | NIS | capability net_bind_service, | yes | through nameservice | |
ldapclient | LDAP | /etc/ldap.secret r, | ssl_certs | yes | through nameservice |
kerberosclient | Kerberos | /etc/{,krb5/}krb5.keytab rk, /tmp/krb5cc* r, | yes | through nameservice | |
winbind, likewise, mdns, authd | winbind pipes, likewise, mdnsd, authd socket | rw on the daemon's pipes or socket | yes | through nameservice |
Command-line tools
| Name | Purpose | Notable grants | .d |
|---|---|---|---|
consoles | terminal devices | /dev/console rw, /dev/tty rw, /dev/pts/[0-9]* rw, /dev/pts/ r, | yes |
terminfo | terminfo databases | r | yes |
user-tmp | temporary files | owner /tmp/** rwkl, /tmp/ rw, and the same for /var/tmp and @{HOME}/tmp | yes |
user-manpages | man pages and groff temp files | r, temp files | yes |
groff | groff tools | mrix on the groff binaries | yes |
gnupg | GnuPG files | named files under @{HOME}/.gnupg/, including secring.gpg r | yes |
aspell, enchant | spelling dictionaries | enchant includes aspell | yes |
libnuma, golang, psi-read, psi-read-poll | small procfs and sysfs sets | see the /proc and /sys table | yes |
alts | libalternatives | includes base | yes |
apparmor_api/introspect, examine, change_profile, find_mountpoint, is_enabled | files a program using libapparmor needs | change_profile includes introspect; is_enabled includes find_mountpoint | no |
Daemons and families
| Name | Purpose | Notable grants | .d |
|---|---|---|---|
authentication | PAM | @{etc_ro}/shadow r, gshadow r, pam_*.so mr, unix_chkpwd Px,; includes kerberosclient, nis, winbind, likewise, smbpass, p11-kit | yes |
wutmp | login records | rwk on wtmp, btmp, lastlog, @{run}/utmp | yes |
libpam-systemd | logind sessions | dbus send for CreateSession, ReleaseSession; includes dbus-strict | yes |
hosts_access | tcp wrappers | /etc/hosts.allow, /etc/hosts.deny | yes |
mysql | MySQL client | socket and charsets | yes |
cups-client | CUPS client | @{run}/cups/cups.sock rw, | yes |
web-data | document roots | read-only, including @{HOME}/public_html/** r, without owner | yes |
apache2-common | Apache family | includes nameservice; /**/.htaccess r,; @{PROC}/@{pid}/attr/{apparmor/,}current rw, for change_hat | yes |
dovecot-common | Dovecot family (22 profile files) | capability setgid, | yes |
postfix-common | Postfix family | capability setuid, setgid, sys_chroot | yes |
frr, frr-snmp | FRR family (18 profiles) | network, and six capabilities; # LOGPROF-SUGGEST: no | yes |
samba, samba-rpcd, smbpass | Samba family | /var/lib/samba/** rwk, | yes |
transmission-common | Transmission family | 162 rule lines; # LOGPROF-SUGGEST: no | yes |
php, php5, php-worker | PHP | configuration, modules, session files rwlk | yes |
Crypto and TLS
| Name | Purpose | Notable grants | Users |
|---|---|---|---|
ssl_certs | CA bundles and public certificates | read-only | 10 |
ssl_keys | private keys | /etc/ssl/** r, and ACME, dehydrated, letsencrypt and certbot private keys | 3 |
p11-kit | PKCS#11 modules | module 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
| Name | Notable 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 |
python | interpreter 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 |
php | see daemons |
golang | cgroup CPU quota files |
Desktop and graphics
| Name | Notable grants | Includes |
|---|---|---|
X | Xauthority files owner ... r, /tmp/.X11-unix/* rw, and the abstract X sockets, deny /var/cache/libx11/compose/* wlk, | dri-common |
wayland | owner @{run}/user/*/wayland-[0-9]* rw, | |
gtk | themes and settings, owner @{HOME}/.Xauthority r, owner @{HOME}/.xsession-errors w, | |
qt5, qt6 | plugin and QML trees mr; write variants qt5-settings-write, qt6-settings-write, qt5-compose-cache-write, qt6-compose-cache-write | |
gnome | GTK module trees mr, @{PROC}/@{pid}/mounts r, | base, fonts, gtk, X, freedesktop.org, xdg-desktop, user-tmp, wayland, opengl, vulkan |
kde | KDE configuration; opt-in write sets kde-globals-write, kde-icon-cache-write, kde-language-write, recent-documents-write, trash | base, fonts, X, freedesktop.org, xdg-desktop, user-tmp, qt5 |
fonts | system fonts r, owner @{HOME}/.{,cache/}fontconfig/** mrwkl, | |
freedesktop.org | applications, icons, mime databases r; recently-used.xbel* rw | |
xdg-desktop | rw on the XDG base directories themselves, not their contents | |
dconf | owner @{run}/user/*/dconf/user rw,, database r | |
dri-common, dri-enumerate, mesa | /dev/dri/** rw,, shader cache rw | mesa includes both dri files |
nvidia | capability ipc_lock, /dev/nvidia* rw | |
opengl, vulkan | mesa, nvidia | |
video | /dev/video[0-9]* rw, | |
audio | rw on OSS and ALSA devices, @{PROC}/asound/** rw,, PulseAudio cookie, socket and shm | |
ibus, fcitx, fcitx-strict, mozc | input methods |
D-Bus
| Name | Grants |
|---|---|
dbus-strict | @{run}/dbus/system_bus_socket rw, and the six handshake calls to org.freedesktop.DBus |
dbus | dbus-strict plus dbus bus=system, |
dbus-session-strict | the session socket owner @{run}/user/[0-9]*/bus rw,, abstract @/tmp/dbus-*, machine-id |
dbus-session | adds /usr/bin/dbus-launch ix, and dbus bus=session, |
dbus-accessibility-strict, dbus-accessibility | the accessibility bus; the non-strict one has dbus bus=accessibility, |
dbus-network-manager-strict | named 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
| Name | What it is |
|---|---|
xdg-open, gio-open, gvfs-open, exo-open, kde-open5 | meant 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-readers | lists of /usr/bin/NAME Cx -> sanitized_helper,; the including profile must also include ubuntu-helpers |
ubuntu-helpers | defines profile sanitized_helper |
ubuntu-gnome-terminal, ubuntu-xterm, ubuntu-konsole | ix 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_browsers | defines profile snap_browsers with child profiles |
Deny-only
| Name | Rules | Users |
|---|---|---|
private-files | deny 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}/.*rc | through the strict one and ubuntu-browsers.d/user-files |
private-files-strict | includes private-files; audit deny ... mrwkl on .aws, .gnupg, .ssh, keyrings, .mozilla, Chromium, Evolution, Thunderbird, KMail, KWallet | 9 |
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.
| Abstraction | Lines |
|---|---|
nameservice-strict | 30 |
base | 94 |
nameservice | 142 |
kde | 279 |
gnome | 357 |
xdg-open | 776 |
Side grants to know
| Abstraction | Rule | File and line |
|---|---|---|
authentication | @{etc_ro}/shadow r, @{etc_ro}/gshadow r, | authentication:23-24 |
ssl_keys | /etc/ssl/** r, | ssl_keys:19 |
dbus | dbus bus=system, | dbus:18 |
dbus-session | dbus bus=session, /usr/bin/dbus-launch ix, | dbus-session:18-19 |
dbus-accessibility | dbus bus=accessibility, | dbus-accessibility:18 |
user-tmp | owner /tmp/** rwkl, (with l) | user-tmp:21 |
bash | @{HOME}/.bash_history rw, without owner | bash:18 |
audio | /dev/snd/* rw, @{PROC}/asound/** rw, | audio:36-39 |
nameservice | network 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-download | owner @{HOME}/[^.]* rwl, | user-write:20, user-download:20 |
web-data | @{HOME}/public_html/** r, without owner | web-data:20-21 |
base | owner @{HOME}/.Private/** mrixwlk, | base:177 |
nvidia | capability ipc_lock, | nvidia:7 |
ubuntu-konsole | capability sys_ptrace, | ubuntu-konsole:10 |
dovecot-common | capability setgid, | dovecot-common:14 |
postfix-common | capability setuid, setgid, sys_chroot, | postfix-common:17-19 |
frr | six capabilities and network, | frr:18-24 |
ubuntu-helpers | profile 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.
| Abstraction | Rules | Lines |
|---|---|---|
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_size | base:95-128 |
crypto | @{PROC}/sys/crypto/fips_enabled, @{PROC}/sys/crypto/* | crypto:24,27 |
nameservice | @{PROC}/@{pid}/net/psched, ipv6_route, route | nameservice:55,102-103 |
nss-systemd | @{PROC}/sys/kernel/random/boot_id | nss-systemd:30 |
bash | @{PROC}/@{pid}/mounts, @{PROC}/filesystems | bash:37-38 |
gnome | @{PROC}/@{pid}/mounts | gnome:82 |
golang | owner @{PROC}/@{pid}/mountinfo, owner @{PROC}/@{pid}/cgroup, cgroup CPU quota files | golang:5-8 |
audio | @{PROC}/asound/** rw, | audio:39 |
nvidia | @{PROC}/interrupts, @{PROC}/modules, @{PROC}/driver/nvidia/params | nvidia:20-23 |
mesa | @{sys}/devices/@{pci_bus}/**/{revision,config} | mesa:17 |
apparmor_api/find_mountpoint | @{PROC}/@{pids}/mounts | find_mountpoint:16 |
psi-read, psi-read-poll | @{PROC}/pressure/{cpu,memory,io}, r and rw | line 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
| Place | Reaches | Read through |
|---|---|---|
/etc/apparmor.d/abstractions/NAME.d/* | every profile that includes NAME | include if exists <abstractions/NAME.d> at the end of NAME |
/etc/apparmor.d/local/PROFILE | one profile | include if exists <local/PROFILE> at the end of the profile |
- Exceptions without a
.dline:ubuntu-browsers(no include line),ubuntu-helpers(include if exists <local/ubuntu-helpers>inside its profile), and the files underapparmor_api/andubuntu-browsers.d/. - The tree ships no
NAME.ddirectory. All 198 profile files directly underprofiles/apparmor.dhave alocal/include (grep). - A deny rule in
NAME.dcannot be undone by an ordinary allow rule of an including profile.
Include mechanics and messages
| Text | Meaning |
|---|---|
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 policy | an 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,ron the script andixon the interpreter.
| Interpreter | Abstraction |
|---|---|
bash, dash, sh | abstractions/bash |
perl | abstractions/perl |
python, python2, python3, python3.N | abstractions/python |
ruby, rubyN.N | abstractions/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 underabstractions/or listed incustom_includesoflogprof.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, allno.--no-abstraction(aa-genprof,aa-logprof) removes the proposals; new profiles still getbase.
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-helpersheader: 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.openglheader: line 2 reads# Vulkan access requirements. Documentation only.ruby: covers onlyruby/1.[89]directories, so the abstraction thataa-genprofadds for a Ruby script may grant nothing useful. Not verified against an installed Ruby.audioreads PipeWire's client configuration (audio:89-91) but has no rule for a PipeWire socket. Not verified on a system.audit denyin a complain-mode profile: the kernel code reads as allowing the access; open question. Theprivate-filespair usesaudit denyfor most of its rules.- Not determined: what happens at exec time for
Cx -> sanitized_helper,when the profile has nosanitized_helperchild (such a profile compiles with-Q); whether distributions ship files inabstractions/*.d/.
for AppArmor developers
Code
| What | Where |
|---|---|
include path search, ##included marker | parser/parser_lex.l:170-181 |
Could not open, if exists | parser/parser_lex.l:192-197 |
| text inclusion (buffer push), directory includes | parser/parser_lex.l:207-216, :128 |
##skipped duplicate include | parser/parser_lex.l:223 |
| duplicate check | parser/parser_include.c:165 |
| per-profile include cache | parser/parser_yacc.y:396-397, :454-455 |
abi in a profile body; first declaration wins | parser/parser_yacc.y:722, :1892-1903 |
| default warning classes | parser/parser.h:77-78 |
match_includes, valid_include | utils/apparmor/aa.py:1419-1459, :1463-1475 |
| menu order | utils/apparmor/aa.py:1152-1156 |
is_known_rule | utils/apparmor/aa.py:2341-2351 |
loadincludes | utils/apparmor/aa.py:2519-2534 |
| interpreter mapping, new profile | utils/apparmor/aa.py:372-381, :391-404 |
LOGPROF-SUGGEST | utils/apparmor/regex.py:93, utils/apparmor/aa.py:2034-2038, utils/apparmor/profile_storage.py:83 |
--no-abstraction | utils/aa-logprof:32, utils/aa-genprof:72, utils/apparmor/aa.py:284-286 |
| variable gap in the matcher | utils/apparmor/aare.py:49, :83, utils/apparmor/common.py:238-243 |
Roads from here
PREAMBLE AND REUSE
- include — the include rule and if exists
- Abstractions and tunables — where abstractions and tunables live
- The abi rule and the abi files — the abi line every abstraction starts with
QUALIFIERS
- allow and deny — why a deny in an abstraction cannot be undone
IN PRACTICE · general-purpose apps
- Profiles for general-purpose apps — the profile style that is built from abstractions
IN PRACTICE · security-sensitive programs
- Profiles for security-sensitive programs — why precise profiles pick the strict variants
- Writing rules for /sys and /proc — the /proc and /sys rules abstractions already carry
TOOLS · utils/
- aa-logprof — the tool that proposes include lines
LIBAPPARMOR
- D-Bus mediation — what the dbus abstractions actually control