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

Part of journeys

01 demo looks inside its worker

PTRACE RULES demo worker label demo//worker reads the worker's state, for example through /proc/<pid>/ ptrace access check: read gdb profile debugger PTRACE_ATTACH ptrace access check: trace a different permission: trace ptrace (read) peer=demo//worker, line 19 of demo's profile look, do not control whose process
demo reads the state of its worker, labelled demo//worker, for example through /proc; the access passes the kernel's ptrace access check with the read mode. A debugger attaching with PTRACE_ATTACH passes the same check with the trace mode. Line 19 of demo's profile is ptrace (read) peer=demo//worker: look, do not control, and whose process.

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_check and ptrace_traceme (lsm.c:128-164, registered at lsm.c:1786-1787).
  • read is requested when the kernel's check carries PTRACE_MODE_READ; trace for every other mode and for PTRACE_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/mask contains read trace (apparmorfs.c:2586-2589).
  • gdb under a profile debugger is invented for the map, like demo and its worker.
  • Kernel statements are read from the kernel source and were not run.

02 ptrace, a permission, a peer

GRAMMAR QUALIFIERS ptrace PERMISSIONS peer=LABEL , trace read tracedby readby r = read w = write = trace rw = both none for tracedby, readby ptrace, all four, any peer ptrace (read) peer=demo//worker, ptrace (readby, tracedby) peer=debugger, several permissions need parentheses; peer is a plain label: no parentheses ptrace (read) peer=@{profile_name}, the profile's own name
A syntax diagram: optional qualifiers, the word ptrace, optional permissions, optional peer=LABEL, a comma. The four permissions trace, read, tracedby and readby. Four example rules: a bare ptrace rule, demo's line 19, a rule with two permissions in parentheses, and a rule with the profile's own name as peer. r is read, w and write are trace.

[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

  • peer may be written once, and only = is accepted (ptrace.cc:40-51).
  • Qualifiers: audit, deny, allow, prompt and priority= are taken (audit deny ptrace readby peer=/sbin/init, in ok_22.sd). owner is 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

03 Two things you do, two things done to you

PERMISSIONS demo profile demo the peer read demo looks at the peer trace demo controls the peer: attach, PTRACE_TRACEME by its child readby the peer looks at demo tracedby the peer controls demo all four are written in demo's profile; peer= always names the other task ptrace (read) peer=demo//worker, ptrace (tracedby) peer=debugger,
demo on the left under the profile demo, the peer on the right. read: demo looks at the peer. trace: demo controls the peer. readby: the peer looks at demo. tracedby: the peer controls demo. All four are written in demo's profile, and peer always names the other task.

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 is trace (lsm.c:147-164).
  • Requests are single permissions, so a log record names one of read, trace, readby, tracedby (task.c:217-230).
  • readby and tracedby are the tracer's read and trace as 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

ONE ATTACH, TWO CHECKS ptrace(PTRACE_ATTACH, demo_pid) gdb profile debugger demo the kernel profile debugger trace toward demo? yes ptrace (trace) peer=demo, in the debugger's profile profile demo tracedby toward debugger? no -1 EACCES ptrace (tracedby) peer=debugger, the rule demo's profile needs abstractions/base ptrace (readby), ptrace (tracedby), ptrace (read) peer=@{profile_name}, the tracee side is already open to any peer to refuse debuggers a profile needs a deny rule
gdb under the profile debugger attaches to demo. The kernel asks the profile debugger for trace toward demo: yes. It asks the profile demo for tracedby toward debugger: no, and the attach fails with EACCES. demo's profile needs ptrace (tracedby) peer=debugger. abstractions/base already grants readby and tracedby for any peer and read for the profile's own name.

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_ptrace checks every profile of the tracer's label with the request, and every profile of the tracee's label with the request shifted to the ...by form (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), and ptrace (read) peer=@{profile_name}, (base:134-142). The comments there name the override: deny ptrace (readby) ... and deny 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.

05 Where the cross-check stops for security researchers

ATTACK SURFACE gdb unconfined PTRACE_ATTACH demo tracee side skipped: the tracer is unconfined demo's tracedby rules are not consulted signals: an unconfined sender is still checked against the receiver's profile a profile feature set without ptrace no ptrace rules in the policy same label: allowed other label: capability sys_ptrace demo being traced exec demo-helper (Px) may the tracer trace the new label? no info="ptrace prevents transition" read from the kernel source; not run
Three cases. An unconfined gdb attaches to demo: the tracee side is skipped because the tracer is unconfined, unlike signals, where an unconfined sender is still checked against the receiver's profile. A profile compiled for a feature set without ptrace: the same label is allowed, another label needs the capability sys_ptrace. A traced demo executes its helper with a profile transition: if the tracer may not trace the new label the transition is refused with the info ptrace prevents transition.

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_perm returns 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 to aa_capable(..., CAP_SYS_PTRACE, ...) with an audit of the result (task.c:282-304).
  • The transition check before an exec or a change_profile of a traced task, with info="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/base grants readby and tracedby to any peer. In profiles that include it, the tracer's profile is the only gate between two confined tasks unless the tracee adds a deny.
  • 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_scope and the kernel's credential checks are separate and still apply.
  • All of this is read from the kernel source and was not run.

06 What the tracer and the log see

THE DENIAL gdb demo ptrace(PTRACE_ATTACH, ...) = -1 EACCES apparmor="DENIED" operation="ptrace" profile="demo" pid=22465 comm="gdb" requested_mask="tracedby" denied_mask="tracedby" peer="debugger" trace read the tracer's profilethe tracer's profile tracedby readby the tracee's profilethe tracee's profile demo's profile refused to be traced: ptrace (tracedby) peer=debugger, the mask tells you which profile to edit and which word to add trace is a lot of power over the peer
gdb's attach to demo is cut and returns EACCES. The log record has profile demo, requested and denied mask tracedby and peer debugger: demo's profile refused to be traced, and the rule to add there is ptrace (tracedby) peer=debugger. trace and read point at the tracer's profile, tracedby and readby at the tracee's profile.

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_mask and denied_mask with one of read, trace, readby, tracedby, and peer= (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.
  • pid and comm are 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). Hence comm="gdb" next to profile="demo".
  • In complain mode the record says ALLOWED. A plain deny 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

IN THE PARSER ptrace (read) peer=demo//worker, label class (\x10|) ptrace 9 \x09 peer pattern demo//worker 0x4 read no peer: [^\000]+ with \x10: the path the kernel's ptrace check walks without it: what "does this profile mediate ptrace?" finds trace 0x2 << 2 tracedby 0x8 read 0x4 << 2 readby 0x10 PTRACE_PERM_SHIFT aa_may_ptrace() tracer profiles: profile_tracer_perm(request) tracee profiles: profile_tracee_perm(request << 2) aa_profile_match_label(start[AA_CLASS_LABEL], \x09, peer)
demo's line 19 compiles to an optional label class byte \x10, the ptrace byte \x09 and the peer pattern demo//worker, with permission 0x4 for read. With \x10 it is the path the kernel's ptrace check walks; without it, it is what the test for ptrace mediation finds. trace 0x2 shifted left by two is tracedby 0x8, read 0x4 shifted is readby 0x10. aa_may_ptrace asks the tracer's profiles with the request and the tracee's profiles with the shifted request.

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

for AppArmor developers for security researchers

Read more

08 Mistakes and their messages

MISTAKES ptrace readby tracedby peer=demo//worker, use (readby, tracedby) syntax error, unexpected TOK_TRACEDBY, expecting TOK_CONDID or TOK_END_OF_RULE ptrace attach peer=demo//worker, the word is trace syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE ptrace read peer=(label=demo//worker), write peer=demo//worker syntax error, unexpected TOK_CONDLISTID, expecting TOK_CONDID or TOK_END_OF_RULE capability ptrace trace, the capability is sys_ptrace, a different rule syntax error, unexpected TOK_PTRACE, expecting TOK_ID or TOK_END_OF_RULE owner ptrace, owner prefix not allowed on ptrace rules ptrace (trace) peer=demo, in the debugger's profile only parses; the attach still fails until demo's side allows tracedby
Five wrong ptrace rules with the parser's message: two permissions without parentheses; attach instead of trace; a peer group in parentheses; ptrace written as a capability; owner on a ptrace rule. A sixth rule, ptrace (trace) peer=demo in the debugger's profile only, parses, but the attach still fails until demo's side allows tracedby.

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 is AppArmor 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 for set.
  • 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 enforced is printed when the feature set has no ptrace; it needs --warn=rule-not-enforced.

09 Looking at processes, in practice

ROADS ptrace (read) peer=demo//worker, four permissions, one peer; both profiles are asked prac-sys-proc /proc of another process syn-signal the same two-sided check syn-capability sys_ptrace sec-threat-model the unconfined tracer prac-abstractions what base already grants k-exec traced tasks, transitions adm-denials reading the record
Ptrace rules in the centre with roads to prac-sys-proc, syn-signal, syn-capability, prac-abstractions, sec-threat-model, k-exec and adm-denials.

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 trace or read in the tracer's profile and tracedby or readby in the tracee's profile; either refusal is EACCES.
  • abstractions/base grants readby and tracedby for 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 peer means any peer (tree).
  • peer is a plain label pattern, written once and without parentheses (tree).

Permissions

WordDirectionChecked inKernel request that leads to it
readthis profile looks at the peerthe tracer's profilea ptrace access check with PTRACE_MODE_READ
tracethis profile controls the peerthe tracer's profileevery other mode, and PTRACE_TRACEME (the parent is the tracer)
readbythe peer looks at this profilethe tracee's profilethe tracer's read, shifted
tracedbythe peer controls this profilethe tracee's profilethe tracer's trace, shifted

What the kernel checks

TracerTraceeChecks
confinedconfinedread or trace in every profile of the tracer, and readby or tracedby in every profile of the tracee
confinedunconfinedthe tracer's profile only
a profile that does not mediate ptrace (compiled for a feature set without ptrace)anythe 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

SeatOn a ptrace rule
priority=taken
audittaken
allow, deny, prompttaken
owner, otherrefused: 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=...

MaskThe profile that refusedThe rule to add there
tracethe tracer'sptrace (trace) peer=TRACEE,
readthe tracer'sptrace (read) peer=TRACEE,
tracedbythe tracee'sptrace (tracedby) peer=TRACER,
readbythe tracee'sptrace (readby) peer=TRACER,

profile= names the profile that refused and peer= the label of the other task.

Errors and warnings

LineMessage
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

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/base grants readby and tracedby to 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_scope and 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 outside security/apparmor and was not read.

Roads from here

START HERE

RULE CLASSES

PROFILE STRUCTURE

  • Child profiles — demo//worker and other child profile names as peers

IN PRACTICE · general-purpose apps

IN PRACTICE · security-sensitive programs

SECURITY · threat model and limits

RUNNING THE PARSER

IN THE KERNEL