Ali Husain Software engineer and product designer

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.

Seaward's chart of a sample shop server: seven ports can be reached from outside and ufw allows only four of them. The three container ports are drawn as lanes that cross the firewall's shoreline.Seaward's chart of a sample shop server: seven ports can be reached from outside and ufw allows only four of them. The three container ports are drawn as lanes that cross the firewall's shoreline.
Seaward on a phone: 7 ports can be reached from outside, ufw allows only 4 of them.Seaward on a phone: 7 ports can be reached from outside, ufw allows only 4 of them.
The passage to port 5432 on a phone: one packet followed rule by rule to the rule that lets it through.The passage to port 5432 on a phone: one packet followed rule by rule to the rule that lets it through.

A firewall's list is what was asked for; the rules the kernel runs are what the server got. Docker publishes a port with rules of its own, and a database answers the whole internet while ufw still reads deny. Seaward reads the rules that are really loaded, follows a packet through them the way the kernel does, and says for every port who can reach it and which rule decides. It only reads: it changes no rule and puts no packet on the network.

1,212
automated tests, run on every change
2,111
real packets sent through the Linux kernel to check it, with no disagreement
121
rulesets built inside a real kernel: 81 written, 40 random
0
Go dependencies: one static 4 MB binary

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.

Also in Infrastructure

Open to remote work.

ali@gallowforge.dev