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

Part of journeys

01 demo calls a service on the bus

D-BUS RULES demo org.demo session busdaemon one unix socket /org/demo org.demo.Api.Status() org.freedesktop.secrets org.freedesktop.login1 a dbus rule: which bus, which path, which interface, which peer dbus send bus=session path=/org/demo interface=org.demo.Api peer=(name=org.demo), line 13 of demo's profile no rule for those messages
demo is connected to the session bus daemon by one unix socket. Three services sit behind the daemon: org.demo, org.freedesktop.secrets and org.freedesktop.login1. A message for the path /org/demo and the interface org.demo.Api travels from demo through the daemon to org.demo. Line 13 of demo's profile is a dbus rule for that message; the other two services are not covered by any rule.

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/mask contains acquire 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.secrets and org.freedesktop.login1 stand for other services on a bus. org.demo, its interface and the member Status are 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

02 dbus, a permission, conditionals, a peer group

GRAMMAR QUALIFIERS dbus PERMISSIONS CONDITIONALS peer=( name= label= ) , permissions send receive bind eavesdrop also write = send, read = receive, r w rw conditionals bus= path= interface= member= name= peer group peer=( name= label= ) last, once one value each, = only, patterns dbus, dbus send bus=session path=/org/demo interface=org.demo.Api peer=(name=org.demo), dbus bind bus=session name=org.demo, alone: all four permissions on every bus
A syntax diagram: optional qualifiers, the word dbus, optional permissions, optional conditionals, an optional peer group with name and label, a comma. The permissions send, receive, bind and eavesdrop. The conditionals bus, path, interface, member and name. Three example rules; a bare dbus rule allows all four permissions on every bus.

[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, prompt and priority= are taken (audit deny dbus send bus=session,, prompt dbus send, and priority=5 dbus send, are accepted by the parser built from the tree). owner is refused: owner prefix not allowed on dbus rules (dbus.h:54-58).
  • Variables are expanded in all six strings, and repeated slashes in path are 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-case RW is not accepted.

for AppArmor developers for security researchers

In the code

03 Three kinds of rule in one keyword

THREE KINDS message rule path interface member peer=(name label) dbus send path=/org/demo, send receive service rule name outside the group dbus bind name=org.demo, bind eavesdrop rule bus and nothing else eavesdrop dbus eavesdrop bus=session, no permission written: send receive bind none of the three: all four dbus bind bus=session interface=org.demo.Api, bind with a message conditional dbus "bind" access cannot be used with message rule conditionals
Three columns. A message rule has path, interface, member and a peer group, and takes send and receive. A service rule has name outside the group and takes bind. An eavesdrop rule has only the bus and takes eavesdrop. Without a written permission each kind gets the permissions that fit it. A rule with bind and an interface is refused by the parser.

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

MESSAGE RULES the message bus session path /org/demo interface org.demo.Api destination org.demo member Status line 13 dbus send bus=session path=/org/demo interface=org.demo.Api peer=(name=org.demo), the peer's bus name member is not in the rule: any member matches dbus receive bus=session interface=org.demo.Api peer=(label=demo-helper), the peer by its AppArmor label instead of its bus name a bus name belongs to whoever may bind it
Line 13 of demo's profile, broken over five lines, next to a message with the fields bus session, path /org/demo, interface org.demo.Api, destination org.demo and member Status. Each conditional points at one field; member has no conditional, so any member matches. A second rule names the peer by its AppArmor label instead of its bus name.

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.
  • label is 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, so peer=(name=org.demo) matched a call addressed to org.demo and 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, interface and member are also accepted inside peer=( ) and are stored as if written outside (dbus send bus=session peer=(path=/x),); apparmor.d(5) documents only name and label there (dbus.cc:77-84, apparmor.d.pod:342).

05 Owning a name, and listening in

SERVICE AND EAVESDROP demo-helper session busdaemon RequestName("org.demo") dbus bind bus=session name=org.demo, may own org.demo something else RequestName("org.demo") its profile has no bind rule for that name monitor dbus eavesdrop bus=session, may see messages addressed to others dbus acquire bus=session name=org.demo, syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE the kernel's feature file calls bind "acquire"; in a profile the word is bind
demo-helper asks the session bus daemon for the name org.demo; its profile has a dbus bind rule for that name. Another program asks for the same name and has no bind rule for it. A monitor program with a dbus eavesdrop rule may see messages addressed to others. The kernel's feature file calls bind acquire; in a profile the word is bind.

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, gives syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE. The word acquire is the kernel's, in the feature file features/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.
  • RequestName is 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\.a with 0x40; dbus eavesdrop bus=session, gives \x20session with 0x20.

06 Compiled by the parser, asked for by the bus daemon for AppArmor developers for security researchers

IN THE PARSER dbus send bus=session path=/org/demo interface=org.demo.Api peer=(name=org.demo), class, busnamepeer labelpathinterfacemember \x20session 00 org\.demo 00 [^\000]* 00 /org/demo 00 org\.demo\.Api 00 [^\000]* 0x2 send eavesdrop rule bind rule send / receive rule the kernel: no D-Bus hook, one file /sys/kernel/security/apparmor/.access bus daemon not in either source tree: see D-Bus mediation query profile_query_cb() walks the query, returns allow, deny, audit, quiet masks a profile contributes to a dbus query only if it also mediates network class 15
Line 13 compiles to six fields joined by zero bytes: the class byte \x20 with the bus session, the name org.demo, any peer label, the path /org/demo, the interface org.demo.Api and any member, with permission 0x2. An eavesdrop rule uses the first field, a bind rule the first two, a send or receive rule all six. In the kernel the .access file and profile_query_cb answer a query from the bus daemon, which is in neither source tree.

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]* with 0x2.
  • 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 \d32 is 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 dbus in the feature set the rule is dropped, with the warning dbus rules not enforced, which is off by default (dbus.cc:203, dbus.cc:220-223).
  • Kernel: aa_write_access takes the commands label\0, profile\0 and labelall\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 with abi <abi/3.0>, and abi <abi/4.0>, got the reply allow 0xffffffff deny 0x00000000 audit 0x00000000 quiet 0xffffffff to every dbus question, their calls were delivered and nothing was logged; the same profile with abi <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 sets policy-features to a feature file with network_v9.
  • Bus names are claims: peer=(name=...) is as strong as the bind rules 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).

07 Mistakes and their messages

MISTAKES dbus acquire bus=session name=org.demo, the word is bind 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), yours or the peer's, not both dbus conditional "name" can only be specified once dbus send bus=(session system), write two rules dbus conditional "bus" only supports a single value dbus bind eavesdrop, two permissions need parentheses syntax error, unexpected TOK_EAVESDROP, expecting TOK_END_OF_RULE a rule that parses is compiled; whether it is enforced depends on the bus daemon and the kernel's feature set
Five wrong dbus rules with the parser's message: acquire is a syntax error, the word is bind; label outside the peer group; name written twice; a list of buses; two permissions without parentheses. A rule that parses is compiled; whether it is enforced depends on the bus daemon and the kernel's feature set.

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

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

ROADS dbus send ... peer=(name=org.demo), the grammar and what the parser compiles dbus-mediation who enforces it and what the denial looks like lib-query the query interface syn-unix the socket to the bus syn-rule-conditionals the peer group prac-abstractions shipped dbus rules upstream-and-ubuntu kernels and daemons that mediate D-Bus
D-Bus rules in the centre with a main road to dbus-mediation and roads to lib-query, syn-unix, syn-rule-conditionals, prac-abstractions and upstream-and-ubuntu.

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 send and receive; service rules (name=) take bind; eavesdrop rules take only bus=.
  • 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

ConditionalWhereMeaningMakes the rule a
busoutside the groupthe bus: session, system or another nameno kind by itself
pathoutsidethe object pathmessage rule
interfaceoutsidethe interfacemessage rule
memberoutsidethe method or signal namemessage rule
nameoutsidethe name the profile may ownservice rule
nameinside peer=( )the peer's bus namemessage rule
labelinside peer=( ) onlythe peer's AppArmor labelmessage rule

Every conditional takes one value and only =. Values are patterns. A conditional that is left out matches anything.

The three kinds

KindConditionalsPermissionsWithout a written permissionWrong mix
messagebus, path, interface, member, peer=(name label)send, receivesend receivedbus "bind" access cannot be used with message rule conditionals
servicebus, namebindbinddbus "send" and/or "receive" accesses cannot be used with service rule conditionals
eavesdropbuseavesdrop-dbus "eavesdrop" access can only contain a bus conditional
none of these (dbus, or bus= only)busanyall four-

A rule with message conditionals and a name outside the group: dbus rule contains message conditionals and service conditionals.

Qualifiers

SeatOn a dbus rule
priority=taken
audittaken
allow, deny, prompttaken
owner, otherrefused: owner prefix not allowed on dbus rules

Feature gating

  • The parser compiles dbus rules when the feature set has dbus (the kernel file features/dbus/mask contains acquire send receive). Otherwise the rule is dropped and, with --warn=rule-not-enforced, the parser prints dbus 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 under abi/3.0 and abi/4.0 were not consulted (every question answered allow 0xffffffff, nothing logged); under abi/5.0 they were. Ubuntu kernels do not have the test: on Ubuntu 26.04 (kernel 7.0.0-43) all three were enforced.

Errors and warnings

LineMessage
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 conditionalinvalid dbus conditional "NAME"
a group other than peerdbus rule: invalid conditional group NAME=()
feature set without dbus (warning, off by default)dbus rules not enforced

for AppArmor developers for security researchers

Encoding

for security researchers

Known discrepancies and limits

  • bus, path, interface and member are accepted inside peer=( ) 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 eavesdrop and bind queries are formed, which label it queries). Only the parser's encoding and the kernel's reply are covered.

Roads from here

START HERE

FILE ACCESS

PREAMBLE AND REUSE

QUALIFIERS

RULE CLASSES

IN PRACTICE · general-purpose apps

LIBAPPARMOR