mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-22 07:48:26 +00:00
53ad528f7d
Surfaces local services reachable from the mesh, paired with their
current `inet fips` baseline filter classification. Lands to the
right of the existing TUN section in the Traffic block.
A new daemon control query `show_listening_sockets` returns IPv6
listeners bound to either `::` (wildcard) or the node's fd00::/8
address, each classified as Accept / Drop / Unknown / NoFirewall
against the running inbound chain. fipstop renders the result as a
table beside the Traffic counters: Accept rows in default White,
Drop / Unknown in DarkGray, a yellow banner above the table when
`fips-firewall.service` is inactive, and a trailing `*` on
wildcard binds to remind the operator the bind is not
fips0-specific.
Daemon side:
- `src/control/listening.rs` walks `/proc/net/tcp6` and
`/proc/net/udp6` via the procfs crate (LISTEN state for TCP,
wildcard remote for UDP), filters to fips0-reachable binds, and
resolves inodes to PID / comm via `/proc/<pid>/fd`.
- `src/control/firewall_state.rs` shells out to
`nft -j list table inet fips` and walks the inbound chain.
Recognises canonical accepts (`tcp/udp dport N accept`,
`dport { ... } accept`, `dport A-B accept`), the iifname-scoping
line, conntrack and icmpv6 lines (skipped). Any rule with
unrecognised matchers (saddr filters, jumps, daddr filters) or
non-terminal verdicts forces Unknown classification for the
ports it references. Eleven unit tests cover the classification
logic; the listening enumerator carries a /proc-parsing test of
its own.
- `show_listening_sockets` emits
`{fips0_addr, firewall_active, sockets[]}` with per-row
`{proto, local_addr, port, pid, process, filter, wildcard_bind}`.
fipstop side:
- `src/bin/fipstop/ui/dashboard.rs` splits the Traffic block into
a 50/50 horizontal layout; the existing TUN + Forwarded panel
occupies the left half.
- `src/bin/fipstop/ui/listening.rs` renders the right half.
- `main.rs` fetches the new query each tick when the Node tab is
active. Errors are non-fatal: an old daemon without the query
leaves the payload at None and the panel renders "loading...".
`Cargo.toml` gains `procfs = "0.18"` on the Linux target. IPv4
listeners are not enumerated — fips0 is IPv6-only.
Folded in: revert the default-socket lookup from writability-probe
back to existence-based selection. The previous tempfile-probe on
`/run/fips` silently steered fipstop / fipsctl onto an XDG path
the daemon never bound for any user in the `fips` group whose
shell session had not yet picked up the supplementary group (no
re-login after `usermod -aG`). `XDG_RUNTIME_DIR` is set on every
modern systemd-managed user session, so this hit the common case.
The kernel checks actual group membership at `connect(2)`, so a
user who genuinely cannot connect now gets a clear `EACCES`
rather than a silent path mismatch. Drops the now-unused
`is_writable_dir` helper. `XDG_RUNTIME_DIR` existence validation
is preserved.
Documentation:
- `docs/reference/cli-fipstop.md` — Node-tab row updated, new
"Listening on fips0 panel" section.
- `docs/reference/control-socket.md` — `show_listening_sockets`
added to the read-only queries table.
- `docs/how-to/enable-mesh-firewall.md` — new "Verify with
fipstop" section.
- `docs/tutorials/host-a-service.md` — fipstop callouts at
Steps 3, 5, 6 + Troubleshooting bullet + wildcard-bind reminder
under "What you've learned".
- `CHANGELOG.md` — new bullet under `Added / Operator Tooling`,
resolver `Fixed` entry rewritten to describe the
existence-based final shape.
193 lines
6.6 KiB
Markdown
193 lines
6.6 KiB
Markdown
# Enable the Mesh-Interface Firewall
|
|
|
|
FIPS ships a default-deny nftables baseline at `/etc/fips/fips.nft` that
|
|
restricts inbound traffic on the `fips0` mesh interface to conntrack
|
|
replies and ICMPv6 echo. The baseline is **not** enabled by default — see
|
|
[../design/fips-security.md](../design/fips-security.md) for the threat
|
|
model and the rationale behind keeping activation explicit. This guide
|
|
covers the operator steps to load the baseline, extend it with per-host
|
|
allowances, and inspect drops.
|
|
|
|
## Activate the baseline
|
|
|
|
The package ships `fips-firewall.service`, a systemd oneshot that runs
|
|
`nft -f /etc/fips/fips.nft` on start and removes the `inet fips` table
|
|
on stop. To activate:
|
|
|
|
```sh
|
|
sudo systemctl enable --now fips-firewall.service
|
|
```
|
|
|
|
This loads the table now and arranges for it to load on every subsequent
|
|
boot. To disable and tear it down:
|
|
|
|
```sh
|
|
sudo systemctl disable --now fips-firewall.service
|
|
```
|
|
|
|
To reload after editing `/etc/fips/fips.nft` or adding a drop-in under
|
|
`/etc/fips/fips.d/`:
|
|
|
|
```sh
|
|
sudo systemctl reload-or-restart fips-firewall.service
|
|
```
|
|
|
|
The file is idempotent — it begins with `add table inet fips; flush
|
|
table inet fips;` so re-running it replaces the live ruleset atomically.
|
|
Equivalently:
|
|
|
|
```sh
|
|
sudo nft -f /etc/fips/fips.nft
|
|
```
|
|
|
|
## Folding the baseline into the host's main nftables
|
|
|
|
If you prefer to load the baseline from your existing
|
|
`/etc/nftables.conf` rather than via the systemd unit, include it
|
|
directly:
|
|
|
|
```nft
|
|
# in /etc/nftables.conf
|
|
include "/etc/fips/fips.nft"
|
|
```
|
|
|
|
In that case do **not** enable `fips-firewall.service` — the host's main
|
|
nftables setup owns the loading. The two paths are mutually exclusive.
|
|
|
|
## Extend with per-host allowances via drop-ins
|
|
|
|
The baseline drops everything inbound on `fips0` except conntrack
|
|
replies and ICMPv6 echo. To open specific services to specific mesh
|
|
nodes, drop a file into `/etc/fips/fips.d/` ending in `.nft`. Each
|
|
file is included inline into the `inbound` chain at the marked point
|
|
and may contain any nftables rule lines valid in that context.
|
|
|
|
Reload after editing:
|
|
|
|
```sh
|
|
sudo systemctl reload-or-restart fips-firewall.service
|
|
# or: sudo nft -f /etc/fips/fips.nft
|
|
```
|
|
|
|
### Allow inbound SSH from a specific mesh node
|
|
|
|
```nft
|
|
# /etc/fips/fips.d/ssh-from-bastion.nft
|
|
ip6 saddr fd97:1234:5678:9abc:def0:1234:5678:9abc tcp dport 22 accept
|
|
```
|
|
|
|
The source filter is the node's mesh address. To find a node's mesh
|
|
address, look in their `fips.pub` (which contains the npub) and derive
|
|
the `fd97:...` address from it, or query the running daemon:
|
|
|
|
```sh
|
|
fipsctl show identity-cache
|
|
fipsctl show peers
|
|
```
|
|
|
|
### Allow inbound DNS broadly
|
|
|
|
Some services need to be reachable from any mesh node (a public DNS
|
|
resolver, a public bootstrap node):
|
|
|
|
```nft
|
|
# /etc/fips/fips.d/dns-public.nft
|
|
udp dport 53 accept
|
|
tcp dport 53 accept
|
|
```
|
|
|
|
Omit the source filter only when the service is intended to be
|
|
universally reachable on the mesh. The baseline's purpose is to make
|
|
"universally reachable" an explicit decision rather than the default.
|
|
|
|
### Multiple nodes, one service
|
|
|
|
```nft
|
|
# /etc/fips/fips.d/git-from-trusted.nft
|
|
ip6 saddr {
|
|
fd97:1111:2222:3333:4444:5555:6666:7777,
|
|
fd97:8888:9999:aaaa:bbbb:cccc:dddd:eeee
|
|
} tcp dport 9418 accept
|
|
```
|
|
|
|
Set syntax keeps multi-node rules readable and is more efficient than a
|
|
chain of individual rules.
|
|
|
|
## Verify with fipstop
|
|
|
|
`fipstop`'s Node tab carries a **Listening on fips0** panel
|
|
(right-half of the Traffic block) that pairs each local IPv6
|
|
listener with its current baseline-filter classification. After
|
|
adding or editing a drop-in and reloading, this is the fastest
|
|
way to confirm the rule landed correctly without manually
|
|
parsing `nft list table inet fips`.
|
|
|
|
| Panel state | Reading |
|
|
| ----------- | ------- |
|
|
| Service row in **default White** with `OPEN` in the State column | The chain has a canonical, unrestricted accept rule for this (proto, port). The service is reachable from any mesh node. |
|
|
| Service row in **DarkGray** with `filt` | No matching accept rule; the chain falls through to `counter drop`. The service is not reachable from the mesh. |
|
|
| Service row in **DarkGray** with `filt?` | A rule references the port but uses matchers the panel cannot fully decompose (saddr filter, jump, daddr filter). The intent is operator-defined; inspect with `sudo nft list table inet fips` to see the actual rule. |
|
|
| **Yellow banner** above the panel: "fips-firewall.service inactive — all listeners exposed" | The `inet fips` table is not loaded. Every listener is mesh-reachable (subject only to whatever ACL you have at the peer layer). |
|
|
|
|
A common workflow when extending the baseline is to keep `fipstop`
|
|
open on the Node tab in one terminal while editing
|
|
`/etc/fips/fips.d/` in another. After each
|
|
`sudo systemctl reload-or-restart fips-firewall.service`, the panel
|
|
re-classifies on the next poll tick and the affected row's State
|
|
column flips. A row staying `filt` after you expected `OPEN`
|
|
usually means the drop-in failed to load (syntax error in any file
|
|
under `/etc/fips/fips.d/` aborts the whole reload) or carries a
|
|
saddr filter that triggers `filt?` rather than `OPEN`.
|
|
|
|
The classifier is conservative: it recognizes only the canonical
|
|
unrestricted shapes (`tcp dport N accept`, `udp dport N accept`,
|
|
`dport { ... } accept`, `dport A-B accept`). Source-restricted
|
|
accepts intentionally render as `filt?` rather than `OPEN` —
|
|
the panel is a security screen, and any rule that varies by
|
|
source is an operator decision the panel will not silently bless
|
|
as fully open.
|
|
|
|
## Inspect drops
|
|
|
|
The baseline counter increments on every dropped packet. Inspect it:
|
|
|
|
```sh
|
|
sudo nft list table inet fips
|
|
```
|
|
|
|
Look for the `counter packets N bytes M drop` line at the bottom of the
|
|
`inbound` chain. A non-zero counter means mesh nodes are sending
|
|
traffic that hits the default-deny — usually benign (probes, neighbor
|
|
discovery) but occasionally a misconfigured drop-in.
|
|
|
|
To see which packets are being dropped, uncomment the `log` line near
|
|
the bottom of `/etc/fips/fips.nft`:
|
|
|
|
```nft
|
|
log prefix "fips drop: " level info limit rate 10/minute
|
|
```
|
|
|
|
Reload:
|
|
|
|
```sh
|
|
sudo nft -f /etc/fips/fips.nft
|
|
```
|
|
|
|
Then tail the kernel log:
|
|
|
|
```sh
|
|
sudo journalctl -k -f -g "fips drop:"
|
|
```
|
|
|
|
The rate-limit prevents flooding the journal under sustained probing.
|
|
Adjust the rate, log level, or prefix as needed for the situation.
|
|
Re-comment the rule when you are done; production hosts do not need
|
|
the log line on by default.
|
|
|
|
## See also
|
|
|
|
- [../design/fips-security.md](../design/fips-security.md) — threat
|
|
model, baseline design, and coexistence with other firewalls
|
|
- [../reference/security.md](../reference/security.md) — consolidated
|
|
security reference
|