93 lines
4.6 KiB
Markdown
93 lines
4.6 KiB
Markdown
# Native Linux nftables Engine (`NativeLinuxNftablesEngine`)
|
|
|
|
The `NativeLinuxNftablesEngine` manages Linux firewall filtering and Network Address Translation (NAT) via direct in-process interaction with `libnftables.so.1` and the Linux Netfilter Netlink subsystem.
|
|
|
|
---
|
|
|
|
## 1. Protocol Architecture & In-Process Netfilter Binding
|
|
|
|
`nx9-wg` uses `libnftables` in-process C-ABI FFI via `NftContext` to execute atomic transaction batches without spawning the `nft` or `iptables` CLI utilities:
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ NativeLinuxNftablesEngine │
|
|
└───────────────────────────┬────────────────────────────┘
|
|
│
|
|
In-Process FFI Transactions
|
|
via libnftables (NftContext)
|
|
│
|
|
┌───────────────────────────▼────────────────────────────┐
|
|
│ Netfilter Subsystem (table inet nx9_wg) │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Table Scoping & Multi-Tenant Host Isolation
|
|
|
|
To prevent breaking container networks, hypervisors, or external security tools, `nx9-wg` enforces strict table isolation:
|
|
|
|
### A. Dedicated Table Namespace: `table inet nx9_wg`
|
|
All chains, sets, rules, and NAT masquerade policies are strictly contained inside `table inet nx9_wg`.
|
|
|
|
### B. Zero Table Interference
|
|
- **No Global Flushes**: `nx9-wg` NEVER executes `flush ruleset` or alters tables belonging to Docker (`table ip docker`), Kubernetes (`table inet cni`), libvirt (`table ip libvirt`), fail2ban, or UFW/Firewalld.
|
|
- **Ownership Verification**: Before modifying or inspecting rules, `nx9-wg` validates table family (`inet`) and name (`nx9_wg`). Any foreign table is rejected and untouched.
|
|
|
|
---
|
|
|
|
## 3. Ruleset Architecture & Chains
|
|
|
|
The generated `inet nx9_wg` table contains three dedicated chains:
|
|
|
|
```
|
|
table inet nx9_wg {
|
|
chain input {
|
|
type filter hook input priority filter; policy accept;
|
|
# Custom peer filter rules (e.g. UDP/TCP port restrictions)
|
|
}
|
|
|
|
chain forward {
|
|
type filter hook forward priority filter; policy accept;
|
|
# Inter-client routing and subnet forward policies
|
|
}
|
|
|
|
chain postrouting {
|
|
type nat hook postrouting priority srcnat; policy accept;
|
|
# Outbound NAT masquerade scoped strictly to managed WireGuard subnets
|
|
ip saddr { 10.100.0.0/24 } oifname != "wg0" masquerade
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Scoped NAT Masquerade Invariant
|
|
|
|
Outbound NAT masquerading is dynamically scoped exclusively to managed WireGuard client subnets:
|
|
1. **Subnet Deduplication**: Overlapping subnets are merged to prevent redundant rules.
|
|
2. **Interface Exclusion**: Traffic routing back into the WireGuard interface (`oifname != "wg*"`) is not masqueraded to preserve true source IPs for site-to-site tunnels.
|
|
3. **No Catch-All Masquerade**: `nx9-wg` never creates a catch-all `masquerade` rule that affects non-WireGuard traffic on the host.
|
|
4. **Interface and Subnet Network CIDRs**: Masquerade sources include each enabled Interface address CIDR and each enabled Subnet Network CIDR. A peer allocated from a selected Network (for example outside the WireGuard interface `/24`) is masqueraded from that Network CIDR; the Interface address itself is unchanged.
|
|
|
|
---
|
|
|
|
## 5. Atomic Rule Compilation & Verification
|
|
|
|
The ruleset builder (`NftablesRulesetBuilder`) compiles desired database state into a single atomic Netfilter transaction buffer:
|
|
1. **Deterministic Rule Ordering**: Rules are sorted by priority index (ascending) to guarantee consistent packet evaluation.
|
|
2. **Protocol Grouping**: Supports `tcp`, `udp`, `tcp_udp`, `icmp`, and `any`.
|
|
3. **Port & Port-Range Parsing**: Supports single ports (`53`), comma-separated lists (`80,443`), and contiguous ranges (`8000-8100`).
|
|
4. **Validation via `nft_ctx_buffer_output`**: The compiled batch is verified by `libnftables` before committing to the kernel.
|
|
|
|
---
|
|
|
|
## 6. Runtime Dependency Qualification
|
|
|
|
On Linux systems, `nx9-wg` dynamically links against:
|
|
- `libnftables.so.1` (provided by `libnftables1` / `nftables` package)
|
|
- `libmnl.so.0`
|
|
- `libnftnl.so.11`
|
|
|
|
No runtime dependency on the `nft` CLI binary or shell scripts exists.
|