feat: complete nx9-wg v0.8.0 platform
This commit is contained in:
thakares committed
1 parent
c75e5c4e71
commit
c8a9b7cde6
52 files changed
+7751
-725
No files matched your search
+50
-22
@@ -1,43 +1,71 @@
|
||||
# Security Model and Best Practices
|
||||
# Security Model, Privilege Architecture & Best Practices
|
||||
|
||||
`nx9-wg` implements a strict, self-hosted, fail-closed security architecture.
|
||||
`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
|
||||
## 1. Single Administrator Identity Model
|
||||
|
||||
- **Fixed Database Identity**: The administrative record in SQLite is locked with `CHECK (id = 1)`.
|
||||
- **No RBAC or Multi-Tenancy**: Eliminates attack surface from privilege escalation, permission bypasses, or broken object-level authorization.
|
||||
- **Argon2id Password Hashing**: State-of-the-art memory-hard password derivation (`argon2id`). Plaintext passwords are never stored in memory longer than verification duration and never written to disk or logs.
|
||||
- **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. Token and Session Security
|
||||
## 2. API Token and Session Architecture
|
||||
|
||||
- **Hashed API Tokens**: API tokens use the `nx9_<base64>` format. Only the SHA-256 cryptographic digest of the token is persisted in SQLite. Compromise of the database does not reveal plaintext API tokens.
|
||||
- **Global Session Invalidation**: When the administrator changes their password, all active sessions across all devices are immediately invalidated in SQLite.
|
||||
- **HttpOnly Cookies**: Session tokens sent to browsers use `HttpOnly`, `SameSite=Strict`, and `Secure` (when TLS is active).
|
||||
- **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. Brute-Force Rate Limiting
|
||||
## 3. Filesystem Permissions Matrix
|
||||
|
||||
- `nx9-wg` maintains an append-only tracking log of login attempts in SQLite.
|
||||
- If more than 5 failed authentication attempts originate from the same IP address within a 15-minute sliding window, subsequent login requests are rejected with `HTTP 429 Too Many Requests`.
|
||||
| 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. Secret Handling and Memory Safety
|
||||
## 4. Zero Subprocess Execution Guarantee
|
||||
|
||||
- **Redacted Debug Outputs**: Types holding sensitive material (`WireGuardPrivateKey`, `WireGuardPresharedKey`, `Admin`, `ApiToken`) implement custom `std::fmt::Debug` formatters outputting `[REDACTED]`.
|
||||
- **No Plaintext Logging**: Secrets are strictly excluded from structured `tracing` event spans.
|
||||
`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. Audit Logging
|
||||
## 5. nftables Scoping & Firewall Isolation
|
||||
|
||||
Every state-changing operation records an append-only audit event:
|
||||
- Authentication (`Login`, `Logout`, `LoginFailed`)
|
||||
- Credential Lifecycle (`PasswordChange`, `TotpChange`, `ApiTokenCreate`, `ApiTokenRevoke`)
|
||||
- Network & WireGuard (`InterfaceCreate`, `PeerCreate`, `PeerRotateKeys`, `RouteCreate`, `FirewallCreate`)
|
||||
- System Operations (`BackupCreate`, `BackupRestore`, `ReconciliationRun`)
|
||||
- **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`.
|
||||
- Web UI and REST API responses redact private keys and token hashes.
|
||||
- CLI status output strictly redacts sensitive 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`)
|
||||
Reference in new issue
Block a user