03 Infrastructure/Seaward
Seaward
Command-line tool · open source
Which ports on a Linux server can really be reached from outside, and the rule that decides each one.
Why it exists
A firewall manager such as ufw lists the ports I allowed. The kernel works from the loaded packet rules, and other programs load rules too.
Docker publishes a container's port with its own rules, which never pass that list. The manager says closed and the database answers the internet.
What it does
Seaward reads the loaded rules, the listeners and Docker's published ports, and says who can reach each port: the internet, the local network, VPN peers or nobody. Ports the manager never allowed come first.
seaward why 5432 follows one packet and prints the rule that rewrote its destination and the rule that let it in.
How it is built
A packet walked in kernel order
A connection's first packet is taken through the kernel's stages in order, so every verdict is a printable path.
Two listings, settled by rule
iptables and nft write into the same kernel tables and neither listing is complete, so each rule is taken from the one that can say it.
Undecided is an answer
A condition the model cannot read is followed both ways. If the ends differ, the port is undecided.
It only reads
The collector is a fixed list of listing commands, and a snapshot is one text file.
How I know it works
- 2,111 packets
- The lab loads 81 written rulesets and 40 random ones into the real kernel, in network namespaces (private copies of the network stack), sends real packets and compares. 0 disagreements.
- 1,212 tests
- 1,134 Go test cases with the race detector and 78 for the demo page.
- 2 machines
- CI turns on ufw on one runner and firewalld on another, publishes a container past each, and checks the answers against real connections.
What was hard
A scan that stopped silently
The first release checked only a capped list, 48 rewritten ports and at most twelve groups of senders (sources the rules treat alike), and said nothing when it stopped: of sixteen addresses let in by sixteen rules it found eleven. It also expected a port and its rewrite in one rule, so a port forwarded behind a jump to another chain was never asked about. Independent reviews found both.
Now the search follows the packet's path, and a report that reaches a ceiling lists what was not asked. The lab holds the scan itself to the kernel: a port the kernel answers on must be one the scan found.
Limits
- A cloud firewall or router in front of the machine is not seen.
- A scan has rows for TCP and UDP ports only.
- Past 1,024 groups of senders or 4,096 ports the scan stops, lists what was not asked, and
--check does not exit 0. - eBPF, IPVS and IPsec are not modelled, and a port whose packets pass an nftables egress or bridge chain is undecided.