Ptrace rules
tracing other tasks for application developers for administrators for security researchers
A ptrace rule allows a task to trace or read another task or to be traced or read by one limited by the other task's label. The kernel asks the tracer's profile for trace or read and the tracee's profile for tracedby or readby. An unconfined tracer is not checked against the tracee's profile.
On the map: rule classes
▶ Watch this deck — 9 scenes, ~6 min
Worth seeing first
- Signal rules — peer labels, and both profiles being asked
- Capability rules — the sys_ptrace capability that tracing also needs
Part of journeys
- Network, IPC and privileges, step 9 of 14 · previous: Signal rules · next: User namespace rules
01 demo looks inside its worker
ptrace (read) peer=demo//worker, lets a profile pass the kernel's ptrace read check for tasks with that label. Attaching as a debugger needs trace.
Demo keeps an eye on its workers, and some of what it reads about them is guarded by the same kernel check that guards a debugger: the ptrace access check. That check comes in two strengths. Read, for looking. And trace, for taking control, the way a debugger does. When the task doing it is confined, its profile needs a ptrace rule for that strength and for the label of the process it looks at. Line nineteen gives demo the read permission for tasks labelled demo//worker, and nothing more.
Details and sources
Details
- LSM hooks
ptrace_access_checkandptrace_traceme(lsm.c:128-164, registered at lsm.c:1786-1787). readis requested when the kernel's check carriesPTRACE_MODE_READ;tracefor every other mode and forPTRACE_TRACEME(lsm.c:139-141, lsm.c:158-159).- Which operations use the read mode (for example which files under
/proc/<pid>/) is decided by the rest of the kernel, not by AppArmor, and was not read for this deck. The wiki page below is the place to look. - An operation guarded this way needs the ptrace rule in addition to any file rule for the path used.
- The feature file
/sys/kernel/security/apparmor/features/ptrace/maskcontainsread trace(apparmorfs.c:2586-2589). gdbunder a profiledebuggeris invented for the map, likedemoand its worker.- Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), PTrace rules.
- apparmor.net: Profiles quick reference, ptrace rules.
- wiki: TechnicalDoc_Proc_and_ptrace.
- Kernel documentation: Yama:
ptrace_scope, a separate restriction. - /proc and /sys in practice.
02 ptrace, a permission, a peer
[QUALIFIERS] ptrace [trace|read|tracedby|readby | ( ... )] [peer=LABEL],. No permission means all four; no peer means any.
Ptrace rules are about as short as rules get. The keyword, one permission or a list in parentheses, and optionally peer=LABEL. There are four permissions: trace, read, tracedby and readby. Leave the permission out and you get all four. Leave the peer out and it's any peer. The label is a pattern, and as in signal rules the peer is the plain kind, with no parentheses. The profile's own name is a useful peer for a program that inspects its own children.
Details and sources
Details
peermay be written once, and only=is accepted (ptrace.cc:40-51).- Qualifiers:
audit,deny,allow,promptandpriority=are taken (audit deny ptrace readby peer=/sbin/init,in ok_22.sd).owneris refused:owner prefix not allowed on ptrace rules(ptrace.h:50-56). - The rules in
abstractions/base: base:134-142.
for AppArmor developers for security researchers
In the code
- Bits: trace
0x2, read0x4, tracedby0x8, readby0x10(ptrace.h:27-31). - The scanner state
PTRACE_MODE(parser_lex.l:663-695, parser_lex.l:887-888). - The productions: parser_yacc.y:1472-1513. The constructor: ptrace.cc:54-67.
03 Two things you do, two things done to you
read and trace: this profile acts on the peer. readby and tracedby: the peer acts on this profile.
Four permissions, two pairs. Read and trace are about what your program does to someone else: read to look, trace to control, which is what a debugger attaching needs. Readby and tracedby face the other way. They say who may look at your program, and who may control it. All four live in your own profile, and peer always names the other task. So a profile can say: I may read my workers. And separately: only the debugger profile may trace me.
Details and sources
Details
- When a task asks to be traced by its parent (
PTRACE_TRACEME), the parent is the tracer and the request istrace(lsm.c:147-164). - Requests are single permissions, so a log record names one of
read,trace,readby,tracedby(task.c:217-230). readbyandtracedbyare the tracer'sreadandtraceas seen from the tracee (task.h:92-96); see "Both profiles are asked".- The bits in the parser: ptrace.h:27-31.
- Kernel statements are read from the kernel source and were not run.
04 Both profiles are asked
Tracing needs trace (or read) in the tracer's profile and tracedby (or readby) in the tracee's. abstractions/base grants readby and tracedby for any peer.
As with signals, the kernel asks both sides. Say a confined debugger attaches to demo. First the debugger's profile: may you trace a task labelled demo? Then demo's profile: may you be traced by the debugger? If either says no, the attach fails with EACCES. So a debugger rule alone isn't enough when the target is confined. In practice the second half is often already there. The base abstraction allows being read and being traced by anyone, and reading tasks of your own profile. A profile that wants to refuse debuggers has to say so with a deny.
Details and sources
Details
aa_may_ptracechecks every profile of the tracer's label with the request, and every profile of the tracee's label with the request shifted to the...byform (task.c:316-329; the shift: task.h:92-96). A refusal is-EACCES(lib.c:440).- The three lines of
abstractions/base:ptrace (readby),,ptrace (tracedby),andptrace (read) peer=@{profile_name},(base:134-142). The comments there name the override:deny ptrace (readby) ...anddeny ptrace (tracedby) .... - A real record: testcase_ptrace_01.in (
requested_mask="tracedby" denied_mask="tracedby"). - An unconfined tracer is an exception to the second check; it is described for security researchers in "Where the cross-check stops" and in the reference below.
- Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), PTrace rules.
- Signal rules: the same two-sided check.
- Abstractions in practice, stacking.
05 Where the cross-check stops for security researchers
The tracee-side check is skipped for an unconfined tracer (task.c:275). Without ptrace mediation the test is "same label or sys_ptrace" (task.c:293-303). A traced task's profile transition is checked against its tracer (domain.c:50-80).
Three edges of this check that a reviewer should know. One: if the tracer is unconfined, the tracee's profile isn't consulted at all. A tracedby rule can keep confined debuggers out. It can't keep an unconfined root shell out. That's different from signals, where the receiver's profile is asked even for an unconfined sender. Two: a profile compiled for a feature set without ptrace has no ptrace rules, and the kernel falls back to an older test. Same label is fine; anything else needs the sys_ptrace capability. Three: a task that's being traced can't change profile at exec unless its tracer would be allowed to trace the new label.
Details and sources
for security researchers
Details
profile_tracee_permreturns 0 if the tracee's profile is unconfined, if the tracer's label is unconfined, or if the tracee's profile does not mediate the ptrace class (task.c:270-280).profile_tracer_perm: nothing for an unconfined profile; the rule check when the profile mediates ptrace; otherwise the same label is allowed, and any other label goes toaa_capable(..., CAP_SYS_PTRACE, ...)with an audit of the result (task.c:282-304).- The transition check before an exec or a
change_profileof a traced task, withinfo="ptrace prevents transition": domain.c:50-80. - The parser's warning for a dropped class,
ptrace rules not enforced(ptrace.cc:115, ptrace.cc:130-133), is off by default. - Kernel statements are read from the kernel source and were not run.
for security researchers
Attack surface
- The tracee-side permissions defend against confined peers only.
abstractions/basegrantsreadbyandtracedbyto any peer. In profiles that include it, the tracer's profile is the only gate between two confined tasks unless the tracee adds adeny.- On the fallback path the gate is one capability for all peers.
- The check is by label: any task that reaches the peer label is a valid tracer or tracee.
- Yama's
ptrace_scopeand the kernel's credential checks are separate and still apply. - All of this is read from the kernel source and was not run.
for security researchers
Read more
06 What the tracer and the log see
operation="ptrace" requested_mask=... denied_mask=... peer="LABEL". trace/read: the tracer's profile refused. tracedby/readby: the tracee's.
The caller sees EACCES, whichever side refused. In the log, the mask is the giveaway. Trace or read means the tracer's own profile lacks the rule. Tracedby or readby means the profile of the task being looked at refused. The profile field names that profile, and peer names the other task's label. Put the mask word and the peer into a ptrace rule in that profile and you have the fix. Whether you want to grant it is another question. Trace is a lot of power over the peer.
Details and sources
Details
- Fields:
requested_maskanddenied_maskwith one ofread,trace,readby,tracedby, andpeer=(task.c:217-250). The mask printer returns one name, and requests are single permissions (task.c:217-230). - The record on the slide is built, not observed. Its layout is that of testcase_ptrace_01.in (
apparmor="DENIED" operation="ptrace" profile=... pid=22465 comm="ptrace" requested_mask="tracedby" denied_mask="tracedby" peer=...), with demo's names. pidandcommare those of the calling task, which for an attach is the tracer: by the code, the hook runs in the tracer's context (lsm.c:128-145). Hencecomm="gdb"next toprofile="demo".- In complain mode the record says
ALLOWED. A plaindeny ptrace ...rule refuses without a record. - When a profile was compiled without ptrace mediation, a refusal is a capability denial for
sys_ptrace: see capability rules. - Kernel statements are read from the kernel source and were not run.
07 Byte 9 under the label class for AppArmor developers for security researchers
ptrace.cc:118-162 emits (\x10|)\x09peer; task.c:316-329 asks the tracer with the request and the tracee with request << 2; the match is lib.c:393-405.
The compiled form is tiny. gen_policy_re writes an optional label class byte, then byte nine for ptrace, then the peer pattern, with one permission mask. The two alternatives serve two readers. The kernel's check starts at the label class and steps over nine. The test for whether a profile mediates ptrace looks for nine at the top. The four permissions are two bits, shifted. aa_may_ptrace asks the tracer's profiles for the request as it is, and the tracee's profiles for the same request shifted left by two. That turns read into readby and trace into tracedby.
Details and sources
for AppArmor developers for security researchers
Details
(\x10|)\x09demo//workerwith0x4was printed by the parser built from the tree with-D rule-exprsfor demo's line 19. Without a peer the pattern is[^\000]+(ptrace.cc:118-162).- The class marker
\d9is added at priority 1001 (parser_regex.c:1412-1414). - The rule is dropped when the feature set lacks
ptrace(ptrace.cc:130-133). - The short forms
randwreuse the bits0x4and0x2shared by all IPC classes (parser_misc.c:763-772). - Kernel:
xcheck_labelsinaa_may_ptrace(task.c:316-329);profile_ptrace_perm(task.c:253-268);aa_profile_match_label(lib.c:393-405); the shift (task.h:92-96). - Kernel statements are read from the kernel source and were not run.
for AppArmor developers for security researchers
Read more
08 Mistakes and their messages
Lists in parentheses; trace, not attach; peer=LABEL without parentheses. A rule on one side only is valid and not sufficient.
Two permissions without parentheses stop the parser at the second word. The permission is called trace, not attach. The peer is a plain label, with no group. Ptrace isn't a capability name. The capability is sys_ptrace, and the kernel only asks for it when a profile was compiled without ptrace mediation. There's no owner. And then there's the mistake no parser can catch. You wrote the tracer's rule, it compiles, and tracing still fails, because the other profile hasn't agreed.
Details and sources
Details
- Messages are from the parser built from the AppArmor tree (
-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel). The full form isAppArmor parser error for FILE in profile FILE at line N: MESSAGE. only "=" allowed in conditions of ptrace rules(ptrace.cc:43).invalid ptrace rule conditional "%s"(ptrace.cc:48), for example forset.ptrace conditional "peer" can only be specified once.perms contains invalid permissions for ptrace(ptrace.cc:59).capability ptrace trace,is a test file that must fail: bad_05.sd.- The warning
ptrace rules not enforcedis printed when the feature set has noptrace; it needs--warn=rule-not-enforced.
09 Looking at processes, in practice
Ptrace rules work with file rules for /proc and with the peer's profile.
Ptrace rules rarely travel alone. Reading another process often goes through the proc file system, for example, where a file rule and a ptrace rule can both apply; the practice deck walks through that. Signal rules use the same two-sided check. The capability deck covers sys_ptrace. And the threat model deck puts the unconfined tracer in context.
Details and sources
Details
- Tracing needs
traceorreadin the tracer's profile andtracedbyorreadbyin the tracee's profile; either refusal isEACCES. abstractions/basegrantsreadbyandtracedbyfor any peer.- Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2) and the kernel tree named on the page. The kernel behaviour was read from the source, not observed on a running kernel.
Read more
Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the line (-Q -K --skip-kernel-load --warn=all, feature set abi/5.0), with nothing loaded into a kernel; "code" means the source was read, not run. Every statement about the kernel is read from the kernel source.
Grammar
PTRACE RULE: [QUALIFIERS] ptrace [PERMISSIONS] [peer=LABEL] ,
PERMISSIONS: PERMISSION | ( PERMISSION [,] ... )
PERMISSION: trace | read | tracedby | readby
r is read; w and write are trace; rw and wr are both
- No permission means all four. No
peermeans any peer (tree). peeris a plain label pattern, written once and without parentheses (tree).
Permissions
| Word | Direction | Checked in | Kernel request that leads to it |
|---|---|---|---|
read | this profile looks at the peer | the tracer's profile | a ptrace access check with PTRACE_MODE_READ |
trace | this profile controls the peer | the tracer's profile | every other mode, and PTRACE_TRACEME (the parent is the tracer) |
readby | the peer looks at this profile | the tracee's profile | the tracer's read, shifted |
tracedby | the peer controls this profile | the tracee's profile | the tracer's trace, shifted |
What the kernel checks
| Tracer | Tracee | Checks |
|---|---|---|
| confined | confined | read or trace in every profile of the tracer, and readby or tracedby in every profile of the tracee |
| confined | unconfined | the tracer's profile only |
a profile that does not mediate ptrace (compiled for a feature set without ptrace) | any | the same label is allowed; another label needs the capability sys_ptrace |
A refusal is EACCES. The case of an unconfined tracer is in the section for security researchers below.
Qualifiers
| Seat | On a ptrace rule |
|---|---|
priority= | taken |
audit | taken |
allow, deny, prompt | taken |
owner, other | refused: owner prefix not allowed on ptrace rules |
The rules in abstractions/base
ptrace (readby),
ptrace (tracedby),
ptrace (read) peer=@{profile_name},
Source: base:134-142. The comments there give the override: deny ptrace (readby) ... and deny ptrace (tracedby) ....
The log record
apparmor="DENIED" operation="ptrace" profile=... pid=... comm=... requested_mask="tracedby" denied_mask="tracedby" peer=...
| Mask | The profile that refused | The rule to add there |
|---|---|---|
trace | the tracer's | ptrace (trace) peer=TRACEE, |
read | the tracer's | ptrace (read) peer=TRACEE, |
tracedby | the tracee's | ptrace (tracedby) peer=TRACER, |
readby | the tracee's | ptrace (readby) peer=TRACER, |
profile= names the profile that refused and peer= the label of the other task.
Errors and warnings
| Line | Message |
|---|---|
ptrace readby tracedby peer=demo//worker, | syntax error, unexpected TOK_TRACEDBY, expecting TOK_CONDID or TOK_END_OF_RULE |
ptrace attach peer=demo//worker, | syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE |
ptrace read peer=(label=demo//worker), | syntax error, unexpected TOK_CONDLISTID, expecting TOK_CONDID or TOK_END_OF_RULE |
capability ptrace trace, | syntax error, unexpected TOK_PTRACE, expecting TOK_ID or TOK_END_OF_RULE |
owner ptrace, | owner prefix not allowed on ptrace rules |
ptrace read set=hup, | invalid ptrace rule conditional "set" |
ptrace peer=a peer=b, | ptrace conditional "peer" can only be specified once |
an operator other than = | only "=" allowed in conditions of ptrace rules |
feature set without ptrace (warning, off by default) | ptrace rules not enforced |
for AppArmor developers for security researchers
Encoding
- One policydb rule:
(\x10|)\x09and the peer pattern,[^\000]+when there is no peer (ptrace.cc:118-162).\x10is the label class (16),\x09the ptrace class (9). - Bits: trace
0x2, read0x4, tracedby0x8, readby0x10(ptrace.h:27-31). The kernel shifts the tracer's request left by two for the tracee (task.h:92-96). - Class marker
\d9at priority 1001 (parser_regex.c:1412-1414). - Kernel:
aa_may_ptrace(task.c:316-329),profile_tracer_permandprofile_tracee_perm(task.c:270-304),aa_profile_match_label(lib.c:393-405).
for security researchers
Limits
- An unconfined tracer is not checked against the tracee's profile (task.c:270-280). Tracee-side rules defend against confined peers only.
abstractions/basegrantsreadbyandtracedbyto any peer.- Without ptrace mediation the test is "same label, or the capability
sys_ptrace" (task.c:282-304). - A traced task's profile transition is checked against its tracer; a refusal carries
info="ptrace prevents transition"(domain.c:50-80). - The check is by label. Yama's
ptrace_scopeand the kernel's credential checks are separate. - Not determined: which kernel paths use the read mode of the ptrace access check (for example which files under
/proc/<pid>/). That is decided outsidesecurity/apparmorand was not read.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
RULE CLASSES
- Signal rules — the other rule that both profiles must agree on
- Capability rules — sys_ptrace and the fallback when ptrace rules are not mediated
- Rule conditionals — the plain peer conditional
PROFILE STRUCTURE
- Child profiles — demo//worker and other child profile names as peers
IN PRACTICE · general-purpose apps
- Choosing abstractions — the ptrace rules every profile gets from abstractions/base
IN PRACTICE · security-sensitive programs
- Writing rules for /sys and /proc — reading /proc of another process in practice
SECURITY · threat model and limits
- AppArmor's threat model (no slides yet) — what an unconfined tracer can do
RUNNING THE PARSER
- Reading a denial — reading a ptrace denial
IN THE KERNEL
- Exec and domain transitions — why a traced task may be refused a profile transition
- Labels in the kernel — how a peer label is matched