Security
COMSTAR is pre-alpha and primarily a personal LAN deployment. For vulnerabilities in this project, open a private report to the repository owner (avoid posting tokens, configs, or home network details publicly).
Upstream dependencies (AO, Reach, CPAI, openWakeWord, etc.) have their own policies — report there when the issue is in those projects.
Never commit:
- Tokens, API keys, OAuth client secrets
- Real
config/comstar.yaml/comstar.dev.yaml config/comstar.mac.env- Face images used for enrollment (prefer gitignore)
- Google refresh tokens under
~/.local/share/comstar/google/
Use .example / .example.yaml templates only.
Never bind WebSocket ports to 0.0.0.0 unless all three are true:
COMSTAR_ENV=dev- Config file basename is
comstar.dev.yaml -
dev.bind_lan: trueanddev.lan_tokenis non-empty
Production configs must ship with dev.bind_lan: false. A T0 test asserts the example production template keeps bind_lan false. The bridge logs a warn on every dev-mode start naming the bound interface.
Ports 8777/8778 (and VM service) are subject to the same gates when exposed beyond loopback.
Admin HTTP (:8781) is gated separately. Bind LAN with
COMSTAR_ADMIN_BIND_LAN + COMSTAR_ADMIN_TOKEN (or admin.bind_lan /
admin.token). When LAN-bound, /admin/* requires X-Comstar-Lan-Token or
?token= except GET /admin/health and static assets. /oauth/google/* never
requires the admin token. Details: Admin Console.
| Boundary | Rule |
|---|---|
| Guest sessions | Restricted overlay — no HA, no Google, no terminal control |
| Overlay leakage | Always SessionBridge.stop() on SIGTERM / identity change |
| Google tokens |
0600 per-userid files; guests cannot pair |
| Speech PCM | LAN only in Phase 1 — same boundary as CPAI |
→ Privacy Model · Contracts — MCP
- Software: stop systemd user units (Runbook).
- Network: unplug Ethernet / disable Wi-Fi.
- Hardware: physical mic mute / camera cover — the promise you can make to a guest.