Symlinks: rules see through them

rules see the target for application developers for administrators for security researchers

AppArmor matches the path of the object the kernel ends up at after following every symlink and never the name the program passed. A rule for a symlink's own path grants nothing on its target. Covers the paths shipped profiles spell out and what creating and reading a symlink need and what a planted symlink can do to other programs.

On the map: security-sensitive programs

▶ Watch this deck — 10 scenes, ~8 min

Worth seeing first

Part of journeys

01 You allowed the file, and it is still denied

SYMLINKS profile demo /usr/bin/demo { /etc/resolv.conf r, } demo open("/etc/resolv.conf") /etc/resolv.conf denied apparmor="DENIED" operation="open" profile="demo" name="/run/systemd/resolve/stub-resolv.conf" ... requested_mask="r" denied_mask="r" a symlink, on a system where a resolver manages it /run/systemd/resolve/stub-resolv.conf the rule named the link; the check used the file behind it
The profile demo has the rule /etc/resolv.conf r. The program opens /etc/resolv.conf, which is a symlink to /run/systemd/resolve/stub-resolv.conf. The open is denied, and the denial record names the file under /run.

AppArmor matches the resolved path. Where /etc/resolv.conf is a symlink, opening it is checked as its target, and name= in the denial shows the target.

You wrote a rule that lets demo read /etc/resolv.conf. Demo opens exactly that path, and it's denied. Why? Look at the name in the denial. It isn't the path in your rule. It's a file under /run. On a system where a resolver manages that file, resolv.conf is a symlink, and AppArmor checks the place the kernel arrives at, not the name the program used. This deck is about that one fact and what follows from it: how to write rules that match, what a symlink can't do, what you need to create one, and what an attacker can do with one.

Details and sources

Details

  • The string to put in a rule is the value of name= in the denial. It is the name AppArmor rebuilt for the object that was opened, and it can differ in every component from what the program passed.
  • requested_mask="r" is what the program asked for and denied_mask="r" the part that was refused. profile= is the profile that refused it.
  • The record on the slide is built for the map: the field layout is that of an operation="open" record in the libapparmor test suite (syslog_datetime_01.in), with the profile, name and masks of this example. The values are illustrative.
  • Whether /etc/resolv.conf is a symlink depends on the system; neither source tree proves it. The tree's evidence is the comment in the shipped abstraction: "On systems where /etc/resolv.conf is managed programmatically, it is a symlink to @{run}/(whatever program is managing it)/resolv.conf." (nameservice-strict:34-35), followed by rules for the targets, next to @{etc_ro}/resolv.conf r, for the case of a regular file (nameservice-strict:21).
  • On such a system the name starts with /run/ and not /var/run/, because /var/run is resolved as well where it is a symlink.
  • The kernel behaviour is read from the kernel source; nothing on this slide was observed on a running kernel.

for AppArmor developers for security researchers

Code

  • The name is built from the mount and dentry of the opened object by d_namespace_path (path.c:88-128); the open hook passes &file->f_path (lsm.c:498-500).

02 The kernel walks first and asks AppArmor last

open("/bin/sh") ON A MERGED-/usr SYSTEM demo open("/bin/sh") /bin symlink -> usr/bin /usr/bin/sh symlink -> dash /usr/bin/dash a regular file: the walk ends no AppArmor question here AppArmor is asked once: may demo read /usr/bin/dash ? /bin/sh r, matches nothing /usr/bin/dash r, matches
demo opens /bin/sh on a system where /bin is a symlink to usr/bin and /usr/bin/sh is a symlink to dash. The kernel follows both links without asking AppArmor, then asks once whether demo may read /usr/bin/dash. The rule /bin/sh r matches nothing; /usr/bin/dash r matches.

In the kernel symlinks are followed in the VFS before AppArmor's file hook. Only the final object's path is matched; directories and links on the way are not checked by AppArmor.

Here's what happens between the open call and the check, on a system where /bin is a symlink to /usr/bin, and sh in there is a symlink to dash. The kernel walks the path one component at a time. At /bin it finds a symlink and carries on in /usr/bin. At sh it finds another, and lands on dash. AppArmor isn't asked anything along the way: in the kernel it has no hook for following a link, and none for the directories passed through. Only at the end does the kernel ask: may demo read /usr/bin/dash? So a rule for /bin/sh matches nothing.

Details and sources

Details

All of this is read from the kernel source. That /bin is a symlink to usr/bin and /usr/bin/sh a symlink to dash describes a common layout, not a fact from either tree.

  • The last component of a path is followed only when the call follows links. O_NOFOLLOW, lstat and AT_SYMLINK_NOFOLLOW stop at the link itself.
  • A link text that starts with / restarts the walk at the task's root.
  • Mounts with nosymfollow, and openat2 with RESOLVE_NO_SYMLINKS, fail with ELOOP in the VFS, before any AppArmor check.
  • AppArmor has no hook for following a link, none for readlink, and none for the permission check on each directory passed through. Search permission on directories (x in the file mode) is left to the ordinary Unix permission checks.
  • No rule is needed for a symlink's own path in order to pass through it.

Read more

for AppArmor developers for security researchers

Code

  • pick_link reads the link text and continues the walk (namei.c:2013-2091); it calls security_inode_follow_link at namei.c:2059-2062.
  • step_into_slowpath decides whether an entry is a symlink that must be followed (namei.c:2104-2116).
  • AppArmor's hook list has no inode_follow_link, inode_readlink or inode_permission entry (lsm.c:1796-1816).
  • apparmor_file_open checks &file->f_path, the object the walk ended at (lsm.c:498-500).
  • The ELOOP for nosymfollow and RESOLVE_NO_SYMLINKS: namei.c:2046-2048.

03 The name comes from the file, not from you

WHAT NAME DOES THE RULE HAVE TO MATCH? the file the name is built from here, upwards to / open("../etc/demo/./demo.conf") /etc/demo/demo.conf no dots, no symlinks: real directory entries from / down chroot /srv/chroot; open("/etc/passwd") /srv/chroot/etc/passwd seen from the system's root, not the chroot's /var/lib/ntp/@{PROC}/@{pid}/net/if_inet6 r, ntpd's shipped profile: files under its chroot opendir("/etc/demo") /etc/demo/ a directory's name ends in a slash a file descriptor from another mount namespace info="Failed name lookup - disconnected path" no path from your root: denied, unless the profile has attach_disconnected
Four cases around one file object. A path with dots is matched as /etc/demo/demo.conf. A file opened inside a chroot at /srv/chroot is matched as /srv/chroot/etc/passwd. A directory is matched as /etc/demo/ with a trailing slash. A file descriptor from another mount namespace has no path from the root and is denied as a disconnected path.

The matched name is rebuilt from the object: absolute, without ., .. or symlinks, from the mount namespace root (so a chroot's files keep their outside path), with a trailing / for directories. No path to the root means info="Failed name lookup - disconnected path".

It helps to turn the picture around. AppArmor doesn't take your path and tidy it up. In the kernel it starts from the file the kernel found and rebuilds a name from that file up to the root. So dots and symlinks simply aren't there. If the program runs in a chroot, the name still starts at the system's root, which is why the shipped profile for ntpd lists files under its chroot directory. A directory's name ends with a slash. And if the file can't be reached from your root at all, say it came from another mount namespace, there's no full name. The access is denied as a disconnected path, unless the profile carries the attach_disconnected flag.

Details and sources

Details

Read from the kernel source; not observed on a running kernel.

  • The path with dots in the first case is an illustration: the name is the chain of real directory entries above the object, so it contains no ., no .. and no symlink.
  • A file reached through a bind mount is named through that mount.
  • Chroot: the name starts at the root of the mount namespace. The shipped ntpd profile lists the files ntpd opens after it has changed root to /var/lib/ntp, for example /var/lib/ntp/@{PROC}/@{pid}/net/if_inet6 r, (usr.sbin.ntpd:57, usr.sbin.ntpd:72-73). The profile flag chroot_relative makes the name relative to the task's root instead.
  • A directory's name gets a trailing /, so a rule for the directory itself is written /etc/demo/ r,.
  • When the lookup fails the request is denied and the record carries one of four info= texts: Failed name lookup - deleted entry, Failed name lookup - disconnected path, Failed name lookup - name too long, Failed name lookup. The record shows whatever partial name was built.
  • flags=(attach_disconnected) puts the leading / back on a disconnected name. flags=(attach_disconnected.path=/att/unix-chkpwd/) puts a prefix in front, and the shipped profile then has rules with that prefix, such as /att/unix-chkpwd/run/systemd/journal/dev-log w, (unix-chkpwd:14, unix-chkpwd:41-46).
  • File systems that are internal to the kernel and cannot be mounted by users are skipped by the path checks.
  • The one place the program's own spelling can appear: an exec whose name lookup failed is audited with the string as given.

for AppArmor developers for security researchers

Code

04 Write the rule for where the file really is

HOW THE SHIPPED PROFILES DO IT a symlink on some systems, and the shipped text /bin -> usr/bin profile ping /{usr/,}bin/{,iputils-}ping { bin.ping: both spellings /var/run -> /run @{run}=/run/ /var/run/ tunables/run: a variable with two values /etc/resolv.conf -> /run/... @{etc_ro}/resolv.conf r, @{run}/systemd/resolve/stub-resolv.conf r, nameservice-strict: link and targets /etc/localtime -> /usr/share/zoneinfo/... @{etc_ro}/localtime r, /usr/share/zoneinfo{,-icu}/** r, base: link and target tree $ readlink -f /etc/resolv.conf /run/systemd/resolve/stub-resolv.conf or copy name= from the denial: it is already the resolved path
Four paths that are symlinks on some systems, each next to the shipped policy text that copes with it: ping's attachment with both bin spellings, the run variable with two values, the resolv.conf rules of nameservice-strict, and the localtime rules of the base abstraction. Below, readlink -f prints the target of /etc/resolv.conf.

Name the target, and both spellings where layouts differ: /{usr/,}bin/, @{run}=/run/ /var/run/, @{run}/systemd/resolve/stub-resolv.conf r,. Find it with readlink -f PATH or the denial's name=.

So how do you write rules that hold? Look at what ships. The profile for ping attaches to /bin and to /usr/bin, so it works whether bin is a directory or a link. The run variable has two values, /run and /var/run. The name service abstraction grants resolv.conf where it might be a real file, and also the places where resolvers keep the real one. Base does the same for local time and the zone info tree. The method is always the same: name the target, and if systems differ, name both. To find the target, run readlink -f on the path, or take the name from the denial, which is already resolved.

Details and sources

Details

  • The shipped lines on the slide, with whitespace collapsed: - profile ping /{usr/,}bin/{,iputils-}ping { (bin.ping:15). A second example of both spellings is /{usr/,}bin/ls mix, (bash:45). - @{run}=/run/ /var/run/ (run:1). - @{etc_ro}/resolv.conf r, (nameservice-strict:21) and @{run}/systemd/resolve/stub-resolv.conf r, with its neighbours (nameservice-strict:36-38). - @{etc_ro}/localtime r, (base:34-35) and /usr/share/zoneinfo{,-icu}/** r, (base:41-42).
  • Which of these paths are symlinks depends on the system. The trees show only that shipped policy is written to cope with both cases.
  • readlink -f PATH and realpath PATH resolve every component and print the final path. namei -l PATH shows each step of the walk. The output on the slide is an example for a system where systemd-resolved manages the file; it was not taken from a machine.
  • Do not add a rule for a symlink's own path in order to follow it: following is not checked. A rule on the link's path is needed only to create, remove or rename the link itself (see the scene "Creating, removing and reading the link itself").
  • alias rules rewrite rule paths when the policy is compiled. They are a separate mechanism, shown commented out in alias:13-19.

06 A symlink cannot widen a profile

THE GOOD NEWS /srv/www/** r, demo /srv/www/index.html matched as /srv/www/index.html: allowed /srv/www/x symlink -> /etc/shadow /etc/shadow open("/srv/www/x") matched as /etc/shadow: denied apparmor="DENIED" operation="open" profile="demo" name="/etc/shadow" ... requested_mask="r" denied_mask="r" the check is on the file that was opened, so swapping the link changes nothing
The profile has /srv/www/** r. Opening /srv/www/index.html is allowed. /srv/www/x is a symlink to /etc/shadow; opening it is matched as /etc/shadow and denied, and the denial record names /etc/shadow.

With /srv/www/** r,, opening a symlink /srv/www/x that points to /etc/shadow is matched as /etc/shadow and denied. Symlinks cannot extend what a profile allows. This is read from the kernel code; it was not run on a kernel.

All of this cuts in your favour too. Demo may read everything under /srv slash www. Somebody drops a symlink in there that points at the shadow file, hoping demo will serve it. Demo opens the link. The kernel follows it, arrives at /etc/shadow, and that's the name AppArmor checks. Denied. The rule for the web directory doesn't come into it. And since the check is made on the file that was actually opened, there's no gap between checking and opening for someone to swap the link in. A symlink can make your rule miss. It can't make your rule cover more.

Details and sources

Details

This scene is derived from the kernel code. It was not run on a kernel, and the record is built for the map on the layout of an operation="open" record in the libapparmor test suite (syslog_datetime_01.in); its values are illustrative.

  • The open check is made on the object that was opened, after the walk. The name is rebuilt from that object, so /srv/www/x does not appear in it.
  • Because the check and the open concern the same object, replacing the symlink between a check and the open does not change which name is matched. Compare a program that checks a path string itself and then opens it: there the link can be swapped between the two steps, which is the classic symlink attack.
  • A hard link is the opposite case. It is a real second name for the file, and the file is judged under that name: see hard links.
  • AppArmor's check comes on top of the ordinary Unix permission checks on the target, which still apply.

for AppArmor developers for security researchers

Code

10 Where to go from here

ROADS symlinks: the target's path decides name the target · w to create · a link cannot widen you prac-hardlinks a second real name prac-sys-proc trees made of symlinks attachment the profile a resolved binary gets adm-denials the name= field k-match how the name is matched also: syn-flags-other (attach_disconnected) · sec-path-limits (deciding by name) syn-file-rules · syn-access-modes · prac-privileged
Symlinks in the centre, with the recap name the target, w to create, a link cannot widen you, and roads to the decks prac-hardlinks, prac-sys-proc, attachment, adm-denials and k-match, and a row naming syn-flags-other, sec-path-limits, syn-file-rules, syn-access-modes and prac-privileged.

Next: prac-hardlinks, prac-sys-proc, attachment, syn-flags-other, adm-denials, sec-path-limits, k-match.

Three things to keep. Rules name the target. Making a link needs w on its own name. And a link can't widen your profile, though it can mislead somebody else's program. Hard links are the opposite case, a second real name, and they have their own deck. Proc and sys are whole trees of symlinks, with a deck of their own too. The attachment deck covers which profile a binary gets. And for the mechanics underneath, there's the kernel matching deck.

Details and sources

Details

  • Rules name the target: the name matched is the resolved path of the object, and name= in a denial shows it.
  • Creating, removing or renaming a symlink needs w on the link's own path. l and link rules concern hard links.
  • A symlink cannot give a profile access its rules do not grant on the target. A planted link can still mislead another program, which is judged by its own confinement.
  • What each deck answers: - Hard links: what a second real name for a file changes. - /proc and /sys: writing rules for trees that are full of symlinks. - Privileged programs: where exact paths matter most. - Attachment: which profile a binary gets. - Other profile flags: attach_disconnected. - Reading denials: the name= field and the rest of the record. - The limits of deciding by name, how the kernel matches a name. - File rules, access modes.
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). Nothing was run on a live kernel.

Read more

Basis of the statements on this page: the kernel behaviour is read from the source of mainline Linux 7.4 (7.4-rc2, 97d73c825) and the shipped policy from the AppArmor tree at 836052d21 (6.0.0~alpha2). Nothing here was observed on a running kernel. "Derived" means reasoned from that code.

Which name is matched

AppArmor does not see the string a program passes. Each file check receives the object the kernel resolved, and the name is rebuilt from it.

OperationObject whose path is used
openthe opened file, after every symlink was followed
execthe opened binary; the same name is used to search for a profile to attach
create, mkdir, mknod, symlink, unlink, rmdirthe entry itself in its parent directory
truncate, chmod, chown, getattrthe looked-up object (the link itself only with a no-follow call)
renameboth names
linkboth names: see prac-hardlinks

Properties of the name:

  • Absolute, with no ., .. or symlink: the chain of real directory entries above the object.
  • It starts at the root of the mount namespace. A task in a chroot at /srv/chroot that opens /etc/passwd is matched as /srv/chroot/etc/passwd. The profile flag chroot_relative makes it relative to the task's root.
  • A file reached through a bind mount is named through that mount.
  • A directory's name ends in /.
  • An object that cannot be reached from the root is disconnected: the request fails with EACCES unless the profile has attach_disconnected (see syn-flags-other).
  • A deleted object fails the lookup too, unless the profile's path flags say otherwise.
  • name= in a denial is this rebuilt name. It is the string to put in a rule.
OperationWhat AppArmor is askedOn which path
symlink(text, new)create; w grants itthe new name; the text is not examined
readlink(path)nothingnot mediated
lstat(path)getattrthe link's own path
unlink(path)delete; w grants itthe link's own path, with the link's own owner
rename(old, new)read, write and delete on the old name (rw grants them); write and create on the new name (w)the link's own names
lchown, fchownat and fchmodat with AT_SYMLINK_NOFOLLOWchown or chmodthe link's own path
link(old, new) where old is a symlink, without AT_SYMLINK_FOLLOWa hard link checkthe symlink itself is linked
open with O_PATH and O_NOFOLLOWnothingnot checked
open with O_NOFOLLOW, without O_PATHnothing: the VFS fails with ELOOP
  • Following a symlink is not an AppArmor event: no rule is needed, or useful, on the link's own path for that.
  • In a creation record ouid= is the caller's fsuid, so an owner rule always matches.
  • l and link rules are about hard links only.

Which paths are symlinks on an installed system is not a fact from either source tree. The left column describes common layouts; the trees show only that shipped policy is written to cope with them. The two /proc rows at the end are the exception: those links are created by the kernel.

Path, where it is a symlinkShipped rule or variableSource
/bin to usr/binprofile ping /{usr/,}bin/{,iputils-}ping {, /{usr/,}bin/ls mix,bin.ping:15, bash:45
/sbin to usr/sbinprofile unix-chkpwd /{,usr/}{,s}bin/unix_chkpwd ...unix-chkpwd:14
/lib, /lib64 to usr/lib.../{usr/,}lib{,32,64}/** r,base:74
/var/run to /run@{run}=/run/ /var/run/run:1
/etc/resolv.conf to a file under /run@{etc_ro}/resolv.conf r, and @{run}/systemd/resolve/stub-resolv.conf r, with its neighboursnameservice-strict:21, nameservice-strict:34-38
/etc/localtime to a file under /usr/share/zoneinfo@{etc_ro}/localtime r, and /usr/share/zoneinfo{,-icu}/** r,base:34-35, base:41-42
/etc/alternatives/NAME to the real binaryname the real binary; notepadqq lists etc/alternatives/notepadqq, which can match only where that entry is a real filenotepadqq:7
/etc/mtab to ../proc/self/mounts/etc/mtab r, and @{PROC}/@{pid}/mounts r,bash:36-37
/proc/self to the pid@{PROC}/@{pid}/{maps,auxv,status} r,base:116
/proc/mounts to self/mounts (kernel)@{PROC}/@{pid}/mounts r,bash:37, root.c:383
/proc/net to self/net (kernel)@{PROC}/@{pid}/net/if_inet6 r,usr.sbin.ntpd:57, proc_net.c:423

More on the /proc rows: prac-sys-proc.

Messages

  • A failed name lookup denies the request with one of four info= texts: Failed name lookup - deleted entry, Failed name lookup - disconnected path, Failed name lookup - name too long, Failed name lookup.
  • Creating a symlink without permission: operation="symlink" with requested_mask="c" and denied_mask="c". The fix is a w rule on the new name. A record from the libapparmor test suite:
apparmor="DENIED" operation="symlink" profile="/home/test.sh" name="/home/b.c" pid=8016 comm="ln" requested_mask="c" denied_mask="c" fsuid=0 ouid=0
  • ELOOP comes from the VFS and not from AppArmor: opening a symlink itself with O_NOFOLLOW (without O_PATH), any symlink on a mount with nosymfollow, and openat2 with RESOLVE_NO_SYMLINKS.
  • EACCES with an AUDIT_ANOM_LINK record (follow_link) comes from fs.protected_symlinks, below.
  • A sysctl of the VFS, 0 or 1, independent of AppArmor. Documentation: kernel docs: protected_symlinks.
  • With the value 1, following a symlink is permitted when one of these holds: the follower's fsuid owns the link; the directory holding it is not both sticky and world-writable; the directory's owner owns the link.
  • Otherwise the walk fails with EACCES and an AUDIT_ANOM_LINK record. No AppArmor record is written and no profile rule changes the result.
  • It is applied to the last component of a path only.
  • CAP_DAC_OVERRIDE does not bypass it.
  • The kernel source gives the variable no initial value, so the kernel's own default is 0. Which value an installed system sets is outside both trees. Keeping it at 1 also covers programs that are not confined.

Finding the resolved path

  • readlink -f PATH or realpath PATH: every component resolved, the final path printed.
  • namei -l PATH: each step of the walk, with owners and modes.
  • name= in the denial: already the resolved name.
  • For an executable also check which profile the process carries: aa-status, ps -Z (see attachment).

for security researchers

Attack surface

Derived from the code; nothing here was run as an exploit.

  • Link planting: a profile with w on a directory can create symlinks there to any path, including paths it is denied. That does not help the confined program, whose own opens are matched on the target. Another program that follows the link is judged by its own profile, or by none. owner /tmp/** rwkl, in abstractions/user-tmp is such a rule (user-tmp:21).
  • readlink is not mediated: link texts are readable subject to the ordinary Unix permission checks only.
  • O_PATH opens return before the LSM open hook, and fstatat on such a descriptor is not mediated either; the shipped who profile says so in a comment (who:19-24).
  • Directory traversal is not mediated: only the final object's name is matched.
  • The name depends on the mount namespace's view: chroots and bind mounts give the same file other names.
  • fs.protected_symlinks covers sticky world-writable directories and the final component only, and is 0 unless something sets it.
  • More: sec-unmediated, sec-path-limits.

for AppArmor developers for security researchers

Code

WhatWhere
aa_path_name, the info stringspath.c:202-222
d_namespace_path: d_absolute_path, chroot_relative, trailing slash, disconnected and deletedpath.c:88-128, path.c:48-72, path.c:151-177
aa_path_perm; a failed lookup audited and deniedfile.c:287-309, file.c:169-177
AppArmor's hook list (no inode_follow_link, inode_readlink, inode_permission)lsm.c:1796-1816
create and symlink hookslsm.c:271-278, lsm.c:319, lsm.c:360-365
unlink, rename, getattr, open hookslsm.c:327-330, lsm.c:403-442, lsm.c:460-463, lsm.c:498-500
exec: name and attachmentdomain.c:684-699
w to AA_MAY_CREATE; getattr on every statepolicy_compat.c:84-86, policy_compat.c:103
pick_link, security_inode_follow_link, ELOOPnamei.c:2013-2091
may_follow_link, the sysctlnamei.c:1280-1307, namei.c:1210, namei.c:1217-1225
nd_jump_linknamei.c:1174-1195
security_path_symlink callnamei.c:5835
readlinkstat.c:568-584
O_PATH in do_dentry_openopen.c:951-956
/proc/self, magic linksself.c:11-28, base.c:1800-1813
parser: path flags written to the kernelparser_interface.c:536-537

Not determined

  • Whether lstat of a path matched by no rule can be denied under policy that carries a permission table. For policy in the older format the getattr permission is added to every state.
  • Which symlinks exist on an installed system and which value distributions set for fs.protected_symlinks: neither tree contains this.
  • Whether fs.protected_symlinks was applied to non-final components in earlier kernels; only mainline Linux 7.4 was read.

Roads from here

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

PROFILE HEAD

IN PRACTICE · security-sensitive programs

SECURITY · threat model and limits

RUNNING THE PARSER

IN THE KERNEL