Network address conditionals
ip, port, interface for application developers for administrators for security researchers
Network rules for inet and inet6 accept ip= port= interface= and label= and a peer=( ) group for the remote end. The parser checks and compiles them only for a feature set that has af_inet. The mainline kernel has none and checks family type and protocol only so there the conditionals are dropped at compile time without a message.
On the map: rule classes
▶ Watch this deck — 9 scenes, ~6 min
Worth seeing first
- Network rules — the family and type rule these conditionals narrow
- Rule conditionals — conditionals and the peer group that goes last
- Capability rules — the capability a low port still needs
Part of journeys
- Network, IPC and privileges, step 5 of 14 · previous: Rule conditionals · next: Unix socket rules
01 Only this address, only this port
ip= and port= restrict an inet or inet6 network rule to a local address and port. Whether they are enforced depends on the kernel's feature set.
Line eleven of demo's profile lets it use any TCP socket over IP version four: any local port, any remote host. Often you know more than that. Demo listens on localhost, port 8080, and nowhere else. The network rule has conditionals for it: ip= an address, port= a number. They restrict the rule to sockets with that local address and port. Hold on to one thing before you rely on them, though. Whether they're enforced depends on the kernel, and we'll get to that in a moment.
Details and sources
Details
- The conditionals exist for
inetandinet6only. With one of them and no family word, the rule coversinetandinet6(network.cc:503-511). With any other family it is an error:network family does not support local or peer conditionals(network.cc:551-554). - They are compiled only when the feature set has
network_v8/af_inetornetwork_v9/af_inet(network.cc:1031); see "Compiled only for a kernel that has af_inet" in this deck. - The slide shows what the rule means as written. The addresses are documentation examples.
- Test file: network/network_ok_20.sd.
02 Local conditionals, then the peer group
network [PERMS] [inet|inet6] [TYPE] [ip=A] [port=N|N-M] [interface=I] [label=L] [peer=(ip=A port=N label=L)],.
The conditionals come after the family and the type. First the ones about your own socket: ip, port, interface and label. Then, last, the peer group in parentheses, with the remote address, the remote port and a label. So a server rule talks about its local port, and a client rule talks about the peer it dials. Each conditional can appear once, and the operator is the plain equals sign. The peer group follows the rules of the conditionals deck: it goes last, and there's only one.
Details and sources
Details
- Accepted by the tree's parser:
network inet ip=::1 port=80-90,,network inet ip=none,,network inet6 ip=1.2.3.4,,network stream ip=1.2.3.4,,network (connect) inet peer=(ip=1.2.3.4 port=80),. - A conditional given twice:
network conditional "ip" can only be specified once(parser_misc.c:1243). interfaceis local only:interface cannot be set for peer in network rules(network.cc:497-498).label:=NAMEis accepted only inside the group, and the parser marks its value unused (network.h:144; network/skb/ok_setlabel_peer_1.sd).
Read more
for AppArmor developers for security researchers
In the code
network_rule::move_conditionals(network.cc:445-477); the group is passed withpeer = true(network.cc:496).has_local_condsandhas_peer_conds: network.h:225-226.
03 One address, one port or one range
ip= takes one IPv4 or IPv6 address or none: no prefix, no range. port= takes N or N-M up to 65535; port=0 means any port.
The values are deliberately simple. Ip takes one address, version four or version six, or the word none. There's no slash prefix and no range, so you can't write a subnet. Port takes a decimal number up to sixty-five thousand five hundred and thirty-five, or two numbers with a dash for a range, low one first. Port zero is special: it compiles as any port, which fits a socket that hasn't been bound yet. Get a value wrong and the message quotes it back to you.
Details and sources
Details
ip=is parsed as one address (network.cc:335-361, network.cc:415-423):ip=1.2.3givesnetwork invalid ip='1.2.3'. An IPv4 address is accepted in aninet6rule.port=0is compiled as any port number (network.cc:725-731).- Test files:
network ip=127.0.0.1 port=8080,,port=0andport=65535in network/network_ok_20.sd;network port=0-65534,andnetwork peer=(port=1-65535),in network/port-torture.sd. - The messages on the slide were produced by the tree's parser.
- Known discrepancy: a value list is accepted and only its first value is used:
network inet port=(80 81),andnetwork inet port=80,give byte-identical output (run with the tree's parser).
04 Which permissions go with which side
Local conditionals narrow any permission. peer=( ) can be combined only with connect, accept, send and receive.
A connection has two ends, and the conditionals follow that. Things you do to your own socket, like bind, listen and setting options, can only be narrowed by the local address and port. Things that involve the other end, connect, accept, send and receive, can also be narrowed by the peer group. Mix them the wrong way and the parser refuses: you can't bind with a condition on the peer. And a reminder from the capability deck. A rule that lets demo bind port eighty doesn't give it the capability for low ports.
Details and sources
Details
- The local and peer permission sets: network.h:66-77.
- The full message:
network 'create', 'shutdown', 'setattr', 'getattr', 'bind', 'listen', 'setopt', and/or 'getopt' accesses cannot be used with peer socket conditionals(network.cc:526); produced by the tree's parser. Test file: network/perms/bad_opt_2.sd. network (accept) inet peer=(ip=1.2.3.4),is accepted.- In the compiled layout a
bindrule with a port below 1024 is marked as a privileged port (network.cc:815-868). The capability is a separate rule: Capability rules. - Known discrepancy: a peer
labelalone does not count as a peer conditional, sonetwork (bind) peer=(label=foo),is accepted and the rule is not limited to inet and inet6 (network.h:226; run with the tree's parser).
05 Compiled only for a kernel that has af_inet
Without af_inet in the feature set, ip=, port= and the peer group are dropped at compile time and the rule is network FAMILY TYPE,. The mainline kernel exports no af_inet. No warning is printed.
Here's the catch. The parser only compiles addresses and ports when the kernel's feature set says it can check them, with a feature called af_inet. The ABI file that ships with AppArmor lists it. The mainline kernel doesn't export it, and its inet code checks family, type and protocol, and nothing more. So for that kernel your carefully narrowed rule compiles to exactly the same policy as plain network inet stream. And the parser doesn't tell you, whatever warnings you turn on. Look in the features directory: if there's no af_inet file, these conditionals do nothing.
Details and sources
Details
- Run with the tree's parser: with the mainline kernel's feature file as kernel and policy features,
network inet,andnetwork inet ip=1.2.3.4 port=80,give byte-identical output and no warning with--warn=all; with abi/5.0 they differ. Nothing was loaded into a kernel. - The feature tests are
network_v8/af_inetandnetwork_v9/af_inet, each the intersection of the kernel feature set and the policy ABI (parser_main.c:1044-1073). The tree's abi/5.0 listsaf_inet(abi/5.0:66-80). - What the mainline kernel exports: net.c:24-36, apparmorfs.c:2688-2689.
- Its inet code gathers the local and remote address for the audit record and then calls the family, type and protocol check without using them (af_inet.c:62-230, af_inet.c:233-325). Denial records therefore carry
laddr,lport,faddrandfportalthough no rule can match on them. - Malformed addresses are refused with
EINVALorEAFNOSUPPORTbefore the policy check (af_inet.c:116-135, af_inet.c:176-224). interface=needsnetwork_v9_skb/iface, which onlyprofiles/apparmor.d/abi/5.0-interfacelists and the mainline kernel does not export.label=on inet sockets is not matched by the mainline kernel.- Check a running kernel with
ls /sys/kernel/security/apparmor/features/network_v8/oraa-features-abi -x. - Kernel statements are read from the kernel source and were not run.
06 Known discrepancies: rules that end up wider for security researchers
Known discrepancies: without af_inet, address conditionals are dropped from allow and deny rules alike; peer=(label=...) alone compiles to network,; a value list keeps its first value. The parser prints nothing.
For a reviewer this is the part that matters. When the feature set can't express a conditional, the parser doesn't refuse the rule and doesn't warn. It drops the conditional. An allow rule becomes broader: every inet socket. A deny rule becomes broader too, and that one can break things: a deny for one address denies the whole family. The unix rules don't widen a deny; they drop it. Network rules widen it. Two more: a peer label on its own turns into a rule for every family, and a list of ports keeps only the first. All four are on the known bugs list.
Details and sources
for security researchers
Details
- All four rows were run with the tree's parser: the two lines of a row give identical compiled output, with exit status 0 and no warning. The first three use the mainline kernel's feature set. The addresses on the slide are illustrative; the runs used
ip=1.2.3.4 port=80andpeer=(label=foo). Nothing was loaded into a kernel. - Where it happens: the early return for the generic form (network.cc:1031-1039, network.cc:1138-1167).
- The unix class does not downgrade
denyrules, because the downgrade makes the rule less specific (af_unix.cc:204-229). has_peer_conds()tests only the peer address and port (network.h:226).- To check a profile: compile it with
apparmor_parser -S -K(or-Q -D rule-exprs) with and without the conditional, and compare. - Enforcement exists on kernels that export
af_inet: see Upstream and Ubuntu kernels.
for security researchers
Attack surface
- A profile audited on paper as "may only talk to 10.0.0.5:5432" grants all of inet stream on a kernel without
af_inet. - A profile whose author added
deny network inet ip=...as a block list loses all inet networking, which invites replacing it with a broad allow. - The feature set is the kernel's, or the pinned
abi: a profile pinned to abi/5.0 and loaded on a kernel withoutaf_inetis compiled for the intersection. interface=behaves the same withoutnetwork_v9_skb/iface.- Known discrepancy: the manual page documents a local
label:=that cannot be written.
for security researchers
Read more
07 The inet layout after the type for AppArmor developers for security researchers
network.cc:870-998, 1058-1133 writes the inet layout; af_inet.c:233-325 in the mainline kernel checks only family, type and protocol.
When af_inet is in the feature set, gen_net_rule keeps going after the type. A protocol, then the peer's port type and port, an address size byte and the address, a label pattern. Then a command byte, and the same layout again for the local side, with extra commands for listen and for socket options. A port range is split into byte ranges. That's the encoding. On the kernel side of this tree, af_inet.c collects both addresses, but only for the audit record, and every permission function ends in the plain family, type and protocol check.
Details and sources
for AppArmor developers for security researchers
Details
- The byte string was produced with the tree's parser, abi/5.0 and
-D rule-exprs:\x0f\x00\x02\x00\x01..\x02\x00\x50\x01\x0a\x00\x00\x01\x00[^\000]*\x00\x01..., followed by the three alternatives for the local address, with permission 0x40. demo's own line 11 under abi/5.0 gives acreaterule on\x0f\x00\x02\x00\x01and the address layout with 0x1fc076. - Port type bytes: 0 unprivileged, 1 privileged, 2 remote (network.cc:815-868). Address-size byte: 0 none, 1 IPv4, 2 IPv6 (network.h:83-87).
- Port ranges are split into byte ranges (network.cc:719-765);
port=0becomes..(network.cc:725-731). - Command bytes:
CMD_ADDR1, listen 2, option 4 (network.cc:1096-1133). The layout: network.cc:870-998, network.cc:1058-1133. - The interface pattern lives in a second rule set of class
AA_CLASS_NETV9_SKB, 30 (network.cc:929-962, network.cc:1163-1165), which the kernel defines (apparmor.h:39) and uses nowhere else.set_labeland theAA_SET_LABELpermission for send rules belong to that class (network.cc:955-956). - The kernel's inet functions: af_inet.c:233-325.
- Known discrepancy:
network inet icmp,writes protocol value 2 where protocols are emitted. - Kernel statements are read from the kernel source and were not run.
for AppArmor developers for security researchers
Read more
- Network rules, scene "Class, family, type: five bytes".
- The policydb match, rule classes in the parser.
08 Mistakes and their messages
Values and placement are checked at parse time. A rule that parses is not proof that its conditionals are enforced.
The parser validates these conditionals even when it's going to drop them. An address with a prefix length isn't an address. A port has to fit in sixteen bits. The conditionals only belong to inet and inet6, so a unix or netlink rule with a port is refused. Interface is local only. := is only for a label, and outside the peer group it can't be written at all. An accepted rule, then, tells you the syntax is right. It doesn't tell you the kernel enforces it.
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. - Sources of the messages: network.cc:551-554 (family), network.cc:497-498 (interface in the group), network.cc:459 (operator).
network invalid interface='NAME'(network.cc:471).unsupported operator in label conditional of network rulesforlabel in (...)(network.cc:457).network inet port=90-80,givesnetwork invalid port='90-80'. A conditional given twice:network conditional "ip" can only be specified once.
09 Check the kernel before you rely on it
Address conditionals need af_inet in the kernel's feature set. Family and type are enforced everywhere network mediation exists.
So: the conditionals are real syntax, the parser checks them carefully, and a kernel with af_inet enforces them. On the mainline kernel, what holds is family and type. The upstream and Ubuntu deck says which kernels have what, and the features deck shows how to look. If you want fine-grained socket rules that the mainline kernel does enforce, that's the unix deck.
Details and sources
Details
ip=,port=,interface=,label=andpeer=(ip= port= label=)oninetandinet6network rules.- Compiled only for a feature set with
af_inet; otherwise dropped without a message, and the rule is its family and type. - 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. "The mainline kernel" is the kernel tree named on the page; other kernels are in upstream-and-ubuntu.
Grammar
NETWORK RULE: [QUALIFIERS] network [PERMISSIONS] [inet|inet6] [TYPE] [LOCAL ...] [peer=( PEER ... )] , LOCAL: ip=ADDRESS | port=N | port=N-M | interface=NAME | label=PATTERN PEER: ip=ADDRESS | port=N | port=N-M | label=PATTERN | label:=NAME
- The conditionals follow family and type; the peer group is last and written once (tree).
- With a conditional and no family word the rule covers
inetandinet6; any other family is an error (tree). - Each conditional may appear once (tree).
- The rest of the rule is in syn-network; the shared syntax in syn-rule-conditionals.
Conditionals
| Name | Side | Value | Operator | Needs in the feature set | On the mainline kernel |
|---|---|---|---|---|---|
ip | local, peer | one IPv4 or IPv6 address, or none | = | af_inet | dropped at compile time |
port | local, peer | N or N-M, 0 to 65535; 0 is any port | = | af_inet | dropped at compile time |
interface | local | a pattern | = | network_v9_skb/iface | dropped at compile time |
label | local, peer | a pattern | =; := inside peer=( ) | af_inet | not matched |
"Dropped" is from runs of the tree's parser with the mainline kernel's feature file; that the kernel checks only family, type and protocol for inet sockets is from its source (linux:security/apparmor/af_inet.c:233-325).
Values
ip: parsed as a single address. No prefix length, no range, no host name. An IPv4 address is accepted in aninet6rule (tree).port: decimal. A range isLOW-HIGH.port=0compiles as any port number (code).interface,label: patterns in the globbing syntax (code).label:=NAME: accepted only insidepeer=( ); the parser marks the value unused (code).- Known discrepancy: a value list such as
port=(80 81)is accepted and only the first value is used (tree).
Permissions per side
| Side | Permissions |
|---|---|
| local | create, shutdown, setattr, getattr, bind, listen, setopt, getopt |
| peer | connect, accept, send, receive |
- Local conditionals may narrow any permission. The peer group may be combined only with the peer permissions: otherwise
network 'create', 'shutdown', 'setattr', 'getattr', 'bind', 'listen', 'setopt', and/or 'getopt' accesses cannot be used with peer socket conditionals(tree). - A
bindrule for a port below 1024 does not replacecapability net_bind_service,; see syn-capability.
Feature sets
| Feature set | af_inet | network_v9_skb/iface |
|---|---|---|
the tree's abi/5.0 | listed | not listed |
the tree's abi/5.0-interface | listed | listed |
| the mainline kernel | not exported | not exported |
- The parser uses the intersection of the kernel feature set and the policy ABI of the
abirule (code). - Check a running kernel:
ls /sys/kernel/security/apparmor/features/network_v8/oraa-features-abi -x. - Check a profile: compile it with
apparmor_parser -S -Kwith and without the conditional and compare the output. The parser prints no warning when it drops a conditional, at any warning level (tree).
Errors
| Rule | Message |
|---|---|
network inet ip=127.0.0.1/8, | network invalid ip='127.0.0.1/8' |
network inet ip=1.2.3, | network invalid ip='1.2.3' |
network inet port=70000, | network invalid port='70000' |
network inet port=90-80, | network invalid port='90-80' |
network unix port=80, | network family does not support local or peer conditionals |
network inet stream peer=(interface=eth0), | interface cannot be set for peer in network rules |
network inet peer=(ip:=1.2.3.4), | unsupported operator used in conditions of network rules |
network inet label:=foo, | Lexer found unexpected character: ':' (0x3a) in state: NETWORK_MODE |
network inet label in (a), | unsupported operator in label conditional of network rules (code) |
network inet ip=1.2.3.4 ip=1.2.3.5, | network conditional "ip" can only be specified once |
network (bind) inet peer=(port=8080), | the peer permission message above |
| a bad interface name | network invalid interface='NAME' (code) |
All rows are from the tree's parser unless marked.
for AppArmor developers
The inet layout
- With
af_inet, after class, family and type the match string continues: protocol; peer port type (0 unprivileged, 1 privileged, 2 remote) and two port bytes; an address-size byte (0 none, 1 IPv4, 2 IPv6) and the address; NUL, the label pattern, NUL; then the command byteCMD_ADDR(1) and the same layout for the local address; command 2 with two bytes for listen, command 4 with four bytes for socket options (parser/network.cc:870-998,1058-1133). - Example (tree, abi/5.0):
network (connect) inet stream peer=(ip=10.0.0.1 port=80),gives\x0f\x00\x02\x00\x01..\x02\x00\x50\x01\x0a\x00\x00\x01\x00[^\000]*\x00\x01...with permission 0x40. - Port ranges are split into byte ranges (
parser/network.cc:719-765). - The interface pattern is a second rule set in class
AA_CLASS_NETV9_SKB(30) (parser/network.cc:929-962). - Without
af_inetthe function returns after the generic form (parser/network.cc:1031-1039). - The mainline kernel's
af_inet.ccollects local and remote addresses for the audit record and ends every permission function in the family, type and protocol check (linux:security/apparmor/af_inet.c:62-325).
for security researchers
Known discrepancies
None of these is taught as intended behaviour; the verdicts come from the review (sec-bugs). Each was run with the tree's parser unless marked.
- Without
af_inet, inet conditionals are dropped without a message, also fromdenyrules:deny network inet ip=1.2.3.4,compiles asdeny network inet,. - A peer
labelis not treated as a peer conditional:network peer=(label=foo),compiles asnetwork,, andnetwork (bind) peer=(label=foo),is accepted. network inet icmp,carries protocol value 2 where protocols are emitted (code).- The manual page documents a local
label:=;network inet label:=foo,fails in the scanner. - A value list keeps its first value:
network inet port=(80 81),equalsnetwork inet port=80,.
Roads from here
START HERE
- Upstream and Ubuntu kernels — which kernels enforce address conditionals
- The profile language at a glance — every kind of line on one page
PREAMBLE AND REUSE
- The abi rule and the abi files — the feature set a profile is compiled for
QUALIFIERS
- allow and deny — deny rules and why a dropped conditional widens them
RULE CLASSES
- Network rules — the rule these conditionals are added to
- Rule conditionals — the shared syntax and the peer group
- Capability rules — net_bind_service for ports below 1024
- Unix socket rules — the family that does have fine-grained rules everywhere
SECURITY · threat model and limits
- What is not mediated — what a profile does not control
RUNNING THE PARSER
- Kernel features and the policy ABI — checking for af_inet on a running kernel