D-Bus rules
D-Bus messages for application developers for administrators for security researchers
A dbus rule allows sending or receiving D-Bus messages by bus path interface member and peer or owning a well-known name or eavesdropping on a bus. The parser compiles it into the profile. The kernel has no D-Bus hook. The bus daemon asks the kernel what the profile allows.
On the map: rule classes
▶ Watch this deck — 8 scenes, ~5 min
Worth seeing first
- Rule conditionals — the conditional and peer group syntax dbus rules use
- Unix socket rules — the unix socket to the bus that these rules refine
Part of journeys
- Network, IPC and privileges, step 7 of 14 · previous: Unix socket rules · next: Signal rules
01 demo calls a service on the bus
A dbus rule describes D-Bus messages: bus, object path, interface, member and peer. Socket rules only reach the bus daemon.
Demo asks a service called org.demo for its status, over D-Bus. On the wire that's a message to the bus daemon, down the same unix socket every bus client uses. A unix rule can let demo reach the daemon. But then demo could address any service on the bus, the secret store included. D-Bus rules work at the level of the message: which bus, which object path, which interface, and which peer. Line thirteen of demo's profile lets demo send to the demo interface of org.demo, and nothing else.
Details and sources
Details
- The rule is compiled into the profile. The kernel has no D-Bus hook; its only part is the query file
/sys/kernel/security/apparmor/.access(apparmorfs.c:879-897). - The feature file
/sys/kernel/security/apparmor/features/dbus/maskcontainsacquire send receive(apparmorfs.c:2662-2665). - The bus connection itself is a unix socket and needs its own rule: see Unix socket rules.
org.freedesktop.secretsandorg.freedesktop.login1stand for other services on a bus.org.demo, its interface and the memberStatusare invented for the map.- Kernel statements are read from the kernel source. The query path was also run for the D-Bus mediation deck, on Debian sid (kernel 7.3.4), Ubuntu 26.04 (kernel 7.0.0-43) and Debian 13 (kernel 6.12.116) guests with dbus-daemon 1.16.
Read more
- apparmor.d(5), DBus rules.
- wiki: AppArmorDBus.
- D-Bus mediation: how the rules are enforced.
02 dbus, a permission, conditionals, a peer group
[QUALIFIERS] dbus [send|receive|bind|eavesdrop] [bus= path= interface= member= name=] [peer=(name= label=)],.
The grammar follows the pattern from the conditionals deck. After the keyword comes one permission, or a list in parentheses: send, receive, bind or eavesdrop. Then the conditionals: bus, path, interface, member and name. And last the peer group, which holds the peer's name and the peer's label. Each takes a single value, and only the equals sign. Values are patterns, so a path can end in **. Everything is optional. A bare dbus rule allows all four permissions on every bus.
Details and sources
Details
- Qualifiers:
audit,allow,deny,promptandpriority=are taken (audit deny dbus send bus=session,,prompt dbus send,andpriority=5 dbus send,are accepted by the parser built from the tree).owneris refused:owner prefix not allowed on dbus rules(dbus.h:54-58). - Variables are expanded in all six strings, and repeated slashes in
pathare collapsed (dbus.cc:176-199). dbus (),is accepted and means all permissions. A second permission word outside parentheses, or a permission after a conditional, is a syntax error. Upper-caseRWis not accepted.
for AppArmor developers for security researchers
In the code
- Bit values: send
0x2, receive0x4, eavesdrop0x20, bind0x40(apparmor.h:60-65). - The scanner state
DBUS_MODE(parser_lex.l:650-695, parser_lex.l:881-882). - The productions: parser_yacc.y:1302-1354.
- The
dbus_ruleconstructor and its validation: dbus.cc:39-121.
03 Three kinds of rule in one keyword
Message rules (path, interface, member, peer=( )) take send and receive. Service rules (name=) take bind. Eavesdrop rules take only bus=.
One keyword, three different jobs, and the conditionals you write decide which. Mention a path, an interface, a member or a peer, and it's a message rule. Its permissions are send and receive. Write name outside the peer group, and it's a service rule, about owning that name on the bus. Its permission is bind. And eavesdrop stands alone, with nothing but the bus. If you leave the permission out, the parser fills in what fits the kind. Mix the kinds, say bind with an interface, and you get an error that says exactly that.
Details and sources
Details
- The four mixing errors:
dbus rule contains message conditionals and service conditionals(dbus.cc:94),dbus "bind" access cannot be used with message rule conditionals(dbus.cc:102),dbus "send" and/or "receive" accesses cannot be used with service rule conditionals(dbus.cc:104),dbus "eavesdrop" access can only contain a bus conditional(dbus.cc:108). bus=alone belongs to no kind:dbus (bind send) bus=session,is accepted and becomes a bind part and a send part.dbus name=(SomeService),is an implicit bind (ok_bind_1.sd). Other test files: ok_eavesdrop_1.sd, bad_bind_2.sd.- How the kind is decided: dbus.cc:74-117.
04 A message rule, word by word
bus, path, interface, member and peer=(name= label=) each match one property of the message. A conditional left out matches anything.
Read line 13 against the message it allows. Send is the direction. Bus equals session picks the bus. Path and interface name the object and the interface being called. The peer group says who the message goes to, by the name it holds on the bus. Member isn't mentioned, so any method of that interface matches; add member= to narrow it to one. The peer can also be named by its AppArmor label. That's usually the stronger statement, because a bus name belongs to whoever is allowed to bind it.
Details and sources
Details
name=means the peer's name inside the group and the name the profile may own outside it. A rule cannot have both:dbus conditional "name" can only be specified once.labelis only valid inside the group:dbus "label" conditional can only be used inside of the "peer=()" grouping.- A field that is left out compiles to "any characters".
- Accepted by the parser built from the tree:
dbus send bus=session path=/org/a interface=org.a member=Foo peer=(name=org.b label=unconfined),. - "The stronger statement" is reasoning from the service rule (a name is claimed with
bind); it is not a finding about a bus daemon. What a daemon puts into its query is in neither source tree: the card on the slide is the message, not the query. It was since run for D-Bus mediation: dbus-daemon 1.16 puts the destination into the query as the caller wrote it, sopeer=(name=org.demo)matched a call addressed toorg.demoand did not match the same call addressed to the owner's unique name (:1.11).peer=(label=...)does not depend on how the caller addressed the message. - Known discrepancy:
bus,path,interfaceandmemberare also accepted insidepeer=( )and are stored as if written outside (dbus send bus=session peer=(path=/x),); apparmor.d(5) documents onlynameandlabelthere (dbus.cc:77-84, apparmor.d.pod:342).
05 Owning a name, and listening in
dbus bind bus=B name=N, allows owning the name N. dbus eavesdrop bus=B, allows receiving other programs' messages. The feature file's acquire is written bind.
The other two kinds are short. A service has to claim its name on the bus before anyone can call it. The rule for that is bind with name=. It's what stops a confined program from grabbing a name that belongs to someone else, and that's why a peer name in a message rule is worth only as much as the bind rules around it. Eavesdrop is for monitoring tools. It lets a program receive messages that weren't addressed to it, so give it rarely. One detail, if you compare with the kernel's feature list: there, bind is called acquire. In a profile, acquire is a syntax error.
Details and sources
Details
dbus acquire bus=session name=org.demo,givessyntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE. The wordacquireis the kernel's, in the feature filefeatures/dbus/mask(apparmorfs.c:2662-2665).dbus bind eavesdrop,is a syntax error: two permission words need parentheses.- A bind rule has the bus and the name; an eavesdrop rule has the bus only.
RequestNameis the D-Bus call by which a program asks for a name. Neither source tree contains a bus daemon: the slide shows what the rule allows, not how a daemon decides.- Test files: ok_bind_1.sd, ok_eavesdrop_1.sd.
for AppArmor developers for security researchers
In the code
- Compiled forms printed by the parser built from the tree:
dbus bind bus=system name=org.a,gives\x20system\x00org\.awith0x40;dbus eavesdrop bus=session,gives\x20sessionwith0x20.
06 Compiled by the parser, asked for by the bus daemon for AppArmor developers for security researchers
dbus.cc:206-315 emits up to three rules under class 32 (\x20); apparmorfs.c:879-897 answers queries on .access. Enforcement is in the bus daemon.
gen_policy_re builds a vector of six fields: the class byte thirty-two glued to the bus, then the name, the peer label, the path, the interface and the member. They're joined by null bytes, with any characters standing in for what you left out. From it come up to three rules: eavesdrop on the first field, bind on the first two, send and receive on all six. Nothing in the kernel hooks D-Bus. The kernel side is the .access file. A daemon writes a query string, profile_query_cb walks it and returns the masks. The daemon and its query are the D-Bus mediation deck.
Details and sources
for AppArmor developers for security researchers
Details
- Field order: bus, name, peer label, path, interface, member. The name is the second field although the rule writes it last. The string on the slide was printed by the parser built from the tree with
-D rule-exprs:\x20session\x00org\.demo\x00[^\000]*\x00/org/demo\x00org\.demo\.Api\x00[^\000]*with0x2. - Rules added: bind with two fields (dbus.cc:289-295), send and receive with six (dbus.cc:296-302), eavesdrop with one (dbus.cc:303-309).
- The class marker
\d32is added at priority 1001 for every confined profile when dbus is supported (parser_regex.c:1406-1408). Rules are merged by their six strings (dbus.h:67-89). - Without
dbusin the feature set the rule is dropped, with the warningdbus rules not enforced, which is off by default (dbus.cc:203, dbus.cc:220-223). - Kernel:
aa_write_accesstakes the commandslabel\0,profile\0andlabelall\0(apparmorfs.c:1174-1231). The reply carries the allow, deny, audit and quiet masks (apparmorfs.c:1022-1071).profile_query_cb: apparmorfs.c:879-897. - libapparmor's entry point is
aa_query_label(kernel.c:1425-1510). - Kernel statements are read from the kernel source. The query path was also run for the D-Bus mediation deck, on Debian sid (kernel 7.3.4), Ubuntu 26.04 (kernel 7.0.0-43) and Debian 13 (kernel 6.12.116) guests with dbus-daemon 1.16.
for security researchers
Attack surface
- The decision is made in user space by the bus daemon from the kernel's answer. A bus daemon that does not ask enforces nothing, and nothing in the profile or the kernel can tell. See D-Bus mediation.
- A profile contributes nothing to a query, so all permissions are kept for it, in two cases read from the kernel source and seen in the runs of D-Bus mediation: the profile does not mediate the class of the query's first byte, or the class is dbus and the profile does not mediate network class 15 (apparmorfs.c:880-889).
- The parser still emits dbus rules under a policy ABI without
network_v9(the tree's abi/3.0 and abi/4.0). A profile pinned to one of those and loaded on a mainline kernel from 6.17 has dbus rules that are not applied to queries. This was run for D-Bus mediation: on Debian sid (kernel 7.3.4, dbus-daemon 1.16.4) profiles withabi <abi/3.0>,andabi <abi/4.0>,got the replyallow 0xffffffff deny 0x00000000 audit 0x00000000 quiet 0xffffffffto every dbus question, their calls were delivered and nothing was logged; the same profile withabi <abi/5.0>,was refused and logged. On Ubuntu 26.04 (kernel 7.0.0-43), which does not have the kernel test, all three were enforced. A profile with no abi rule behaves like abi/4.0 here unless parser.conf setspolicy-featuresto a feature file withnetwork_v9. - Bus names are claims:
peer=(name=...)is as strong as thebindrules of every other profile on that bus, and unconfined programs are not bound by them.peer=(label=...)names the confinement instead. - Known discrepancy: message conditionals are accepted inside
peer=( )(dbus.cc:77-84).
for AppArmor developers for security researchers
Read more
07 Mistakes and their messages
bind, not acquire; label inside peer=( ); one name per rule; one value per conditional.
The feature file says acquire, but the rule says bind. Label only makes sense for the peer, so it has to be inside the group. Name can appear once. Outside the group it's your name, inside it's the peer's, and one rule can't be about both. Every conditional takes one value, so for two buses write two rules. And two permissions need parentheses. Last, a reminder. The parser accepting a dbus rule says nothing about whether your bus daemon enforces it. The D-Bus mediation deck covers that.
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. - The remaining messages:
only "=" allowed in conditions of dbus rules(dbus.cc:46),invalid dbus conditional "%s"(dbus.cc:64),perms contains unknown dbus access(dbus.cc:100),dbus rule: invalid conditional group %s=(),owner prefix not allowed on dbus rules(dbus.h:54-58). - The mixing errors are listed under "Three kinds of rule in one keyword".
- The warning
dbus rules not enforcedis printed when the feature set has nodbus; it needs--warn=rule-not-enforced.
Read more
for AppArmor developers for security researchers
In the code
- The group check that prints
dbus rule: invalid conditional group %s=(): parser_yacc.y:1346.
08 From the rule to the bus daemon
Grammar here; enforcement and denials in the D-Bus mediation deck.
You can now read and write dbus rules. What you haven't seen is a denial, and that's on purpose. The kernel doesn't make this decision. The bus daemon does, by asking the kernel what your profile allows. The D-Bus mediation deck follows a message through the daemon and shows the log line it writes. From there, the query deck shows the interface underneath. And the unix deck covers the socket that carries all of it.
Details and sources
Details
- Message rules take
sendandreceive; service rules (name=) takebind; eavesdrop rules take onlybus=. - The parser compiles dbus rules into the profile. The kernel has no D-Bus hook; a bus daemon asks the kernel what the profile allows.
- 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. This page covers the grammar and the compiled form. Enforcement by the bus daemon, with runs on three guests, is in D-Bus mediation.
Grammar
DBUS RULE: [QUALIFIERS] dbus [PERMISSIONS] [CONDITIONAL ...] [peer=( [name=PATTERN] [label=PATTERN] )] ,
PERMISSIONS: PERMISSION | ( PERMISSION [,] ... )
PERMISSION: send | receive | bind | eavesdrop
write and w are send; read and r are receive; rw and wr are both
CONDITIONAL: bus=PATTERN | path=PATTERN | interface=PATTERN | member=PATTERN | name=PATTERN
- Two permission words need parentheses;
dbus (),means all permissions (tree). - Permissions come before conditionals; the group is last and written once (tree).
Conditionals
| Conditional | Where | Meaning | Makes the rule a |
|---|---|---|---|
bus | outside the group | the bus: session, system or another name | no kind by itself |
path | outside | the object path | message rule |
interface | outside | the interface | message rule |
member | outside | the method or signal name | message rule |
name | outside | the name the profile may own | service rule |
name | inside peer=( ) | the peer's bus name | message rule |
label | inside peer=( ) only | the peer's AppArmor label | message rule |
Every conditional takes one value and only =. Values are patterns. A conditional that is left out matches anything.
The three kinds
| Kind | Conditionals | Permissions | Without a written permission | Wrong mix |
|---|---|---|---|---|
| message | bus, path, interface, member, peer=(name label) | send, receive | send receive | dbus "bind" access cannot be used with message rule conditionals |
| service | bus, name | bind | bind | dbus "send" and/or "receive" accesses cannot be used with service rule conditionals |
| eavesdrop | bus | eavesdrop | - | dbus "eavesdrop" access can only contain a bus conditional |
none of these (dbus, or bus= only) | bus | any | all four | - |
A rule with message conditionals and a name outside the group: dbus rule contains message conditionals and service conditionals.
Qualifiers
| Seat | On a dbus rule |
|---|---|
priority= | taken |
audit | taken |
allow, deny, prompt | taken |
owner, other | refused: owner prefix not allowed on dbus rules |
Feature gating
- The parser compiles dbus rules when the feature set has
dbus(the kernel filefeatures/dbus/maskcontainsacquire send receive). Otherwise the rule is dropped and, with--warn=rule-not-enforced, the parser printsdbus rules not enforced. - In the mainline kernel from 6.17 a profile takes part in a dbus query only if it also mediates network class 15, which the parser adds only when the feature set has
network_v9/af_unix. Run for D-Bus mediation: on Debian sid (kernel 7.3.4) the dbus rules of profiles compiled underabi/3.0andabi/4.0were not consulted (every question answeredallow 0xffffffff, nothing logged); underabi/5.0they were. Ubuntu kernels do not have the test: on Ubuntu 26.04 (kernel 7.0.0-43) all three were enforced.
Errors and warnings
| Line | Message |
|---|---|
dbus acquire bus=session name=org.demo, | syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE |
dbus send bus=session label=demo-helper, | dbus "label" conditional can only be used inside of the "peer=()" grouping |
dbus send bus=session name=org.demo peer=(name=org.x), | dbus conditional "name" can only be specified once |
dbus send bus=(session system), | dbus conditional "bus" only supports a single value |
dbus bind eavesdrop, | syntax error, unexpected TOK_EAVESDROP, expecting TOK_END_OF_RULE |
dbus bind bus=session interface=org.demo.Api, | dbus "bind" access cannot be used with message rule conditionals |
owner dbus send, | owner prefix not allowed on dbus rules |
an operator other than = | only "=" allowed in conditions of dbus rules |
| an unknown conditional | invalid dbus conditional "NAME" |
a group other than peer | dbus rule: invalid conditional group NAME=() |
feature set without dbus (warning, off by default) | dbus rules not enforced |
for AppArmor developers for security researchers
Encoding
- Six fields joined by zero bytes, in this order: class byte
\x20and bus, name, peer label, path, interface, member. A missing field is[^\000]*(dbus.cc:206-315). - Up to three rules: eavesdrop with one field, bind with two, send and receive with six.
- Permission bits: send
0x2, receive0x4, eavesdrop0x20, bind0x40(apparmor.h:60-65). - The class marker
\d32at priority 1001 (parser_regex.c:1406-1408). - Kernel:
aa_write_access(apparmorfs.c:1174-1231),profile_query_cb(apparmorfs.c:879-897), the reply (apparmorfs.c:1022-1071). libapparmor:aa_query_label(kernel.c:1425-1510).
for security researchers
Known discrepancies and limits
bus,path,interfaceandmemberare accepted insidepeer=( )and stored as if written outside (tree; dbus.cc:77-84). The verdict is in known bugs.- Not in either source tree, and so not stated here: what a bus daemon sends in a query (field order, how
eavesdropandbindqueries are formed, which label it queries). Only the parser's encoding and the kernel's reply are covered.
Roads from here
START HERE
- Upstream and Ubuntu kernels — kernels and daemons that mediate D-Bus
- The profile language at a glance — every kind of line on one page
FILE ACCESS
- Globbing (AARE) — patterns in path interface member and name
PREAMBLE AND REUSE
- The abi rule and the abi files — the feature set that says dbus is supported
QUALIFIERS
- allow and deny — deny and audit on dbus rules
RULE CLASSES
- Rule conditionals — the conditional syntax and the peer group
- Unix socket rules — the unix socket the bus connection runs over
IN PRACTICE · general-purpose apps
- Choosing abstractions — the dbus abstractions shipped with AppArmor
LIBAPPARMOR
- D-Bus mediation — how the bus daemon enforces these rules
- Querying the policy (no slides yet) — the query interface the daemon uses