forked from snxraven/peardock
snxraven
244ff569f5
Holesail is on unless ENABLE_HOLESAIL=0/false/off. The holesail package remains a required dependency; docs and UI copy match the new default.
105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# peardock threat model
|
|
|
|
**Audience:** operators deploying peardock in multi-operator or semi-trusted environments.
|
|
**Scope:** HyperDHT P2P control plane + local Docker Engine socket.
|
|
|
|
---
|
|
|
|
## 1. Assets
|
|
|
|
| Asset | Sensitivity |
|
|
|-------|-------------|
|
|
| `SERVER_SEED` | Critical — identity + vault key derivation |
|
|
| Docker socket access | Critical — full host container control |
|
|
| Registry passwords (vault) | High — encrypted at rest |
|
|
| Peer invite tokens | Medium — short-lived capability grants |
|
|
| Audit log | Medium — forensic integrity |
|
|
| Container data / env secrets | High — via inspect, logs, exec, archive |
|
|
|
|
---
|
|
|
|
## 2. Trust boundaries
|
|
|
|
```
|
|
[Pear client] --Noise/HyperDHT--> [peardock server] --unix socket--> [dockerd]
|
|
|
|
|
+-- peardock-vault.json (AES-GCM)
|
|
+-- peardock-peers.json
|
|
+-- peardock-audit.log
|
|
```
|
|
|
|
- **Anyone with the server public key** can *attempt* a DHT connection.
|
|
- **Default role is admin** unless `PEARDOCK_DEFAULT_ROLE` / `PEARDOCK_ADMIN_KEYS` / peer policy tighten it.
|
|
- **Swarm / plugins** are off unless `ENABLE_SWARM` / `ENABLE_PLUGINS`.
|
|
- **Holesail tunnels** are on by default (`ENABLE_HOLESAIL=0` to disable) — each `hs://` URL is a capability to the target port.
|
|
- **Host FS browse** is **default-deny** unless `PEARDOCK_BROWSE_ROOTS` or `PEARDOCK_BROWSE_OPEN=1`.
|
|
|
|
---
|
|
|
|
## 3. Adversaries
|
|
|
|
1. **Remote internet peer** with public key only — should not get Docker control if allowlist + non-admin default are set.
|
|
2. **Stolen invite token** — limited by TTL / max uses; should be rotated after use.
|
|
3. **Compromised client machine** — can use any role the peer holds until revoke.
|
|
4. **Local host attacker with filesystem** — can steal `SERVER_SEED` and vault if file perms wrong.
|
|
5. **Malicious container** — not in scope for peardock; Engine isolation applies.
|
|
|
|
---
|
|
|
|
## 4. Controls (implemented)
|
|
|
|
| Control | Mechanism |
|
|
|---------|-----------|
|
|
| Transport E2E | HyperDHT Noise |
|
|
| Capability ACL | `viewer` / `operator` / `admin` + `MethodRoles` |
|
|
| Peer policy | Invite, register, revoke, optional allowlist |
|
|
| Audit | Append-only log for privileged methods |
|
|
| Rate limit | Per-peer limiter on RPC |
|
|
| Registry secrets | AES-256-GCM vault (`registry-vault.js`) |
|
|
| Browse FS | Root allowlist / default deny |
|
|
| Feature gates | `ENABLE_SWARM`, `ENABLE_PLUGINS`, `ENABLE_HOLESAIL` (default on; set `0` to disable), `PEARDOCK_UNRESTRICTED_CLI` |
|
|
| Tunnel targets | Loopback / allowlisted hosts only (`PEARDOCK_TUNNEL_HOSTS`) |
|
|
|
|
---
|
|
|
|
## 5. Residual risks
|
|
|
|
- **Default admin** is intentional for single-operator setup — **must** change for multi-tenant.
|
|
- Binary image/export streams are size-capped but still large; DoS via memory if many concurrent transfers.
|
|
- JSON-over-RPC is not hyperschema-validated end-to-end; malformed args rely on handler validation.
|
|
- Swarm secrets/configs once enabled are highly privileged.
|
|
|
|
---
|
|
|
|
## 6. Operator hardening checklist
|
|
|
|
- [ ] Generate unique `SERVER_SEED`; back up offline; never commit `.env`
|
|
- [ ] Set `PEARDOCK_DEFAULT_ROLE=viewer` or `operator`
|
|
- [ ] Set `PEARDOCK_ADMIN_KEYS=<your client public key hex>`
|
|
- [ ] Enable `PEARDOCK_PEER_ALLOWLIST=1` after registering operators
|
|
- [ ] Set `PEARDOCK_BROWSE_ROOTS` only if host path pickers are needed
|
|
- [ ] Leave `ENABLE_SWARM` / `ENABLE_PLUGINS` off unless required
|
|
- [ ] File mode `600` on vault, peer policy, audit, `.env`
|
|
- [ ] Run server as non-root in `docker` group (see `deploy/peardock.service`)
|
|
- [ ] Review `peardock-audit.log` periodically
|
|
- [ ] Revoke lost client keys immediately (`revokePeer` / Access UI)
|
|
|
|
---
|
|
|
|
## 7. Pentest focus areas
|
|
|
|
1. RPC methods missing from `MethodRoles` (should default admin)
|
|
2. Invite race / reuse after expiry
|
|
3. Path traversal on `browseDirectory` / archive paths
|
|
4. Command injection on docker CLI allow-list bypass
|
|
5. Role escalation via handshake args (must be ignored)
|
|
6. Vault decryption with wrong seed / key rotation story
|
|
|
|
---
|
|
|
|
## 8. Explicit non-goals
|
|
|
|
- Multi-tenant hard isolation between Docker namespaces
|
|
- Replacing Docker authorization plugins
|
|
- Protecting against root on the Docker host
|