65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# Firewall and NAT Domain Model Reference
|
|
|
|
This document describes the domain representations, rule structures, port specifications, and safety invariants for packet filtering and NAT in `nx9-wg`.
|
|
|
|
---
|
|
|
|
## 1. Domain Entities
|
|
|
|
### A. Firewall Rule (`FirewallRule`)
|
|
Represents an individual packet filtering rule in the database:
|
|
|
|
| Field | Type | Description |
|
|
| :--- | :--- | :--- |
|
|
| `id` | `Uuid` | Unique identifier (Primary Key) |
|
|
| `name` | `String` | Human-readable identifier (e.g., `allow-dns-udp`) |
|
|
| `direction` | `FirewallDirection` | `In`, `Out`, or `Forward` |
|
|
| `protocol` | `FirewallProtocol` | `Tcp`, `Udp`, `TcpUdp`, `Icmp`, or `Any` |
|
|
| `action` | `FirewallAction` | `Accept`, `Drop`, or `Reject` |
|
|
| `source` | `Option<String>` | Source CIDR or IP (e.g., `10.100.0.0/24`) |
|
|
| `destination` | `Option<String>` | Destination CIDR or IP |
|
|
| `source_port` | `Option<u16>` | Specific source port |
|
|
| `destination_port`| `Option<u16>` | Specific destination port |
|
|
| `port_range` | `Option<String>` | Single port, list, or range (`53`, `80,443`, `8000-8100`) |
|
|
| `interface_id` | `Option<Uuid>` | Optional interface association |
|
|
| `peer_id` | `Option<Uuid>` | Optional cryptographic peer association |
|
|
| `priority` | `i32` | Rule evaluation priority (lower numbers evaluate first) |
|
|
| `enabled` | `bool` | Active state flag |
|
|
|
|
---
|
|
|
|
## 2. Port Specification Syntax
|
|
|
|
The `port_range` field supports three RFC-compliant formats:
|
|
|
|
1. **Single Port**: `80` $\rightarrow$ Evaluates as `dport 80`
|
|
2. **Multi-Port Comma List**: `80,443,8080` $\rightarrow$ Evaluates as `dport { 80, 443, 8080 }`
|
|
3. **Port Range**: `8000-8100` $\rightarrow$ Evaluates as `dport 8000-8100`
|
|
|
|
---
|
|
|
|
## 3. Protocol Grouping
|
|
|
|
- **`Tcp`**: Filters IPv4/IPv6 TCP packets.
|
|
- **`Udp`**: Filters IPv4/IPv6 UDP packets.
|
|
- **`TcpUdp`**: Translates to `{ tcp, udp }` protocol match in a single atomic rule.
|
|
- **`Icmp`**: Translates to `icmp` (IPv4) or `icmpv6` (IPv6).
|
|
- **`Any`**: Omits protocol match, applying action to all transport protocols.
|
|
|
|
---
|
|
|
|
## 4. NAT Masquerade Domain Configuration
|
|
|
|
NAT masquerading is governed by key-value appliance settings in SQLite:
|
|
|
|
- **`enable_nat`**: Boolean string (`"true"` / `"false"`). When enabled, all active managed WireGuard subnets are masqueraded outbound to the host WAN interface.
|
|
- **Dynamic Subnet Calculation**: The reconciliation engine queries all enabled interfaces (`Interface.address_v4`) and generates dedicated masquerade rules for each unique subnet.
|
|
|
|
---
|
|
|
|
## 5. Domain Validation & Invariants
|
|
|
|
1. **Priority Uniqueness & Ordering**: Rules are sorted by `priority ASC, created_at ASC` ensuring determinism.
|
|
2. **CIDR Validation**: Source and destination values must parse as valid IPv4 or IPv6 CIDRs.
|
|
3. **Port Bounds**: Port numbers must fall within standard bounds (`1..=65535`). In ranges `A-B`, `A <= B` is strictly enforced.
|