75 lines
4.8 KiB
Markdown
75 lines
4.8 KiB
Markdown
# Security Model, Privilege Architecture & Best Practices
|
|
|
|
`nx9-wg` is designed with a strict, defense-in-depth, fail-closed security architecture tailored for self-hosted sovereign network infrastructure.
|
|
|
|
---
|
|
|
|
## 1. Single Administrator Identity Model
|
|
|
|
- **Database-Level Constraint**: The administrative record in SQLite is locked with `CHECK (id = 1)`.
|
|
- **Zero Multi-Tenancy / RBAC Attack Surface**: Eliminates privilege escalation, role confusion, and broken object-level authorization vulnerabilities.
|
|
- **Argon2id Password Hashing**: State-of-the-art memory-hard password derivation (`argon2id`). Passwords are never stored in plaintext, never logged, and never included in error responses.
|
|
- **One-Time Credential Delivery**: Generated passwords and raw API tokens are displayed exactly once upon creation (or written to explicit 0600-permission files) and cannot be recovered from the database.
|
|
|
|
---
|
|
|
|
## 2. API Token and Session Architecture
|
|
|
|
- **Cryptographically Hashed Tokens**: API tokens follow the format `nx9_<uuid>_<random>`. Only the SHA-256 digest of the token (`token_hash`) is stored in SQLite. Database exfiltration will not compromise raw API tokens.
|
|
- **Global Session Invalidation**: Changing the administrator password automatically invalidates all active browser sessions across all devices.
|
|
- **Secure Cookie Flags**: Session cookies use `HttpOnly`, `SameSite=Strict`, and `Path=/`.
|
|
- **Brute-Force Rate Limiting**: Exponential backoff and IP-based rate limiting (5 failed attempts per 15-minute sliding window triggers `HTTP 429 Too Many Requests`).
|
|
|
|
---
|
|
|
|
## 3. Filesystem Permissions Matrix
|
|
|
|
| Path | Standard Owner | File Mode | Purpose / Security Scope |
|
|
| :--- | :--- | :--- | :--- |
|
|
| `/usr/local/bin/nx9-wg` | `root:root` | `0755` | Executable binary |
|
|
| `/etc/nx9-wg/` | `root:root` | `0750` | Configuration directory |
|
|
| `/etc/nx9-wg/config.toml` | `root:root` | `0640` | Production configuration file |
|
|
| `/var/lib/nx9-wg/` | `root:root` | `0700` | Working directory and SQLite database storage |
|
|
| `/var/lib/nx9-wg/nx9-wg.db` | `root:root` | `0600` | Authoritative SQLite database with WAL journals |
|
|
| `/var/lib/nx9-wg/backups/` | `root:root` | `0700` | Atomic SQLite database snapshots and checksum manifests |
|
|
| `/var/lib/nx9-wg/admin-password`| `root:root` | `0600` | Initial generated password file |
|
|
| `/var/log/nx9-wg/` | `root:root` | `0750` | Operational logs (if file logging enabled) |
|
|
|
|
---
|
|
|
|
## 4. Zero Subprocess Execution Guarantee
|
|
|
|
`nx9-wg` strictly forbids external subprocess execution in production:
|
|
- **No `std::process::Command` / `tokio::process`**: Eliminates command injection, shell escaping vulnerabilities, and PATH hijack risks.
|
|
- **No External CLI Dependencies**: Does not shell out to `wg`, `ip`, `nft`, `iptables`, `sysctl`, or `bash`.
|
|
- **Direct Kernel Communication**: Communicates via native Linux Netlink sockets (RTNETLINK and WireGuard Generic Netlink) and direct in-process `libnftables` Netfilter bindings.
|
|
|
|
---
|
|
|
|
## 5. nftables Scoping & Firewall Isolation
|
|
|
|
- **Table Isolation**: All rules and chains are strictly confined to `table inet nx9_wg`.
|
|
- **Zero Interference**: `nx9-wg` never flushes or modifies external tables created by Docker, Kubernetes, systemd-networkd, or host firewalls.
|
|
- **Deterministic Priority Rules**: Chains and rules are ordered deterministically by priority index to prevent rule shadowing or accidental packet leaks.
|
|
|
|
---
|
|
|
|
## 6. Secret Redaction & Memory Safety
|
|
|
|
- Custom `std::fmt::Debug` implementations enforce `[REDACTED]` for `WireGuardPrivateKey`, `WireGuardPresharedKey`, `Admin`, and `ApiToken`.
|
|
- **Upstream Import Secret Safety**: Third-party `.conf` previews and import responses never return private keys or preshared keys in cleartext. Sensitive keys are stored strictly in the database and submitted to the kernel over Netlink.
|
|
- **Reconciliation Plan & Report Scrubbing**: Dry-run plans and reconciliation convergence reports scrub private keys and preshared keys to prevent accidental leakage into logs or event streams.
|
|
- **SPA CLI Console Output Sanitization**: The read-only SPA CLI execution endpoint runs an automated secret scrubber over command outputs, stripping private keys and credentials before returning output to the browser.
|
|
- Web UI and REST API responses redact private keys and token hashes.
|
|
- CLI status output strictly redacts sensitive cryptographic keys and password hashes.
|
|
|
|
---
|
|
|
|
## 7. Append-Only Security Audit Logging
|
|
|
|
Every state mutation records an append-only audit event with timestamp, actor, IP address, event type, and context metadata:
|
|
- Authentication events (`Login`, `Logout`, `LoginFailed`)
|
|
- Credential modifications (`PasswordChange`, `ApiTokenCreate`, `ApiTokenRevoke`)
|
|
- WireGuard & Network configurations (`InterfaceCreate`, `PeerCreate`, `RouteCreate`, `FirewallCreate`)
|
|
- System operations (`BackupCreate`, `BackupRestore`, `ReconciliationRun`)
|