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

Part of journeys

01 demo stops its worker

SIGNAL RULES demo worker label demo//worker kill(worker_pid, SIGTERM) term signal (send) set=(term, hup) peer=demo//worker, line 18 of demo's profile direction which signals to whom sshd kill not in the rule
demo calls kill with SIGTERM on its worker, whose label is demo//worker. Line 18 of demo's profile is a signal rule with the direction send, the set term and hup, and the peer demo//worker. A kill signal aimed at sshd is not in the rule and is cut.

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 is apparmor_task_kill (lsm.c:1023-1049, registered at lsm.c:1872).
  • The feature file /sys/kernel/security/apparmor/features/signal/mask lists 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 kill capability) 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.

02 signal, direction, set, peer

GRAMMAR QUALIFIERS signal send | receive send = write = w receive = read = r rw = both set=SIGNALS peer=LABEL , signal, send and receive, every signal, every peer signal (send) set=(term, hup) peer=demo//worker, signal (receive) peer=unconfined, no set: every signal signal send set=usr1, no peer: any peer signal peer=@{profile_name}, the profile's own name peer is a plain label here: no parentheses
A syntax diagram: optional qualifiers, the word signal, optional send or receive, optional set=SIGNALS, optional peer=LABEL, a comma. Five example rules: a bare signal rule, demo's line 18, a receive rule for unconfined peers, a send rule for usr1, and a rule with the profile's own name as peer. Send is also write or w, receive is also read or r.

[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

  • set may be repeated and the sets add up: signal send set=stp set=tstp, is accepted by the parser built from the tree. peer may be written once. Only = is accepted.
  • Qualifiers: audit, deny, allow, prompt and priority= are taken. owner is 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/base on the slide: base:145-151.

for AppArmor developers for security researchers

In the code

03 Signal names, exists and the real-time range

SIGNAL NAMES SIGTERMterm SIGHUPhup SIGUSR1usr1 lower case, no SIG kill(pid, 0)is it alive? exists SIGTSTPtstp orstp the log says signal=stp rtmin+0rtmin+1rtmin+3...rtmin+32 3233343564 rtmin+N counts from the kernel's 32 rtmin+2 kept by the C library usually your first real-time signal 35 names and rtmin+0 .. rtmin+32; the list is in the reference
SIGTERM is written term, SIGHUP hup and SIGUSR1 usr1. kill with signal 0 is written exists. SIGTSTP is tstp or stp. On a number line from 32 to 64, rtmin+0 is signal 32 and rtmin+2 is signal 34, which is usually a program's first real-time signal because the C library keeps the first two.

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. stp and tstp are one signal, and so are io and poll.
  • A rule without set matches every signal, including exists.
  • 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+0 to rtmin+32 (signal.cc:129-134; test file rtsig_01.sd).
  • The kernel maps the signal number: above SIGRTMAX it is unknown, from SIGRTMIN (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 lost and unused, for which the parser has no names. The log name for SIGTSTP is stp (sig_names.h:79).
  • "Usually rtmin+2": C libraries reserve the first real-time signals for themselves, so the SIGRTMIN a program sees is higher than the kernel's.
  • Known discrepancy: set=rtmin+ is accepted as rtmin+0 and set=rtmin+5x as rtmin+5 (signal.cc:129-134).
  • Kernel statements are read from the kernel source and were not run.

Read more

04 Both profiles are asked

ONE SIGNAL, TWO CHECKS demo kill(worker_pid,SIGTERM) worker demo//worker signal (send) set=(term, hup) peer=demo//worker, in demo's profile the kernel profile demo send term to demo//worker? yes profile demo//worker receive term from demo? no kill() = -1 EACCES signal (receive) set=(term, hup) peer=demo, the rule the worker's profile needs with both rules both answers are yes, and term is delivered in demo's full example the worker's profile says all, which covers it
demo calls kill with SIGTERM on its worker. The kernel asks the profile demo for send term to demo//worker: yes. It asks the profile demo//worker for receive term from demo: no, and kill fails with EACCES. The worker's profile needs a signal receive rule with the same set and peer=demo. With both rules the signal is delivered.

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.

05 When one side is unconfined

UNCONFINED demo a shell unconfined term the shell: unconfinednothing to ask demo's profile: send?needs a rule signal (send) set=term peer=unconfined, systemd unconfined demo term systemd: unconfinednothing to ask demo's profile: receive?needs a rule abstractions/base signal (receive) peer=unconfined, signal peer=@{profile_name}, signal (receive, send) set=("exists"), a profile may signal itself is it alive? without the first line the service manager could not stop a confined service
Two cases. demo sends term to an unconfined shell: demo's profile needs a send rule with peer=unconfined, and the shell has no profile to ask. Unconfined systemd sends term to demo: the sender has no profile to ask, but demo's profile needs a receive rule for unconfined. abstractions/base contains that rule, a rule for the profile's own name and a rule for the exists signal.

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_perm returns 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=unconfined is 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 signal has 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 warning signal rules not enforced is off by default.
  • kill(pid, 0) is mediated as exists, so a confined task without that permission cannot probe for processes by signal. The base abstraction grants exists in 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

THE DENIAL demo worker kill() = -1 EACCES apparmor="DENIED" operation="signal" profile="demo" pid=2531 comm="demo" requested_mask="send" denied_mask="send" signal=term peer="demo//worker" demo's profile lacks the send rule: signal (send) set=term peer=demo//worker, apparmor="DENIED" operation="signal" profile="demo//worker" pid=2531 comm="demo" requested_mask="receive" denied_mask="receive" signal=term peer="demo" the worker's profile lacks the receive rule: signal (receive) set=term peer=demo, signal= uses the rule's names; real-time signals read signal=rtmin+N
demo's term signal to its worker is cut and kill returns EACCES. A first log record has profile demo and denied_mask send: demo's profile lacks the send rule. A second record has profile demo//worker and denied_mask receive: the worker's profile lacks the receive rule. The signal field uses the names written in rules.

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_mask and denied_mask (send or receive), signal=NAME or signal=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 fixtures pid and comm are 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 plain deny 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

IN THE PARSER signal (send) set=(term, hup) peer=demo//worker, class 10 \x0a hup = 1, term = 15 [\x01\x0f] peer pattern demo//worker 0x2 send signal receive, (\x10\xa|\x0a.)[^\000]+ 0x4 no set: any signal byte, and a second alternative under the label class SIGTERM 15 -> 15 SIGRTMIN+2 (34) -> 128+2 kill(pid, 0) -> 35 exists the kernel profile_signal_perm() start[10] -> aa_dfa_next(signal byte) -> aa_label_match(peer) -> aa_check_perms(send | receive) send is the write bit, receive is the read bit
demo's line 18 compiles to the class byte \x0a, a character class with the bytes 01 for hup and 0f for term, and the peer pattern demo//worker, with permission 0x2 for send. A rule without a set has any signal byte and a second alternative under the label class. The kernel maps SIGTERM to 15, real-time signal 34 to 128 plus 2 and signal 0 to 35, then profile_signal_perm walks the class, the signal byte and the peer label and checks send or receive.

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//worker with 0x2 was printed by the parser built from the tree with -D rule-exprs for demo's line 18; (\x10\xa|\x0a.)[^\000]+ with 0x4 for signal 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. exists is 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). audit uses the same bits as the audit mask (signal.cc:339-344).
  • Bits: send 0x2, receive 0x4 (signal.h:29-31), shared with the short forms w and r of every IPC class (parser_misc.c:763-772).
  • The class marker \d10 is 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_labels in aa_may_signal (ipc.c:102-116).
  • Not determined: why the form without a peer also emits the \x10\x0a alternative. 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

MISTAKES signal send set=sigterm, write set=term unknown signal "sigterm" signal send set=TERM,signal send set=9, unknown signal "TERM"unknown signal "9" signal send set=hup,int, use set=(hup, int) unknown signal "hup,int" signal send peer=(label=demo//worker), write peer=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 not caught by the parser: the missing rule in the other profile
Six wrong signal rules with the parser's message: sigterm, TERM and 9 are unknown signals; hup,int without parentheses is one unknown signal; a peer group in parentheses is a syntax error; the in operator is refused; owner is not allowed on signal rules.

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 is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.
  • invalid signal rule conditional "%s" (signal.cc:180). Names are case sensitive: Set is 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}, gives unknown signal "@{sigs}": variables are not expanded in signal names.
  • peer=/bin/bash /bin/dash fails (bad_04.sd).
  • The warning signal rules not enforced (signal.cc:285) is printed when the feature set has no signal; it needs --warn=rule-not-enforced.

09 The same check, next door

ROADS signal (send) set=(term, hup) peer=demo//worker, direction, signal set, peer; both profiles are asked syn-ptrace both sides, for tracing syn-unix both ends of a socket prac-abstractions the rules from base syn-child-profiles names like demo//worker k-labels matching a peer adm-denials reading the record syn-rule-conditionals set= and the plain peer
Signal rules in the centre with roads to syn-ptrace, syn-unix, prac-abstractions, syn-child-profiles, k-labels, adm-denials and syn-rule-conditionals.

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 send in the sender's profile and receive in the target's profile; either refusal is EACCES.
  • 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 set means every signal, exists included. No peer means any peer (tree).
  • set may be repeated and the sets add up; peer is written once and without parentheses (tree).

Signal names

NameSignalInternal number
hupSIGHUP1
intSIGINT2
quitSIGQUIT3
illSIGILL4
trapSIGTRAP5
abrtSIGABRT6
busSIGBUS7
fpeSIGFPE8
killSIGKILL9
usr1SIGUSR110
segvSIGSEGV11
usr2SIGUSR212
pipeSIGPIPE13
alrmSIGALRM14
termSIGTERM15
stkfltSIGSTKFLT16
chldSIGCHLD17
contSIGCONT18
stopSIGSTOP19
stp, tstpSIGTSTP20
ttinSIGTTIN21
ttouSIGTTOU22
urgSIGURG23
xcpuSIGXCPU24
xfszSIGXFSZ25
vtalrmSIGVTALRM26
profSIGPROF27
winchSIGWINCH28
io, pollSIGIO, SIGPOLL29
pwrSIGPWR30
sysSIGSYS31
emtSIGEMT32
existssignal 0, the existence test of kill(pid, 0)35
rtmin+0 to rtmin+32real-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

SenderTargetChecks
confinedconfinedsend in every profile of the sender toward the target's label, and receive in every profile of the target toward the sender's label
confinedunconfinedsend in the sender's profile with a peer that matches unconfined
unconfinedconfinedreceive in the target's profile with a peer that matches unconfined
a profile compiled without signal rules for a feature set that lacks signalanynone for that profile (by the code)

A peer in another namespace is matched as :ns:name. A refusal is EACCES.

Qualifiers

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

FieldMeaning
profilethe profile that refused
requested_mask, denied_masksend (the sender's profile refused) or receive (the target's profile refused)
signalthe name as written in rules; rtmin+N for real-time signals; stp for SIGTSTP
peerthe label of the other task

Errors and warnings

LineMessage
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 set the signal byte is .; the form printed for signal receive, is (\x10\xa|\x0a.)[^\000]+, with a second alternative under the label class (tree).
  • Bits: send 0x2, receive 0x4 (signal.h:29-31). Class marker \d10 at 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 as rtmin+0, and set=rtmin+5x as rtmin+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

ATTACHMENT, NAMESPACES, STACKING

PREAMBLE AND REUSE

RULE CLASSES

PROFILE STRUCTURE

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

IN PRACTICE · general-purpose apps

RUNNING THE PARSER

IN THE KERNEL