Network rules
families and types for application developers for administrators for security researchers
A network rule allows socket operations for an address family and a socket type. Twelve permissions from create to receive can narrow it. A confined program with no matching rule gets EACCES from socket. What the rule compiles to depends on the kernel's feature set.
On the map: rule classes
▶ Watch this deck — 9 scenes, ~6 min
Worth seeing first
- The abi rule and the abi files — why a rule class may be accepted and enforce nothing
Part of journeys
- Write your first profile, step 8 of 12 · previous: The owner qualifier · next: Profiles for general-purpose apps
- Network, IPC and privileges, step 3 of 14 · previous: Capability rules · next: Rule conditionals
01 demo opens a socket
network FAMILY TYPE, allows sockets of that family and type. Without a matching rule a confined task gets EACCES from socket().
Demo is a network service, so the first thing it does is ask for a socket. Under a profile that isn't automatic. The kernel looks for a network rule that covers this family and this type, and if there's none, the socket call fails with EACCES. The rule is one line: network, the family, the type. Inet is IP version four. Stream is the connection-oriented type, which for inet means TCP. That's line eleven of demo's profile. Everything else demo does with the socket is checked against the same rule.
Details and sources
Details
- The LSM hook
socket_createasks for the permissioncreatewith the family, type and protocol of the call (lsm.c:1258-1291). It does nothing for sockets the kernel creates for itself and for an unconfined task (lsm.c:1265-1269). A refusal isEACCES. - A profile with no network rule refuses every socket when the feature set has network mediation (
network_v8, ornetwork_v9withaf_unix): every profile that is not in unconfined or default_allow mode then mediates networking, whether or not it has a network rule. The slide assumes such a feature set. - Feature files:
/sys/kernel/security/apparmor/features/network_v8/af_maskandnetwork_v9/af_mask(net.c:24-36). network inet stream,is line 11 of demo's profile. The programdemoand its profile are invented for the map.- Kernel statements are read from the kernel source and were not run.
02 network, permissions, family, type
[QUALIFIERS] network [PERMISSIONS] [FAMILY] [TYPE] [CONDITIONALS],. Each part left out means "all".
Everything after the keyword is optional. Network on its own allows all networking. Add a family and it's that family with all its types. Add a type and it's narrower again. If you want to limit what demo may do with the socket, put a permission list right after the keyword, before the family, and use parentheses when there's more than one. A single word that isn't a family name is taken as a type, so network tcp covers TCP over both IP versions. Address and port conditionals come last, and they have their own deck.
Details and sources
Details
- Accepted by the tree's parser:
network inet,,network inet tcp,,network tcp,,network stream,,network (create, bind listen) inet,,network create inet stream,,network rw inet,,network "inet",,audit deny network,,prompt network inet,. - There is no third word after family and type.
- Qualifiers:
audit,deny,allowandpromptare taken.priority=andownerare refused:priority prefix not allowed on network rules,owner prefix not allowed on network rules(network.h:270-276). - Rules for the same family merge.
Read more
for AppArmor developers for security researchers
In the code
- Three
network_ruleproductions (parser_yacc.y:1154-1194); the permission list at parser_yacc.y:1409-1415. - The scanner state
NETWORK_MODE(parser_lex.l:627-694, entered at parser_lex.l:870-872); the constructors at network.cc:489-603.
03 Families, types and three aliases
Family = the AF_ name in lower case (45 of them); type = stream, dgram, seqpacket, rdm, raw, packet; tcp, udp, icmp are aliases. Names are case sensitive.
The words map straight onto the socket call. The family is the AF constant in lower case, without the prefix: inet, inet6, netlink, unix. The type is the sock constant, the same way: stream, dgram, raw. For convenience tcp means stream and udp means dgram, and the parser produces exactly the same policy either way. The resolver sockets in the nameservice abstraction are a good real example. What you can't do is name a protocol by number. There's no word for SCTP, so an SCTP socket is matched by its type.
Details and sources
Details
- The 45 family names come from base_af_names.h:1-46; the table is in the reference below.
- Aliases (network.cc:124-153): for
inet,tcpisstream,udpisdgramandicmpisraw; forinet6,tcpandudp.network inet stream,andnetwork inet tcp,give identical output (run with the tree's parser). - Refused with
Invalid network entry.:network inet dccp,,network inet sctp,,network inet6 icmp,,network inet icmpv6,,network bogus,,network INET,,network local,. - The parser does not consult the kernel's
af_mask: a family the kernel lacks is compiled anyway. - The kernel matches the type recorded on the socket (net.c:237) and has a separate hook for SCTP bind and connect (lsm.c:1409-1424; feature
network_v8/sctp). - A real example: abstractions/nameservice:92-99.
- Known discrepancy: with a feature set that has
af_inet,network inet icmp,carries protocol value 2 rather than 1 (network.cc:148-149). It is not relevant to the mainline kernel, which matches no protocol for inet rules. - Kernel statements are read from the kernel source and were not run.
Read more
for AppArmor developers for security researchers
In the code
network_mappings[]is built from the generatedaf_names.h, six rows per family (network.cc:124-160); the names are checked against the build host's headers (Makefile:391-402).net_find_mapping: network.cc:288-333.
04 Twelve permissions, one per step
create bind listen accept connect shutdown getattr setattr getopt setopt send receive. Each socket call requests one; a rule without a list grants all.
If family and type are too coarse, the permission list says which operations are allowed. They follow the life of a socket. Create for the socket call. Setopt and getopt for options. Bind, listen and accept for a server, connect for a client. Send and receive for the data. Getattr for asking the socket its name, and shutdown at the end. A rule with no list has all of them, which is what line eleven does. A server that should not dial out could leave connect off the list. You can also write read and write for receive and send.
Details and sources
Details
- Hook, operation name in the log, permission:
socket_create,create, create (lsm.c:1258-1291);socket_bind,bind, bind (lsm.c:1372-1388);socket_connect,connect, connect (lsm.c:1390-1407);socket_listen,listen, listen (lsm.c:1426-1440);socket_accept,accept, accept (lsm.c:1446-1461);socket_sendmsg,sendmsg, send (lsm.c:1483-1502);socket_recvmsg,recvmsg, receive (lsm.c:1504-1508);socket_getsocknameandsocket_getpeername, getattr (lsm.c:1527-1535);socket_getsockoptandsocket_setsockopt, getopt and setopt (lsm.c:1555-1567);socket_shutdown, shutdown (lsm.c:1569-1572). - Other spellings:
readorrforreceive,writeorwforsend, andrw. - Sending with
MSG_FASTOPENon TCP or MPTCP is also checked as connect (lsm.c:1490-1499; featuretcp-fast-open). - A socket used through
readandwrite, or passed over a unix socket, is checked again as send and receive when the label cached on the file does not cover the task (file.c:551-573). - No socket hook requests
setattr. - Local permissions (
create,shutdown,setattr,getattr,bind,listen,setopt,getopt) cannot be combined with peer conditionals; the peer permissions aresend,receive,connectandaccept. - Kernel statements are read from the kernel source and were not run.
Read more
- apparmor.d(5), Network permissions.
- Unix socket rules: the same twelve permissions.
for AppArmor developers for security researchers
In the code
- Bit values: network.h:39-61; the words in the grammar: parser_yacc.y:1356-1407.
map_perms()folds the bits before they go into the policydb (network.h:114-120); the kernel'smap_other()unfolds them (policy_compat.c:197-202). Kernel names: net.h:22-39.
05 What demo and the log see
Network denials return EACCES and log family=, sock_type=, protocol=, requested= and denied=. Records for connected inet sockets add laddr, lport, faddr, fport.
Demo's rule says inet. One day it's started with an IP version six address. The socket call fails with EACCES, and demo probably reports permission denied. The log has the answer: operation="create", the family, the socket type, and which permission was denied. Those three words are your rule. For calls on a connected socket, the record also carries the local and remote address and port, which helps you see who demo was talking to. And remember: a deny rule refuses the same way, silently.
Details and sources
Details
- The first record on the slide is built from the kernel's format strings (
family=,sock_type=,protocol=,requested=,denied=; net.c:38-78, net.c:118-166) with demo's values, which are illustrative. - The second record is shortened from testcase_network_04.in. That older sample has no
requested=anddenied=fields. laddr,lport,faddrandfportcome from the common LSM audit code, for sockets other than unix (lsm_audit.c:297-314).- A family the kernel has no name for is logged as
unknown(N). Theinfo=reasons arefailed af match,failed type matchandfailed protocol match(net.c:234-247). - Operation names:
create,bind,connect,listen,accept,sendmsg,recvmsg,getsockname,getpeername,getsockopt,setsockopt,socket_shutdown(audit.h:75-87). The class is alwaysnet. - The check uses the label of the calling task and asks each confined profile of it (net.c:282-284, net.c:301-303).
- Kernel statements are read from the kernel source and were not run.
Read more
06 The same line on three kernels
With network_v8 or network_v9 the rule keeps its permissions; with only the legacy network feature it is reduced to family and type; with none it is dropped. Use --warn=rule-not-enforced --warn=rule-downgraded to be told.
What you've seen so far is what a current kernel does. The parser compiles each rule for the kernel's feature set, or for the one your abi line pins, and network rules have changed shape over the years. With the current form, the rule keeps its permissions. For an old kernel that only knows the first form, the rule becomes just family and type, and connect-only quietly becomes everything. With no network feature at all, the rule is dropped. None of this is announced unless you ask. Run the parser with the two warn options and it tells you.
Details and sources
Details
- The three results on the slide were produced with the tree's parser and three feature files: with only the legacy feature,
network (connect) inet stream,gives the same output asnetwork inet stream,; with no network feature, every network rule gives the output of a profile without it. Nothing was loaded into a kernel. - The feature tests are
network,network_v8,network_v9,network_v8/af_inet,network_v9/af_inet,network/af_unix,network_v9/af_unix,network_v9_skbandnetwork_v9_skb/iface. Each is the intersection of the kernel feature set and the policy ABI (parser_main.c:1044-1073). - The mainline kernel exports
network_v8withaf_mask,tcp-fast-openandsctp, andnetwork_v9withaf_mask,af_unixandtcp-fast-open(net.c:24-36, apparmorfs.c:2688-2689). It has no reader for the legacy per-family table. - Warnings, all off by default:
network rules not enforced,profile NAME network rules not enforced(network.cc:669-672),downgrading extended network unix socket rule to generic network rule(af_unix.cc:537). - Where to look:
/sys/kernel/security/apparmor/features/network_v8/andnetwork_v9/, oraa-features-abi -x.
for security researchers
Attack surface
- The compiled rule can be broader than the text. On a legacy-only feature set the permission list and all conditionals are lost (network.cc:1138-1167, parser_interface.c:572-584).
- Conditionals that the feature set cannot express (
ip=,port=,label=,interface=) are dropped without a message at any warning level, also fromdenyrules: see Network address conditionals. - Every network rule that covers
AF_UNIXalso creates aunixrule. Known discrepancy (run with the tree's parser): the permission list is not carried into it, so with the mainline feature setnetwork (create) unix stream,allows every operation on abstract and unnamed unix stream sockets, andnetwork (create),does the same for all unix types (af_unix.cc:105-125): see Unix socket rules. - Known discrepancy (run with the tree's parser): on the legacy-only feature set the parser prints
network rules not enforcedalthough it writes the table. - Not mediated by these rules: sockets the kernel creates for itself (lsm.c:1265-1266), and the packet path: the secmark hooks act only on profiles with a secmark table, which this parser does not write (net.c:371-403).
07 Class, family, type: five bytes for AppArmor developers for security researchers
network.cc:1000-1038 writes class, family, type; net.c:228-274 walks them and reads the permissions at the type state.
On a current feature set, each family in a rule becomes one policydb rule: the class byte, fifteen for version nine, two bytes of family, two of type, and the folded permission bits attached to that state. In the kernel, every socket hook dispatches on the family. For the generic path, aa_profile_af_perm starts at the class, feeds the family and the type, and takes the permissions right there, only going on to the protocol if the state asks for it. The class marker rules are why a profile with no network rule still denies sockets.
Details and sources
for AppArmor developers for security researchers
Details
- The bytes
0f 00 02 00 01and the permission value 0x40 were produced with the tree's parser and the mainline feature file, fornetwork (connect) inet stream peer=(ip=10.0.0.1 port=80),, which compiles to the same single rule as the line on the slide. - Classes:
AA_CLASS_NET4,AA_CLASS_NETV814,AA_CLASS_NETV915,AA_CLASS_NETV9_SKB30 (policydb.h:28, policydb.h:38-39, policydb.h:54). - In the kernel
RULE_MEDIATES_NETtries class 15 and falls back to the kernel'sAA_CLASS_NET, which is 14 (policy.h:346-358, apparmor.h:30-31). The walk: net.c:192-274. - All six types together (
ALL_TYPES, 0x43e) become..in the match string (network.cc:40, network.cc:1009-1029). - The legacy table
net_allowed_afholds, per family, three u16 values: allow without deny, allowed and audited, deny and quiet (parser_interface.c:572-582). - The rule class is mergeable and compared by family map and conditionals (network.cc:1301-1314). The grammar action also creates the unix rule and updates the legacy table (parser_yacc.y:757-779).
- The class markers are added for every confined profile at parser_regex.c:1415-1440.
- Known discrepancy: the unix class-marker rule matches the family bytes 0x00 0x31 instead of 0x00 0x01 (parser_regex.c:1339-1353). No effect was found for the mainline kernel.
- 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
At most a family and a type; permissions first and in parentheses when several; no priority= and no owner.
A network rule takes at most two words, so inet stream tcp is one too many: tcp already means stream. The names are lower case. Permissions go before the family, not after. Two permissions without parentheses stop the parser at the second. Network rules are one of the few classes that refuse priority, and they refuse owner too. And a permission that's about your own socket, like bind, can't be combined with conditions on the peer.
Details and sources
Details
- The parser prints an error as
AppArmor parser error for FILE in profile FILE at line N: MESSAGE; the slide shows MESSAGE, produced by the tree's parser. The messages of rows 3 and 4 continue with the tokens the parser expected. - The full text of the last message:
network 'create', 'shutdown', 'setattr', 'getattr', 'bind', 'listen', 'setopt', and/or 'getopt' accesses cannot be used with peer socket conditionals(network.cc:526). - An unknown word in the permission list is read as
randwletters:network (bogus) inet,givesInternal: unexpected net perms character 'b' in input, andnetwork (rwx) inet,the same forx. owner network inet,givesowner prefix not allowed on network rules(network.h:270-276).network inet xattrs=(a=b),givesnetwork rule: invalid conditional group xattrs=().- Failing examples in the tree: the
network_bad_*.sdfiles in parser/tst/simple_tests/network.
Read more
09 Finer rules for two families
Next: address conditionals, unix rules, and the feature set of your kernel.
Family and type are the coarse grid. Two families have finer rules: inet and inet6, with address and port conditionals, and unix sockets, with their own rule class. Low ports and raw sockets also need a capability. And since so much here depends on the kernel, the features deck and the upstream and Ubuntu deck tell you what yours enforces.
Details and sources
Details
[QUALIFIERS] network [PERMISSIONS] [FAMILY] [TYPE] [CONDITIONALS],: each part left out means all.- A refused socket operation returns
EACCESand is logged withfamily=,sock_type=anddenied=. - What a rule compiles to depends on the feature set;
--warn=rule-not-enforced --warn=rule-downgradedmakes the parser say so. - 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), with nothing loaded into a kernel; "code" means the parser source or the kernel source was read, not run. Nothing here was observed on a running kernel.
Grammar
NETWORK RULE: [QUALIFIERS] network [PERMISSIONS] [FAMILY] [TYPE] [CONDITIONALS] , PERMISSIONS: PERMISSION | ( PERMISSION ... ) QUALIFIERS: [audit] [allow|deny|prompt]
- Every part after the keyword is optional and means "all" when left out (tree).
- A permission list comes before the family; more than one permission needs parentheses; inside them blanks or commas separate (tree).
- The first word is looked up as a family; a single word that is not a family is looked up as a type or alias across all families:
network tcp,is inet and inet6 stream (tree). - At most two words. Names are case sensitive (tree).
- Conditionals (
ip=,port=,peer=( )) are in syn-network-inet.
Families
The name is the kernel's AF_ constant in lower case (parser/base_af_names.h).
| Name | Constant | Number |
|---|---|---|
unspec | AF_UNSPEC | 0 |
unix | AF_UNIX | 1 |
inet | AF_INET | 2 |
ax25 | AF_AX25 | 3 |
ipx | AF_IPX | 4 |
appletalk | AF_APPLETALK | 5 |
netrom | AF_NETROM | 6 |
bridge | AF_BRIDGE | 7 |
atmpvc | AF_ATMPVC | 8 |
x25 | AF_X25 | 9 |
inet6 | AF_INET6 | 10 |
rose | AF_ROSE | 11 |
netbeui | AF_NETBEUI | 13 |
security | AF_SECURITY | 14 |
key | AF_KEY | 15 |
netlink | AF_NETLINK | 16 |
packet | AF_PACKET | 17 |
ash | AF_ASH | 18 |
econet | AF_ECONET | 19 |
atmsvc | AF_ATMSVC | 20 |
rds | AF_RDS | 21 |
sna | AF_SNA | 22 |
irda | AF_IRDA | 23 |
pppox | AF_PPPOX | 24 |
wanpipe | AF_WANPIPE | 25 |
llc | AF_LLC | 26 |
ib | AF_IB | 27 |
mpls | AF_MPLS | 28 |
can | AF_CAN | 29 |
tipc | AF_TIPC | 30 |
bluetooth | AF_BLUETOOTH | 31 |
iucv | AF_IUCV | 32 |
rxrpc | AF_RXRPC | 33 |
isdn | AF_ISDN | 34 |
phonet | AF_PHONET | 35 |
ieee802154 | AF_IEEE802154 | 36 |
caif | AF_CAIF | 37 |
alg | AF_ALG | 38 |
nfc | AF_NFC | 39 |
vsock | AF_VSOCK | 40 |
kcm | AF_KCM | 41 |
qipcrtr | AF_QIPCRTR | 42 |
smc | AF_SMC | 43 |
xdp | AF_XDP | 44 |
mctp | AF_MCTP | 45 |
Rules that cover unix also create a unix rule; see syn-unix.
Types and aliases
| Word | Constant | Alias |
|---|---|---|
stream | SOCK_STREAM | tcp for inet and inet6 |
dgram | SOCK_DGRAM | udp for inet and inet6 |
raw | SOCK_RAW | icmp for inet |
seqpacket | SOCK_SEQPACKET | |
rdm | SOCK_RDM | |
packet | SOCK_PACKET |
There is no word for a protocol number: network inet sctp, and network inet dccp, are refused (tree).
Permissions
| Word | Also written | Side | Requested by (LSM hook) | Operation in the log |
|---|---|---|---|---|
create | local | socket_create | create | |
bind | local | socket_bind | bind | |
listen | local | socket_listen | listen | |
accept | peer | socket_accept | accept | |
connect | peer | socket_connect | connect | |
send | write, w | peer | socket_sendmsg | sendmsg |
receive | read, r | peer | socket_recvmsg | recvmsg |
getattr | local | socket_getsockname, socket_getpeername | getsockname, getpeername | |
setattr | local | none | ||
getopt | local | socket_getsockopt | getsockopt | |
setopt | local | socket_setsockopt | setsockopt | |
shutdown | local | socket_shutdown | socket_shutdown |
- A rule without a list grants all twelve (code).
rwissendandreceive. - Local permissions cannot be combined with peer conditionals (tree).
- The hooks are read from
linux:security/apparmor/lsm.c:1258-1572, not from a run.
Qualifiers
| Seat | On a network rule |
|---|---|
priority= | refused: priority prefix not allowed on network rules (tree) |
audit | taken |
allow, deny, prompt | taken: deny is not logged; prompt is in syn-prompt |
owner, other | refused: owner prefix not allowed on network rules (tree) |
What depends on the feature set
| The feature set has | The rule is compiled as | Lost |
|---|---|---|
network_v8 or network_v9 | family, type and permissions | conditionals, unless it also has af_inet: see syn-network-inet |
only the legacy network | family and type | the permission list and all conditionals |
| no network feature | nothing: the rule is dropped | everything; networking is not mediated |
- Results from the tree's parser with three feature files (tree).
- The parser reports this only with
--warn=rule-not-enforcedand--warn=rule-downgraded; both are off by default (code). - See adm-features, syn-abi and upstream-and-ubuntu.
The log record
| Field | Meaning |
|---|---|
operation= | the socket operation, see the permission table |
class="net" | always |
family= | the family name, or unknown(N) |
sock_type= | the socket type |
protocol= | the protocol number |
requested=, denied= | permission names |
laddr=, lport=, faddr=, fport= | local and remote address and port, for sockets other than unix |
info= | failed af match, failed type match or failed protocol match |
Read from the kernel's format strings (linux:security/apparmor/net.c:38-166, linux:security/lsm_audit.c:297-314).
Errors and warnings
| Rule | Message |
|---|---|
network inet stream tcp, | syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE |
network INET stream, | Invalid network entry. |
network inet sctp, | Invalid network entry. |
network inet create, | syntax error, unexpected TOK_CREATE, expecting TOK_END_OF_RULE |
network send receive inet, | syntax error, unexpected TOK_RECEIVE, expecting TOK_END_OF_RULE |
network (bogus) inet, | Internal: unexpected net perms character 'b' in input |
priority=1 network inet, | priority prefix not allowed on network rules |
owner network inet, | owner prefix not allowed on network rules |
network (bind) inet peer=(port=8080), | network 'create', 'shutdown', 'setattr', 'getattr', 'bind', 'listen', 'setopt', and/or 'getopt' accesses cannot be used with peer socket conditionals |
network inet xattrs=(a=b), | network rule: invalid conditional group xattrs=() |
any network rule, no network feature, --warn=rule-not-enforced | warning network rules not enforced |
a unix rule on a feature set without unix mediation, --warn=rule-downgraded | warning downgrading extended network unix socket rule to generic network rule |
All rows are from the tree's parser.
for AppArmor developers
Encoding
- Per family one policydb rule: the class byte (
AA_CLASS_NETV915, orAA_CLASS_NETV814), two bytes of family and two of type, big endian, with the folded permissions at that state (parser/network.cc:1000-1038).network (connect) inet stream,is\x0f\x00\x02\x00\x01with 0x40 (tree). - All six types become
..(parser/network.cc:1009-1029). - Class markers for classes 14 and 15 are added to every confined profile (
parser/parser_regex.c:1415-1440), which is why a profile without network rules refuses sockets. - The legacy table
net_allowed_af: per family three u16 values (parser/parser_interface.c:572-582). - Kernel: every socket hook dispatches on the family; the generic match
aa_profile_af_permstarts at the class, feeds family and type and reads the permissions there (linux:security/apparmor/net.c:192-274). - Grammar and scanner:
parser/parser_yacc.y:1154-1194,parser/parser_lex.l:627-694.
for security researchers
Known discrepancies
None of these is taught as intended behaviour; the verdicts come from the review.
network (PERMISSIONS) unix ...creates a unix rule with every permission (tree): see syn-unix.- inet conditionals are dropped without a message when the feature set has no
af_inet, also fromdenyrules (tree): see syn-network-inet. network inet icmp,carries protocol value 2 on a feature set withaf_inet(code).- The unix class-marker rule matches the family bytes 0x00 0x31 (code).
- On a legacy-only feature set the parser prints
network rules not enforcedalthough it writes the table (tree).
Roads from here
START HERE
- Upstream and Ubuntu kernels — which kernel enforces which part
- The profile language at a glance — every kind of line on one page
PREAMBLE AND REUSE
- The abi rule and the abi files — pinning the feature set a profile is compiled for
QUALIFIERS
- allow and deny — deny and why it is quiet
RULE CLASSES
- Network address conditionals — address and port conditionals for inet and inet6
- Unix socket rules — unix sockets and the unix rule every network unix rule creates
- Capability rules — net_bind_service and net_raw are separate rules
- Rule conditionals — the shared conditional syntax
IN PRACTICE · general-purpose apps
- Choosing abstractions — the nameservice abstraction and its network rules
SECURITY · threat model and limits
- What is not mediated — what network rules do not see
RUNNING THE PARSER
- Kernel features and the policy ABI — reading the kernel's feature set
- Reading a denial — reading a network denial