Security

Security

---

Reporting

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.

---

Secrets

Never commit:

• Tokens, API keys, OAuth client secrets
• Real config/comstar.yaml / comstar.dev.yaml
• config/comstar.mac.env
• AO mTLS PEMs under ~/.local/share/comstar/ao-mtls/
• Face images used for enrollment (prefer gitignore)
• Google refresh tokens under ~/.local/share/comstar/google/
• Road VPN secrets under ~/.local/share/comstar/road/

Use .example / .example.yaml templates only.

---

LAN binding (triple gate)

Never bind WebSocket ports to 0.0.0.0 unless all three are true:

1. COMSTAR_ENV=dev
2. Config file basename is comstar.dev.yaml
3. dev.bind_lan: true and dev.lan_token is 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.

---

Session / MCP boundaries

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

---

AO mTLS material

When orchestration.mtls.enabled, client PEMs live under ~/.local/share/comstar/ao-mtls/ (0600). Never commit them. Enroll from Admin AO pairing or make ao-mtls-enroll. Sessions fail closed if material is missing. Speech sidecars stay cleartext HTTP on the LAN. → ADR 0013

---

Offline SoftAP

Open SoftAP COMSTAR-<hostname> only while the Pi has no uplink. Admin token still required. → ADR 0014

---

Kill switches

1. Software: stop systemd user units (Runbook).
2. Network: unplug Ethernet / disable Wi-Fi.
3. Hardware: physical mic mute / camera cover — the promise you can make to a guest.

---

Related pages

• Privacy Model
• Admin Console
• Dev Loop
• Contributing for Agents
• Google Workspace