Writing rules for /sys and /proc

trees of symlinks for application developers for administrators for security researchers

Programs open /proc/self and /sys/class paths but AppArmor matches /proc/PID and /sys/devices paths because both trees are full of symlinks. Covers the PROC and pid and sys variables and what owner means on /proc files and the ptrace check behind them. Also how wide shipped profiles glob device paths and how to find the resolved name.

On the map: security-sensitive programs

▶ Watch this deck — 10 scenes, ~8 min

Worth seeing first

Part of journeys

01 Two rules that look right and never match

/proc AND /sys profile demo /usr/bin/demo { /proc/self/status r, /sys/class/net/eth0/address r, } $ sudo apparmor_parser -r /etc/apparmor.d/demo no output: accepted demo (pid 1234) open("/proc/self/status") open("/sys/class/net/eth0/address") both denied apparmor="DENIED" operation="open" profile="demo" name="/proc/1234/status" ... ... operation="open" profile="demo" name="/sys/devices/pci0000:00/0000:00:1f.6/net/eth0/address" ... self became a number; class became a device path
The profile demo has the rules /proc/self/status r and /sys/class/net/eth0/address r. The parser accepts it without output. demo, pid 1234, opens both paths and both are denied. The denial records name /proc/1234/status and a path under /sys/devices instead.

/proc/self/status r, and /sys/class/net/eth0/address r, are accepted by the parser and never match: AppArmor checks /proc/<pid>/status and a path under /sys/devices/. The kernel side is read from the kernel code.

Demo reads its own status from proc, and its network card's address from sys. So you write those two paths into the profile. The parser takes them without a word. Demo runs, and both reads are denied. Look at the names in the denials: /proc/1234/status, and a long path under /sys/devices. Neither is what you wrote. Proc and sys are built out of symlinks, and AppArmor matches where the kernel ends up. This deck shows how to write rules for these two trees: the variables that help, what owner means there, how wide to glob, and how to find the real name.

Details and sources

Details

The kernel behaviour here is read from the kernel code; nothing was observed on a running kernel. Both records are built for the map on the field layout of an operation="open" record in the libapparmor test suite (syslog_datetime_01.in); their values are illustrative.

  • /proc/self is a symlink whose text is the caller's process (thread-group) id in decimal. The kernel follows it before AppArmor is asked, so the name that is matched is /proc/1234/status.
  • /sys/class/net/eth0 is a symlink into /sys/devices/. The attribute file address lives in the device directory, and that is the name that is matched.
  • The device path on the slide, pci0000:00/0000:00:1f.6, is an illustration of the shape the shipped rule @{sys}/devices/@{pci_bus}/*/net/*/address r, matches (opencl-pocl:22). It differs from machine to machine.
  • The parser accepts such rules without a diagnostic. This was checked with the tree's own parser (6.0.0~alpha2) on a scratch profile containing /proc/self/maps r,: exit status 0 and no warning. That run used -Q -K --skip-kernel-load, which compiles without loading; the apparmor_parser -r line on the slide stands for "compiles without a diagnostic".
  • name= in a denial is the resolved name, and it is the string to start a rule from. requested_mask is what the program asked for, denied_mask the part that was refused.
  • demo's read of /proc/self/status would in fact be granted by abstractions/base, which has @{PROC}/@{pid}/{maps,auxv,status} r, (base:116). The demo profile on the slide includes nothing.

for AppArmor developers for security researchers

Code

02 /proc/self is a number by the time AppArmor looks

WHAT /proc/self BECOMES demo (pid 1234) /proc/self a symlink with the text "1234" /proc/1234/status AppArmor is asked about /proc/1234/status @{PROC}/@{pid}/status r, @{PROC} is /proc/ · @{pid} is a number, 1 to 4999999 matches open("/proc/mounts") /proc/mounts -> self/mounts /proc/self -> 1234 /proc/1234/mounts @{PROC}/@{pid}/mounts r, abstractions/bash /proc/net -> self/net · /proc/thread-self -> 1234/task/1240
demo, pid 1234, opens /proc/self/status. /proc/self is a symlink with the text 1234, so AppArmor is asked about /proc/1234/status, and the rule @{PROC}/@{pid}/status r matches. /proc/mounts is a link to self/mounts and ends at /proc/1234/mounts, which abstractions/bash grants as @{PROC}/@{pid}/mounts r.

/proc/self/X is matched as /proc/<pid>/X; /proc/mounts and /proc/net/X as /proc/<pid>/mounts and /proc/<pid>/net/X. Write @{PROC}/@{pid}/X. Both variables come from include <tunables/global>.

/proc/self is a symlink, and its text is your process ID. The kernel follows it before AppArmor is asked. So demo, process one two three four, opening /proc/self/status, is checked against /proc/1234/status. The shipped tunables give you two variables for this: one for the mount point and one for the number. Written with the @{PROC} and @{pid} variables, the rule matches. And /proc/mounts, which looks like an ordinary file, is itself a link to self/mounts. It resolves twice, and ends at the mounts file of process one two three four. That's why the bash abstraction grants it in the pid form. /proc/net works the same way, and thread-self adds a task directory.

Details and sources

Details

Read from the kernel code; not observed on a running kernel. The pid 1234 and the thread id 1240 are illustrations.

  • /proc/self is a symlink whose text is the caller's thread-group id; /proc/thread-self has the text <tgid>/task/<tid>. The number is the one in the pid namespace of that procfs mount.
  • /proc/mounts is a symlink to self/mounts and /proc/net a symlink to self/net. That is why abstractions grant @{PROC}/@{pid}/mounts r, (bash:37) and @{PROC}/@{pid}/net/route r, (nameservice:103) and not /proc/mounts or /proc/net/route.
  • @{PROC}=/proc/ (proc:12) and @{pid} (kernelvars:16). A profile that uses them must include tunables/global (or tunables/proc and tunables/kernelvars) in its preamble.
  • @{PROC} ends in a slash and rules write @{PROC}/name; the parser collapses the doubled slash. The tree's parser prints aare: /proc/meminfo for @{PROC}/meminfo.
  • A site with procfs mounted elsewhere extends the variable in tunables/proc.d (proc:15).
  • demo's own status read is already granted by abstractions/base: @{PROC}/@{pid}/{maps,auxv,status} r, (base:116).
  • The entries exe, cwd, root and fd/N under a process directory are not text links: the kernel jumps to the target, and the open is matched under the target's own name. See symlinks, the scene "/proc/self and the links that jump".
  • Shipped examples for thread paths: @{PROC}/@{tid}/attr/{apparmor/,}{current,exec} w, (change_profile:13) and owner @{PROC}/@{pid}/task/@{tid}/comm rw, (dig:46).

for AppArmor developers for security researchers

Code

03 @{pid} means any process, not yours

@{pid} MEANS ANY PROCESS @{PROC}/@{pid}/maps r, @{pid} = {[1-9],[1-9][0-9],[1-9][0-9][0-9], ... ... [1-4][0-9][0-9][0-9][0-9][0-9][0-9]} seven alternatives; @{pids} and @{tid} are the same pattern /proc/1234/maps demo itself /proc/1/maps init /proc/987/maps sshd the file rule matches all three procfs asks: may this task inspect that process? (a ptrace read check) own process: not asked needs a ptrace (read) rule needs a ptrace (read) rule apparmor="DENIED" operation="ptrace" profile="demo" pid=1234 comm="demo" requested_mask="read" denied_mask="read" peer="unconfined" convention: @{pid} where a program looks at itself, @{pids} where it looks at others
The rule @{PROC}/@{pid}/maps r. @{pid} expands to seven alternatives covering any number from 1 to 4999999, so the file rule matches /proc/1234/maps of demo itself, /proc/1/maps of init and /proc/987/maps of sshd. Behind it procfs asks whether the task may inspect that process: its own process is not asked about, the others need a ptrace read rule, and the denial is a ptrace record.

@{pid}, @{pids} and @{tid} all expand to a number from 1 to 4999999; none means "this process". For maps, environ, fdinfo, mem and the magic links, procfs also makes a ptrace access check, which needs a ptrace (read) rule for other processes (read from the kernel code).

@{pid} looks like it means my pid. It doesn't. It's a pattern the parser expands when it compiles the profile: any number from one to about five million. The kernel doesn't substitute your own process ID. So this rule names the maps file of every process on the system. What keeps demo out of other processes' memory maps is a second check. For files like maps, proc itself asks whether you may inspect that process, and that reaches AppArmor as a ptrace read request. Looking at your own process skips it. Anything else needs a ptrace rule. So a denial here can show up as operation ptrace, not as a file. @{pids} and @{tid} are the same pattern, used by convention for other processes and threads.

Details and sources

Details

Read from the kernel code and from the shipped tunables; not run on a kernel. The pids and the programs behind them are illustrations.

  • @{pid}={[1-9],[1-9][0-9],...,[1-4][0-9][0-9][0-9][0-9][0-9][0-9]} (kernelvars:16); @{tid}=@{pid} and @{pids}=@{pid} (kernelvars:19, kernelvars:22). The pattern matches 1 to 4999999. The kernel's limit on pids is 4·1024·1024 on 64-bit, so it covers every valid pid.
  • The file's own comment calls these placeholders "until kernel vars are implemented" (kernelvars:9-14). The parser expands the variable when it compiles the profile; nothing substitutes the task's own pid at run time.
  • The record on the slide is built for the map on the layout of the ptrace records in the libapparmor test suite (operation="ptrace" profile= pid= comm= requested_mask= denied_mask= peer=); its values are illustrative. requested_mask="read" follows from AppArmor treating a read-mode ptrace check as read.
  • Files with the ptrace check in procfs: maps, smaps and the other memory-map files, mem (which asks for attach, not read), fdinfo, the ns/* links, environ, and the magic links exe, cwd, root, fd/N. status has none: it is readable subject to the file permissions unless procfs is mounted with hidepid.
  • A task looking at its own thread group passes the check before any security module is asked.
  • What abstractions/base grants: ptrace (readby),, ptrace (tracedby), and ptrace (read) peer=@{profile_name}, (base:134-142). A profile with base can read these files of processes under the same profile.
  • lsof pairs its /proc/@{pids}/... rules with ptrace read, and capability sys_ptrace, (lsof:25-28).
  • Wider stand-ins: [0-9]* in owner @{PROC}/@{pid}/task/[0-9]*/comm rw, is one digit followed by anything but a slash (sbin.dhclient:53); a plain * also matches names that are not numbers: @{PROC}/*/mounts r, (usr.lib.dovecot.lmtp:35), /proc/*/cmdline r, (iotop-c:24-25).

for AppArmor developers for security researchers

Code

04 owner on /proc files: same user, with one trap

OWNER ON /proc owner @{PROC}/@{pid}/fd/ r, demo (fsuid 1000) /proc/1234/fd/ demo itself: owned by uid 1000 owner matches /proc/1300/fd/ another of ann's processes: uid 1000 owner matches /proc/987/fd/ sshd: uid 0 the rule does not apply helper: was setuid root, now uid 1000 /proc/2000/fd/ its own, but owned by root: not dumpable denied its own files by an owner rule in the shipped profiles the fd/ rule appears 7 times without owner and 7 times with
With owner @{PROC}/@{pid}/fd/ r, demo running as user 1000 can list /proc/1234/fd/ of itself and /proc/1300/fd/ of another process of the same user, but the rule does not apply to /proc/987/fd/ of sshd, owned by root. A helper that started setuid root and dropped to uid 1000 is not dumpable: its own /proc files are owned by root and the owner rule does not apply.

owner @{PROC}/@{pid}/... applies when the reader's fsuid equals the target process's effective uid. Files of a non-dumpable process are owned by root, so owner fails for a program that dropped privileges (read from the kernel code).

So how do you narrow any pid without writing ptrace rules? With owner. The files in a process's proc directory are owned by that process's effective user, and owner compares that with the reader. So with owner in front, demo running as ann can list its own file descriptors, and those of ann's other processes. The rule doesn't apply to sshd's. There's one trap. When a process isn't dumpable, typically a set-user-ID program that dropped its privileges, the kernel makes its proc files owned by root. That program is then denied its own files by an owner rule. If your privileged helper breaks exactly there, that's why.

Details and sources

Details

Read from the kernel code; not run on a kernel. The pids 1300, 987 and 2000, ann and the helper are illustrations.

  • owner compares the reader's fsuid with the owner of the file. For the files in /proc/<pid>/ procfs sets that owner to the target process's effective uid and gid.
  • For a process that is not dumpable, entries other than the world-readable directories are owned by root of the process's user namespace. A program that was started setuid and then dropped its privileges is in that state, and so an owner rule denies it access to its own /proc files.
  • Files of kernel threads are owned by root.
  • Shipped examples: owner @{PROC}/@{pid}/mountinfo r, (golang:5, lsblk:56); owner @{PROC}/@{pid}/fd/ r, (gio-open:56); owner @{PROC}/@{pid}/{cgroup,cpuset,status} r, (opencl-pocl:41).
  • The count on the slide is over profiles/apparmor.d: the fd/ directory rule appears 7 times without owner (six with @{pid}, one with @{pids}) and 7 times with it (one of them as owner @{att}@{PROC}/@{pid}/fd/ r,).
  • owner on /proc/sys or /sys attributes is meaningful only for programs that run as root. A real record for a directory under /sys/class/ shows ouid=0 (syslog_datetime_01.in), and wpa_supplicant, a root daemon, has owner @{PROC}/sys/net/ipv{4,6}/conf/** rw, (wpa_supplicant:123).
  • Not determined: the owner of sysfs files in general.

for AppArmor developers for security researchers

Code

06 Device paths differ from machine to machine

THE SAME DISK ATTRIBUTE ON FOUR MACHINES /sys/devices/pci0000:00/0000:00:17.0/ata1/host0/.../block/sda/size PCI /sys/devices/virtual/block/loop0/size virtual /sys/devices/vbd-51712/block/xvda/size Xen /sys/devices/css0/0.0.0000/0.0.0100/block/dasda/size IBM Z @{sys}/devices/@{pci_bus}/** r, @{sys}/devices/virtual/** r, @{sys}/devices/platform/** r, lsblk # Needed for Xen PVH guests @{sys}/devices/vbd-@{int}/block/** r, # Needed for channel subsystem for IBM Z @{sys}/devices/css@{int}/** r, ... and more, for disks over network and for Azure @{pci_bus} = pci@{hex4}:@{hex2} matches pci0000:00 @{int} 1 to 10 digits @{sys}/devices/**/usb[0-9]**/speed r, lsusb: leaf fixed, location globbed each added line in lsblk has a comment naming the kind of machine that needed it
The size attribute of a disk under four different /sys/devices paths: a PCI path, virtual, a Xen vbd device and an IBM Z channel subsystem. The lsblk profile lists a rule per bus root, with comments for Xen and IBM Z. The variable @{pci_bus} is pci@{hex4}:@{hex2} and @{int} is one to ten digits. The lsusb profile globs the location and fixes the attribute name.

/sys/devices/... paths depend on bus topology. Use @{pci_bus} (pci@{hex4}:@{hex2}) and @{int}, enumerate bus roots as lsblk does, or glob the location and keep the attribute literal as lsusb does: @{sys}/devices/**/usb[0-9]**/speed r,.

You take the device path from your denial, paste it into the profile, and it works. On your machine. The middle of a /sys/devices path is the machine's wiring: a PCI address here, virtual there, a Xen block device, a channel subsystem on a mainframe. lsblk's shipped profile shows what that does to a precise rule: PCI, virtual, platform, and then one line after another, for Xen, for network disks, for IBM Z, for Azure, each with a comment. The tunables help: the @{pci_bus} variable matches any PCI root, and the @{int} variable matches a number. lsusb takes the other approach: glob the location, keep the attribute name exact. Either way, the leaf is what you pin down.

Details and sources

Details

The four paths at the top are illustrations shaped after the rules in the lsblk profile and their comments. They are not taken from a log.

  • The rules on the slide: @{sys}/devices/@{pci_bus}/** r,, @{sys}/devices/virtual/** r,, @{sys}/devices/platform/** r, (lsblk:26-28); "Needed for Xen PVH guests" with @{sys}/devices/vbd-@{int}/block/** r, (lsblk:36-37); "Needed for disks over network e.g. Hyper-V VMs (including Azure), IBM Power, ..." with @{sys}/devices/**/host@{int}/** r, (lsblk:39-40); "Needed for channel subsystem for IBM Z" with @{sys}/devices/css@{int}/** r, (lsblk:42-43); "Needed for Azure ACPI/NVMe" with two rules that spell out ACPI device names (lsblk:45-47).
  • lsusb lists one attribute per line under @{sys}/devices/**/usb[0-9]**/: uevent, busnum, descriptors, devnum, speed and more (lsusb:64-68).
  • @{sys}/devices/@{pci_bus}/**/config r, matches /sys/devices/pci0000:00/0000:00:02.0/config and devices behind deeper bridges, but not platform devices, virtual devices or USB controllers on a platform bus.
  • @{run} has two values, /run/ and /var/run/, so a rule written with it becomes two rules. udev data read next to sysfs is written @{run}/udev/data/*usb:* r, (lsusb:54).
  • tunables/sys is an empty, deprecated file; @{sys} is defined in tunables/kernelvars. @{securityfs} and @{apparmorfs} are not part of tunables/global and must be included separately.
  • Known discrepancy: @{u16} in tunables/system has an unbalanced bracket, [1-9][@{d}@{d} (system:38), and mis-matches three-digit values. The tree's parser, run with -D rule-exprs, prints the malformed alternation and exits 0. No shipped profile uses the variable. @{u8} is a four-value variable, which is probably intended.

The variables:

VariableDefinitionSource
@{sys}/sys/kernelvars:33
@{PROC}/proc/proc:12
@{pid}, @{pids}, @{tid}a number from 1 to 4999999kernelvars:16-22
@{d}[0-9]system:12
@{h}[0-9a-fA-F]system:24
@{int}1 to 10 digitssystem:27
@{hex2}, @{hex4}two and four hex digitssystem:60-61
@{pci_bus}pci@{hex4}:@{hex2}system:99-100
@{run}/run/ /var/run/run:1

07 How wide? Four shipped answers

FROM ONE FILE TO EVERYTHING @{PROC}/sys/net/ipv6/conf/all/disable_ipv6 r, ping: one file @{sys}/devices/**/usb[0-9]**/descriptors r, lsusb: one attribute, any location @{sys}/devices/@{pci_bus}/** r, lsblk: a bus subtree, read only @{sys}/devices/** r, @{PROC}/** r, Xorg, phpsysinfo: everything every process's cmdline and environ, as far as the file rule goes write: one leaf @{sys}/devices/@{pci_bus}/**/backlight/*/brightness rw, Xorg /proc/sys/kernel/task_delayacct rw, iotop-c severity.db rates /proc/** 6 to read and 9 to write, /sys/** 4 and 8
Four shipped levels of read access, from narrow to broad: ping reads one file under /proc/sys; lsusb one attribute at any location; lsblk a whole bus subtree; Xorg and the phpsysinfo hat everything under /sys/devices and /proc. Write rules name one leaf: Xorg writes the backlight brightness, iotop-c writes /proc/sys/kernel/task_delayacct.

Read access ranges from one file (ping) through one attribute at any location (lsusb) and a bus subtree (lsblk) to @{sys}/devices/** r, (Xorg) and @{PROC}/** r, (phpsysinfo). Write rules name one leaf.

How wide should you go? The tree has four answers. Ping reads one file under /proc/sys, by exact name. lsusb reads named attributes wherever a USB device sits. lsblk reads whole bus subtrees. And at the top, Xorg reads all of /sys/devices, and the phpsysinfo hat reads all of proc. That last one covers every process's command line and environment as far as the file rule goes, with only file ownership and the ptrace check behind it. For a general tool, a read-only subtree can be a fair trade. What stays narrow even in the broad profiles is writing: Xorg writes one attribute under sys, the backlight brightness, and one file under proc. The tools' own severity table rates writing in these trees far above reading.

Details and sources

Details

All rules on the slide are quoted from shipped profiles. What each covers is read from the rules and from the kernel code.

  • One file: @{PROC}/sys/net/ipv6/conf/all/disable_ipv6 r, (bin.ping:27).
  • One attribute at any location: @{sys}/devices/**/usb[0-9]**/descriptors r, (lsusb:66), one of a list of attribute rules (lsusb:64-96).
  • A bus subtree: @{sys}/devices/@{pci_bus}/** r, (lsblk:26).
  • Everything, read only: @{sys}/**/ r,, @{sys}/devices/** r,, @{sys}/module/** r, (Xorg:97-99); @{PROC}/** r, and @{sys}/devices/** r, in the phpsysinfo hat (phpsysinfo:24, phpsysinfo:31). @{PROC}/** r, includes every process's environ, cmdline and maps as far as the file rule is concerned; the file permissions and the ptrace check remain.
  • Write, one leaf: @{sys}/devices/@{pci_bus}/**/backlight/*/brightness rw, (Xorg:101); /proc/sys/kernel/task_delayacct rw, (iotop-c:28).
  • Xorg's only other write rule in these two trees is @{PROC}/mtrr rw, (Xorg:95): again one named file.
  • The shipped exception to "write names one leaf": @{PROC}/asound/** rw, (audio:39).
  • severity.db, the table the tools use to rank what a profile grants: /proc/** 6 for read and 9 for write, /proc/kallsyms 7 for read, /sys/** 4 and 8, /sys/firmware/** 10 for write (severity.db:71-77).
  • In between: tshark's dumpcap child has file r @{sys}/devices/{,**}, and file rw @{sys}/devices/**/statistics/rx_*, (tshark:57-58); lsof names each per-process file (lsof:38-52).
  • Three spellings of proc paths exist in the tree: @{PROC}/kmsg, /proc/kmsg and /proc/*/cmdline.

The guidance in four lines:

  • Take the resolved name from name= in the denial, or from readlink -f.
  • Replace the pid with @{pid} (own) or @{pids} (others), and add owner where the target runs as the same user.
  • For sysfs keep the attribute name literal, glob or enumerate the device location, and add the class or bus directory rule with a trailing slash.
  • Write access in /proc/sys and /sys should name one file.

08 Dead rules and wide rules: what to look for for security researchers

ATTACK SURFACE DEAD: rules that grant nothing /proc/self/maps r, /sys/class/net/*/address r, compile without a warning; never match the author believes access is granted; the quick fix is often a broad glob WIDE: rules that grant more than they say @{PROC}/@{pid}/{maps,auxv,status} r, base, no owner every process's status; maps and auxv: ptrace + DAC only /proc/*/cmdline r, iotop-c * is any name, not only a pid: cmdline of all processes @{PROC}/** r, phpsysinfo hat @{PROC}/asound/** rw, abstractions/audio the second gate for other processes is the ptrace read check, but abstractions/base grants ptrace (read) peer=@{profile_name}, ptrace (readby), ptrace (tracedby), three gates: the file rule · ownership (DAC and owner) · the ptrace check
Two columns. Dead rules that grant nothing: /proc/self/maps r and /sys/class/net/*/address r compile without a warning and never match. Wide rules that grant more than they say: @{PROC}/@{pid}/{maps,auxv,status} r in abstractions/base without owner; /proc/*/cmdline r in iotop-c; @{PROC}/** r in the phpsysinfo hat and @{PROC}/asound/** rw in abstractions/audio. The second gate is the ptrace read check, and abstractions/base grants ptrace read for the same profile.

/proc/self/... rules are accepted without a diagnostic and never match. @{pid} rules cover all processes; for maps, environ, mem and fd links the effective limits are the ptrace check and DAC (read from the kernel code). abstractions/base grants @{PROC}/@{pid}/{maps,auxv,status} r, without owner.

Two things to hunt for when you review proc and sys rules. First, dead rules: anything with the word self, or a class path that names an attribute. The parser accepts them silently, and they never match. The practical danger is the quick fix that follows. Second, wide rules. the @{pid} variable is every process. Base grants status, maps and auxv for any pid without owner, so what protects another process's maps is the ptrace check and file ownership, not the file rule. A star in place of the pid isn't even limited to numbers. And some profiles grant a whole tree. Base also lets processes under the same profile inspect each other. So judge these rules by all three gates together: the file rule, ownership, and ptrace.

Details and sources

Details

Everything here is read from the shipped policy and from the kernel code; nothing was run on a kernel. The two "dead" rules are examples written for the map: no shipped profile has a rule containing /proc/self (there is only a comment, systemd-detect-virt:22).

  • The wide rules are quoted: @{PROC}/@{pid}/{maps,auxv,status} r, (base:116); /proc/*/cmdline r, (iotop-c:24); @{PROC}/** r, (phpsysinfo:24); @{PROC}/asound/** rw, (audio:39).
  • Known discrepancy: the parser prints no warning for a rule containing /proc/self, which can never match. Checked with the tree's parser on a scratch profile: exit status 0, no diagnostic. This is a missing diagnostic rather than wrong behaviour.
  • Known discrepancy: the @{u16} variable has an unbalanced bracket; see the scene "Device paths differ from machine to machine".

for security researchers

Attack surface

  • Dead rules. Any rule with the literal self under /proc, and any rule that names an attribute through /sys/class/, /sys/bus/.../devices/, /sys/block/ or /sys/dev/. As an illustration of how to look for them: grep -n '/proc/self\|/sys/class/.*[^/] ' PROFILE.
  • The breadth of @{pid}. It is every process. Which per-process files have a ptrace check in procfs: maps, smaps, mem, environ, fdinfo, ns/* and the magic links. Which do not: status, cmdline and stat are readable subject to the file permissions and the hidepid mount option.
  • The ptrace rules in base: ptrace (readby),, ptrace (tracedby),, ptrace (read) peer=@{profile_name}, (base:134-142). "Same profile" covers every process running under that profile, whatever user or session it belongs to.
  • owner is the available narrowing. Its exception is the non-dumpable process, whose files are owned by root.
  • Magic links. /proc/<pid>/fd/N, exe, cwd and root are matched under the target's own name, after procfs has made its own ptrace-mode check. What counts is a file rule for the target plus access to the link. open("/proc/PID/fd/N") is a new open of the target. readlink on them is not mediated by AppArmor.
  • Write rules under /proc/sys and /sys in shipped policy: @{PROC}/asound/** rw,; w on @{sys}/devices/**/usb@{int}/{,**} (devices-usb:18); owner @{PROC}/sys/net/ipv{4,6}/conf/** rw, (wpa_supplicant:123).
  • severity.db rates /proc/** 6 to read and 9 to write, /sys/** 4 and 8 (severity.db:71-77).
  • @{PROC}/@{pid}/attr/{apparmor/,}current write rules are the interface for changing confinement: see aa_change_profile and aa_change_hat.

for AppArmor developers for security researchers

Code

09 Finding the name to write

FROM DENIAL TO RULE ... operation="open" profile="demo" name="/proc/1234/mountinfo" requested_mask="r" denied_mask="r" fsuid=1000 ouid=1000 /proc/1234/mountinfo r, works until the next run $ readlink -f /sys/class/net/eth0/address /sys/devices/pci0000:00/0000:00:1f.6/net/eth0/address the same answer, without waiting for a denial $ apparmor_parser -p /etc/apparmor.d/demo | grep mountinfo already granted by an include? generalise by hand the number becomes @{pid}; ouid = fsuid, so add owner @{PROC}/@{pid}/mountinfo r, owner @{PROC}/@{pid}/mountinfo r, as in abstractions/golang 1 - /proc/1234/mountinfo r, [2 - /proc/*/mountinfo r,] what aa-logprof offers: a star, not @{pid} for /sys: keep the attribute name, generalise the device part
From denial to rule in four steps. The denial names /proc/1234/mountinfo; writing that path works only until the next run. readlink -f on /sys/class/net/eth0/address prints the path under /sys/devices. apparmor_parser -p shows whether an include already grants the path. Then generalise by hand to @{PROC}/@{pid}/mountinfo r and add owner. aa-logprof offers the logged path and /proc/*/mountinfo.

Resolved name: name= in the denial, or readlink -f PATH. Check includes with apparmor_parser -p. Replace the pid with @{pid} and add owner when ouid equals fsuid. aa-logprof proposes /proc/*/..., not @{PROC}/@{pid}/....

Here's the working method. Take the name from the denial. It's already resolved, with a real pid in it. Or ask the system directly: readlink -f on the path your program opens prints where it ends up. Before you add anything, print the expanded profile and check whether an include already grants it. Then generalise: the number becomes the @{pid} variable, and if the ouid in the record equals the fsuid, put owner in front. Do it by hand, because aa-logprof's own suggestion for a proc path is a star in place of the pid, not the variable. For sys, keep the attribute name and generalise the device part, as the last slides showed.

Details and sources

Details

The record on the slide is built for the map on the field layout of an operation="open" record in the libapparmor test suite (syslog_datetime_01.in); its values are illustrative. The readlink -f output is an illustration consistent with the first scene. The two options in the aa-logprof panel are what the tool's code proposes for such a path; a full aa-logprof session was not run.

  • The resolved name: name= in the denial, readlink -f PATH, or realpath PATH. For a device node, udevadm info -q path -n DEVICE prints the sysfs device path.
  • apparmor_parser -p FILE prints the profile with its includes flattened, so grep shows whether an abstraction already has the rule. Variables are not expanded in that output: search for the file name, not for /proc/.
  • owner @{PROC}/@{pid}/mountinfo r, is shipped in abstractions/golang (golang:5) and in the lsblk profile (lsblk:56).
  • ouid= equal to fsuid= in the record means the program owns the file, so an owner rule would match.
  • What abstractions/base already grants in these trees, all r (base:95-128): @{PROC}/sys/kernel/version, @{PROC}/sys/kernel/ngroups_max, @{PROC}/sys/crypto/fips_enabled, @{PROC}/meminfo, @{PROC}/stat, @{PROC}/cpuinfo, @{sys}/devices/system/cpu/ with online and possible, the transparent hugepage files enabled and hpage_pmd_size, @{PROC}/@{pid}/{maps,auxv,status}, @{PROC}/filesystems, @{PROC}/sys/vm/overcommit_memory, @{PROC}/sys/kernel/cap_last_cap.
  • Smaller sets: crypto (@{PROC}/sys/crypto/*), nameservice (@{PROC}/@{pid}/net/route, ipv6_route, psched), bash and gnome (@{PROC}/@{pid}/mounts), nss-systemd (boot_id), golang (mountinfo, cgroup, cgroup cpu quota files), psi-read, and the apparmor_api/* abstractions. The full table is in the reference below.
  • aa-logprof offers the logged path, paths of existing rules that match, and the globs of the [globs] section of logprof.conf. The procfs entry there is ^/proc/\d+/ = /proc/*/, "strip pid numbers from /proc accesses" (logprof.conf:148-149). There is no entry for /sys.
  • Known discrepancy: aa-logprof's rule matching does not expand variables. With the tree's module, AARE('@{PROC}/meminfo', True).match('/proc/meminfo') is False, so a rule written with @{PROC} or @{pid} may not be recognised as covering a later log event, and the tool may ask again. A full aa-logprof session was not run. A # XXX marker in the code and an existing test expectation suggest this is known.

for AppArmor developers

Code

10 Where to go from here

ROADS /proc and /sys: write the resolved path @{PROC}/@{pid} · owner · class/ plus devices/ · literal leaf prac-symlinks why the resolved path counts prac-privileged where exact rules matter prac-abstractions what base already grants syn-variables @{PROC}, @{pid}, @{sys} syn-ptrace the second gate syn-owner the owner qualifier also: adm-denials (the name= field) · ut-logprof (what the tool proposes) syn-builtin-variables · syn-globbing · sec-path-limits
/proc and /sys in the centre, with the recap @{PROC}/@{pid}, owner, class/ plus devices/, literal leaf, and roads to the decks prac-symlinks, prac-privileged, prac-abstractions, syn-variables, syn-ptrace and syn-owner, and a row naming adm-denials, ut-logprof, syn-builtin-variables, syn-globbing and sec-path-limits.

Next: prac-symlinks, prac-privileged, prac-abstractions, syn-variables, syn-ptrace, syn-owner, adm-denials, ut-logprof.

Self becomes a pid, so write the @{PROC} and @{pid} variables, and remember that pid means any process. Owner narrows it to your user. In sys, write one rule for the class directory and one for the device path, with the attribute name exact. The symlinks deck explains the mechanism under all of this. The ptrace deck covers the second gate, and variables, owner and reading denials have decks of their own.

Details and sources

Details

  • /proc/self becomes /proc/<pid>, so rules are written @{PROC}/@{pid}/.... @{pid} means any process; owner narrows a rule to processes of the same user, and a ptrace check stands behind the sensitive per-process files.
  • In /sys, a class or bus directory needs its own rule with a trailing slash, and attributes are matched under /sys/devices/. Keep the attribute name literal; glob or enumerate the device location.

What each deck answers:

Nothing in this deck was run on a live kernel; the kernel behaviour is read from the kernel code.

Read more

Basis of the statements on this page: the kernel behaviour is read from the kernel source and the shipped policy from the AppArmor tree. Nothing here was observed on a running kernel. Parser statements marked "parser run" were made with the tree's own apparmor_parser (6.0.0~alpha2), compiling without loading (-Q -K --skip-kernel-load).

What the program opens and what is matched

The program opensAppArmor matches
/proc/self/X/proc/<tgid>/X
/proc/thread-self/X/proc/<tgid>/task/<tid>/X
/proc/mounts/proc/<tgid>/mounts
/proc/net/X/proc/<tgid>/net/X
/proc/<pid>/exe, cwd, root, fd/Nthe target's own path: a new open of the target
/sys/class/C/D/attr/sys/devices/.../attr
/sys/bus/B/devices/D/attr/sys/devices/.../attr
/sys/block/D/attr/sys/devices/.../block/D/attr
/sys/dev/char/M:m/attr, /sys/dev/block/M:m/attr/sys/devices/.../attr
the directory /sys/class/C/ itself/sys/class/C/

Not symlinks, and named directly: /sys/devices/system/cpu/..., /sys/kernel/..., /sys/module/..., /sys/fs/cgroup/... (a separate cgroup file system mounted there). Examples: @{sys}/devices/system/cpu/online r, (base:108), @{sys}/module/apparmor/parameters/enabled r, (is_enabled:17), @{sys}/fs/cgroup/**/cpu.max r, (golang:8).

A rule with the literal word self under /proc never matches. The pid is the number in the pid namespace of that procfs mount.

Variables

VariableDefinitionSourceIncluded by tunables/global
@{PROC}/proc/; sites extend it in tunables/proc.dproc:12yes
@{sys}/sys/kernelvars:33yes
@{pid}a number from 1 to 4999999, as seven alternativeskernelvars:16yes
@{tid}, @{pids}@{pid}kernelvars:19, kernelvars:22yes
@{d}[0-9]system:12yes
@{h}[0-9a-fA-F]system:24yes
@{int}1 to 10 digitssystem:27yes
@{hex2}, @{hex4}two and four hex digitssystem:60-61yes
@{pci_bus}pci@{hex4}:@{hex2}system:99-100yes
@{run}/run/ /var/run/: two values, so one rule becomes tworun:1yes
@{securityfs}@{sys}/kernel/security/securityfs:10no: include it separately
@{apparmorfs}@{securityfs}/apparmor/apparmorfs:11no: include it separately
  • @{PROC} and @{sys} end in a slash; rules write @{PROC}/name and the parser collapses the doubled slash (parser run: aare: /proc/meminfo).
  • tunables/sys is an empty, deprecated file.
  • @{pid}, @{pids} and @{tid} compile to the same pattern. By convention @{pid} is written where a program looks at itself, @{pids} where it looks at other processes, @{tid} for thread ids. None of them means "this process".

Per-process files and their second check

procfs itself asks whether the reader may inspect the target process. For a process outside the reader's own thread group that question reaches AppArmor as a ptrace request.

File under /proc/<pid>/procfs asks forAppArmor rule needed for another processOwn process
maps, smaps and the other memory-map filesptrace readptrace (read) peer=...,not asked
environptrace readptrace (read) peer=...,not asked
fdinfo/Nptrace readptrace (read) peer=...,not asked
ns/*ptrace readptrace (read) peer=...,not asked
exe, cwd, root, fd/N (magic links)ptrace read, then the target is opened under its own nameptrace (read) peer=..., and a file rule for the targetnot asked; the file rule for the target is still needed
memptrace attachptrace (trace) peer=...,not asked
status, cmdline, statnothing on open; file permissions and the hidepid mount optionnone
  • The target side needs the matching readby or tracedby permission; abstractions/base grants ptrace (readby), and ptrace (tracedby), to every profile that includes it, plus ptrace (read) peer=@{profile_name}, (base:134-142).
  • A denial at this gate is logged with operation="ptrace", not as a file denial.
  • lsof pairs its /proc/@{pids}/... rules with ptrace read, and capability sys_ptrace, (lsof:25-28).

owner on procfs and sysfs

  • owner compares the reader's fsuid with the owner of the file.
  • Files in /proc/<pid>/ are owned by the target process's effective uid and gid.
  • For a process that is not dumpable (typically a setuid program that dropped privileges), entries other than the world-readable directories are owned by root of the process's user namespace. An owner rule then denies that program its own files.
  • Files of kernel threads are owned by root.
  • owner on /proc/sys or /sys attributes is meaningful only for programs that run as root: a real record for /sys/class/power_supply/ shows ouid=0.
  • Shipped: owner @{PROC}/@{pid}/mountinfo r, (golang:5, lsblk:56), owner @{PROC}/@{pid}/fd/ r, (gio-open:56, samba-rpcd:26), owner @{PROC}/@{pid}/{cgroup,cpuset,status} r, (opencl-pocl:41), owner @{PROC}/@{pid}/task/@{tid}/comm rw, (dig:46). Over profiles/apparmor.d the fd/ directory rule appears 7 times without owner and 6 times with it.

What abstractions already grant

AbstractionRules in /proc and /sysSource
base@{PROC}/sys/kernel/version, ngroups_max, @{PROC}/sys/crypto/fips_enabled, @{PROC}/meminfo, stat, cpuinfo, @{sys}/devices/system/cpu/ with online and possible, transparent hugepage enabled and hpage_pmd_size, @{PROC}/@{pid}/{maps,auxv,status}, @{PROC}/filesystems, @{PROC}/sys/vm/overcommit_memory, @{PROC}/sys/kernel/cap_last_cap; all rbase:95-128
crypto (included by base)@{PROC}/sys/crypto/fips_enabled r,, @{PROC}/sys/crypto/* r,crypto:24-27
nameservice@{PROC}/@{pid}/net/psched r,, ipv6_route r,, route r,nameservice:55, nameservice:102-103
bash@{PROC}/@{pid}/mounts r,, @{PROC}/filesystems r,bash:37-38
gnome@{PROC}/@{pid}/mounts r,gnome:82
nss-systemd@{PROC}/sys/kernel/random/boot_id r,nss-systemd:30
golangowner @{PROC}/@{pid}/mountinfo r,, owner @{PROC}/@{pid}/cgroup r,, cgroup cpu quota filesgolang:5-8
audio@{PROC}/asound/** rw,: read and write on the whole ALSA procfs treeaudio:39
mesa@{sys}/devices/@{pci_bus}/**/{revision,config} r,mesa:17
nvidia@{PROC}/interrupts, @{PROC}/modules, @{PROC}/driver/nvidia/paramsnvidia:20-23
video@{sys}/class/video4linux/** r, and device pathsvideo:7-17
devices-usb-read, devices-usb@{sys}/devices/**/usb@{int}/{,**} r,; devices-usb adds wdevices-usb-read:19-26, devices-usb:18
apparmor_api/examine, introspect, change_profile, find_mountpoint, is_enabledthe attr files, @{PROC}/@{pids}/mounts r,, the apparmor module parameterexamine:14, change_profile:13, find_mountpoint:16, is_enabled:17-18
psi-read, psi-read-poll@{PROC}/pressure/{cpu,memory,io}, r and rwpsi-read:6

base's @{PROC}/@{pid}/{maps,auxv,status} r, has no owner. For another process's maps and auxv the ptrace check still applies; for status it does not.

Shipped rules by breadth

LevelRuleSource
one file@{PROC}/sys/net/ipv6/conf/all/disable_ipv6 r,bin.ping:27
one file, write/proc/sys/kernel/task_delayacct rw,iotop-c:28
one attribute, any location@{sys}/devices/**/usb[0-9]**/descriptors r, and its neighbourslsusb:64-96
per-process files, each named@{PROC}/@{pids}/stat r,, @{PROC}/@{pids}/task/@{tid}/fd/ r, and morelsof:38-52
a bus subtree@{sys}/devices/@{pci_bus}/** r,, virtual/**, platform/**, then Xen, network disks, IBM Z, Azurelsblk:26-28, lsblk:36-47
everything under devices, write on one leaf@{sys}/**/ r,, @{sys}/devices/** r,, @{sys}/module/** r,; @{sys}/devices/@{pci_bus}/**/backlight/*/brightness rw,Xorg:97-101
devices, with a write globfile r @{sys}/devices/{,**},, file rw @{sys}/devices/**/statistics/rx_*,tshark:57-58
everything@{PROC}/** r,, @{sys}/devices/** r,phpsysinfo:24, phpsysinfo:31
loose pid patterns@{PROC}/*/mounts r,; /proc/*/cmdline r,, /proc/*/task/ r,: * is any single name, not only a numberusr.lib.dovecot.lmtp:35, iotop-c:24-25

utils/severity.db rates /proc/** 6 for read and 9 for write, /proc/kallsyms 7 for read, /sys/** 4 and 8, /sys/firmware/** 10 for write (severity.db:71-77).

Finding and generalising a path

  • The resolved name: name= in the denial; readlink -f PATH or realpath PATH; udevadm info -q path -n DEVICE for the sysfs path of a device node.
  • Is it already granted: apparmor_parser -p FILE | grep NAME prints the profile with its includes flattened.
  • Take the resolved name. Replace the pid with @{pid} (own) or @{pids} (others), and add owner where the target runs as the same user (ouid= equals fsuid= in the record).
  • For sysfs keep the attribute name literal, glob the device location with @{pci_bus}/** or ** or enumerate bus roots, and add the class or bus directory rule with a trailing slash.
  • Write access in /proc/sys and /sys should name one file.

What aa-logprof does with these paths

  • It offers the logged path, paths of existing rules that match, and the globs of the [globs] section of logprof.conf.
  • The procfs glob is ^/proc/\d+/ = /proc/*/, "strip pid numbers from /proc accesses" (logprof.conf:148-149). There is no entry for /sys.
  • It does not offer @{PROC} or @{pid}.

for security researchers

Attack surface

  • Dead rules: any rule with a literal self under /proc, and any rule that names an attribute through /sys/class/, /sys/bus/.../devices/, /sys/block/ or /sys/dev/. They compile and never match. No shipped profile has a /proc/self rule.
  • @{pid} is every process. For maps, environ, mem, fdinfo, ns/* and the magic links the effective limits are the ptrace check and the file permissions; status, cmdline and stat have no ptrace check.
  • base grants ptrace (read) peer=@{profile_name}, with readby and tracedby: processes under one profile can inspect each other.
  • owner narrows a rule to the reader's own uid; a non-dumpable process is the exception.
  • Magic links are matched under the target's name after procfs's own check; readlink on them is not mediated by AppArmor.
  • Write rules in these trees in shipped policy: @{PROC}/asound/** rw,, w on @{sys}/devices/**/usb@{int}/{,**}, owner @{PROC}/sys/net/ipv{4,6}/conf/** rw,.
  • severity.db ratings, above.
  • @{PROC}/@{pid}/attr/{apparmor/,}current write rules are the interface for changing confinement: lib-change-profile, lib-change-hat.

Known discrepancies

  • No diagnostic for /proc/self rules. Checked with a parser run on a scratch profile containing /proc/self/maps r,: exit status 0, no warning. A missing diagnostic rather than wrong behaviour.
  • aa-logprof's rule matching ignores variables. Checked by importing the tree's module: AARE('@{PROC}/meminfo', True).match('/proc/meminfo') is False and AARE('/proc/meminfo', True).match('/proc/meminfo') is True. A full aa-logprof session was not run; a # XXX marker and an existing test expectation suggest it is known.
  • @{u16} in tunables/system has an unbalanced bracket, [1-9][@{d}@{d} (system:38). Checked with a parser run using -D rule-exprs: the malformed alternation is printed and the exit status is 0. Three-digit values are mis-matched; no shipped profile uses the variable. @{u8} is a four-value variable, probably intended.

Not determined

  • Which kernel code path reaches the /proc/sys special case for internal mounts in AppArmor's name building.
  • The owner of sysfs files in general.
  • Whether stat on a class symlink itself can be denied.
  • Differences in distribution kernels for procfs mediation.
  • The behaviour of a full aa-logprof session on rules written with variables.

for AppArmor developers for security researchers

Code

WhatWhere
/proc/self, /proc/thread-selfself.c:11-28, thread_self.c:11-25
/proc/mounts, /proc/netroot.c:383, proc_net.c:423
magic links: check and jumpbase.c:1787, base.c:1800-1813
procfs ptrace callersbase.c:818-826, base.c:855, base.c:984, fd.c:94, namespaces.c:63
hidepidbase.c:728-742
owner of procfs inodesbase.c:1872-1897, base.c:1953
__ptrace_may_accessptrace.c:325-327, ptrace.c:371
PID_MAX_LIMITthreads.h:34-35
class, subsystem, device and dev linkscore.c:3510-3522, core.c:3580-3589, core.c:3327-3332
bus and block linksbus.c:583, genhd.c:507, genhd.c:1011
kernfs link textsymlink.c:67, symlink.c:87
apparmor_ptrace_access_checklsm.c:128-141
apparmor_file_open, owner conditionlsm.c:465-500, lsm.c:491-496
d_namespace_path, the /proc/sys special casepath.c:89-128, path.c:105-110
parser: filter_slashesparser_regex.c:61, parser_regex.c:659
tools: globs, proposals, matchingaa.py:2547-2552, aa.py:2378-2408, aare.py:49, common.py:230-259, test-aare.py:239

Roads from here

FILE ACCESS

PREAMBLE AND REUSE

QUALIFIERS

RULE CLASSES

IN PRACTICE · general-purpose apps

IN PRACTICE · security-sensitive programs

SECURITY · threat model and limits

RUNNING THE PARSER

TOOLS · utils/

  • aa-logprof — what the tool proposes for /proc paths