Why AppArmor

profiles, labels, modes for everyone

What AppArmor is for. A profile is a named list of what one program may do. The kernel attaches it when the program starts and checks file access, exec, capabilities, mounts, sockets and signals against it. Also what the modes do and what a denial looks like.

On the map: start here

▶ Watch this deck — 8 scenes, ~6 min

Part of journeys

01 One program, one list of what it may do

WHY APPARMOR demo /usr/bin/demo, a small network service /etc/demo/demo.conf /var/lib/demo/state what demo needs /home/user/.ssh/id_rsa a bug: demo reads your SSH key file permissions allow it: same user profile demo not on the list the kernel checks every access against the list
The program demo reaches its configuration and state files and, through a bug, an SSH key; a profile drawn around demo cuts the access to the key

AppArmor confines a program to what its profile allows. The check is made by the kernel, in addition to ordinary file permissions.

Meet demo, a small network service. To do its job it needs two things on disk: its configuration, and a directory where it keeps its state. Now suppose demo has a bug, and one day something talks it into opening your SSH key. Ordinary file permissions look at the user, and demo runs as you, so the open just works. AppArmor adds a second question, and this one is about the program: is this on demo's list? That list is called a profile. The kernel checks it on every access, and the key stays out of reach.

Details and sources

Details

  • AppArmor is a Linux Security Module named apparmor (lsm.c:2648). In the kernel it registers one table of 81 hooks, apparmor_hooks[] (lsm.c:1785, registered at lsm.c:2621).
  • The question "is this on demo's list" for a file is the call aa_path_perm(op, current_cred(), label, path, 0, mask, cond), made only when the label of the calling process is not unconfined (lsm.c:229-232).
  • A file request that no rule allows gets the error -EACCES, "Permission denied" (file.c:246-247).
  • Whether AppArmor is on: /sys/module/apparmor/parameters/enabled reads Y (lsm.c:2018); the boot parameter is apparmor= (lsm.c:2029). The command aa-enabled prints Yes and exits 0 (aa_enabled.c:92-99).
  • The program demo, its files and the SSH key scenario are invented for the map. Nothing on this slide was observed on a running kernel.

Read more

02 A profile is a text file of rules

THE PROFILE /etc/apparmor.d/demo abi <abi/5.0>, include <tunables/global> profile demo /usr/bin/demo { } demo: the name /usr/bin/demo: the program it attaches to include <abstractions/base> a shared set of basics network inet stream, /etc/demo/** r, owner /var/lib/demo/** rwk, /usr/bin/demo-helper Px -> demo-helper, TCP sockets read its configuration its own state files run a helper under the helper's profile /home/user/.ssh/id_rsa no rule: refused written by hand, shipped in a package, or built from logs by aa-genprof and aa-logprof
The nine-line profile of demo as a text file, with a note beside each rule saying what it allows, and an SSH key that no rule covers

A profile is a named set of rules kept as text under /etc/apparmor.d. What no rule allows is refused. The language has many more rule kinds; the syntax map lists them.

This is demo's profile. It's an ordinary text file, kept by default under /etc/apparmor.d. The head gives the profile a name and the path of the program it attaches to. Inside the braces, one line pulls in a shared set of basics. After that every line is one rule, ending with a comma: demo may use TCP sockets, read its configuration, read, write and lock state files it owns, and run a helper under the helper's own profile. There's no line for your SSH key, and what isn't listed is refused. You can write this file by hand, get it with a package, or let the tools draft it from what the program was seen doing.

Details and sources

Details

  • The nine-line profile is in the reference under this deck. The parser built from the AppArmor tree at 836052d21 compiled it with -Q -K --skip-kernel-load --warn=all: exit status 0, no warning. It was not loaded into a kernel.
  • Default base directory: /etc/apparmor.d (parser_include.c:63-67); apparmor_parser -b DIR (--base) changes it (parser_main.c:153).
  • include <abstractions/base> reads abstractions/base from the base directory: base.
  • "What isn't listed is refused": in the kernel a file request with a permission outside the allowed set gets -EACCES (file.c:246-247). In enforce mode the record type is DENIED (audit.c:211-214).
  • "Let the tools draft it": aa-genprof PROGRAM and aa-logprof read the log and propose rules (aa.py:1501-1507).
  • Rule kinds on the slide: network inet stream, (network), path rules with r and rwk (access modes), owner (owner), Px -> demo-helper (named transitions).

Read more

03 Loaded once, attached when the program starts

HOW DEMO GETS ITS PROFILE /etc/apparmor.d/demo $ apparmor_parser -r /etc/apparmor.d/demo kernel compiled, loaded at boot: apparmor.service does this for every profile profile demo already running: still unconfined demo (pid 4100) started after the load demo (pid 4242) exec of /usr/bin/demo matches $ cat /proc/4242/attr/current demo (enforce)
apparmor_parser loads the profile demo into the kernel; a demo process that was already running stays unconfined, and one started afterwards gets the profile attached at exec

apparmor_parser loads a profile; the kernel attaches it at exec, by the program's path. A process started before the load stays unconfined until it is restarted. Its label reads demo (enforce).

A profile sitting in a file confines nothing. First apparmor_parser compiles it and hands it to the kernel; at boot, a service does that for every profile. Now the kernel holds a profile named demo. A demo that was already running isn't touched: it stays unconfined. But the next time the program is executed, the kernel sees that its path matches, and attaches the profile. From then on the process carries a label, and you can read it: the name, then the mode. So after you load a new profile, restart the program.

Details and sources

Details

  • Load or replace one file: apparmor_parser -r FILE (--replace, parser_main.c:156). It writes the compiled policy to /sys/kernel/security/apparmor/.replace (apparmorfs.c:2942).
  • At boot: apparmor.service runs /lib/apparmor/apparmor.systemd reload (apparmor.service:22), which runs the parser over each profile directory (rc.apparmor.functions:137).
  • Attachment happens at exec, in the LSM hook bprm_creds_for_exec (lsm.c:1862). For an unconfined task the kernel searches the loaded profiles for one whose attachment matches the path of the program (domain.c:697-699). Nothing does this for a task that is already running.
  • Read a label: cat /proc/PID/attr/current, or /proc/PID/attr/apparmor/current, the name libapparmor tries first (kernel.c:424-426). The kernel answers in apparmor_getprocattr (lsm.c:828-835).
  • Format: the word unconfined, or LABEL (MODE) such as demo (enforce). libapparmor splits it at the last ( (kernel.c:578-615).
  • From C: int aa_getcon(char **label, char **mode); and int aa_gettaskcon(pid_t target, char **label, char **mode); (apparmor.h:110-111).
  • All loaded profiles with their modes: /sys/kernel/security/apparmor/profiles (apparmorfs.c:2709), which aa-status reads (aa_status.c:175-179).
  • The process ids and the /proc output on the slide are invented; they follow the format above and are not a captured session.

04 What the kernel checks

WHAT IS CHECKED open("/etc/demo/demo.conf") demo check: open, read label of the process profile demo /etc/demo/** r, allowed files path rules, link starting programs ix Px Cx ... capabilities capability resource limits set rlimit mounts mount umount pivot_root sockets network, unix signals, tracing signal, ptrace namespaces, io_uring userns, io_uring a process with no profile unconfined: these checks are skipped
An open by demo stops at a kernel check point that asks the profile demo; below, eight groups of checked operations with the rule kind for each

The kernel checks files, exec, capabilities, resource limits, mounts, network and unix sockets, signals, ptrace, user namespace creation and io_uring. Each has a rule kind in the profile language.

Let's follow one call. Demo opens its configuration file. On the way, the kernel stops at a check point, looks up the label of the calling process, and asks the profile. The path rule says read, so the open goes ahead. The same thing happens at other check points: creating, renaming and linking files, starting another program, using a capability, raising a resource limit. And further: mounting, every socket operation, unix sockets included, sending a signal, tracing another process, creating a user namespace, and some io_uring operations. Each has its own kind of rule. A process with no profile is unconfined, and passes straight through.

Details and sources

Details

All of this is read from the kernel source, not observed on a running kernel. The full table, with the operation names that appear in the log, is in the reference under this deck.

  • A check point is an LSM hook. AppArmor's are listed in apparmor_hooks[] (lsm.c:1785).
  • Files by path: path_link, path_unlink, path_symlink, path_mkdir, path_rmdir, path_mknod, path_rename, path_chmod, path_chown, path_truncate, inode_getattr (lsm.c:1796-1806). Open files: file_open, file_permission, mmap_file, file_lock and others (lsm.c:1808-1816).
  • Exec: bprm_creds_for_exec (lsm.c:1862). Capabilities: capable (lsm.c:1789). Resource limits: task_setrlimit (lsm.c:1871).
  • Mounts: sb_mount, move_mount, sb_umount, sb_pivotroot (lsm.c:1791-1794). Sockets: socket_create to socket_shutdown (lsm.c:1830-1843); unix sockets also unix_stream_connect and unix_may_send (lsm.c:1827-1828).
  • Signals: task_kill; user namespaces: userns_create (lsm.c:1872-1873). Ptrace: ptrace_access_check, ptrace_traceme (lsm.c:1786-1787). io_uring: uring_override_creds, uring_sqpoll (lsm.c:1888-1889).
  • Unconfined passes straight through: the wrappers test if (!unconfined(label)) before asking the profile (lsm.c:229-232).
  • Fine-grained unix socket mediation is announced to user space as /sys/kernel/security/apparmor/features/network_v9/af_unix (net.c:31-35).

for AppArmor developers for security researchers

In the code

  • The mediation class numbers (AA_CLASS_FILE 2, AA_CLASS_CAP 3, AA_CLASS_MOUNT 7, AA_CLASS_NETV9 15, AA_CLASS_NS 21, AA_CLASS_IO_URING 22 and the rest) are at apparmor.h:19-41.
  • apparmor_capable has the same shape as the file wrapper (lsm.c:199); signals are checked in apparmor_task_kill (lsm.c:1023) and user namespace creation in apparmor_userns_create (lsm.c:1051).

05 Not every rule is enforced by every kernel

WHERE A RULE IS ENFORCED a profile /etc/demo/** r, network inet stream, dbus send bus=session, the parser accepts the whole language the kernel enforces most rules where it has a check for that kind of rule this map: the kernel Ubuntu kernels carry AppArmor patches of their own $ ls /sys/kernel/security/apparmor/features capability caps dbus domain file io_uring mount namespaces network_v8 network_v9 policy ptrace query rlimit signal what the running kernel supports the bus daemon enforces dbus rules not the kernel Upstream and Ubuntu kernels which kernel enforces what D-Bus mediation how the bus daemon decides
A profile whose rules go to the kernel, labelled the kernel, except a dbus rule that goes to the bus daemon; below, the kernel features directory and the two decks that explain each case

A rule is enforced only where a check for it exists. This map describes mainline Linux; features/ shows what your kernel supports. Which kernel enforces what is in the deck Upstream and Ubuntu kernels; dbus rules, enforced by the bus daemon, are in D-Bus mediation.

One caution before you rely on a rule. The parser accepts the whole language, but a rule only protects you where something enforces it, and that isn't the same everywhere. For most rules that something is the kernel, and kernels differ. This map describes mainline Linux; a distribution kernel, Ubuntu's for one, carries AppArmor patches of its own. The features directory shows what the kernel you're running supports, so look there rather than assume. D-Bus rules are different again: the bus daemon enforces them, not the kernel. Each of the two has its own deck: upstream and Ubuntu, and D-Bus mediation.

Details and sources

Details

  • What the running kernel supports: ls /sys/kernel/security/apparmor/features. In the kernel the entries are policy, domain, file, network_v8, network_v9, mount, namespaces, capability, rlimit, caps, ptrace, signal, dbus, query, io_uring (apparmorfs.c:2684-2700). The listing on the slide is that table sorted as ls prints it; it is not a captured session.
  • aa-features-abi -x prints the feature set of the running kernel in the form used by the abi rule (aa-features-abi.pod:64).
  • The parser reads the same directory, /sys/kernel/security/apparmor/features (features.c:53). A rule class the kernel lacks is left out and the profile still loads; apparmor_parser --warn=rule-not-enforced reports it (parser_main.c:281).
  • features/dbus/mask contains acquire send receive (apparmorfs.c:2662-2663), but the kernel has no D-Bus check point: the bus daemon asks the kernel through /sys/kernel/security/apparmor/.access (apparmorfs.c:2704).
  • Facts checked in the kernel source: fine-grained unix socket mediation is present (net.c:33); there is no check point for mqueue rules; the prompt qualifier is unpacked and not acted on.
  • The features directory is one row of the top-level table of the AppArmor filesystem (apparmorfs.c:2714).

Read more

06 The same access in four modes

PROFILE MODES demo /home/user/.ssh/id_rsa open(..., O_RDONLY) no rule allows it the default enforce open fails Permission denied in the log apparmor="DENIED" complain open succeeds in the log apparmor="ALLOWED" kill the process gets a signal SIGKILL by default in the log apparmor="KILLED" unconfined open succeeds no check, no log profile demo /usr/bin/demo flags=(complain) { a deny rule still refuses in complain mode
demo opens an SSH key that no rule allows; four columns show the result in enforce, complain, kill and unconfined mode, and the flag that selects a mode

enforce refuses and logs DENIED. complain allows and logs ALLOWED. kill logs KILLED and signals the process. unconfined is not checked. The mode is a flag: flags=(complain).

Back to the bug: demo opens your key, and no rule allows it. What happens next depends on the profile's mode. Enforce is the default. The open fails with permission denied, and the kernel logs a denial. Complain lets the open through and logs what would have been refused, which is how you learn what a program needs. Kill logs, and sends the process a signal. And an unconfined profile isn't checked at all. You choose the mode with a flag in the head of the profile. One thing people miss: complain doesn't mean allow everything. An explicit deny rule still refuses.

Details and sources

Details

Kernel behaviour is read from the kernel source, not observed on a running kernel.

  • Syntax: profile demo /usr/bin/demo flags=(complain) {. The mode names the parser accepts are enforce, complain, kill, unconfined, prompt and default_allow (profile.cc:30-39); no flag means enforce.
  • Enforce: the file request fails with -EACCES (file.c:246-247) and the record type is DENIED.
  • Complain: the record type is ALLOWED (audit.c:211-212) and the errors -EPERM and -EACCES become success (audit.h:206-211). Other errors are returned unchanged.
  • Kill: the record type is KILLED and the process is sent the profile's signal (audit.c:221-231). The signal is SIGKILL (policy.c:412) unless the flag kill.signal=NAME names another.
  • Unconfined: the wrappers skip the check (lsm.c:229-232).
  • The record type names AUDIT, ALLOWED, DENIED, HINT, STATUS, ERROR, KILLED are the table at audit.c:29-38.
  • "Complain doesn't mean allow everything": for files the complain set is ~(perms->allow | perms->deny), so a permission named by a deny rule stays refused (file.c:117-118).
  • Parser messages, verbatim: Profile flag 'complain' conflicts with 'kill' (profile.h:307), Invalid profile flag: NAME. (profile.h:261).
  • Without editing the profile: a symlink to it in /etc/apparmor.d/force-complain/ forces complain mode; the parser prints Warning: found NAME in /etc/apparmor.d/force-complain, forcing complain mode (parser_main.c:1330-1332). aa-complain and aa-enforce edit the flags and reload.

for AppArmor developers for security researchers

In the code

  • For the other rule classes the modes are applied by aa_apply_modes_to_perms (lib.c:364-372): kill sets perms->kill, complain sets perms->complain, the user mode (flag prompt) sets perms->prompt.
  • The parser packs the mode with profile_mode_packed (profile.h:75-87): no mode packs as enforce, default_allow as unconfined.

07 What a denial looks like

THE DENIAL audit: type=1400 audit(1772549301.213:78826): apparmor="DENIED" operation="open" class="file" profile="demo" name="/home/user/.ssh/id_rsa" pid=4242 comm="demo" requested_mask="r" denied_mask="r" fsuid=1000 ouid=1000 apparmor="DENIED" refused (enforce mode) profile="demo" the profile that said no operation="open" what demo tried name="/home/user/.ssh/id_rsa" on what requested_mask="r" what it asked for denied_mask="r" the part that was refused /home/user/.ssh/id_rsa r, the rule that would allow it, if you wanted that aa-logprof reads these lines and proposes the rules
A denial log line for demo opening an SSH key, six of its fields explained, and the rule that the name and the denied mask would make

A denial names the profile, the operation, the object and the refused permission. name plus denied_mask is the rule that would allow it. In complain mode the same line says ALLOWED.

Here's what the kernel's log line looks like when demo reaches for the key. It's long, but four parts matter. First, denied, and the profile that refused. Then the operation, and the name it was applied to. Then the permission that was asked for, and the part of it that was refused. Put the name and the denied permission together, and you have the rule that would allow it. Here you don't want that rule: the denial is the profile doing its job. When you do want it, aa-logprof reads these lines and proposes the rules for you.

Details and sources

Details

  • The line on the slide is composed for the example, not captured. It follows two real lines of the libapparmor test corpus, both quoted in the reference under this deck: file_without_filename.in:1 and avc_audit_01.in:1.
  • Where it arrives: the kernel log (dmesg, journalctl -k), or /var/log/audit/audit.log when auditd runs. The record is type=1400 (AVC).
  • Fields written first, in this order, by the kernel: apparmor=, operation=, class=, info=, error=, namespace=, profile= (or label= for a stack), name= (audit.c:93-141).
  • File fields: requested_mask=, denied_mask=, fsuid=, ouid=, target= (file.c:45-76). pid= and comm= are added by the kernel's common LSM audit code (audit.c:164).
  • From record to rule: name is the path and denied_mask the permission letters. For the corpus line above the rule is /home/user/.ssh/ r, (avc_audit_01.profile:2).
  • aa-logprof parses each line with libapparmor's parse_record (logparser.py:288) and asks what to do with it.
  • A name taken from a user-controlled source can appear hex-encoded; aa-decode decodes it.

08 Where to go from here

ROADS Why AppArmor The pipeline from text to kernel tables Syntax map everything a profile can say Attachment which profile a program gets Mode flags enforce, complain, kill Reading denials every field of the line aa-status what is loaded and confined Upstream and Ubuntu which kernel enforces what D-Bus mediation the bus daemon decides
Eight roads from Why AppArmor: the pipeline, the syntax map, attachment, mode flags, reading denials, aa-status, upstream and Ubuntu kernels and D-Bus mediation

Next: the pipeline for how policy is compiled and loaded, the syntax map for the language, attachment for how profiles are picked.

That's the whole idea: a profile, loaded, attached at exec, checked by the kernel, with a mode and a log. If you wonder how text becomes something the kernel can check, take the pipeline. To see everything a profile can say, open the syntax map. Attachment has a long deck of its own, and so do the mode flags. For running systems, there are the decks on reading denials and on aa-status. And the caution about where a rule is enforced has two decks: upstream and Ubuntu, and D-Bus mediation.

Details and sources

Details

  • The chain in one line: text under /etc/apparmor.d, apparmor_parser -r FILE, attachment at exec, a check at each LSM hook, a mode, a record in the log.
  • Three commands to see each step on a running system: aa-status (loaded profiles and confined processes), cat /proc/PID/attr/current (the label of one process), journalctl -k | grep apparmor= (the records).
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). No kernel with AppArmor was used; kernel behaviour is stated from the source.

Read more

The example

The program demo and its files are invented for this map. Its profile is the nine lines below.

abi <abi/5.0>,
include <tunables/global>
profile demo /usr/bin/demo {
  include <abstractions/base>
  network inet stream,
  /etc/demo/** r,
  owner /var/lib/demo/** rwk,
  /usr/bin/demo-helper Px -> demo-helper,
}

The profile was compiled, without loading it, by the tree's parser (6.0.0~alpha2) through tools/head-parser, with -Q -K --skip-kernel-load --warn=all, --base set to the tree's profiles/apparmor.d and the tree's abi/5.0 features. The parser exited 0 and printed no warning.

No kernel with AppArmor was available when this deck was written. The log line in the denial scene and the output of /proc/4242/attr/current are built from the kernel's format strings and from lines of the libapparmor test corpus. They are not a captured session, and the process ids are invented.

What mainline Linux 7.4 checks

Operation groupRule kind in a profileOperation names in the log
Files, by pathpath rules, linklink, unlink, symlink, mkdir, rmdir, mknod, rename_src, rename_dest, chmod, chown, truncate, getattr
Open filespath rules (r w a k m)open, file_receive, file_perm, file_mmap, file_mprotect, file_lock
Starting programs and changing profileexec modes (ix, Px, Cx, Ux), change_profile, hatsexec, change_hat, change_profile, change_onexec, stack, stack_onexec
Capabilitiescapabilitycapable
Resource limitsset rlimitsetrlimit
Mountsmount, remount, umount, pivot_rootmount, umount, pivotroot
Network socketsnetworkcreate, post_create, bind, connect, listen, accept, sendmsg, recvmsg, getsockname, getpeername, getsockopt, setsockopt, socket_shutdown
Unix socketsunixthe socket operations above
Signalssignalsignal
Tracingptraceptrace
User namespacesusernsuserns_create
io_uringio_uringuring_override, uring_sqpoll
  • One system call can pass several check points. An open is checked when the file is opened and a later read is checked again as file_perm.
  • A process with no profile is unconfined and these checks are skipped.
  • A rule kind reaches the kernel only when both the kernel and the ABI the profile declares support it. See syn-abi and adm-features.

Where a rule is enforced

A rule in a profile is enforced only where a check for it exists. This deck describes mainline Linux 7.4, read at commit 97d73c825 (7.4-rc2). The answer changes between releases and between mainline and distribution kernels.

  • Which kernel enforces which rule kind, in mainline Linux release by release and in Ubuntu kernels with their extra AppArmor patches, is the subject of upstream-and-ubuntu. mqueue and prompt are covered there.
  • dbus rules are enforced by the bus daemon, not by the kernel. See dbus-mediation.
  • List /sys/kernel/security/apparmor/features on the running system instead of assuming. See adm-features.
  • Identities in the profile head are not sent to mainline Linux 7.4. See syn-identities.

Profile modes

Flag in the profileKernel modeWhen no rule allows the accessLog type
none, or enforceenforceThe operation fails. For a file the error is EACCES, "Permission denied"DENIED
complaincomplainThe operation goes aheadALLOWED
killkillThe operation fails and the process is sent a signal, SIGKILL unless kill.signal= names anotherKILLED
unconfinedunconfinedNot checkednone
promptuserNot acted on in mainline Linux 7.4, see upstream-and-ubuntu
default_allowunconfinedThe parser packs it as unconfinednone
  • The mode is written in the head of the profile: flags=(complain), or the short form (complain).
  • In complain mode a deny rule still refuses, silently. By the code of mainline Linux 7.4 an audit deny file rule is the exception: it is logged as ALLOWED and let through (file.c:142-149, audit.c:211-234; read, not run). A stacked profile or a peer's profile that is in enforce mode can still refuse too.
  • Complain mode turns only the errors EPERM and EACCES into success. Other errors are returned unchanged.
  • kill.signal=NAME chooses the signal of kill mode. An unknown name is the error unknown signal specified for kill.signal='NAME'.
  • Two different modes in one flags list are an error: Profile flag 'complain' conflicts with 'kill'.
  • An unknown flag is the error Invalid profile flag: NAME.
  • A symlink to the profile in the force-complain directory under the base directory forces complain mode. The parser prints Warning: found NAME in /etc/apparmor.d/force-complain, forcing complain mode.

See syn-flags-modes.

The denial line

Two real lines from the libapparmor test corpus. The first is libraries/libapparmor/testsuite/test_multi/avc_audit_01.in:

type=AVC msg=audit(1279948288.415:39): apparmor="DENIED" operation="open" parent=12332 profile="/usr/sbin/cupsd" name="/home/user/.ssh/" pid=12333 comm="ls" requested_mask="r" denied_mask="r" fsuid=0 ouid=1000

The rule that allows it, from avc_audit_01.profile beside it:

/usr/sbin/cupsd {
  /home/user/.ssh/ r,

}

The second is newer and carries class=. It is libraries/libapparmor/testsuite/test_multi/file_without_filename.in:

Mar 03 07:48:21 examplehost.internal kernel: audit: type=1400 audit(1772549301.213:78826): apparmor="DENIED" operation="open" class="file" profile="firefox" pid=16417 comm="vaapitest" requested_mask="wr" denied_mask="wr" fsuid=1000 ouid=0
FieldMeaning
apparmorThe record type: AUDIT, ALLOWED, DENIED, HINT, STATUS, ERROR or KILLED
operationWhat was attempted, see the table of operation names above
classThe rule class that was consulted, such as file
info, errorAn explanation and an error number, when the kernel has one
namespaceThe policy namespace, when the profile is not in the root namespace
profileThe profile that made the decision. For a stack of profiles the field is label
nameThe object: for a file, its path
requested_maskEverything that was asked for
denied_maskOnly the part that was refused
fsuid, ouidThe user id of the process and the owner of the file
targetA second name or a target label, when the operation has one
pid, commThe process id and command name
  • apparmor="ALLOWED" is the same event in complain mode. apparmor="AUDIT" is an allowed access that an audit rule asked to log.
  • A deny rule without audit writes no record.
  • Strings that come from user-controlled sources, such as name, can appear hex-encoded instead of quoted.

See adm-denials.

Who loads policy

  • Profiles are text files. The default base directory is /etc/apparmor.d.
  • apparmor_parser -r FILE compiles a profile and loads it, replacing a loaded profile of the same name.
  • At boot apparmor.service runs /lib/apparmor/apparmor.systemd reload, which loads every profile.
  • aa-load loads already compiled policy from the cache without running the compiler.
  • Loading needs the permission to administer policy. It fails with EACCES when that permission is missing or when policy is locked.
  • On a kernel without AppArmor the parser prints Cache read/write disabled: interface file missing. (Kernel needs AppArmor 2.4 compatibility patch.)
  • The kernel attaches a profile by path only at exec. A process that was running unconfined before the load stays unconfined until it is restarted. Replacing a profile that is already loaded does update the processes that carry it.
  • A process's label is read from /proc/PID/attr/current. It is the word unconfined, or the label followed by the mode: demo (enforce).

See pipeline, adm-loading and ut-status.

for AppArmor developers

The hook table

AppArmor registers one table, apparmor_hooks[] (linux:security/apparmor/lsm.c:1785), with security_add_hooks in apparmor_init (lsm.c:2621). It has 81 LSM_HOOK_INIT entries; 55 of them decide an access. The number after each hook is its line in lsm.c.

GroupHooksClass and code
Files by pathpath_link 1796, path_unlink 1797, path_symlink 1798, path_mkdir 1799, path_rmdir 1800, path_mknod 1801, path_rename 1802, path_chmod 1803, path_chown 1804, path_truncate 1805, inode_getattr 1806AA_CLASS_FILE; operation names at include/audit.h:50-61
Open filesfile_open 1808, file_receive 1809, file_permission 1810, mmap_file 1813, file_mprotect 1814, file_lock 1815, file_truncate 1816AA_CLASS_FILE; include/audit.h:62-68
Exec and domain changebprm_creds_for_exec 1862, bprm_committing_creds 1863, bprm_committed_creds 1864, setprocattr 1821, setselfattr 1819apparmor_bprm_creds_for_exec at domain.c:985
Capabilitiescapable 1789, capget 1788AA_CLASS_CAP; aa_capable
Resource limitstask_setrlimit 1871AA_CLASS_RLIMITS
Mountsb_mount 1792, move_mount 1791, sb_umount 1793, sb_pivotroot 1794AA_CLASS_MOUNT; apparmor_sb_mount dispatches on the flags at lsm.c:707-742
Network socketssocket_create 1830, socket_post_create 1831, socket_socketpair 1832, socket_bind 1833, socket_connect 1834, socket_listen 1835, socket_accept 1836, socket_sendmsg 1837, socket_recvmsg 1838, socket_getsockname 1839, socket_getpeername 1840, socket_getsockopt 1841, socket_setsockopt 1842, socket_shutdown 1843, sctp_bind_connect 1844AA_CLASS_NET, AA_CLASS_NETV9; include/audit.h:75-87
Unix socketsunix_stream_connect 1827, unix_may_send 1828, and the socket hooks for AF_UNIXaf_unix.c; feature network_v9/af_unix at net.c:33
Packets (secmark)socket_sock_rcv_skb 1846, inet_conn_request 1854, under CONFIG_NETWORK_SECMARK; netfilter hook apparmor_ip_postroute at lsm.c:1726AA_CLASS_NETV9_SKB
Signalstask_kill 1872AA_CLASS_SIGNAL; aa_may_signal at lsm.c:1023-1049
Ptraceptrace_access_check 1786, ptrace_traceme 1787AA_CLASS_PTRACE
User namespacesuserns_create 1873AA_CLASS_NS; lsm.c:1051-1071
io_uringuring_override_creds 1888, uring_sqpoll 1889, under CONFIG_IO_URINGAA_CLASS_IO_URING
Reading labelsgetprocattr 1820, getselfattr 1818, socket_getpeersec_stream 1848, socket_getpeersec_dgram 1850, secid_to_secctx 1882, lsmprop_to_secctx 1883, secctx_to_secid 1884, release_secctx 1885, current_getlsmprop_subj 1868, task_getlsmprop_obj 1870no decision
Label bookkeepingcred_alloc_blank 1857, cred_free 1858, cred_prepare 1859, cred_transfer 1860, task_alloc 1867, task_free 1866, file_alloc_security 1811, file_free_security 1812, sk_alloc_security 1823, sk_free_security 1824, sk_clone_security 1825, sock_graft 1852no decision
Audit filter rulesaudit_rule_init 1876, audit_rule_known 1877, audit_rule_match 1878, audit_rule_free 1879, under CONFIG_AUDITno decision; audit.c:254-301
  • The wrappers share one shape, here from lsm.c:230-232: if (!unconfined(label)) error = aa_path_perm(op, current_cred(), label, path, 0, mask, cond);. apparmor_capable (lsm.c:199-211) does the same with aa_capable.
  • The class numbers are at linux:security/apparmor/include/apparmor.h:19-41.
  • In mainline Linux 7.4 the prompt field is at include/perms.h:78, unpacked at policy_unpack.c:916 and set at lib.c:371-372; no other kernel code reads it. Identities are serialized under features_supports_identity_names at parser/parser_interface.c:562. The code behind mqueue and dbus is in upstream-and-ubuntu and dbus-mediation.

for AppArmor developers

Modes and audit in the code

  • aa_apply_modes_to_perms (linux:security/apparmor/lib.c:364-381): kill mode sets perms->kill = ~perms->allow; complain mode sets perms->complain |= ~(perms->allow | perms->deny); user mode sets perms->prompt the same way. File rules do not go through it: aa_audit_file (linux:security/apparmor/file.c:95-153) computes the complain mask itself (117-118) and returns the error early only for a quieted request (142-149).
  • aa_audit (linux:security/apparmor/audit.c:200-237) picks the record type: ALLOWED in complain mode, otherwise DENIED, changed to KILLED in kill mode. It calls send_sig_info(profile->signal, ...) for a kill record and returns complain_error(ad->error) for an allowed one.
  • complain_error (linux:security/apparmor/include/audit.h:206-211) maps -EPERM and -EACCES to 0.
  • profile->signal = SIGKILL is the default, set at linux:security/apparmor/policy.c:412.
  • The record type names are the table at linux:security/apparmor/audit.c:29-38.
  • The kernel unpacks the mode at linux:security/apparmor/policy_unpack.c:1222-1237. The parser packs it with profile_mode_packed (parser/profile.h:75-87): no mode packs as enforce and default_allow as unconfined.
  • The parser's mode names are profile_mode_table (parser/profile.cc:30-39). The flag errors are at parser/profile.h:247, 261 and 307; the force-complain warning at parser/parser_main.c:1330-1331.
  • audit_pre (linux:security/apparmor/audit.c:93-141) writes apparmor, operation, class, info, error, namespace, profile or label and name, in that order. file_audit_cb (linux:security/apparmor/file.c:45-76) writes requested_mask, denied_mask, fsuid, ouid and target. pid and comm come from common_lsm_audit, called at audit.c:164.
  • The file error -EACCES is set at linux:security/apparmor/file.c:247.
  • Exec: apparmor_bprm_creds_for_exec (linux:security/apparmor/domain.c:985), profile_transition (domain.c:665), find_attach (domain.c:394), x_to_label (domain.c:574). An unconfined task reaches find_attach at domain.c:697-698.
  • Replacing a loaded profile updates the tasks that carry it: __replace_profile and aa_label_replace (linux:security/apparmor/policy.c:1066, 1099).
  • Loading is gated by aa_may_manage_policy (linux:security/apparmor/policy.c:1001, called at apparmorfs.c:625); policy_locked is reported at policy.c:1014-1015.
  • User space splits label (mode) in splitcon (libraries/libapparmor/src/kernel.c:578-615).

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

PROFILE HEAD

RUNNING THE PARSER

TOOLS · utils/

LIBAPPARMOR

  • D-Bus mediation — dbus rules are enforced by the bus daemon and not by the kernel