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
- Symlinks: rules see through them — rules see where a symlink ends, the mechanism underneath
- Variables — the variables that keep per-process paths readable
- The owner qualifier — owner rules, used for per-process files in /proc
Part of journeys
- Hardening a privileged program, step 4 of 11 · previous: Symlinks: rules see through them · next: Child profiles
01 Two rules that look right and never match
/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/selfis 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/eth0is a symlink into/sys/devices/. The attribute fileaddresslives 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; theapparmor_parser -rline 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_maskis what the program asked for,denied_maskthe part that was refused.- demo's read of
/proc/self/statuswould in fact be granted byabstractions/base, which has@{PROC}/@{pid}/{maps,auxv,status} r,(base:116). The demo profile on the slide includes nothing.
Read more
- apparmor.d(5): Access Modes Details, apparmor_parser(8)
- apparmor.net: Troubleshooting, apparmor.net: Denials quick guide
- Symlinks (the scenes "The walk" and "/proc/self and the links that jump"), reading a denial.
for AppArmor developers for security researchers
Code
proc_self_get_linkreturns the thread-group id as text: self.c:11-28. The class symlink is created by the driver core at core.c:3521-3522.- The open hook builds the name from the opened file: lsm.c:498-500.
02 /proc/self is a number by the time AppArmor looks
/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/selfis a symlink whose text is the caller's thread-group id;/proc/thread-selfhas the text<tgid>/task/<tid>. The number is the one in the pid namespace of that procfs mount./proc/mountsis a symlink toself/mountsand/proc/neta symlink toself/net. That is why abstractions grant@{PROC}/@{pid}/mounts r,(bash:37) and@{PROC}/@{pid}/net/route r,(nameservice:103) and not/proc/mountsor/proc/net/route.@{PROC}=/proc/(proc:12) and@{pid}(kernelvars:16). A profile that uses them must includetunables/global(ortunables/procandtunables/kernelvars) in its preamble.@{PROC}ends in a slash and rules write@{PROC}/name; the parser collapses the doubled slash. The tree's parser printsaare: /proc/meminfofor@{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,rootandfd/Nunder 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) andowner @{PROC}/@{pid}/task/@{tid}/comm rw,(dig:46).
Read more
for AppArmor developers for security researchers
Code
proc_self_get_link: self.c:11-28;proc_thread_self_get_link: thread_self.c:11-25; themountslink: root.c:383; thenetlink: proc_net.c:423.apparmor_file_open: lsm.c:465-500;d_namespace_path: path.c:89-128.- The one procfs special case in AppArmor's name building: on an internal mount, a procfs name that starts with
/sys/gets/procprepended, with a TODO about the hard-coded/proc(path.c:105-110). Which kernel code path reaches it was not determined. - The parser's
filter_slashes: parser_regex.c:61, called at parser_regex.c:659.
03 @{pid} means any process, not yours
@{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,smapsand the other memory-map files,mem(which asks for attach, not read),fdinfo, thens/*links,environ, and the magic linksexe,cwd,root,fd/N.statushas none: it is readable subject to the file permissions unless procfs is mounted withhidepid. - A task looking at its own thread group passes the check before any security module is asked.
- What
abstractions/basegrants:ptrace (readby),,ptrace (tracedby),andptrace (read) peer=@{profile_name},(base:134-142). A profile with base can read these files of processes under the same profile. lsofpairs its/proc/@{pids}/...rules withptrace read,andcapability sys_ptrace,(lsof:25-28).- Wider stand-ins:
[0-9]*inowner @{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).
Read more
for AppArmor developers for security researchers
Code
apparmor_ptrace_access_check: lsm.c:128-141, with the read or trace mapping at lsm.c:139-141.__ptrace_may_access: the own-thread-group return at ptrace.c:325-327, the security hook at ptrace.c:371.- procfs callers:
proc_mem_openbase.c:818-826,membase.c:855,environbase.c:984, magic links base.c:1787,fdinfofd.c:94,ns/*namespaces.c:63. PID_MAX_LIMIT: threads.h:34-35.- The tree's parser run with
-D rule-exprsonowner @{PROC}/@{pid}/fd/ r,prints the seven-way alternation.
04 owner on /proc files: same user, with one trap
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.
ownercompares 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
ownerrule denies it access to its own/procfiles. - 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: thefd/directory rule appears 7 times withoutowner(six with@{pid}, one with@{pids}) and 7 times with it (one of them asowner @{att}@{PROC}/@{pid}/fd/ r,). owneron/proc/sysor/sysattributes is meaningful only for programs that run as root. A real record for a directory under/sys/class/showsouid=0(syslog_datetime_01.in), andwpa_supplicant, a root daemon, hasowner @{PROC}/sys/net/ipv{4,6}/conf/** rw,(wpa_supplicant:123).- Not determined: the owner of sysfs files in general.
Read more
for AppArmor developers for security researchers
Code
task_dump_owner: base.c:1872-1897, called at base.c:1953.apparmor_file_openfills the owner condition from the inode: lsm.c:491-496.
05 /sys/class is a directory of symlinks
/sys/class/<class>/, /sys/bus/<bus>/devices/, /sys/block/ and /sys/dev/{char,block}/ hold symlinks into /sys/devices/. Rule for the listing: @{sys}/class/net/ r,. Rule for an attribute: @{sys}/devices/.../address r,.
Sys has the same trick on a bigger scale. The directories you browse, class, bus, block, are indexes. Their entries are symlinks, and the real device directories, with their attribute files, live under /sys/devices. So one innocent cat does two different things. Listing the class directory is a read of the class path itself. That needs a rule with the class name and a trailing slash. Reading the address goes through the link and is checked under /sys/devices. That needs a second rule, with the device path. Here's a real denial of the first kind: the name is a class directory. Both of these rules ship in one of the OpenCL abstractions, side by side.
Details and sources
Details
The kernel side is read from the kernel code. The tree contents on the slide are illustrations. The record is real: it is in the libapparmor test suite (complex_profile_name.in), with the long profile name shortened with ....
- When a device is added, the kernel creates a symlink named after the device in its class directory, pointing at the device's own directory, plus a
subsystemlink back and adevicelink to the parent. Buses do the same in/sys/bus/<bus>/devices/./sys/block/is a directory of links, and so are/sys/dev/char/<maj>:<min>and/sys/dev/block/<maj>:<min>. - The link texts are relative paths made of
../components. The kernel walks them, and the name AppArmor matches is the location under/sys/devices/. - Devices without a parent live under
/sys/devices/virtual/<class>/. - The two rules on the slide:
@{sys}/class/net/ r,(opencl-pocl:18) and@{sys}/devices/@{pci_bus}/*/net/*/address r,(opencl-pocl:22). - The same pairing elsewhere:
@{sys}/bus/usb/devices/ r,with@{sys}/devices/**/usb[0-9]**/uevent r,(lsusb:58, lsusb:64);@{sys}/block/ r,,@{sys}/class/block/ r,,@{sys}/dev/block/ r,with@{sys}/devices/@{pci_bus}/** r,(lsblk:22-26). - The
wpa_supplicantprofile records the pairing in a comment:@{sys}/devices/@{pci_bus}/**/ieee80211/phy[0-9]*/name r,followed by "Might also need @{sys}/class/ieee80211/ r," (wpa_supplicant:139-140). @{sys}/class/video4linux/** r,(video:8) covers only names that stay under/sys/class/. An attribute opened through a class entry is matched by the/sys/devices/...rule a few lines below it (video:12).- Not symlinks, and named directly in rules:
/sys/devices/system/cpu/...,/sys/kernel/...,/sys/module/..., and/sys/fs/cgroup/..., which is a separate file system mounted there. - AppArmor has no sysfs-specific code in its path handling; this is the ordinary open check.
- Not determined: whether
staton the class symlink itself can be denied.
for AppArmor developers for security researchers
Code
- Class,
subsystemanddevicelinks: core.c:3510-3522;/sys/dev/{char,block}links: core.c:3580-3589; bus device links: bus.c:583;/sys/block: genhd.c:507, genhd.c:1011; virtual devices: core.c:3327-3332. - kernfs builds the relative link text: symlink.c:67, symlink.c:87.
apparmor_file_open: lsm.c:465.
06 Device paths differ from machine to machine
/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). lsusblists one attribute per line under@{sys}/devices/**/usb[0-9]**/:uevent,busnum,descriptors,devnum,speedand more (lsusb:64-68).@{sys}/devices/@{pci_bus}/**/config r,matches/sys/devices/pci0000:00/0000:00:02.0/configand 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/sysis an empty, deprecated file;@{sys}is defined intunables/kernelvars.@{securityfs}and@{apparmorfs}are not part oftunables/globaland must be included separately.- Known discrepancy:
@{u16}intunables/systemhas 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:
| Variable | Definition | Source |
|---|---|---|
@{sys} | /sys/ | kernelvars:33 |
@{PROC} | /proc/ | proc:12 |
@{pid}, @{pids}, @{tid} | a number from 1 to 4999999 | kernelvars:16-22 |
@{d} | [0-9] | system:12 |
@{h} | [0-9a-fA-F] | system:24 |
@{int} | 1 to 10 digits | system:27 |
@{hex2}, @{hex4} | two and four hex digits | system:60-61 |
@{pci_bus} | pci@{hex4}:@{hex2} | system:99-100 |
@{run} | /run/ /var/run/ | run:1 |
07 How wide? Four shipped answers
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'senviron,cmdlineandmapsas 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/kallsyms7 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/{,**},andfile rw @{sys}/devices/**/statistics/rx_*,(tshark:57-58);lsofnames each per-process file (lsof:38-52). - Three spellings of proc paths exist in the tree:
@{PROC}/kmsg,/proc/kmsgand/proc/*/cmdline.
The guidance in four lines:
- Take the resolved name from
name=in the denial, or fromreadlink -f. - Replace the pid with
@{pid}(own) or@{pids}(others), and addownerwhere 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/sysand/sysshould name one file.
08 Dead rules and wide rules: what to look for for security researchers
/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".
Read more
for security researchers
Attack surface
- Dead rules. Any rule with the literal
selfunder/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,cmdlineandstatare readable subject to the file permissions and thehidepidmount 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. owneris the available narrowing. Its exception is the non-dumpable process, whose files are owned by root.- Magic links.
/proc/<pid>/fd/N,exe,cwdandrootare 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.readlinkon them is not mediated by AppArmor. - Write rules under
/proc/sysand/sysin shipped policy:@{PROC}/asound/** rw,;won@{sys}/devices/**/usb@{int}/{,**}(devices-usb:18);owner @{PROC}/sys/net/ipv{4,6}/conf/** rw,(wpa_supplicant:123). severity.dbrates/proc/**6 to read and 9 to write,/sys/**4 and 8 (severity.db:71-77).@{PROC}/@{pid}/attr/{apparmor/,}currentwrite rules are the interface for changing confinement: see aa_change_profile and aa_change_hat.
for AppArmor developers for security researchers
Code
hidepid: base.c:728-742. The ptrace callers in procfs: base.c:818-826, base.c:984, base.c:1787; the jump of a magic link: base.c:1800-1813.__ptrace_may_access: ptrace.c:325-327, ptrace.c:371.apparmor_ptrace_access_check: lsm.c:128-141.
09 Finding the name to write
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, orrealpath PATH. For a device node,udevadm info -q path -n DEVICEprints the sysfs device path. apparmor_parser -p FILEprints the profile with its includes flattened, sogrepshows 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 inabstractions/golang(golang:5) and in thelsblkprofile (lsblk:56).ouid=equal tofsuid=in the record means the program owns the file, so anownerrule would match.- What
abstractions/basealready grants in these trees, allr(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/withonlineandpossible, the transparent hugepage filesenabledandhpage_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),bashandgnome(@{PROC}/@{pid}/mounts),nss-systemd(boot_id),golang(mountinfo,cgroup, cgroup cpu quota files),psi-read, and theapparmor_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 oflogprof.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# XXXmarker in the code and an existing test expectation suggest this is known.
Read more
for AppArmor developers
Code
glob_common: aa.py:2547-2552;propose_file_rules: aa.py:2378-2408;convert_regexp: common.py:230-259.- The unexpanded variables in
AARE: aare.py:49, aare.py:83; the test expectation: test-aare.py:239.
10 Where to go from here
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/selfbecomes/proc/<pid>, so rules are written@{PROC}/@{pid}/....@{pid}means any process;ownernarrows 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:
- Symlinks: why the resolved path is the one that is matched.
- Profiles for security-sensitive programs: where exact
/procand/sysrules matter most. - Choosing abstractions: the
/procand/sysrules base already grants. - Variables and built-in variables: how
@{PROC}and@{pid}expand. - Globbing: one star against two stars in device paths.
- The owner qualifier, ptrace rules.
- Reading a denial: the
name=field. aa-logprof: what the tool proposes. - The limits of name-based mediation.
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 opens | AppArmor 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/N | the 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
| Variable | Definition | Source | Included by tunables/global |
|---|---|---|---|
@{PROC} | /proc/; sites extend it in tunables/proc.d | proc:12 | yes |
@{sys} | /sys/ | kernelvars:33 | yes |
@{pid} | a number from 1 to 4999999, as seven alternatives | kernelvars:16 | yes |
@{tid}, @{pids} | @{pid} | kernelvars:19, kernelvars:22 | yes |
@{d} | [0-9] | system:12 | yes |
@{h} | [0-9a-fA-F] | system:24 | yes |
@{int} | 1 to 10 digits | system:27 | yes |
@{hex2}, @{hex4} | two and four hex digits | system:60-61 | yes |
@{pci_bus} | pci@{hex4}:@{hex2} | system:99-100 | yes |
@{run} | /run/ /var/run/: two values, so one rule becomes two | run:1 | yes |
@{securityfs} | @{sys}/kernel/security/ | securityfs:10 | no: include it separately |
@{apparmorfs} | @{securityfs}/apparmor/ | apparmorfs:11 | no: include it separately |
@{PROC}and@{sys}end in a slash; rules write@{PROC}/nameand the parser collapses the doubled slash (parser run:aare: /proc/meminfo).tunables/sysis 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 for | AppArmor rule needed for another process | Own process |
|---|---|---|---|
maps, smaps and the other memory-map files | ptrace read | ptrace (read) peer=..., | not asked |
environ | ptrace read | ptrace (read) peer=..., | not asked |
fdinfo/N | ptrace read | ptrace (read) peer=..., | not asked |
ns/* | ptrace read | ptrace (read) peer=..., | not asked |
exe, cwd, root, fd/N (magic links) | ptrace read, then the target is opened under its own name | ptrace (read) peer=..., and a file rule for the target | not asked; the file rule for the target is still needed |
mem | ptrace attach | ptrace (trace) peer=..., | not asked |
status, cmdline, stat | nothing on open; file permissions and the hidepid mount option | none |
- The target side needs the matching
readbyortracedbypermission;abstractions/basegrantsptrace (readby),andptrace (tracedby),to every profile that includes it, plusptrace (read) peer=@{profile_name},(base:134-142). - A denial at this gate is logged with
operation="ptrace", not as a file denial. lsofpairs its/proc/@{pids}/...rules withptrace read,andcapability sys_ptrace,(lsof:25-28).
owner on procfs and sysfs
ownercompares 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
ownerrule then denies that program its own files. - Files of kernel threads are owned by root.
owneron/proc/sysor/sysattributes is meaningful only for programs that run as root: a real record for/sys/class/power_supply/showsouid=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). Overprofiles/apparmor.dthefd/directory rule appears 7 times withoutownerand 6 times with it.
What abstractions already grant
| Abstraction | Rules in /proc and /sys | Source |
|---|---|---|
| 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 r | base: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 |
| golang | owner @{PROC}/@{pid}/mountinfo r,, owner @{PROC}/@{pid}/cgroup r,, cgroup cpu quota files | golang:5-8 |
| audio | @{PROC}/asound/** rw,: read and write on the whole ALSA procfs tree | audio:39 |
| mesa | @{sys}/devices/@{pci_bus}/**/{revision,config} r, | mesa:17 |
| nvidia | @{PROC}/interrupts, @{PROC}/modules, @{PROC}/driver/nvidia/params | nvidia:20-23 |
| video | @{sys}/class/video4linux/** r, and device paths | video:7-17 |
| devices-usb-read, devices-usb | @{sys}/devices/**/usb@{int}/{,**} r,; devices-usb adds w | devices-usb-read:19-26, devices-usb:18 |
| apparmor_api/examine, introspect, change_profile, find_mountpoint, is_enabled | the attr files, @{PROC}/@{pids}/mounts r,, the apparmor module parameter | examine:14, change_profile:13, find_mountpoint:16, is_enabled:17-18 |
| psi-read, psi-read-poll | @{PROC}/pressure/{cpu,memory,io}, r and rw | psi-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
| Level | Rule | Source |
|---|---|---|
| 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 neighbours | lsusb:64-96 |
| per-process files, each named | @{PROC}/@{pids}/stat r,, @{PROC}/@{pids}/task/@{tid}/fd/ r, and more | lsof:38-52 |
| a bus subtree | @{sys}/devices/@{pci_bus}/** r,, virtual/**, platform/**, then Xen, network disks, IBM Z, Azure | lsblk: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 glob | file 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 number | usr.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 PATHorrealpath PATH;udevadm info -q path -n DEVICEfor the sysfs path of a device node. - Is it already granted:
apparmor_parser -p FILE | grep NAMEprints the profile with its includes flattened. - Take the resolved name. Replace the pid with
@{pid}(own) or@{pids}(others), and addownerwhere the target runs as the same user (ouid=equalsfsuid=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/sysand/sysshould 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 oflogprof.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
selfunder/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/selfrule. @{pid}is every process. Formaps,environ,mem,fdinfo,ns/*and the magic links the effective limits are the ptrace check and the file permissions;status,cmdlineandstathave no ptrace check.- base grants
ptrace (read) peer=@{profile_name},withreadbyandtracedby: processes under one profile can inspect each other. ownernarrows 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;
readlinkon them is not mediated by AppArmor. - Write rules in these trees in shipped policy:
@{PROC}/asound/** rw,,won@{sys}/devices/**/usb@{int}/{,**},owner @{PROC}/sys/net/ipv{4,6}/conf/** rw,. severity.dbratings, above.@{PROC}/@{pid}/attr/{apparmor/,}currentwrite rules are the interface for changing confinement: lib-change-profile, lib-change-hat.
Known discrepancies
- No diagnostic for
/proc/selfrules. 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 andAARE('/proc/meminfo', True).match('/proc/meminfo')is True. A full aa-logprof session was not run; a# XXXmarker and an existing test expectation suggest it is known. @{u16}intunables/systemhas 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/sysspecial case for internal mounts in AppArmor's name building. - The owner of sysfs files in general.
- Whether
staton 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
| What | Where |
|---|---|
/proc/self, /proc/thread-self | self.c:11-28, thread_self.c:11-25 |
/proc/mounts, /proc/net | root.c:383, proc_net.c:423 |
| magic links: check and jump | base.c:1787, base.c:1800-1813 |
| procfs ptrace callers | base.c:818-826, base.c:855, base.c:984, fd.c:94, namespaces.c:63 |
hidepid | base.c:728-742 |
| owner of procfs inodes | base.c:1872-1897, base.c:1953 |
__ptrace_may_access | ptrace.c:325-327, ptrace.c:371 |
PID_MAX_LIMIT | threads.h:34-35 |
| class, subsystem, device and dev links | core.c:3510-3522, core.c:3580-3589, core.c:3327-3332 |
| bus and block links | bus.c:583, genhd.c:507, genhd.c:1011 |
| kernfs link text | symlink.c:67, symlink.c:87 |
apparmor_ptrace_access_check | lsm.c:128-141 |
apparmor_file_open, owner condition | lsm.c:465-500, lsm.c:491-496 |
d_namespace_path, the /proc/sys special case | path.c:89-128, path.c:105-110 |
parser: filter_slashes | parser_regex.c:61, parser_regex.c:659 |
| tools: globs, proposals, matching | aa.py:2547-2552, aa.py:2378-2408, aare.py:49, common.py:230-259, test-aare.py:239 |
Roads from here
FILE ACCESS
- Globbing (AARE) — one star against two stars in device paths
PREAMBLE AND REUSE
- Variables — how variables like PROC and pid expand
- Built-in variables — the variables the parser defines itself
QUALIFIERS
- The owner qualifier — the owner qualifier
RULE CLASSES
- Ptrace rules — the second check behind per-process files
IN PRACTICE · general-purpose apps
- Choosing abstractions — the /proc and /sys rules base already grants
IN PRACTICE · security-sensitive programs
- Symlinks: rules see through them — why the resolved path is the one that is matched
- Profiles for security-sensitive programs — where exact /proc and /sys rules matter most
SECURITY · threat model and limits
- The limits of name-based mediation — the limits of deciding by name
RUNNING THE PARSER
- Reading a denial — reading the name field
TOOLS · utils/
- aa-logprof — what the tool proposes for /proc paths