Signal rules
sending signals for application developers for administrators for security researchers
A signal rule allows sending signals to or receiving signals from tasks whose label matches peer and can be limited to a set of signals. The kernel asks the sender's profile for send and the target's profile for receive on every signal. A refusal is EACCES and a record with the signal name and the peer.
On the map: rule classes
▶ Watch this deck — 9 scenes, ~6 min
Worth seeing first
- Rule conditionals — the set= and peer= conditional syntax
- Child profiles — the child profile name used as the worker's peer label
Part of journeys
- Network, IPC and privileges, step 8 of 14 · previous: D-Bus rules · next: Ptrace rules
01 demo stops its worker
signal (send) set=(term, hup) peer=demo//worker, lets a profile send two signals to tasks with one label.
Demo starts workers, and now and then it has to stop one, with a term signal. Under a profile, that's something demo needs permission for, and the permission is specific: which direction, which signals, and whose process. Line eighteen says demo may send term and hup to tasks labelled demo//worker, its child profile. A kill aimed at anything else isn't covered, and neither is any other signal aimed at the worker. That's all a signal rule is: direction, signal set, peer.
Details and sources
Details
- LSM hook
task_kill; AppArmor's function isapparmor_task_kill(lsm.c:1023-1049, registered at lsm.c:1872). - The feature file
/sys/kernel/security/apparmor/features/signal/masklists the signal names the kernel knows (apparmorfs.c:2591-2594). - The kernel's own rules for who may signal whom (the same user, or the
killcapability) still apply first.capability kill,is a separate rule: see capability rules. - The program
demo, its worker and their profiles are invented for the map. - Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), Signal rules.
- apparmor.net: Profiles quick reference, signal rules.
- Child profiles: where the label
demo//workercomes from.
02 signal, direction, set, peer
[QUALIFIERS] signal [send|receive|(send, receive)] [set=SIG|set=(SIG ...)] [peer=LABEL],. Each part left out matches everything.
The grammar is small. After the keyword comes the direction: send or receive, or both in parentheses, or nothing, which also means both. Then set=, with one signal or a list. Then peer=, with a label. Leave any of them out and that part matches everything, so signal, on its own allows all signalling in both directions. The label is a pattern. A handy value is the profile's own name, for a program that signals its own children. And note that the peer here is the plain kind, without parentheses.
Details and sources
Details
setmay be repeated and the sets add up:signal send set=stp set=tstp,is accepted by the parser built from the tree.peermay be written once. Only=is accepted.- Qualifiers:
audit,deny,allow,promptandpriority=are taken.owneris refused:owner prefix not allowed on signal rules(signal.h:51-57). - The peer goes through variable expansion (signal.cc:249-252); the signal names do not.
- Rules with the same permissions, peer and signal set are merged.
- The lines from
abstractions/baseon the slide: base:145-151.
for AppArmor developers for security researchers
In the code
- The scanner state
SIGNAL_MODE(parser_lex.l:658-695, parser_lex.l:884-885). - The productions: parser_yacc.y:1434-1470. The conditionals and the constructor: signal.cc:166-200.
03 Signal names, exists and the real-time range
Names are lower case without SIG. exists is signal 0. rtmin+N (0 to 32) counts from the kernel's SIGRTMIN (32), not the C library's.
Signals are named the way the kill command names them: lower case, without the SIG prefix. Term, hup, usr1. One name isn't a real signal: exists. That's signal zero, what a program sends just to find out whether a process is alive, and it needs permission like any other. The terminal stop signal can be written tstp or stp, and the kernel's log says stp. Real-time signals are rtmin+N, counted from the kernel's base of thirty-two. The C library keeps the first ones for itself, so your program's first real-time signal is usually rtmin+2 in a profile.
Details and sources
Details
- The names (signal.cc:42-78):
hup int quit ill trap abrt bus fpe kill usr1 segv usr2 pipe alrm term stkflt chld cont stop stp tstp ttin ttou urg xcpu xfsz vtalrm prof winch io poll pwr sys emt exists.stpandtstpare one signal, and so areioandpoll. - A rule without
setmatches every signal, includingexists. - Refused by the parser built from the tree with
unknown signal "...":sigterm,TERM,HUP,9,rtmax,cld,iot,lost,rtmin+33. - Real-time signals:
rtmin+0tortmin+32(signal.cc:129-134; test file rtsig_01.sd). - The kernel maps the signal number: above
SIGRTMAXit is unknown, fromSIGRTMIN(32 in the kernel) it is 128 plus the offset, otherwise it comes from a table (ipc.c:21-30, sig_names.h:8-55). Signal 0, the existence test, is in that table (sig_names.h:9). - The kernel's table also has
lostandunused, for which the parser has no names. The log name for SIGTSTP isstp(sig_names.h:79). - "Usually
rtmin+2": C libraries reserve the first real-time signals for themselves, so theSIGRTMINa program sees is higher than the kernel's. - Known discrepancy:
set=rtmin+is accepted asrtmin+0andset=rtmin+5xasrtmin+5(signal.cc:129-134). - Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), Signal rules.
- The full table is in the reference below.
04 Both profiles are asked
A signal needs send in the sender's profile and receive in the target's profile. Either refusal gives EACCES.
Here's what catches everyone the first time. You write the send rule in demo's profile, it looks right, and the kill still fails. The kernel asks two profiles. First the sender's: may you send term to that label? Then the target's: may you receive term from this sender? If either says no, the signal isn't delivered and kill returns EACCES. So the worker's profile needs the mirror image: signal receive, the same set, and peer=demo. In demo's full example the worker's profile just says all, which covers it.
Details and sources
Details
- The cross-check: each profile of the sender's label is asked for write (send) toward the target's label, and each profile of the target's label for read (receive) toward the sender's label (
aa_may_signal, ipc.c:102-116;profile_signal_perm, ipc.c:87-99). - A refusal is
-EACCES(lib.c:440). - With stacked labels every profile on each side is asked. The peer is matched as a whole compound label first and then component by component (label.c:1443-1456). A peer in another namespace is matched as
:ns:name(label.c:1301-1309). - Real records for both sides: testcase_signal_01.in (
requested_mask="send") and testcase_signal_02.in (requested_mask="receive"). - In the map's example profile the worker is
profile worker { all, }. This slide imagines a stricter worker. - Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), Signal rules.
- Ptrace rules and unix socket rules: the same two-sided check.
- Stacking, namespaces.
05 When one side is unconfined
An unconfined target is not consulted. An unconfined sender is not consulted, but the target's profile still needs signal (receive) peer=unconfined,; abstractions/base has it.
What if one side has no profile? An unconfined target is easy. There's nothing to ask on that side, so only the sender's rule counts, with peer=unconfined. The other way round is the one to remember. An unconfined sender isn't checked itself, but the target's profile still is. So when the service manager sends term to demo, demo's profile has to allow receiving from unconfined. That rule is in the base abstraction, together with one that lets a profile signal itself. That's why you rarely write it by hand.
Details and sources
Details
profile_signal_permreturns 0 for an unconfined profile and for a profile that does not mediate the signal class (ipc.c:87-97). The receive check has no exception for an unconfined sender (ipc.c:114-115).- The three lines of
abstractions/base, with their comments (base:143-151): "Allow unconfined processes to send us signals by default", "Allow us to signal ourselves", "Checking for PID existence is quite common so add it by default for now". peer=unconfinedis a label pattern like any other.- Kernel statements are read from the kernel source and were not run.
for security researchers
Attack surface
- The receive side protects a confined task from confined senders, and from unconfined ones only as far as its profile omits
peer=unconfined. The base abstraction grants it. - By the code, a profile compiled for a feature set without
signalhas no signal rules at all and the class is not mediated: both checks return 0 for it (ipc.c:93-95). This is derived, not run. The parser's warningsignal rules not enforcedis off by default. kill(pid, 0)is mediated asexists, so a confined task without that permission cannot probe for processes by signal. The base abstraction grantsexistsin both directions to every peer.- The check is by label, not by pid, uid or binary: any task that can obtain the peer label is a valid peer.
06 What demo and the log see
operation="signal" requested_mask="send"|"receive" denied_mask=... signal=NAME peer="LABEL"; profile= is the side that refused.
From demo's side both failures look the same: kill returns EACCES. The log tells them apart. Read three fields. Profile is the side that refused. The mask says send or receive. And peer is the other party. If the profile is demo and the mask is send, demo's rule is missing. If the profile is the worker's and the mask is receive, it's the worker's profile you need to edit. The signal field uses the same names you write in a rule, so the record almost is the rule.
Details and sources
Details
- Fields:
requested_maskanddenied_mask(sendorreceive),signal=NAMEorsignal=rtmin+N,peer=(ipc.c:52-76). - Both records on the slide are built, not observed. Their layout is that of testcase_signal_01.in and testcase_signal_02.in (
operation="signal" profile=... pid=2531 comm=... requested_mask=... denied_mask=... signal=term peer=...), with demo's names. In both fixturespidandcommare the sender's. - SIGTSTP is logged as
signal=stp(sig_names.h:79). - In complain mode the signal is delivered and the record says
ALLOWED. A plaindeny signal ...rule refuses without a record. - Known discrepancy (by reading the code): for a signal number without a mapping the field is written
signal=unknown(N)without a leading blank, glued to the previous field (ipc.c:66). - Kernel statements are read from the kernel source and were not run.
07 Class byte, signal byte, peer label for AppArmor developers for security researchers
signal.cc:288-351 emits \x0a[signals]peer; ipc.c:87-99 walks class, signal byte, label.
gen_policy_re writes one rule: the class byte ten, a character class with one byte per signal in the set, then the peer, converted from its pattern. Without a set it writes any byte, plus a second alternative under the label class that the kernel's signal path doesn't walk. The kernel maps the signal number to the same internal byte, with real-time signals at 128+N. Then profile_signal_perm starts at the class, steps over the signal byte, matches the peer label and checks one bit: write for send, read for receive.
Details and sources
for AppArmor developers for security researchers
Details
\x0a[\x01\x0f]demo//workerwith0x2was printed by the parser built from the tree with-D rule-exprsfor demo's line 18;(\x10\xa|\x0a.)[^\000]+with0x4forsignal receive,.- Internal numbers are 1 to 35 and 128+N for real-time signals (signal.cc:37-39);
find_signal_mapping: signal.cc:127-144.existsis 35 in the parser, and the kernel maps signal 0 to the same value (sig_names.h:9). - The rule is emitted by
gen_policy_re(signal.cc:288-351).audituses the same bits as the audit mask (signal.cc:339-344). - Bits: send
0x2, receive0x4(signal.h:29-31), shared with the short formswandrof every IPC class (parser_misc.c:763-772). - The class marker
\d10is added at priority 1001 (parser_regex.c:1409-1411). - The rule is dropped when the feature set lacks
signal(signal.cc:300-303, parser_main.c:1087-1089). - Kernel:
map_signal_num(ipc.c:21-30),profile_signal_perm(ipc.c:87-99),xcheck_labelsinaa_may_signal(ipc.c:102-116). - Not determined: why the form without a peer also emits the
\x10\x0aalternative. The only reader of the label class start in the kernel is the ptrace path. - 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
Lower-case names without SIG, lists in parentheses, peer=LABEL without parentheses. The parser cannot see a missing rule in the peer's profile.
The parser knows signals only by their short lower-case names: no SIG prefix, no capitals, no numbers. Two signals need the list form, with parentheses. The peer is a plain label, so the parenthesised group you know from unix rules is a syntax error here. Equals is the only operator. And there's no owner for signals. One mistake the parser can't catch for you is the one from a moment ago: the missing rule in the other profile.
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. invalid signal rule conditional "%s"(signal.cc:180). Names are case sensitive:Setis refused.signal conditional "peer" can only be specified once(parser_misc.c:1244).perms contains invalid permission for signals(signal.cc:192).signal set=@{sigs},givesunknown signal "@{sigs}": variables are not expanded in signal names.peer=/bin/bash /bin/dashfails (bad_04.sd).- The warning
signal rules not enforced(signal.cc:285) is printed when the feature set has nosignal; it needs--warn=rule-not-enforced.
Read more
09 The same check, next door
Both profiles are asked: the same holds for ptrace and unix rules.
Signal rules are the smallest example of an idea you'll meet again: the kernel asks both profiles. Ptrace rules do the same for tracing, and unix rules for connections. The base abstraction already gives every profile a few signal rules, so look there before adding your own. Names like demo//worker come from child profiles. And if peer labels raised questions, the labels deck is where they're answered.
Details and sources
Details
- A signal needs
sendin the sender's profile andreceivein the target's profile; either refusal isEACCES. - An unconfined side is not asked; the confined side still is.
- 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
SIGNAL RULE: [QUALIFIERS] signal [PERMISSIONS] [set=SIGNAL | set=( SIGNAL ... )] ... [peer=LABEL] ,
PERMISSIONS: send | receive | ( send [,] receive )
write and w are send; read and r are receive; rw is both
SIGNAL: a name from the table below | rtmin+N (N from 0 to 32)
- No permission means both. No
setmeans every signal,existsincluded. Nopeermeans any peer (tree). setmay be repeated and the sets add up;peeris written once and without parentheses (tree).
Signal names
| Name | Signal | Internal number |
|---|---|---|
hup | SIGHUP | 1 |
int | SIGINT | 2 |
quit | SIGQUIT | 3 |
ill | SIGILL | 4 |
trap | SIGTRAP | 5 |
abrt | SIGABRT | 6 |
bus | SIGBUS | 7 |
fpe | SIGFPE | 8 |
kill | SIGKILL | 9 |
usr1 | SIGUSR1 | 10 |
segv | SIGSEGV | 11 |
usr2 | SIGUSR2 | 12 |
pipe | SIGPIPE | 13 |
alrm | SIGALRM | 14 |
term | SIGTERM | 15 |
stkflt | SIGSTKFLT | 16 |
chld | SIGCHLD | 17 |
cont | SIGCONT | 18 |
stop | SIGSTOP | 19 |
stp, tstp | SIGTSTP | 20 |
ttin | SIGTTIN | 21 |
ttou | SIGTTOU | 22 |
urg | SIGURG | 23 |
xcpu | SIGXCPU | 24 |
xfsz | SIGXFSZ | 25 |
vtalrm | SIGVTALRM | 26 |
prof | SIGPROF | 27 |
winch | SIGWINCH | 28 |
io, poll | SIGIO, SIGPOLL | 29 |
pwr | SIGPWR | 30 |
sys | SIGSYS | 31 |
emt | SIGEMT | 32 |
exists | signal 0, the existence test of kill(pid, 0) | 35 |
rtmin+0 to rtmin+32 | real-time signals, counted from the kernel's SIGRTMIN (32) | 128 to 160 |
The internal numbers are the parser's (signal.cc:42-78); they are not the signal numbers of any architecture.
What the kernel checks
| Sender | Target | Checks |
|---|---|---|
| confined | confined | send in every profile of the sender toward the target's label, and receive in every profile of the target toward the sender's label |
| confined | unconfined | send in the sender's profile with a peer that matches unconfined |
| unconfined | confined | receive in the target's profile with a peer that matches unconfined |
a profile compiled without signal rules for a feature set that lacks signal | any | none for that profile (by the code) |
A peer in another namespace is matched as :ns:name. A refusal is EACCES.
Qualifiers
| Seat | On a signal rule |
|---|---|
priority= | taken |
audit | taken |
allow, deny, prompt | taken |
owner, other | refused: owner prefix not allowed on signal rules |
The rules in abstractions/base
# Allow unconfined processes to send us signals by default
signal (receive) peer=unconfined,
# Allow us to signal ourselves
signal peer=@{profile_name},
# Checking for PID existence is quite common so add it by default for now
signal (receive, send) set=("exists"),
Source: base:143-151.
The log record
apparmor="DENIED" operation="signal" profile=... pid=... comm=... requested_mask="send" denied_mask="send" signal=term peer=...
| Field | Meaning |
|---|---|
profile | the profile that refused |
requested_mask, denied_mask | send (the sender's profile refused) or receive (the target's profile refused) |
signal | the name as written in rules; rtmin+N for real-time signals; stp for SIGTSTP |
peer | the label of the other task |
Errors and warnings
| Line | Message |
|---|---|
signal send set=sigterm, | unknown signal "sigterm" |
signal send set=TERM, | unknown signal "TERM" |
signal send set=9, | unknown signal "9" |
signal send set=hup,int, | unknown signal "hup,int" |
signal send peer=(label=demo//worker), | syntax error, unexpected TOK_CONDLISTID, expecting TOK_CONDID or TOK_END_OF_RULE |
signal send set in (hup, int), | only "=" allowed in conditions of signal rules |
owner signal, | owner prefix not allowed on signal rules |
signal Set=hup, | invalid signal rule conditional "Set" |
signal peer=a peer=b, | signal conditional "peer" can only be specified once |
feature set without signal (warning, off by default) | signal rules not enforced |
for AppArmor developers for security researchers
Encoding
- One policydb rule: class byte
\x0a(10), a character class with the internal number of each signal in the set, the peer pattern (signal.cc:288-351). - Without
setthe signal byte is.; the form printed forsignal receive,is(\x10\xa|\x0a.)[^\000]+, with a second alternative under the label class (tree). - Bits: send
0x2, receive0x4(signal.h:29-31). Class marker\d10at priority 1001 (parser_regex.c:1409-1411). - Kernel:
map_signal_num(ipc.c:21-30),profile_signal_perm(ipc.c:87-99),aa_may_signal(ipc.c:102-116).
for security researchers
Known discrepancies
set=rtmin+is accepted asrtmin+0, andset=rtmin+5xasrtmin+5(tree; signal.cc:129-134).- For a signal number without a mapping the kernel writes
signal=unknown(N)without a leading blank (code; ipc.c:66). - The verdicts are in known bugs.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
ATTACHMENT, NAMESPACES, STACKING
- Profile stacking — peers with more than one profile
PREAMBLE AND REUSE
- Built-in variables — peer=@{profile_name}
- The abi rule and the abi files — the feature set that enables signal mediation
RULE CLASSES
- Ptrace rules — the other rule that both profiles must agree on
- Rule conditionals — set= lists and the plain peer
- Capability rules — the kill capability is a separate check
PROFILE STRUCTURE
- Child profiles — demo//worker and other child profile names as peers
IN PRACTICE · general-purpose apps
- Choosing abstractions — the signal rules every profile gets from abstractions/base
RUNNING THE PARSER
- Reading a denial — reading a signal denial
IN THE KERNEL
- Labels in the kernel — how a peer label is matched