Unix socket rules

unix domain sockets for application developers for administrators for security researchers

A unix rule mediates unix domain sockets that have an abstract address or no address by socket type and local address and by the address and label of the peer. Sockets bound to a file name are governed by file rules. For a stream connection the kernel asks the profiles of both ends.

On the map: rule classes

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

Part of journeys

01 demo talks to its helper

UNIX SOCKET RULES demo demo-helper profile demo-helper unix stream socket something else another profile unix (send, receive) type=stream peer=(label=demo-helper), line 12 of demo's profile what demo's socket who is at the other end no rule for that peer
demo and demo-helper are joined by a unix stream socket. A dashed line leads from demo to another program under another profile. Line 12 of demo's profile is a unix rule with the permissions send and receive, type=stream for demo's socket and a peer group naming the label demo-helper. The line to the other program is cut: no rule covers that peer.

unix PERMISSIONS type=T addr=A peer=(addr=A label=L), mediates unix sockets by the local socket and by the peer's address and label.

Demo hands some of its work to a helper, and the two talk over a unix socket, the kind of socket that doesn't leave the machine. A plain network unix rule would let demo talk to any unix socket on the system. A unix rule can say more. It names the permissions, here send and receive. It says what kind of socket demo holds: a stream socket. And in the peer group it says who's at the other end: any process confined by the profile demo-helper. That's line 12 of demo's profile. With it, demo exchanges data with its helper, and with nobody else, over such sockets.

Details and sources

Details

  • The rule covers unix sockets with an abstract address or no address. Sockets bound to a file name are checked against file rules (see "Three kinds of address").
  • The kernel mediates unix sockets this finely when the feature set has network_v9/af_unix: the file /sys/kernel/security/apparmor/features/network_v9/af_unix (net.c:24-36).
  • Shipped rules of the same shape: unix (send receive) type=stream, (glycin.loaders:16), unix (receive, send) type=stream peer=(label=dovecot), (usr.lib.dovecot.anvil:23), unix (accept, bind, listen, receive, send) type=stream addr="@/tmp/.X11-unix/X[0-9]*", (Xorg:65).
  • The program demo, its helper and their profiles are invented for the map.
  • Kernel statements are read from the kernel source and were not run.

Read more

02 unix, permissions, two conditionals, a peer group

GRAMMAR QUALIFIERS unix PERMISSIONS type=T addr=A demo's own side peer=( addr=A label=L ) , the other end permissions create bind listen accept connect shutdown getattr setattr getopt setopt send receive unix, unix (send, receive) type=stream peer=(label=demo-helper), unix (bind, listen, accept) type=stream addr=@demo, unix (connect) peer=(addr=@demo), everything, on abstract and unnamed unix sockets unix stream, syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE the type is always type=NAME
A syntax diagram: optional qualifiers, the word unix, an optional permission list, optional type=T, optional addr=A, an optional peer group with addr=A and label=L, a comma. Four example rules, from a bare unix rule to demo's line 12. The twelve permissions. The type is always written type=NAME.

[QUALIFIERS] unix [PERMISSIONS] [type=T] [addr=A] [peer=(addr=A label=L)],. Conditionals come before the peer group.

The shape will look familiar from network rules: the keyword, an optional permission list, then conditionals. On demo's own side there are two. Type equals stream, dgram or seqpacket. And addr= the socket's address. Then comes the peer group, with the peer's address and its label. The permissions are the same twelve as for network rules. Leave everything out, and unix, allows every operation on these sockets. One difference from network rules: the type is always written with type=. Unix stream on its own is a syntax error.

Details and sources

Details

  • Qualifiers: audit, deny, allow, prompt and priority= are taken (network rules take fewer). owner is refused: owner prefix not allowed on unix rules (af_unix.h:52-61).
  • type=: one value, on the local side only. Names: stream, dgram, seqpacket. Also accepted, and matching nothing on Linux: none, raw, rdm, dccp, packet (network.cc:66-93).
  • protocol= is named and refused: 'protocol' conditional is not currently supported.
  • unix stream, is refused by the parser built from the tree: syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE.
  • Variables are expanded in addr, in the peer addr and in the peer label (af_rule.cc:161-171, af_unix.cc:166-181).
  • Test files: ok_bind_1.sd (unix addr=@SomeService,), ok_msg_7.sd (unix (send) addr=none,).

for AppArmor developers for security researchers

In the code

03 Three kinds of address, and one the rule does not take

ADDRESSES the programthe addressthe rule bind("\0demo") @demo unix (bind) addr=@demo, abstracta pattern: addr=@demo* works too socketpair() none unix (send) addr=none, no address bind(), no name given @00a3f unix (bind) addr=auto, autobindfive hex digits chosen by the kernel bind("/run/demo.sock") /run/demo.sock a file /run/demo.sock rw, a file rule unix addr=/run/demo.sock, unix rule: invalid value for addr='/run/demo.sock'
Four rows, each with what the program does, the address the kernel sees and the rule that matches it. Binding to an abstract name gives @demo and the rule unix (bind) addr=@demo. A socket pair has no address: addr=none. Autobind gives a name of five hex digits: addr=auto. Binding to /run/demo.sock gives a file, matched by a file rule. A path in addr is refused by the parser.

addr=@name (abstract, a pattern), addr=none (unnamed), addr=auto (autobind). A socket bound to a path needs a file rule for the path; addr=/path is an error.

Unix sockets come with three kinds of address, and the rule spells each one differently. An abstract address is a name that lives only in the kernel. In a rule it starts with an at sign, and the rest is a pattern, so globs work. A socket with no address at all, like the two ends of a socket pair, is addr=none. Autobind, where the kernel picks the name, is addr=auto. Then there's a fourth kind: a socket bound to a file name. The unix rule doesn't match that one. It's a file, so you allow it with a file rule on the path.

Details and sources

Details

  • Accepted by the parser built from the tree: unix addr=none,, unix addr=auto,, unix addr=@foo*,, unix addr=@,, unix addr="@a b",, unix (connect) peer=(addr=none),. A rule without addr matches any address and no address (af_unix.cc:65-71, af_unix.cc:257-290).
  • The kernel matches the socket's address including the leading zero byte of an abstract name, or a constant for an unnamed socket (match_addr, af_unix.c:63-83).
  • Sockets with a file name: every unix check calls unix_fs_perm instead, which checks the profile's file rules for the socket's path with the request reduced to the file permissions in NET_FS_PERMS (af_unix.c:34-61, af_unix.c:240-243, af_unix.c:302-305, net.h:41-45). bind to a path returns at once in the unix code because the file hooks handle it (af_unix.c:269-271).
  • The file rule's rw on the slide is illustrative, and so are /run/demo.sock and the autobind name @00a3f (five characters from [0-9a-f], af_unix.cc:39-40).
  • A pattern error in addr surfaces late and without a line number: unix addr=@foo[, gives Regex grouping error: Unclosed grouping or character class, expecting close }, Unable to parse input line 'foo[', ERROR processing policydb rules for profile demo, failed to load and ERROR generating policy re for profile demo, failed to load; the exit status is 255.
  • In the log the address is addr=none, a path, or "@name" (net.c:80-115).
  • Kernel statements are read from the kernel source and were not run.

04 Your socket, then the peer

TWO SIDES demo-helper @demo demo unix stream socket profile demo-helper unix (create, bind, listen) type=stream addr=@demo, the helper's own socket create bind listen shutdown getattr setattr getopt setopt look at the local socket only unix (accept, send, receive) type=stream addr=@demo peer=(label=demo), checked against who connects send receive connect accept may add a peer group unix (bind) peer=(addr=@demo), a local permission with a peer group unix socket ... 'bind', 'listen', 'setopt', and/or 'getopt' accesses cannot be used with peer socket conditionals label inside peer=( ) is the peer's; there is no label for your own side
demo-helper owns a stream socket with the abstract address @demo; demo is at the other end. In the helper's profile one rule gives create, bind and listen with the local conditionals type and addr only; a second rule gives accept, send and receive and adds a peer group with the label demo. Eight permissions look at the local socket only, four may take a peer group. A rule with bind and a peer group is refused by the parser.

create bind listen setopt getopt getattr setattr shutdown look at the local socket. send receive connect accept can also be limited by peer=(addr= label=).

Take the helper's side for a moment. Creating the socket, binding it to the abstract name demo and listening are things the helper does to its own socket. So that rule has only the local conditionals. Accepting a connection and exchanging data involve somebody else, so that rule can add a peer group that says who: here, tasks confined by demo. The parser enforces the split. A local permission such as bind together with a peer group is an error. And the label conditional exists only inside the group. It's always the peer's label; there's no label for your own side.

Details and sources

Details

  • The full message: unix socket 'create', 'shutdown', 'setattr', 'getattr', 'bind', 'listen', 'setopt', and/or 'getopt' accesses cannot be used with peer socket conditionals (af_unix.cc:138-139). Test file: bad_bind_1.sd.
  • unix label=a, gives unknown rule: 'label' conditional is only valid in the peer expression (af_rule.cc:76-80).
  • The peer label is a pattern matched against the peer's profile name, once per profile of the peer's label that is in view (af_unix.c:173-193).
  • unix peer=(label=unconfined), and unix peer=(label=@{profile_name}), are accepted by the parser built from the tree.
  • The kernel does not match a local label: the source has the comment todo: local label matching (af_unix.c:97-98).
  • Known discrepancy: apparmor.d(5) documents a local label and attr= and opt= conditionals; the parser has none of them. See known bugs.
  • Kernel statements are read from the kernel source and were not run.

05 Both ends are asked

ONE CONNECT, TWO CHECKS demo connect("@demo") demo-helper listens on @demo the kernel demo's profile connect send receive toward demo-helper? yes unix (connect, send, receive) type=stream peer=(addr=@demo label=demo-helper), in demo demo-helper's profile accept send receive toward demo? no connect() = -1 EACCES apparmor="DENIED" operation="connect" class="net" profile="demo-helper" ... family="unix" sock_type="stream" protocol=0 requested="send receive accept" denied="send receive accept" addr="@demo" peer_addr=none peer="demo" the record names the profile that said no: here the helper's
demo connects to the abstract socket @demo of demo-helper. The kernel asks demo's profile for connect, send and receive toward demo-helper: yes. It asks demo-helper's profile for accept, send and receive toward demo: no. The connect fails with EACCES and the log record names the profile demo-helper, the permissions send receive accept and the peer demo.

A unix stream connection needs connect send receive in the connecting profile and accept send receive in the listener's, each toward the other's label. Datagrams need send in the sender and receive in the receiver.

This is the part that surprises people. When demo connects, the kernel asks twice. First demo's profile: may you connect, send and receive toward a socket owned by demo-helper? Then the helper's profile: may you accept, send and receive from demo? If either one says no, the connect fails with EACCES. So a working pair needs a rule in each profile. When it fails, look at the profile field of the log record. It tells you which side refused, and the peer field tells you who the other one was. Here it was the helper's profile that said no.

Details and sources

Details

  • LSM hooks: unix_stream_connect and unix_may_send (lsm.c:1189-1256). For a connection the kernel requests connect send receive from the connecting label toward the listener's label and accept send receive from the listener's label toward the connecting one; both checks run and either refusal fails the call (lsm.c:1127-1149). For a datagram the sender needs send and the receiving socket's label receive (lsm.c:1235-1256).
  • The listener-side check is skipped when the listener is a socket with a file name: the file rule decided.
  • The call fails with EACCES.
  • The record on the slide is built, not observed. Its layout is that of testcase_unix_01.in (operation="connect" class="net" profile=... family="unix" sock_type="stream" protocol=0 requested="send receive connect" denied="send receive connect" addr=none peer_addr="@test_abstract_socket" peer=...), turned to the listener's side with demo's values. The words send receive accept and their order follow from the request the kernel builds for the listener and the order of its name table (net.c:38-78).
  • Fields: addr=, peer_addr=, peer= (net.c:80-166). Real records: testcase_unix_01.in to testcase_unix_03.in in the same directory.
  • Reasons in info=: failed local address match, failed local label match, failed cmd selection match, failed peer address match, failed peer label match, failed listen backlog match, failed sockopt match (af_unix.c:100-102, af_unix.c:150, af_unix.c:167, af_unix.c:188, af_unix.c:313, af_unix.c:379).
  • An unconfined end has no profile to ask. After successful checks the socket remembers its label and its peer's label (af_unix.c:652-716). socketpair labels both ends and links them (lsm.c:1328-1357).
  • Kernel statements are read from the kernel source and were not run.

for security researchers

Attack surface

  • The two-sided check exists for abstract and unnamed sockets on a kernel whose feature set has network_v9/af_unix.
  • For a socket with a file name only the file rule on the path stands between a confined client and the server: the peer's label is not consulted on the listener side (lsm.c:1127-1149).
  • A received file descriptor for a socket is checked again when it is used, not at the moment it is passed (file.c:551-573).
  • How other kernels differ is in Upstream and Ubuntu kernels.

06 network unix and unix: each brings the other

TWO SPELLINGS you writethe parser adds network unix stream, unix type=stream, unix (send, receive) type=stream peer=(label=demo-helper), network (send, receive) unix stream, a kernel with fine-grained unix mediation the unix rules decide type, address and peer label are checked a kernel with family and type only the network rules decide the peer label is not checked there a deny unix rule is not turned into a network rule: on that kernel it is dropped Known discrepancy: a permission list on network unix; see the details
Two written rules on the left and the rule the parser adds for each on the right: network unix stream brings unix type=stream; demo's unix rule brings network (send, receive) unix stream. A kernel with fine-grained unix mediation lets the unix rules decide. A kernel that knows family and type only lets the network rules decide and does not check the peer label. A deny unix rule is not turned into a network rule; on that kernel it is dropped.

A network rule covering AF_UNIX also creates a unix rule; a unix rule also creates network unix TYPE. Kernels with fine-grained unix mediation use the unix rules; others use the network rule. deny unix rules are not downgraded: there they are dropped.

Unix sockets can be written two ways, and the parser keeps the two in step. Write network unix stream, and it also adds a unix rule for stream sockets. Write a unix rule, and it also adds a network unix rule for that type. Why? Kernels differ. One with fine-grained unix mediation consults the unix rules. One that only knows family and type consults the network rule. So your profile works on both, more loosely on the second, where nobody checks the peer. Deny is the exception. A deny unix rule isn't turned into a network rule; on such a kernel it's dropped, and it denies nothing.

Details and sources

Details

  • Which rules the kernel uses: for unix sockets it takes the unix paths whenever the profile mediates the unix class (RULE_MEDIATES_UNIX, policy.h:360-363) and falls back to the family and type check otherwise (af_unix.c:212-223).
  • network unix, generates six unix rules, one per type name (stream, dgram, seqpacket, rdm, raw, packet); unix, is one rule for any type. Seen with the parser built from the tree.
  • A deny unix rule is not turned into a network rule "because the downgrade makes the rule less specific" (af_unix.cc:204-229). With a feature set that has family and type only, deny unix (connect) type=stream peer=(addr=@foo), compiles to the same output as an empty profile.
  • Warnings, all off by default: downgrading extended network unix socket rule to generic network rule (af_unix.cc:537), extended network unix socket rules not enforced (af_unix.cc:184-187), deny unix socket rule not enforced, can't be downgraded to generic network rule (af_unix.cc:227). Turn them on with --warn=rule-downgraded --warn=rule-not-enforced.
  • For demo's line 12 and the feature set abi/5.0 the parser also emits a network (send, receive) unix stream, rule.
  • Kernel statements are read from the kernel source and were not run.

for security researchers

Attack surface

  • Known discrepancy, seen with the parser built from the tree and the mainline kernel's feature set: the unix rule generated from a network rule is built from the socket type only and gets every permission (parser_yacc.y:762-777, af_unix.cc:105-125). network (create) unix stream, therefore compiles a generic rule with create and unix rules that allow bind, listen, accept, connect, send, receive, getopt and setopt on abstract and unnamed stream sockets toward any peer. The unix rules are the ones the kernel consults.
  • The same holds for network (create), and any network (...) rule without a family, since they include unix. With deny, deny network (bind) unix, denies every unix operation.
  • On a kernel with family and type only a unix rule loses its address and peer conditions (the downgrade). That is the documented design.
  • Known discrepancy, on the bug list as "deny unix rules are dropped when the kernel lacks fine-grained unix mediation, even where the downgrade would be exact": the drop also covers deny rules without an address, label or peer conditional (deny unix,, deny unix type=stream,), whose downgrade to deny network unix would be exact; network, deny unix, then allows every unix socket operation and prints nothing by default (af_unix.cc:204-229). Seen with the parser built from the tree and a feature set without fine-grained unix mediation.
  • Known discrepancy: the warning deny unix socket rule not enforced ... is printed also when the rule is compiled.
  • See known bugs.

for AppArmor developers for security researchers

In the code

  • The network rule emitted with demo's line 12 under abi/5.0 is \x0f\x00\x01\x00\x01 with send and receive (0x6), printed by the parser built from the tree with -D rule-exprs.

07 Up to six rules, each a prefix of the next for AppArmor developers for security researchers

IN THE PARSER classAF_UNIXtypeprotocol 0f 00 01 00 01 .. create addr 00 label 00 shutdown getattr bind accept 02 .. listen(backlog) 04 .. getopt setopt(option) 01 peer addr 00 peer label send receive connect accept af_unix.c: aa_unix_create_perm _bind_perm _listen_perm _accept_perm _opt_perm _sock_perm _peer_perm each walks to its stop \x0f\x00\x01\x00\x01...*\x00[^\000]*\x00\x01.*\x00demo-helper 0x6 line 12: send and receive bind with no addr, or addr=auto, is compiled a second time with an empty address
A track of match-string cells: class byte 0f, the family AF_UNIX, the type, the protocol, where create stops; then the address, a zero, the label slot, a zero, where shutdown, getattr, bind and accept stop; a branch with command byte 02 for listen and one with 04 for socket options; and straight on command byte 01, the peer address, a zero and the peer label for send, receive, connect and accept. The match string of demo's line 12 and the kernel functions that walk it.

af_unix.cc:516-666 emits the chain; af_unix.c in the kernel walks it per hook, with command bytes 1 (peer), 2 (listen), 4 (options).

One unix rule can become six policydb rules. They share a prefix: the class byte, the unix family, the type and the protocol. Create stops right there. The local permissions go on through the address and a label slot. Listen and the socket options each add a command byte and two bytes of argument. The peer permissions add command byte one, the peer's address and the peer's label. Because each is a prefix of the next, the kernel's functions in af_unix.c just walk to the position that answers their question. Line twelve of demo's profile is the longest form.

Details and sources

for AppArmor developers for security researchers

Details

  • The chain (af_unix.cc:516-666; layout comment af_unix.cc:344-384). Prefix: class, AF_UNIX (2 bytes), type (2 bytes or ..), protocol (..). 1: create, the prefix. 2: bind without addr or with addr=auto: prefix, \x00, label pattern, \x00 (af_unix.cc:558-584). 3: shutdown setattr getattr bind accept: prefix, address, \x00, label pattern, \x00. 4: listen: rule 3 plus \x02 and .. (the backlog). 5: getopt setopt: rule 3 plus \x04 and .. (the option name). 6: send receive connect accept: rule 3 plus \x01, peer address, \x00, peer label pattern.
  • Address encodings: abstract is a zero byte and the pattern; none is the byte 0x01; auto is a zero byte and five [0-9a-f]; absent is .* (af_unix.cc:257-290).
  • The class byte is 15 with network_v9, else 14 with network_v8, else 4. The source calls the middle case wrong and keeps it for compatibility (af_unix.cc:233-245).
  • The string on the slide was printed by the parser built from the tree with -D rule-exprs for demo's line 12 under abi/5.0.
  • Kernel walk per entry point (af_unix.h:34-53): create (af_unix.c:202-224), bind (af_unix.c:255-284), listen (af_unix.c:286-320), accept (af_unix.c:322-350), options (af_unix.c:352-386), getattr, shutdown and re-validation (af_unix.c:226-253), peer (af_unix.c:389-426).
  • An address that is too short or too long is -EINVAL (af_unix.c:478-487). The label slot on the local side is a null transition in the kernel.
  • Known discrepancy (by reading the code): audit unix (getopt), marks both option bits as audited at that position (af_unix.cc:631-637).
  • Known discrepancy: the unix class marker matches the family bytes 0x00 0x31 (parser_regex.c:1339-1353); the kernel tests only the class start state.
  • 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 unix stream, write type=stream syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE unix addr=/run/demo.sock, use a file rule unix rule: invalid value for addr='/run/demo.sock' unix label=demo-helper, unknown rule: 'label' conditional is only valid in the peer expression unix (send, receive) peer=(label=demo-helper) type=stream, the group goes last syntax error, unexpected TOK_CONDID, expecting TOK_END_OF_RULE unix type=stream attr=foo, the manual page lists attr= and opt=; the parser has neither unix rule: invalid conditional 'attr' owner unix, owner prefix not allowed on unix rules "unknown rule:" is the parser's wording for conditionals unix shares with other socket rules
Six wrong unix rules with the parser's message: unix stream is a syntax error; a path in addr is an invalid value; label outside the peer group is refused; a conditional after the peer group is a syntax error; attr is an invalid conditional; owner is not allowed on unix rules.

type= is required for the type; no path in addr=; label only inside peer=( ); the group last; no attr= or opt=; no owner.

Coming from network rules, you'll want to write unix stream. Here the type needs type=. A path in addr is refused: paths are for file rules. Label on its own is refused too; it lives in the peer group. And the group has to be the last thing in the rule. The manual page mentions two more conditionals, attr and opt, but the parser doesn't know them. Owner isn't allowed on a unix rule either. You'll notice that some of these messages begin with the words unknown rule. That's just the parser's wording for the conditionals unix shares with other socket rules.

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.
  • unix type=bogus,: socket rule: invalid socket type 'bogus'.
  • unix type=stream type=dgram,: socket rule conditional "type" can only be specified once.
  • unix type=(stream dgram),: unknown rule: conditional 'type' only supports a single value.
  • unix peer=(type=stream),: unknown rule: 'type' conditional is not allowed in the peer expression.
  • unix addr=@x addr=@y,: unix socket conditional "addr" can only be specified once.
  • unix protocol=0,: unknown rule: 'protocol' conditional is not currently supported.
  • A permission that is not one of the twelve: perms contains invalid permissions for unix socket rules (af_unix.cc:137).
  • Test files that must fail: bad_modifier_3.sd (unix send type in (dgram, stream),), bad_peer_1.sd (unix send peer(addr=wat),), bad_attr_3.sd (unix setattr peer=(label=orange),).
  • Known discrepancy: the unknown rule: prefix comes from a literal rule name passed for the shared conditionals (af_rule.cc:66).
  • Known discrepancy: apparmor.d(5) lists attr=, opt= and a local label (apparmor.d.pod:367, apparmor.d.pod:375-377); the parser has none of them. See known bugs.

09 Sockets, files and the bus

ROADS unix ... peer=(label=demo-helper), abstract and unnamed sockets, by local socket and by peer syn-file-rules sockets with a path syn-network network unix k-labels what a label is syn-rule-conditionals the peer group syn-dbus messages on the bus syn-signal both sides again upstream-and-ubuntu other kernels adm-denials reading a unix denial
Unix socket rules in the centre with roads to syn-network, syn-file-rules, syn-rule-conditionals, k-labels, syn-dbus, syn-signal, upstream-and-ubuntu and adm-denials.

Abstract and unnamed unix sockets: this deck. Sockets with a path: file rules. Messages on the bus: D-Bus rules.

Unix rules cover the sockets that have no file behind them. Sockets with a path go back to file rules, and the coarse network unix rule is the fallback on kernels that only know family and type. If the label in the peer group is new to you, the labels deck explains it, and the rule conditionals deck has the group itself. D-Bus, which runs over a unix socket, has its own rules for the messages inside. And signal rules are another place where both sides need a rule.

Details and sources

Details

  • A unix rule covers unix sockets with an abstract address or no address. A socket bound to a path is governed by the file rule for the path.
  • A stream connection needs connect send receive in the connecting profile and accept send receive in the listener's.
  • 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 unless another is named), 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

UNIX RULE:   [QUALIFIERS] unix [PERMISSIONS] [type=TYPE] [addr=ADDRESS] [peer=( [addr=ADDRESS] [label=LABEL] )] ,
PERMISSIONS: PERMISSION | ( PERMISSION [,] ... )
PERMISSION:  create bind listen accept connect shutdown getattr setattr getopt setopt send receive
             send is also write or w; receive is also read or r; rw is both
TYPE:        stream | dgram | seqpacket
ADDRESS:     @PATTERN | none | auto
  • The conditionals come before the peer group; the group is written once and last (tree).
  • unix, allows every operation on unix sockets with an abstract address or no address (tree).

Conditionals

ConditionalSideValueNotes
typelocalone of stream, dgram, seqpacketone value; also accepted and matching nothing on Linux: none, raw, rdm, dccp, packet
addrlocal, or inside the group@pattern, none, autoabsent: any address or none; a path is an error
labelinside the group onlya pattern for the peer's profile nameunconfined and variables are accepted
protocol--named and refused
attr, opt, a local label--in apparmor.d(5), not in the parser (known discrepancy)

Permissions

PermissionLooks atKernel entry point
createfamily, type, protocolaa_unix_create_perm
bindthe address being boundaa_unix_bind_perm
listenlocal address, backlogaa_unix_listen_perm
acceptlocal address; with a group, the peer tooaa_unix_accept_perm, aa_unix_peer_perm
getopt, setoptlocal address, option nameaa_unix_opt_perm
getattr, setattr, shutdownlocal addressaa_unix_sock_perm
send, receive, connectlocal address, peer address, peer labelaa_unix_peer_perm
OperationAsked of the caller's profileAsked of the other end's profile
stream connectconnect send receive toward the listeneraccept send receive toward the caller (not for a listener with a file name)
datagram sendsend toward the receiverreceive toward the sender

Address kinds

KindIn a ruleIn the logMediated by
abstractaddr=@name (a pattern)addr="@name"the unix rule
unnamedaddr=noneaddr=nonethe unix rule
autobindaddr=autoaddr="@xxxxx", five hex digitsthe unix rule
file namenot written in addrthe paththe file rule for the path

Qualifiers

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

network unix and unix

You writeThe parser addsUsed by
network unix TYPE, (or any network rule that covers unix)a unix rule for that typekernels with fine-grained unix mediation
unix ... type=TYPE ...,network PERMISSIONS unix TYPE,kernels with family and type only
deny unix ...,nothing-
Warning (off by default)Option
downgrading extended network unix socket rule to generic network rule--warn=rule-downgraded
extended network unix socket rules not enforced--warn=rule-not-enforced
deny unix socket rule not enforced, can't be downgraded to generic network rule--warn=rule-not-enforced

The log record

apparmor="DENIED" operation="connect" class="net" profile=... pid=... comm=... family="unix" sock_type="stream" protocol=0 requested="..." denied="..." addr=... peer_addr=... peer=...

  • profile= is the profile that refused; peer= is the label of the other end.
  • info= reasons: failed local address match, failed local label match, failed cmd selection match, failed peer address match, failed peer label match, failed listen backlog match, failed sockopt match.
  • The caller sees EACCES, or EINVAL for a malformed address.

Errors

LineMessage
unix stream,syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE
unix addr=/run/demo.sock,unix rule: invalid value for addr='/run/demo.sock'
unix label=a,unknown rule: 'label' conditional is only valid in the peer expression
unix (send) peer=(label=a) type=stream,syntax error, unexpected TOK_CONDID, expecting TOK_END_OF_RULE
unix type=stream attr=foo,unix rule: invalid conditional 'attr'
owner unix,owner prefix not allowed on unix rules
unix (bind) peer=(addr=@demo),unix socket 'create', 'shutdown', 'setattr', 'getattr', 'bind', 'listen', 'setopt', and/or 'getopt' accesses cannot be used with peer socket conditionals
unix type=bogus,socket rule: invalid socket type 'bogus'
unix type=stream type=dgram,socket rule conditional "type" can only be specified once
unix type=(stream dgram),unknown rule: conditional 'type' only supports a single value
unix peer=(type=stream),unknown rule: 'type' conditional is not allowed in the peer expression
unix addr=@x addr=@y,unix socket conditional "addr" can only be specified once
unix protocol=0,unknown rule: 'protocol' conditional is not currently supported
unix addr=@foo[,Regex grouping error: Unclosed grouping or character class, expecting close }, then Unable to parse input line 'foo[', ERROR processing policydb rules for profile t, failed to load and ERROR generating policy re for profile t, failed to load (no line number; exit status 255)

for AppArmor developers for security researchers

The compiled chain

Prefix: class byte (15 with network_v9, else 14 with network_v8, else 4), AF_UNIX in two bytes, the type in two bytes or .., the protocol as .. (af_unix.cc:231-255).

RulePermissionsMatch string after the prefix
1createnothing
2bind without addr or with addr=auto\x00, label pattern, \x00
3shutdown setattr getattr bind acceptaddress, \x00, label pattern, \x00
4listenrule 3, \x02, .. (backlog)
5getopt setoptrule 3, \x04, .. (option name)
6send receive connect acceptrule 3, \x01, peer address, \x00, peer label pattern
  • Address encodings: abstract is a zero byte and the pattern; none is byte 0x01; auto is a zero byte and five [0-9a-f]; absent is .* (af_unix.cc:257-290).
  • Kernel entry points: af_unix.h:34-53; the peer walk is profile_peer_perm (af_unix.c:389-426).
  • demo's line 12 under abi/5.0 (tree, -D rule-exprs): \x0f\x00\x01\x00\x01...*\x00[^\000]*\x00\x01.*\x00demo-helper with 0x6.

for security researchers

Known discrepancies

  • The unix rule generated from network (PERMISSIONS) unix gets every permission (tree, mainline feature set; parser_yacc.y:762-777, af_unix.cc:105-125).
  • audit unix (getopt), marks both option bits as audited (code; af_unix.cc:631-637).
  • The unix class marker matches the family bytes 0x00 0x31 (tree; parser_regex.c:1339-1353). No effect found on the mainline kernel, which tests only the class start state.
  • deny unix rules are dropped when the kernel lacks fine-grained unix mediation, even where the downgrade would be exact: deny unix, and deny unix type=stream, have no address, label or peer conditional and could be written as deny network unix, but are dropped like the others; network, deny unix, then allows every unix socket operation and prints nothing by default (tree, feature set without fine-grained unix mediation; af_unix.cc:204-229).
  • The warning deny unix socket rule not enforced ... is printed also when the rule is compiled (tree; af_unix.cc:204-229).
  • The messages for type, protocol and label begin unknown rule: (af_rule.cc:66).
  • apparmor.d(5) documents attr=, opt= and a local label that the parser does not have (apparmor.d.pod:367).
  • The verdicts are in known bugs.

Roads from here

START HERE

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

QUALIFIERS

RULE CLASSES

RUNNING THE PARSER

IN THE KERNEL