# 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