peardock/docs/THREAT_MODEL.md

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