Network policy reference

13 min read

The complete vocabulary of PNP rules as the kernel reads them. The concepts — layers, the forest, the laws — are in Network policy; this page is the lookup table.

Registry layout #

Machine\System\Network\Rules
    CurrentReportingLevel        REG_DWORD 1..6   (optional; absent = 1)
    RawPacket\                   the wire-side layer's forest
        <rule>\
    Packet\                      the per-packet layer's forest
        <rule>\                  one tree root
            <exception>\         a subkey: narrower region, same laws
                ...
    Flow\                        the flow layer's forest
        <rule>\

A rule key's name is its attribution handle and may not contain \ or /. Layer keys other than RawPacket, Packet and Flow are ignored.

Rule values #

The Rules key's own value #

Conditions #

A condition is a value named <Fact>.<Operator>. A rule matches when every condition holds; a condition over a fact the packet lacks is false (the absent-fact law).

Operators #

Integer values may be written as REG_DWORD, REG_QWORD, or as decimal strings; a list of integers is a REG_MULTI_SZ of decimal strings and ranges. Applying an operator a family does not support (GreaterThan on an address, Has on a port) refuses the generation.

Facts #

Address families are strict: an IPv4 pattern never matches an IPv6 address and vice versa, so 0.0.0.0/0 does not swallow IPv6.

A Flow fact is one that is identical for every packet of the flow. The per-packet facts marked "not a Flow fact" are legal in a Flow rule but never present there, so the condition never holds; the viewer flags it. Related and Start.* are the reverse: never present outside Flow.

Counter views #

Counter.<name> reads the stream <name> that some rule's COUNT writes. In parentheses, in any order, at most one of each:

Examples: Counter.dns (total, global); Counter.dns(10s) (last ten seconds, global); Counter.dns(SrcAddr) (total, per source); Counter.dns(1h, SrcAddr+DstAddr) (last hour, per source–destination pair). A view over a stream that no rule anywhere writes refuses the generation; a stream nobody reads is fine. Windows are approximated by eight buckets, so a value can be up to an eighth of a window stale.

Actions #

Actions is a list of expressions. Names are case-insensitive; whitespace is ignored. A rule's actions may contain any mix; at most one verdict results (the strictest listed).

Unknown action names, wrong argument counts, negative or non-integer operands, unminted REJECT kinds, and a TAG operation other than the three above all refuse the generation.

Where a REJECT can speak #

Everywhere, for IP traffic. Inbound, the refusal goes back to the peer. Outbound, the answer the peer would have sent is delivered to the local socket, so the program's connect fails at once with connection refused (Refused, TCP) or host unreachable (Prohibited, or any UDP refusal). Only a packet with no refusal vocabulary — ARP and other non-IP frames, a broadcast or multicast destination, a fragment — is applied as a DROP and counted as degraded; the verdict event still says REJECT and names the kind. The refusals PNP sends pass its own seats unjudged.

In the Flow layer a REJECT sentence answers every later packet of the flow the same way, so a retransmitted SYN gets its reset too. When the refused packet belongs to an established TCP connection (a flow re-judged after a policy change or at a time edge), the other end is torn down as well: the refused packet is turned into a reset and sent where it was going, so both sockets fail at once. New flows and UDP have no far end to tear down.

Layers #

A rule conditioned on a fact its layer never has is legal but can never match; the viewer flags it. A Packet or RawPacket rule that reads a tag a Flow rule writes is a downward read and refuses the generation.

Sentences #

The Flow layer's verdict for a flow is cached on the flow with the policy generation that judged it and an expiry. A packet of a flow whose sentence is current is not evaluated (and emits no event). A sentence is stale, and the flow re-judged on its next packet, when:

• the policy generation has changed since the judgment, or
• a live-time condition (Time.*) the judgment consulted — true or false — would have flipped by now. Hour, minute, second and day-of-week conditions flip exactly when their value would next change the condition's answer; day-of-month, month and year conditions re-judge daily at midnight UTC.

A re-judgment is a full evaluation: effects run again. A flow that conntrack could not give an extension (allocation failure at creation) holds no sentence and is evaluated on every packet, counted.

A loopback flow has two local endpoints and two sentences: judged as out at the outbound seat and as in at the inbound seat, and every packet of it answers to the stricter of the two.

Limits #

The development baseline #

Experimental images ship a seed policy so a fresh machine works while still refusing unsolicited inbound connections. The compiled-in backstop is DROP in every layer; each line below is a visible, deletable yes.

Rules\RawPacket:

Rules\Packet — passes every tracked packet through to Flow, and the untracked housekeeping a host needs:

Rules\Flow — the decisions:

Every other inbound flow meets the Flow backstop, once, on its first packet; untracked inbound packets meet the Packet backstop.

Worked examples #

An exception under a broad rule — drop all inbound except SSH from the LAN, and tell other SSH sources that policy said no:

Rules\Packet\no-inbound            Direction.Equal = in
                                   Actions = DROP
Rules\Packet\no-inbound\ssh        DstPort.Equal = 22
                                   Actions = REJECT(Prohibited)
Rules\Packet\no-inbound\ssh\lan    SrcAddr.Equal = 10.0.0.0/8
                                   Actions = PASS

A flow tag read on the reply — mark DNS queries, report on the replies of marked flows:

Rules\Packet\tag-dns        Protocol.Equal = udp, DstPort.Equal = 53
                            Actions = TAG(dnsq, Add)
Rules\Packet\tagged-reply   Protocol.Equal = udp, SrcPort.Equal = 53
                            Tag.dnsq.GreaterThan = 0
                            Actions = REPORT(4)

Byte accounting per interface — count outbound bytes and refuse a source that pushes more than 100 MB in a minute:

Rules\Packet\egress-bytes   Direction.Equal = out
                            Actions = COUNT(egress, Length)
Rules\Packet\egress-cap     Direction.Equal = out
                            Counter.egress(1m, SrcAddr).GreaterThan = 104857600
                            Actions = DROP

A connection-level allow — let the machine connect out, accept SSH in from the LAN, and refuse every other inbound connection with a reset, each decided once per flow:

Rules\Flow\outbound-ok      Direction.Equal = out
                            Actions = PASS
Rules\Flow\inbound          Direction.Equal = in
                            Actions = REJECT
Rules\Flow\inbound\ssh-lan  Protocol.Equal = tcp, DstPort.Equal = 22
                            SrcAddr.Equal = 10.0.0.0/8
                            Actions = PASS

A curfew that lets downloads finish — no new outbound connections between 22:00 and 06:00 UTC, existing ones run on:

Rules\Flow\curfew           Direction.Equal = out
                            Start.Hour.Equal = 22-23, 0-5
                            Priority = 10
                            Actions = REJECT(Prohibited), REPORT(3)

Written with Time.Hour instead of Start.Hour, the same rule cuts every running outbound connection at 22:00 — on its next packet, with an ICMP admin-prohibited — and the report says which rule did it.

Connection rate limiting — count connections, not packets, by counting in the flow layer:

Rules\Flow\conn-count       Direction.Equal = in, Protocol.Equal = tcp
                            Actions = COUNT(conns)
Rules\Flow\conn-flood       Direction.Equal = in, Protocol.Equal = tcp
                            Counter.conns(1m, SrcAddr).GreaterThan = 100
                            Actions = DROP

Edit this page