Loading policy into the kernel

.load .replace .remove for administrators for AppArmor developers for security researchers

A saved profile changes nothing until its compiled form is written to the kernel. The parser has three actions and each writes to its own file in securityfs. Add refuses a name that is loaded. Replace adds or swaps. Remove takes a profile out. Every profile is one write and one STATUS record. Running programs follow a replaced profile at their next checked operation and become unconfined when it is removed. At boot one parser run with replace loads the whole profile directory.

On the map: running the parser

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

01 A saved profile is not a loaded profile

LOADING POLICY profile demo { /etc/demo/demo.conf r, /etc/demo/secret.conf r, ... } one new rule, saved in the file $ aa-exec -p demo -- cat /etc/demo/secret.conf cat: /etc/demo/secret.conf: Permission denied the kernel still holds the copy it was given earlier $ apparmor_parser -r demo.aap demo.aap profile text binary policy .replace a file of the kernel profile demo loaded, replaced $ aa-exec -p demo -- cat /etc/demo/secret.conf secret the new rule is in force three actions the write checks and records running programs, boot
The profile demo gets a new line, /etc/demo/secret.conf r, and the file is saved. Running cat on /etc/demo/secret.conf under the profile still prints Permission denied, because the kernel holds the copy it was given earlier. The command apparmor_parser -r demo.aap turns the profile text into binary policy, writes it to the file .replace and the kernel replaces the loaded profile demo. The same cat now prints secret. The deck covers the three actions, the write, the checks and records, and running programs and boot.

The kernel enforces the compiled copy it was given, not the file on disk. apparmor_parser -r FILE compiles the file and writes the result to the kernel, which replaces the loaded profile.

Demo was refused a file, so you added one rule to its profile and saved. Run demo again: still refused. Why? Because the kernel doesn't look at profile files. It holds a compiled copy of the profile, loaded some time ago, and your edit hasn't reached it. One command takes it there: apparmor_parser -r. The parser compiles the text into a binary, writes that binary into a file the kernel provides, and the kernel swaps the profile. Now demo gets its file. This deck follows that last step: the three actions, the write itself, what the kernel checks and logs, what happens to programs that are already running, and how it's all done at boot.

Details and sources

Details

  • The denial, the reload and the second cat on the slide were run in a Debian sid guest (kernel 7.3.4). The parser in the guest was the one built from the AppArmor tree, run as apparmor_parser --config-file=/dev/null -K -I DIR (-K is --skip-cache); the slide writes apparmor_parser.
  • Before the reload: aa-exec -p demo -- cat /etc/demo/secret.conf printed cat: /etc/demo/secret.conf: Permission denied and the kernel logged the DENIED record that Reading a denial takes apart.
  • The file with the new rule /etc/demo/secret.conf r, was loaded with apparmor_parser -r (exit status 0); the same cat then printed secret and no record was logged. In the guest the changed file was a second file named demo-fixed.aap holding only the profile demo; the slide calls it demo.aap.
  • That a saved file changes nothing by itself is from the source, not run: nothing in the kernel reads profile text. The kernel is given compiled policy through three files and keeps what it was given.
  • -r is --replace. For each profile the parser builds the binary policy and libapparmor writes it to /sys/kernel/security/apparmor/.replace.
  • The steps before the write (reading the text, compiling the rules, building the binary) are From profile text to kernel; the bytes are The binary policy format.

for AppArmor developers for security researchers

In the code

02 Three actions, three files

THREE ACTIONS the action writes to name not loaded name loaded .load .replace .remove /sys/kernel/security/apparmor apparmor_parser -a demo.aap --add, or no action option added refused: Profile already exists apparmor_parser -r demo.aap --replace added replaced on a running system, reach for -r: it works whether or not the name is loaded apparmor_parser -R demo.aap --remove refused: Profile doesn't exist removed, with its children apparmor_parser: Too many actions given on the command line. one action per run
A table of the three actions of apparmor_parser. -a or --add, also the default with no action option, writes to .load: a name that is not loaded is added, a loaded name is refused with Profile already exists. -r or --replace writes to .replace: a name that is not loaded is added, a loaded name is replaced. -R or --remove writes to .remove: a name that is not loaded is refused with Profile doesn't exist, a loaded profile is removed with its children. The three files are in /sys/kernel/security/apparmor. Two actions in one run give Too many actions given on the command line.

-a (the default) writes to .load and is refused when the name is loaded. -r writes to .replace and adds or replaces. -R writes to .remove and removes the profile with its children.

The parser has three actions, and each one writes to its own file in securityfs. Add is the default: it's what you get with no action option. It writes to .load, and the kernel takes the profile only if that name is free. Load demo twice with add and the second run fails: profile already exists. Replace, -r, writes to .replace, and it doesn't mind. A new name is added, a loaded one is swapped. That makes it the one to reach for on a running system. Remove writes to .remove and takes the profile out, with its children. And it's one action per run: ask for two, and the parser stops.

Details and sources

Details

  • -a, --add: the default when no action option is given (the help text says Add apparmor definitions [default]). Writes each profile's binary to .load. The kernel adds the profile, or fails the write when a profile of that name is loaded; the parser then prints PROGNAME: Unable to add "NAME". Profile already exists and stops loading the rest of that file's profiles.
  • -r, --replace (--reload is an undocumented second spelling): writes each profile's binary to .replace. A name that is not loaded is added; a loaded one is replaced.
  • -R, --remove: the file is still parsed in full, but what is written to .remove is each profile's name. A name that is not loaded fails: PROGNAME: Unable to remove "NAME". Profile doesn't exist. The kernel removes a profile's children with it; the parser does not send hats and children one by one.
  • The two refusals on the slide are from the source, not run: no guest run adds a loaded name or removes a missing one. PROGNAME is the name the parser was started with.
  • With -v, success prints Addition succeeded for "NAME"., Replacement succeeded for "NAME". or Removal succeeded for "NAME".. Without it a successful run prints nothing.
  • One action per run. -a, -r, -R, -S, -o, -N and -p each count as an action; two of them give PROGNAME: Too many actions given on the command line. and exit status 1.
  • The three files are in the apparmor directory of securityfs, normally /sys/kernel/security/apparmor. libapparmor finds the directory through the mount table; -f DIR, --subdomainfs DIR names it.
  • A profile file whose name is also in /etc/apparmor.d/disable/ is skipped for add and replace with Skipping profile in DIR/disable: NAME; remove does not look there.
  • -R together with -B (binary input) is refused: Error: Invalid load option specified: 2.
  • Where the manual page and the code differ, the deck follows the code. The page says replace is "used to replace the definition already in the kernel with the definition given on standard input"; the code accepts files and directories and adds a name that is not loaded.
  • Known discrepancy: Kernel: a refused add is logged as profile_replace with info="profile can not be replaced"; the specific reasons are never printed. From the source, not run.
  • Known discrepancy: Duplicate-definition and load messages name a profile without its namespace or parent.

for AppArmor developers for security researchers

In the code

03 One write per profile

THE WRITE demo.aap demo demo-complain demo-kill binary binary binary .replace per profile: open, one write of the whole binary, close apparmor="STATUS" operation="profile_replace" ... name="demo" pid=1299 apparmor="STATUS" operation="profile_replace" ... name="demo-complain" pid=1299 apparmor="STATUS" operation="profile_replace" ... name="demo-kill" pid=1299 one process, three records $ apparmor_parser -R demo.aap .remove only each name is written: demo -Q: compile, skip the write -S: the binary to standard output -o FILE: the binary to a file with these, nothing is written to the kernel
The file demo.aap holds three profiles: demo, demo-complain and demo-kill. Each is compiled to its own binary and written to .replace with one open, one write of the whole binary and one close. The kernel log shows three STATUS records with operation profile_replace, names demo, demo-complain and demo-kill, all with pid 1299: one process, three records. apparmor_parser -R demo.aap writes only the name demo to .remove. -Q compiles and skips the write, -S sends the binary to standard output and -o FILE to a file; nothing is written to the kernel.

Each profile is one open, one write of the whole binary and one close. A cache file or a binary given with -B goes in one write with every profile in it, children and hats included. -R writes only the profile's name. -Q compiles without writing; -S and -o FILE give you the binary.

What does the write look like? Demo's file holds three profiles: demo and two small siblings. The parser compiles each one into its own binary, opens .replace, and hands over the whole binary in a single write. Then it closes the file and moves on. Three profiles, three writes, and in the log three records from one process. The kernel won't take a profile in pieces. Remove is lighter: the parser still parses your file, but all it writes is each profile's name. And if you only want to compile, -Q stops just short of the write, while two more options hand you the binary instead. Those runs write nothing to the kernel.

Details and sources

Details

  • demo.aap is the file of the guest runs: the profile demo and the two profiles demo-complain (flags=(complain)) and demo-kill (flags=(kill)).
  • The three records are from apparmor_parser -r demo.aap, run right after the same file had been added. Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. On the slide the prefix audit: type=1400 audit(SECONDS:SERIAL): is left out and info="same as current profile, skipping" profile="unconfined" is replaced by ... and comm="apparmor_parser" is left off. In full: apparmor="STATUS" operation="profile_replace" info="same as current profile, skipping" profile="unconfined" name="demo" pid=1299 comm="apparmor_parser", then the same for demo-complain and demo-kill, with audit serials 164, 165 and 166.
  • The parser in the guest was the one built from the AppArmor tree, run as apparmor_parser --config-file=/dev/null -K -I DIR (-K is --skip-cache); the slide writes apparmor_parser.
  • Per profile libapparmor opens the file (openat with O_WRONLY | O_CLOEXEC), writes the whole buffer with one write() and closes it. The directory itself is opened once per parser run.
  • The kernel accepts only a write that starts at offset 0; for any other offset the parser's text is Bad write position. Each write is unpacked by itself, so it must hold complete policy: a profile cannot be sent in pieces.
  • The bytes are the binary policy, or a zstd-compressed one when the parser's compression is on; see The binary policy format.
  • Remove writes the profile's full name with its terminating zero byte: NAME, PARENT//CHILD for a child, :NS://NAME for a profile in a namespace.
  • Compiling from text, the parser writes a profile's hats and child profiles separately, each in a write of its own and named PARENT//CHILD, after the profile itself: parser_interface.c:783-785, parser_policy.c:84-88.
  • .load and .replace also take a binary that holds several profiles, for example a profile with its children or its hats. When the compiled policy comes from the cache, or from a binary file given with -B, the whole file with every profile in it is one buffer and one write. The kernel treats that as one set that is loaded or refused together. See The policy cache.
  • -Q, --skip-kernel-load: the action stays as given and everything else runs, the cache included; only the write is left out. It does not count as an action, so -Q -r is allowed.
  • -S, --stdout and -o FILE, --ofile FILE are actions: the binary goes to standard output or to FILE, which -B accepts later. Both also skip reading the cache. -N (--names) and -p (--preprocess) do not write to the kernel either.
  • With any of these the parser does not open the directory of the three files, so the run needs no privilege to manage policy. -K is a different option: --skip-cache.
  • Known discrepancy: A child or hat that the kernel refuses is reported and then ignored: exit status 0.
  • Known discrepancy: Cache hit on an uncompressed cache loads the profile twice and writes the cache without -W.

for AppArmor developers for security researchers

In the code

04 What the kernel does with a write

IN THE KERNEL a write to .replace: demo's binary 1 may this process manage policy? Access denied. You need policy admin privileges to manage profiles. says the parser 2 unpack and verify the binary apparmor="STATUS" info="invalid profile format" error=-93 300 random bytes written to .load: refused and logged 3 is the name demo loaded? no: the profile is added yes, through .replace: it is replaced yes, through .load: refused, Profile already exists the same bytes as the loaded profile: skipped demo is on the list; one record only now does anything change a load that fails leaves the old profile in place
A write of demo's binary to .replace passes three checks in the kernel. One: may this process manage policy? If not, the parser prints Access denied. You need policy admin privileges to manage profiles. Two: unpack and verify the binary; 300 random bytes written to .load were refused and logged as apparmor STATUS info invalid profile format error -93. Three: is the name demo loaded? No: the profile is added. Yes, through .replace: it is replaced. Yes, through .load: refused, Profile already exists. The same bytes as the loaded profile are skipped. Only then is demo on the list with one record; nothing changes before that.

Three checks: may the writer manage policy, does the binary verify, and is the name loaded. Identical bytes are skipped. Nothing changes until every check has passed.

The kernel doesn't trust what arrives. First question: may this process manage policy? If not, the write fails, and the parser tells you that you need policy admin privileges. Second, the binary is unpacked and verified. We once fed .load three hundred random bytes: the write failed, and the log said invalid profile format. Third, the name. Is a profile called demo loaded already? Through .load, that's an error. Through .replace, it decides between adding and replacing. There's one shortcut: if the bytes are exactly the ones already loaded, the kernel skips the work. Only after every check has passed does anything change. So a load that fails leaves the old profile in place.

Details and sources

Details

  • The order on the slide is the order in the kernel: the permission check, the copy of the data, unpack and verify, the lookup of each name, and only then the change.
  • Check 1. A writer that may not manage policy gets "permission denied" from the write. The parser's text for that refusal is PROGNAME: Access denied. You need policy admin privileges to manage profiles. PROGNAME: Permission denied. You need policy admin privileges to manage profiles. is printed for a different error: the one the kernel returns when a profile marked immutable is replaced The kernel also logs a STATUS record whose info= is policy_locked, not privileged for target profile or not policy admin. From the source, not run. The mode of the files is not the check. Who passes it is Who can change policy.
  • The parser does not check for root itself; it leaves the decision to the kernel.
  • Check 2. The record on the slide is real: 300 bytes from /dev/urandom were written to .load with cat. cat printed write error: Protocol not supported and the kernel logged apparmor="STATUS" info="invalid profile format" error=-93 profile="unconfined" pid=1317 comm="cat". Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. The slide leaves out the prefix and the last three fields. What is verified is Unpacking and verifying policy.
  • Check 3. Each profile in the write is looked up by name. Without the replace permission of .replace, a loaded name fails the whole write. A profile that is new gets its parent looked up as well.
  • The shortcut: the kernel keeps the bytes of every load when it is built and set to export binary policy (the default); without that every replace is carried out. A replace whose bytes equal the ones the loaded profile came from is logged with info="same as current profile, skipping" and not carried out; the write still succeeds. The comparison is on bytes, not on rules: the same text compiled to different bytes is replaced for real (derived from the source).
  • "Only now": the kernel's own comment at that point is "Done with checks that may fail - do actual replacement". A write with several profiles (a cache file, -B) is loaded or refused as one set; after a failure each other profile of the write gets a record with info="valid profile in failed atomic policy load" or "unchecked profile in failed atomic policy load".
  • A namespace named by the write, and placeholder parents of a child profile, are created before the last check and stay after a failure; no loaded profile changes.
  • A profile marked immutable cannot be replaced.
  • Known discrepancy: Kernel: a refused add is logged as profile_replace with info="profile can not be replaced"; the specific reasons are never printed. From the source, not run.

for AppArmor developers for security researchers

In the code

05 One record per profile, and the list

STATUS RECORDS $ apparmor_parser -a demo.aap apparmor="STATUS" operation="profile_load" profile="unconfined" name="demo" pid=1292 comm="apparmor_parser" profile="unconfined" who did it: the parser's own label name="demo" the profile that changed $ apparmor_parser -r demo.aap apparmor="STATUS" operation="profile_replace" info="same as current profile, skipping" ... name="demo" $ apparmor_parser -R demo.aap apparmor="STATUS" operation="profile_remove" profile="unconfined" name="demo" ... the operation is what the kernel did: -r of a name that is not loaded logs profile_load /sys/kernel/security/apparmor/profiles demo (enforce) one line per loaded profile
apparmor_parser -a demo.aap logs apparmor STATUS operation profile_load profile unconfined name demo pid 1292 comm apparmor_parser. The field profile is who did it, the parser's own label; the field name is the profile that changed. apparmor_parser -r demo.aap on the same file logs operation profile_replace with info same as current profile, skipping. apparmor_parser -R demo.aap logs operation profile_remove. A replace of a name that is not loaded logs profile_load. The file /sys/kernel/security/apparmor/profiles has one line per loaded profile with its mode, such as demo (enforce).

A STATUS record names the operation, the writer's label in profile= and the changed profile in name=. /sys/kernel/security/apparmor/profiles lists what is loaded.

How do you know it worked? The parser says nothing on success, but the kernel writes one status record per profile. The first one's operation is profile_load, and two fields are easy to mix up. Profile is who did it: the parser, running unconfined. Name is the profile that changed. Replace the same file again and the operation becomes profile_replace, with a note: same as current profile, skipping. Nothing was swapped. Remove gives profile_remove. One surprise: the operation follows what the kernel did, not the option you typed, so -r on a new name logs profile_load. For the state right now, the profiles file in securityfs lists every loaded profile with its mode.

Details and sources

Details

  • The three records are from three runs on the same file, in this order: -a, -r, -R. Logged by a Debian sid guest (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches); the field names and their order were checked against the kernel source the map describes. On the slide the prefix audit: type=1400 audit(SECONDS:SERIAL): is left out, the first record is broken over two lines and ... stands for profile="unconfined" in the second and for pid=1306 comm="apparmor_parser" in the third. The parser in the guest was the one built from the AppArmor tree, run as apparmor_parser --config-file=/dev/null -K -I DIR (-K is --skip-cache); the slide writes apparmor_parser.
  • In full: apparmor="STATUS" operation="profile_load" profile="unconfined" name="demo" pid=1292 comm="apparmor_parser"; apparmor="STATUS" operation="profile_replace" info="same as current profile, skipping" profile="unconfined" name="demo" pid=1299 comm="apparmor_parser"; apparmor="STATUS" operation="profile_remove" profile="unconfined" name="demo" pid=1306 comm="apparmor_parser". Each run logged three records, one per profile of the file.
  • The form: apparmor="STATUS" operation="OP" [info="TEXT" [error=N]] [namespace="NS"] profile="WRITER" name="TARGET" pid=N comm="C" [ns="TARGETNS"].
  • profile= is the label of the process that wrote, unconfined for a root shell. name= is the profile loaded, replaced or removed. info= appears only when there is something to say, and error= only with it and only when the write failed.
  • The operation is chosen for each profile by what the kernel found: profile_load when no profile of that name was loaded, profile_replace when one was, whichever file was written. So -r of a new name logs profile_load.
  • A replace that changes a loaded profile logs the profile_replace line without info=. From the source: the guest run that changed demo's rules did not keep its record.
  • The record does not say which rules changed. With the audit daemon running the same record is in the audit log as type=AVC msg=audit(...): apparmor="STATUS" .... Where records go is Reading a denial.
  • The profiles file: one line NAME (MODE) per loaded profile; MODE is enforce, complain, kill, unconfined or user. A child is listed as PARENT//CHILD, a profile of a visible child namespace as :NS:NAME (MODE). The line demo (enforce) on the slide is from the source, not run: no guest run printed the file.
  • Reading the file needs the right to view policy (in the first user namespace: effective user or group 0), although its mode is 0444. aa-status reads this file and reports the mode user as prompt; see aa-status and aa-enabled.
  • Each loaded profile also has a directory under policy/profiles/; see apparmorfs.
  • Known discrepancy: Kernel: the profile_remove record of a namespaced name logs ns= with the rest of the written string. From the source, not run.

for AppArmor developers for security researchers

In the code

06 Replace under a running program

REPLACE demo running profile demo the old rules $ apparmor_parser -r demo.aap no restart, and no search for demo's processes stale a forwarding note profile demo the new rules /etc/demo/secret.conf demo's next open: the kernel follows the note and judges by the new rules each process switches at its next checked operation: a file open, a network call, a capability a replace with identical bytes is skipped: nothing changes for anyone
The program demo is running under the profile demo with the old rules. apparmor_parser -r demo.aap puts a new profile demo with the new rules on the list; the old version is stale and carries a forwarding note to the new one. No restart is needed and the kernel does not search for demo's processes. At demo's next open of /etc/demo/secret.conf the kernel follows the note and checks the new rules. Each process switches at its next checked operation: a file open, a network call, a capability. A replace with identical bytes is skipped and changes nothing.

A replaced profile needs no restart. The old version points at the new one, and each running process is judged by the new rules from its next checked operation.

Here's the case you'll meet most. Demo is running, a long-lived service, and you replace its profile. Do you have to restart it? No. And the kernel doesn't go looking for demo's processes either. It puts the new profile on the list under the same name, marks the old one stale, and leaves a forwarding note on it that points at the new one. Demo still holds the old profile. But the next time one of its operations is checked, a file open, a network call, a capability, the kernel follows the note and judges by the new rules. So the change lands at each process's next checked operation. In practice, that's at once.

Details and sources

Details

  • From the source, not run for this deck. The same behaviour was observed on a running kernel for Labels in the kernel, scene "A profile is replaced under a running task": a shell that tried two files every three seconds followed three replacements of its profile without being restarted.
  • What the guest runs of this deck show is the replace itself: after apparmor_parser -r with the new rule, a newly started cat under the profile could open the file.
  • "Forwarding note" is a comparison. The kernel keeps, for every profile, a small object that says which version is current. A replacement points it at the new version and marks the old one stale.
  • No process is visited at the time of the write. Every checked operation starts by looking at the process's own label; when that label is stale, the current version is used for the check. The process's credentials are brought up to date when it next returns to user space.
  • So the new rules apply from each process's next checked operation: a file open, a socket call, a capability check, a signal, an exec.
  • A replace that is skipped as identical changes nothing for running processes.
  • An exec transition that was already taken is not redone: a process that moved into another profile stays in that profile's current version, and changed exec rules count for later execs. See Exec and domain transitions.
  • Children and hats that the new file no longer defines stay loaded; the kernel hands them to the new version of the parent (derived from the source, not run).
  • Files that are already open: the permission remembered on an open file belongs to the label that opened it, and a use under the newer label is checked again against the current rules. This reading of the source is partial (sockets and inherited files take other paths) and nothing was run for it.
  • Known discrepancy, described in Labels in the kernel: Kernel: a stacked label follows only the first replacement of a member profile, because __label_replace is called inside AA_BUG. It concerns tasks under a stack of profiles, not the plain case on this slide.

for AppArmor developers for security researchers

In the code

Read more

07 Remove leaves running programs unconfined

REMOVE demo running profile demo $ apparmor_parser -R demo.aap forwarding note unconfined demo keeps running, no longer confined by this profile $ apparmor_parser -a demo.aap profile demo loaded again the running demo stays unconfined entered at exec, or on request to change a profile: apparmor_parser -r to confine it again: load the profile, then restart it resource limits the profile had set are not restored
The program demo is running under the profile demo. apparmor_parser -R demo.aap removes the profile; its forwarding note now points at unconfined, and demo keeps running, no longer confined by it. apparmor_parser -a demo.aap loads the profile again, but the running demo stays unconfined: a profile is entered at exec or on request. To change a profile use apparmor_parser -r. After a remove, restart what ran under the profile. Resource limits the profile had set are not restored.

-R does not stop a program: it leaves it unconfined. Loading the profile again does not confine it again; a profile is entered at exec or on request. To change a profile use -r.

Remove looks like the opposite of add, and for the list it is. For a running program it's something else. Take demo's profile out while demo runs. Demo isn't stopped. The forwarding note on its old profile now points at unconfined, so from its next checked operation demo runs with no confinement from that profile. And here's the trap: load the profile again, and the running demo doesn't come back under it. A profile is entered when a program is executed, or when it asks to change profile. A load doesn't do that. So to change a profile, replace it. Keep remove for profiles you really want gone. And if you load one again, restart whatever was running under it.

Details and sources

Details

  • From the source, not run for this deck. Observed for Labels in the kernel, scene "A profile is replaced under a running task": after apparmor_parser -R the running shell's label read unconfined and both test files were readable.
  • Remove takes the profile and its children off the list and points their "which version is current" object at the unconfined label of the namespace the profile was in. The kernel's own description: "mark them as replaced by unconfined".
  • The process follows that pointer at its next checked operation, exactly as for a replacement. It is not signalled and not stopped.
  • Loading the profile again creates a new profile with that name. A process is put under a profile at exec, when the profile attaches to the program or an exec rule names it, or when the process asks with a change of profile (aa-exec -p does that for the command it starts). A load does neither (derived from the source). See Exec and domain transitions.
  • The unit file of the AppArmor tree gives the same reason for its empty stop action: "removing AppArmor confinement from running processes (and not being able to re-apply it later)".
  • The kernel's note on resource limits: "removing confinement does not restore rlimits to preconfinement values". A limit the profile had set with an rlimit rule stays on the process.
  • For a process under a stack of profiles only the removed member becomes unconfined when the stacked label is rebuilt (derived; see the known discrepancy named under the previous scene).
  • The record is operation="profile_remove" with name= the profile; it is written after the removal.
  • A name that is not loaded: the write fails and the record has info="profile does not exist". An empty name: info="no profile specified". A name :NS: alone removes that namespace. From the source, not run.

for AppArmor developers for security researchers

In the code

08 Loading at boot

AT BOOT apparmor.service before sysinit.target apparmor.systemd reload the script it starts apparmor_parser --replace -- /etc/apparmor.d one run over the whole directory; the same command is a reload the parser walks the directory and compiles files in parallel ExecStop=/bin/true stop does nothing, on purpose a restart is stop, then start: every profile would be unloaded aa-teardown .remove each profile's name; children go with it this is what the AppArmor source ships; a distribution may wrap it differently
At boot the unit apparmor.service, ordered before sysinit.target, starts the script apparmor.systemd reload, which runs apparmor_parser --replace -- /etc/apparmor.d: one run over the whole directory, files compiled in parallel, and the same command is a reload. The unit has ExecStop=/bin/true: stop does nothing on purpose, because a restart is stop then start and the profiles would be unloaded. aa-teardown writes every loaded profile's name to .remove. This is what the AppArmor source ships; a distribution may wrap it differently.

The shipped unit runs apparmor_parser --replace -- /etc/apparmor.d at boot and on reload. Its stop is /bin/true; aa-teardown unloads every profile.

Who runs the parser when the machine boots? In the AppArmor source it's a systemd unit, ordered early, before most services start. It runs a small script, and the script comes down to one parser run over all of /etc/apparmor.d, with replace. Replace, not add, so the same command works as a reload on a running system. The parser walks the directory itself and compiles files in parallel. Now look at stop: it does nothing, on purpose. Systemd restarts a unit by stopping and starting it, and unloading every profile would leave running programs unconfined. If that's what you want, aa-teardown does it, writing each loaded name to .remove. Your distribution may wrap all this differently.

Details and sources

Details

  • This is what the AppArmor tree ships in its init/ directory, read and not run. Which unit, script and parser.conf a distribution installs is not in the tree.
  • apparmor.service: Type=oneshot, ExecStart=/lib/apparmor/apparmor.systemd reload and the same line for ExecReload. Ordered Before=sysinit.target and After=local-fs.target; ConditionSecurity=apparmor; AssertPathIsReadWrite=/sys/kernel/security/apparmor/.load; RequiresMountsFor=/var/cache/apparmor.
  • apparmor.systemd reload reads the function library rc.apparmor.functions and ends in /sbin/apparmor_parser [--quiet] --replace -- /etc/apparmor.d. --quiet is added on a quiet boot. One more directory can be named in the script; it is empty in the tree.
  • The parser is given the directory and walks it itself, loading each file, with several jobs in parallel.
  • If the parser exits with a non-zero status the script prints Error: At least one profile failed to load and fails.
  • No cache option is on that command line. What the run takes from the cache is decided by /etc/apparmor/parser.conf and the parser's defaults; see The policy cache.
  • start (the path without systemd) runs the parser with --add, and only when the profiles file is empty; otherwise it reports that profiles are already loaded.
  • ExecStop=/bin/true. The comment in the unit: systemd maps restart to stop and start, "which means removing AppArmor confinement from running processes (and not being able to re-apply it later)".
  • aa-teardown runs apparmor.systemd stop: the script reads the profiles file, strips the mode, sorts, leaves out child names (a parent takes its children with it) and writes each name to .remove with printf, without the parser.
  • In a container the script does nothing unless the container has its own policy namespace.
  • One profile on demand: profile-load NAME runs /sbin/apparmor_parser -r -W /etc/apparmor.d/NAME. aa-load loads cache files, always through .replace.
  • Known discrepancy: aa-teardown cannot unload a profile whose mode the kernel prints as user. From the source, not run.

for AppArmor developers for security researchers

In the code

09 From the write to what it changes

ROADS .load .replace .remove pipeline re-blob adm-cache adm-parser before the write k-unpack k-apparmorfs sec-policy-admin in the kernel k-labels k-exec running programs namespaces ut-status adm-denials lib-cache-kernel the namespace option, looking at the result, the library calls
The three files .load, .replace and .remove in the centre. Roads before the write: pipeline, re-blob, adm-cache and adm-parser. Roads in the kernel: k-unpack, k-apparmorfs and sec-policy-admin. Roads for running programs: k-labels and k-exec. And namespaces, ut-status, adm-denials and lib-cache-kernel.

-a, -r, -R; one write and one record per profile. Roads: the pipeline and the binary format, the cache, the kernel side, labels and exec, namespaces, aa-status and denials.

That's the last stretch of a profile's journey: one action, one write per profile, a few checks, one record, and running programs that follow along. Where next? Back up the road, the pipeline deck shows the whole parser run, and the binary format deck opens up what was written. The cache deck explains how a load can skip compiling. On the kernel side there's unpacking and verifying, the filesystem these three files live in, and who may change policy. Labels in the kernel shows the forwarding note for real, and the exec deck shows how a program enters a profile. Namespaces covers -n. And for looking at the result: aa-status, and reading a denial.

Details and sources

Details

  • -n NAME, --namespace NAME puts every profile of the run into the policy namespace NAME. The namespace travels inside the binary; the file written is still .load or .replace, and for remove the namespace is part of the name, :NS://NAME. Policy namespaces has the rest.

Read more

Basis of the statements on this page: "guest" means the command was run in a disposable Debian sid virtual machine (kernel 7.3.4, a distribution kernel without Ubuntu's AppArmor patches) with the parser built from the AppArmor commit 836052d21, run as apparmor_parser --config-file=/dev/null -K -I DIR; the records are quoted without the prefix audit: type=1400 audit(SECONDS:SERIAL):. "source" means read in the AppArmor tree or in the kernel source the map describes, and not run. "derived" means reasoned from the source. Nothing on this page was run on the kernel the map describes; the field names and their order in the guest's records were checked against it.

The three actions

OptionFile writtenWhat is writtenName not loadedName loadedWith -v
-a, --add, or no action option.loadthe binary policy of one profileaddedrefused: Unable to add "NAME". Profile already existsAddition succeeded for "NAME".
-r, --replace (--reload).replacethe binary policy of one profileaddedreplaced, or skipped when the bytes are the loaded onesReplacement succeeded for "NAME".
-R, --remove.removethe profile's full name and a zero byterefused: Unable to remove "NAME". Profile doesn't existremoved with its childrenRemoval succeeded for "NAME".

The two refusals are from the source. Guest: -a, -r and -R of demo.aap in this order each exited with status 0 and printed nothing.

  • One action per run: -a, -r, -R, -S, -o, -N and -p count; two give PROGNAME: Too many actions given on the command line. and exit status 1 (source).
  • After a refused add the parser stops loading the remaining profiles of that file (source).
  • For remove the file is parsed in full and no binary is built. The name is NAME, PARENT//CHILD or :NS://NAME. -R also skips the cache. -R with -B is refused: Error: Invalid load option specified: 2 (source).
  • A file whose name is in /etc/apparmor.d/disable/ is skipped for add and replace: Skipping profile in DIR/disable: NAME (source).

Compiling without loading

OptionCounts as an actionWhat happens
-Q, --skip-kernel-loadnothe given action runs, the cache included; the write to the kernel is left out
-S, --stdoutyesthe binary goes to standard output; the cache is not read
-o FILE, --ofile FILEyesthe binary goes to FILE; the cache is not read
-N, --namesyesprints the profile names
-p, --preprocessyesprints the text after includes

With each of these the parser does not open the directory of the three files (source). A file written with -S or -o is what -B, --binary loads later. -K is --skip-cache and has nothing to do with the kernel write. Every option is in Running apparmor_parser.

Loading into a namespace

-n NAME, --namespace NAME sets the policy namespace of every profile of the run; a file that names another namespace gets the warning -n NAME overriding policy specified namespace :OTHER:. The namespace is inside the binary, the file written is still the root .load or .replace, and the kernel finds or creates the namespace. One write must not mix namespaces: info="policy load has mixed namespaces". For remove the namespace is in the name, :NS://NAME, and :NS: alone removes the namespace. All from the source. See Policy namespaces.

Known discrepancy: -n does not skip the policy cache, so a cached profile can be loaded into the wrong namespace.

The three files

/sys/kernel/security/apparmor/.load, .replace and .remove. libapparmor finds the directory through the mount table and falls back to that path; -f DIR, --subdomainfs DIR names it. The directory is opened once per run. Each namespace directory under policy/namespaces/ has its own three files.

  • One call is one openat, one write of the whole buffer and one close.
  • A write must start at offset 0; otherwise the kernel refuses it and the parser prints Bad write position.
  • The parser calls once per profile, and once more for each hat. From the cache or with -B the whole file is one write, and the kernel loads or refuses it as one set.
  • The buffer is the binary policy, plain or zstd-compressed, with or without the header the cache puts in front; the kernel recognises each. See The binary policy format.
  • The mode of the files is not the access control; the handler checks the writer. See Who can change policy.

What the kernel does with a write, in order

1. The writer must be allowed to manage policy; otherwise the write fails and a STATUS record says why. 2. The data is copied in, unpacked and verified; a refused buffer changes nothing. Guest: 300 random bytes to .load gave write error: Protocol not supported and apparmor="STATUS" info="invalid profile format" error=-93 profile="unconfined" pid=1317 comm="cat". 3. All profiles of the write must be for one namespace, which is found or created. 4. Each name is looked up. A loaded name fails the write unless it came through .replace. A new profile needs its parent; a missing parent is filled in with an empty placeholder profile. 5. From here nothing can fail. Per profile: identical bytes are skipped, otherwise the record is written and the profile is added or replaced. 6. Stacked labels that contain a replaced profile are rebuilt.

A profile marked immutable cannot be replaced. Children of the old profile that the new one does not define are kept (derived).

The STATUS record

apparmor="STATUS" operation="OP" [info="TEXT" [error=N]] [namespace="NS"]
    profile="WRITER" name="TARGET" pid=N comm="C" [ns="TARGETNS"]
FieldMeaning
operationprofile_load, profile_replace or profile_remove: what the kernel did to this profile. -r of a name that is not loaded logs profile_load
infopresent only when there is something to say
errorpresent only with info and only when the write failed
namespace, profilethe label of the process that wrote; unconfined for a root shell
namethe profile loaded, replaced or removed
pid, commthe process that wrote
nsthe target namespace, when the load named one

Guest, one record per profile of the file (demo, demo-complain, demo-kill):

CommandRecord for demo
-a demo.aapapparmor="STATUS" operation="profile_load" profile="unconfined" name="demo" pid=1292 comm="apparmor_parser"
-r demo.aap, unchangedapparmor="STATUS" operation="profile_replace" info="same as current profile, skipping" profile="unconfined" name="demo" pid=1299 comm="apparmor_parser"
-R demo.aapapparmor="STATUS" operation="profile_remove" profile="unconfined" name="demo" pid=1306 comm="apparmor_parser"

With the audit daemon the guest's audit log had type=AVC msg=audit(1794831843.372:434): apparmor="STATUS" operation="profile_replace" info="same as current profile, skipping" profile="unconfined" name="demo" pid=2056 comm="apparmor_parser". A replace with changed rules logs the profile_replace line without info= (source; the guest run that changed the rules did not keep its record).

Texts of info= on this path, all from the source and not run:

info=When
same as current profile, skippingthe bytes are the ones the loaded profile came from (guest)
invalid profile format and the unpacker's other textsthe buffer does not verify (guest for this one); see Unpacking and verifying policy
policy_locked, not privileged for target profile, not policy adminthe writer may not manage policy
policy load has mixed namespaces, failed to prepare namespacethe namespace of the write
profile can not be replaceda loaded name through .load, or an immutable profile
parent does not exista child whose parent cannot be found or made
failed to create raw_data dir and files, failed to createthe entries under policy/
valid profile in failed atomic policy load, unchecked profile in failed atomic policy loadthe other profiles of a write that failed
no profile specified, namespace does not exist, profile does not existremove

Messages of the parser

MessageWhen
Unable to add "NAME". Profile already exists-a of a loaded name
Unable to remove "NAME". Profile doesn't exist-R of a name that is not loaded
Access denied. You need policy admin privileges to manage profiles.the kernel refused the writer
Permission denied. You need policy admin privileges to manage profiles.replacing a profile marked immutable
Bad write positiona write that does not start at offset 0
Profile doesn't conform to protocol, Profile version not supported by Apparmor module, Profile does not match signaturethe kernel refused the buffer
Too many actions given on the command line.two actions
Cached reload succeeded for "FILE".-v, the binary came from the cache

All from the source. The exit status is not in the manual page (known discrepancy: apparmor_parser(8) does not document the exit status).

Running programs

ReplaceRemove
The running processkeeps runningkeeps running
Its confinementthe new version, from its next checked operationunconfined of the profile's namespace, from its next checked operation
A restartnot neededneeded to confine it again, after the profile is loaded
Children and hatsthose the new file lacks stay loaded (derived)removed with the parent
Resource limits set by the profilestay as they were

From the source. Observed on a running kernel for Labels in the kernel: a shell followed three replacements and a removal of its profile without a restart. Not determined: whether every file that is already open is checked again under the new rules; what a kernel with Ubuntu's patches does differently.

The list of loaded profiles

/sys/kernel/security/apparmor/profiles: one line NAME (MODE) per profile of the reader's namespace and the namespaces below it; MODE is enforce, complain, kill, unconfined or user; children as PARENT//CHILD; profiles of a child namespace as :NS:NAME (MODE). The namespace's own unconfined is not listed. The file shows names and modes, not rules. Opening it needs the right to view policy. Source; no guest run printed the file. aa-status reads it; see aa-status and aa-enabled.

At boot, as shipped in the AppArmor tree

FileWhat it does
init/apparmor.serviceExecStart and ExecReload: /lib/apparmor/apparmor.systemd reload; ExecStop=/bin/true; before sysinit.target
init/apparmor.systemdreload: /sbin/apparmor_parser [--quiet] --replace -- /etc/apparmor.d; start: the same with --add, only when nothing is loaded; stop: unload everything
init/rc.apparmor.functionsthe functions behind them
init/aa-teardownapparmor.systemd stop: each name of the profiles file, without children, is written to .remove
init/profile-load NAME/sbin/apparmor_parser -r -W /etc/apparmor.d/NAME
aa-loadloads cache files through .replace

Source. What a distribution installs is not in the tree.

Known discrepancies

  • Kernel: a refused add is logged as profile_replace with info="profile can not be replaced"; the specific reasons are never printed.
  • Kernel: the profile_remove record of a namespaced name logs ns= with the rest of the written string.
  • aa-teardown cannot unload a profile whose mode the kernel prints as user.
  • next_profile_buffer reads past the end of the policy buffer on kernels without set_load.
  • A child or hat that the kernel refuses is reported and then ignored: exit status 0.
  • Cache hit on an uncompressed cache loads the profile twice and writes the cache without -W.
  • -n does not skip the policy cache, so a cached profile can be loaded into the wrong namespace.
  • Duplicate-definition and load messages name a profile without its namespace or parent.

The first three are from reading the source for this deck and were not run.

for AppArmor developers for security researchers

In the code

StepWhere
the action and its countparser_main.c:543-545 parser_main.c:583-590 parser_main.c:957-961
one profile at a timeparser_policy.c:70-82 parser_interface.c:715-765
the three library callskernel_interface.c:314-319 kernel_interface.c:357-363 kernel_interface.c:400-406
open, write, closekernel_interface.c:142-164
the kernel's file handlersapparmorfs.c:687-757
policy_update()apparmorfs.c:607-684
aa_may_manage_policy()policy.c:1001-1029
aa_replace_profiles()policy.c:1184-1472
aa_remove_profiles(), __remove_profile()policy.c:1488-1556 policy.c:200-243
audit_policy()policy.c:840-876
aa_label_replace(), aa_label_remove()label.c:849-875 label.c:785-798
a stale label is followedcred.h:149-161 label.h:408-429
the credentials are updatedtask.c:48-117
the profiles fileapparmorfs.c:2475-2564
the files are createdapparmorfs.c:2936-2952 apparmorfs.c:2253-2269

Read more: apparmor_parser(8), --add, --replace, --remove, aa_kernel_interface(3), aa-teardown(8), wiki: AppArmorInterfaces.

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

SECURITY · threat model and limits

RUNNING THE PARSER

TOOLS · utils/

LIBAPPARMOR

IN THE KERNEL

THE DFA ENGINE · libapparmor_re