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 |
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):
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_freeraises aValueErrorwhen 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
summarizeof both, is refused. net_ofreads IPv4 only. It takes255.255.255.0or0.0.0.255alike;255.255.255.255and0.0.0.0are read as subnet masks. A mask whose bits are not contiguous is refused.splitneeds 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).
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.
.protocolis the code the device shows, with its kind:O,O IA,O E2,D EX. Sor.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 inshow route, andvrfis refused there. On Junos the VRFNAMEis the tableNAME.inet.0; with novrf,inet.0. Junos gives only the active route to each network.- A snapshot holds the global table only. Asking it for a
vrfit 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 onios,iosxe,asa,nxosandjunos. Under--replayit 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.
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-groupalways 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 Nlines: 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.
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.
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.
.lineis the name of the term that decides,.numberits place. When no term matches, the line isimplicit 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-addressandaddress, withexcept, by the longest prefix;source-prefix-listanddestination-prefix-listwhen the list is in the same configuration;protocol;source-port,destination-portandport, as numbers, ranges and the port names of Junos; the actionsaccept,discard,rejectandnext term.count,logandsyslogchange 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-exceptforms of protocol and port, a filter called from a filter, apoliceror any other action it does not know, a term with two final actions, and a prefix list that is missing, empty or written withapply-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
pingwithprotocol icmpandicmp-type echo-requestdoes 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.