Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

Address planning, route lookup and the access-list test

Address planning, route lookup, the access-list test.

All documentation pages

This page covers three kinds of questions a program can answer from data, with no change to any device: which subnets are free in a block, which route a device would use for an address, and whether an access list would let a flow pass.

Examples: address_plan, acl_test.

Address planning

The address types IP and Net are on types-and-units.md. These are the commands and methods for planning:

Call Result
next_free(block, prefix, used) Net: the first subnet of that prefix length in the block that overlaps no used subnet
free_nets(block, used) list[Net]: the free space of the block as the fewest subnets, in address order
net_of(address, mask) Net: the network that holds the address, from a subnet mask or a wildcard
summarize(nets) list[Net]: the shortest list of subnets that covers the same addresses
n.split(prefix) list[Net]: the subnet cut into pieces of a longer prefix
n.overlaps(other) bool: do the two subnets share an address
ip in n, small in n bool: is the address, or the smaller subnet, inside n
Bogolang
block: Net = 192.0.2.0/24
used: list[Net] = [192.0.2.0/26, 192.0.2.128/27]
print(next_free(block, 26, used))
print(free_nets(block, used))
print(net_of(192.0.2.77, 255.255.255.192), net_of(192.0.2.77, 0.0.0.63))
print(summarize([192.0.2.0/26, 192.0.2.64/26, 192.0.2.128/25, 198.51.100.0/24]))
print(198.51.100.0/24.split(26))
192.0.2.64/26
[Net("192.0.2.64/26"), Net("192.0.2.160/27"), Net("192.0.2.192/26")]
192.0.2.64/26 192.0.2.64/26
[Net("192.0.2.0/24"), Net("198.51.100.0/24")]
[Net("198.51.100.0/26"), Net("198.51.100.64/26"), Net("198.51.100.128/26"), Net("198.51.100.192/26")]

A Net also has .address, .prefix, .mask, .wildcard, .broadcast, .size (the number of addresses) and .hosts (the usable addresses, one at a time):

Bogolang
n: Net = 198.51.100.0/26
print(n.mask, n.wildcard, n.broadcast, n.size)
print(n.overlaps(198.51.100.32/27), 198.51.100.16/28 in n)
gateway: IP = next(n.hosts)

The rules:

  • next_free raises a ValueError when no subnet of that size is left, with how much of the block is used: 192.0.2.0/24 has no free /24: 128 of its 256 addresses are used (50%).
  • A used subnet outside the block is ignored. Used subnets that overlap each other are counted once.
  • IPv4 and IPv6 are planned each on their own: a used list that mixes them, or a summarize of both, is refused.
  • net_of reads IPv4 only. It takes 255.255.255.0 or 0.0.0.255 alike; 255.255.255.255 and 0.0.0.0 are read as subnet masks. A mask whose bits are not contiguous is refused.
  • split needs a longer prefix, and gives at most 65536 pieces.

Each call works on whole numbers, so a /8 cut into /30 is quick. The example address_plan gives a subnet to each new site with next_free, checks the subnets other teams asked for with overlaps, and prints the free space with free_nets:

10.40.12.0/23: no, it overlaps 10.40.12.0/24
10.40.70.0/24: no, it overlaps 10.40.64.0/18
10.40.128.0/24: free, it can be given

Route lookup

routes(source: Device | Snapshot, vrf: str = '') -> RouteTable

routes reads the routing table of a device, or takes the one inside a snapshot (see devices.md). A RouteTable answers the longest match.

Call Result
rt.lookup(ip) Route or None: the longest match
rt.lookup_all(ip) list[Route]: every route of that longest match, such as equal-cost paths
rt.routes, len(rt), for r in rt All the routes

A Route has .net (Net), .protocol (str), .next_hop (IP or None), .interface (str), .distance and .metric (int).

Bogolang
before: Snapshot = load_snapshot("before/edge-rt1.json")
rt: RouteTable = routes(before)
for r in rt:
    print(r)
best: Route | None = rt.lookup(192.0.2.200)
print(best)

On the snapshot before/edge-rt1.json of snapshot_compare:

S 0.0.0.0/0 via 203.0.113.1
C 192.0.2.0/26 is directly connected, GigabitEthernet0/0/1
L 192.0.2.1/32 is directly connected, GigabitEthernet0/0/1
O 198.51.100.0/24 via 192.0.2.2, GigabitEthernet0/0/1
C 203.0.113.0/30 is directly connected, GigabitEthernet0/0/0
L 203.0.113.2/32 is directly connected, GigabitEthernet0/0/0
S 0.0.0.0/0 via 203.0.113.1

The last line is the lookup of 192.0.2.200: no subnet holds it, so the default route answers.

  • .protocol is the code the device shows, with its kind: O, O IA, O E2, D EX. So r.protocol == "O" does not match an external OSPF route. On Junos it is the word Junos writes: Static, Direct, Local, OSPF, BGP.
  • When the device shows no distance, it is 1 for a static route and 0 for the others.
  • routes(d, vrf="NAME") reads the table of that VRF. An ASA has no VRF in show route, and vrf is refused there. On Junos the VRF NAME is the table NAME.inet.0; with no vrf, inet.0. Junos gives only the active route to each network.
  • A snapshot holds the global table only. Asking it for a vrf it does not hold is an error.
  • The lookup says what the routing table says. It does not follow a recursive next hop, and it knows nothing of policy routing.
  • routes(d) works on ios, iosxe, asa, nxos and junos. Under --replay it reads the saved output of the routing command.

The access-list test

acl(cfg: Config, name: str) -> Acl
Acl.permits(src: IP, dst: IP, port: int = 0, protocol: str = 'ip', src_port: int = 0) -> Verdict

acl takes an access list out of a configuration, by name or number. .permits says whether a flow would pass, and which line decides. It reads the configuration only: it contacts no device and sends no packet.

Bogolang
cfg: Config = load_config("edge-rt1.cfg", platform="iosxe")
rules: Acl = acl(cfg, "OUTSIDE-IN")
try:
    v: Verdict = rules.permits(203.0.113.50, 198.51.100.10, port=443, protocol="tcp")
    print(v)
except AclError as e:
    print(f"cannot say: {e}")
permitted by line 1: permit tcp any host 198.51.100.10 eq 443
On a Verdict Meaning
.permitted, bool(v) True when the flow passes
.line The line that decides, without its sequence number. implicit deny when no line matches
.number Its place among the entries of the list, from 1. 0 for the implicit deny
Input of permits Meaning
src, dst IPv4 addresses
protocol "ip", "tcp", "udp" or "icmp"
port The destination port. 0 means "not said"
src_port The source port. 0 means "not said"

A port needs protocol="tcp" or "udp".

What the IOS test reads: standard and extended lists, with a name or a number, written as an ip access-list block or as access-list N lines; host, any and wildcard masks; eq, neq, gt, lt and range with numbers or the port names IOS writes (www, domain ...); the protocols ip, tcp, udp and icmp, also written as their numbers (6, 17, 1); log and log-input, which change nothing. Remarks are skipped. When every entry has a sequence number, the entries are taken in the order of their numbers, as the device does. A line for a protocol other than the one asked, such as gre or ospf, is passed over.

It never guesses

A wrong "permitted" is worse than no answer. So when the test cannot be sure, it raises AclError and names the line. It stops:

  • at a line with a word it does not understand, when that line is reached and its addresses match the question: established, a time range, fragments, dscp, evaluate, dynamic, a port name it does not know. A line whose addresses cannot match is passed over, whatever else it says. object-group always stops the test: the addresses themselves cannot be read;
  • when the answer depends on what the question left out: a line for one protocol whose addresses match a question with protocol="ip"; a line that decides by port when the port was not given;
  • at an ICMP line that names a kind, such as echo-reply: the question cannot say which kind of ICMP is meant;
  • on a list written both as a block and as access-list N lines: the order of its entries is not certain.

An IPv6 list is refused with a sentence that says so. A name that is not in the configuration is a ValueError that lists the lists found:

ValueError: There is no access list 'NOPE' in the configuration of edge-rt1. Lists found: OUTSIDE-IN.

The addresses of a line are judged first. On an IOS extended line, when the source or the destination of the flow cannot match the line, the line is passed over, whatever word ends it. A line whose addresses match and that ends with a word the test does not know still stops it.

Bogolang
text: str = ("hostname r1\n"
             "ip access-list extended WEB-IN\n"
             " 10 permit tcp any host 192.0.2.10 eq 443\n"
             " 20 permit tcp any host 192.0.2.10 established\n"
             " 30 permit udp any host 192.0.2.20 eq 53\n")
cfg: Config = Config(Device(name="r1", ip=192.0.2.1, platform="iosxe"), text, "")
rules: Acl = acl(cfg, "WEB-IN")
print(rules.permits(203.0.113.5, 192.0.2.30, port=22, protocol="tcp"))
try:
    print(rules.permits(203.0.113.5, 192.0.2.10, port=22, protocol="tcp"))
except AclError as e:
    print(f"cannot say: {e}")
denied: implicit deny
cannot say: The access-list test does not understand 'established' in this line: permit tcp any host 192.0.2.10 established

The first flow goes to 192.0.2.30, which line 20 can never match, so the test goes past it. The second goes to 192.0.2.10, where line 20 could decide, so it refuses.

From acl_test, with bogo run acl_test.bogo:

flow                      from          to             service    answer      why
------------------------  ------------  -------------  ---------  ----------  --------------------------------------------------------------------------------------------------------------------------------------------
web                       203.0.113.50  198.51.100.10  tcp/443    permitted   line 1: permit tcp any host 198.51.100.10 eq 443
dns                       203.0.113.50  198.51.100.20  udp/53     permitted   line 3: permit udp any host 198.51.100.20 eq domain
sip from a blocked range  192.0.2.10    198.51.100.30  tcp/5060   denied      line 4: deny ip 192.0.2.0 0.0.0.255 any log
sip                       203.0.113.60  198.51.100.30  tcp/5061   permitted   line 5: permit tcp any host 198.51.100.30 range 5060 5061
voice media               203.0.113.60  198.51.100.30  udp/16000  permitted   line 6: permit udp any host 198.51.100.30 range 10000 20000
ntp                       203.0.113.60  198.51.100.99  udp/123    denied      implicit deny
ssh to the web server     203.0.113.60  198.51.100.10  tcp/22     CANNOT SAY  The access-list test does not understand 'established' in this line: permit tcp any any established
ping the web server       203.0.113.60  198.51.100.10  icmp       CANNOT SAY  Line 'permit icmp any any echo-reply' of OUTSIDE-IN decides only ICMP of kind 'echo-reply'. The test cannot say which kind of ICMP you mean.

What the test does not know

It reads the list, not the device. It does not know where a list is applied, in which direction, or what else filters the traffic. ASA and NX-OS lists, IPv6 lists and object groups are not read: acl works on ios, iosxe and junos.

The firewall filter test on Junos

On a Junos configuration, acl(cfg, "NAME") reads the firewall filter firewall family inet filter NAME, or the older form firewall filter NAME. The same .permits answers.

Bogolang
j: Config = load_config("edge-sw2.conf", platform="junos")
mgmt: Acl = acl(j, "MGMT-IN")
v: Verdict = mgmt.permits(192.0.2.10, 192.0.2.21, port=22, protocol="tcp")
print(v)

With a term ssh that accepts TCP port ssh from 192.0.2.0/24, this prints permitted by line 1: ssh.

  • .line is the name of the term that decides, .number its place. When no term matches, the line is implicit discard.
  • Terms are read in order. All the kinds of conditions of a term must match; several values of one kind are alternatives.
  • Understood: source-address, destination-address and address, with except, by the longest prefix; source-prefix-list and destination-prefix-list when the list is in the same configuration; protocol; source-port, destination-port and port, as numbers, ranges and the port names of Junos; the actions accept, discard, reject and next term. count, log and syslog change nothing. A term that matches and has no final action accepts, as Junos does.
  • Refused when reached: tcp-established, tcp-flags, icmp-type, dscp, fragments, ttl, the -except forms of protocol and port, a filter called from a filter, a policer or any other action it does not know, a term with two final actions, and a prefix list that is missing, empty or written with apply-path.
  • A term is passed over when the addresses asked cannot match its addresses, or when it names protocols and the protocol asked is not one of them, whatever else it says. A term ping with protocol icmp and icmp-type echo-request does not stop a TCP question. It stops an ICMP question whose addresses match:
AclError: The filter test does not understand the condition 'icmp-type echo-request' in term ping of filter MGMT-IN.

The addresses of a term must always be readable: a missing prefix list stops the test even on a term for another protocol. - A port condition with a question that is ICMP, or has no protocol, is refused: Junos reads the port from the place where TCP and UDP carry it, whatever the protocol. For port X, which means either side, when one port was given and it is not X, the test asks for the other one. - A term whose conditions are all switched off matches everything, as on the device. - IPv4 only. What a filter inherits from groups in a saved file is not counted, and cfg.warnings says so (see config-audit-templates.md).

Not proven

The IOS test was asked one question about each of 312 real access lists: it answered 271 and refused 41, each for a reason listed above. Its answers, and those of the Junos filter test, were compared with a second evaluator written apart, on thousands of random lists and questions, and agreed. No packet was ever sent through a list or a filter on a device to check an answer. Route lookup has read one real IOS-XE switch. See not-proven.md.