ESPectre
No promiscuous capture
Supported first-party firmware operates as an associated Wi-Fi station and does not enable Wi-Fi promiscuous mode. A deployment must join a network; protected networks require valid credentials.
Security and responsible use
Wi-Fi sensing avoids collecting images or audio, but presence and movement data can still expose people’s routines. Use ESPectre only with proper authority, clear notice, and a proportionate purpose.
SECURITY MODEL
Built to sense on a network you control.
ESPectre deliberately keeps the supported sensing path associated with a Wi-Fi network and limits normal operation to derived motion information.
Derive motion locally
Normal sensing frontends process CSI on the ESP32 and expose derived movement, motion state, and limited diagnostics. Raw CSI export belongs to the separate, explicit Streamer research workflow.
Limit what leaves the device
Canonical MQTT sensing messages omit raw CSI, Wi-Fi names, BSSIDs, local IP and MAC addresses, packet captures, and serial logs. The device ID is a stable SHA-256-derived pseudonym instead of the raw MAC, but messages still include that linkable ID, user-provided labels, movement data, and operational diagnostics.
Important limitation: association is a deliberate safeguard, not proof of consent or authority. Open networks do not require a password, authorized credentials can be misused, and open-source software can be modified. The operator remains responsible for every deployment.
LOCAL ACCESS
Direct WebSocket stays inside the trusted LAN.
The hosted portal connects from HTTPS to the selected ESPectre device's cleartext local WebSocket. Chrome 147 added Local Network Access permission checks for WebSockets and prompts before a public site can reach a local address. Allow that permission only when you intend to manage a device on the current network.
- Browser support: the hosted Direct workflow supports Chrome 147 or later on desktop with Local Network Access; Chrome 151 on macOS passed the hosted HTTPS validation path against a physical ESP32-C3. Firefox and Safari block this HTTPS-to-
ws://path under their mixed-content policies. Edge and mobile Chrome remain unclaimed until their physical browser runs are recorded. An unclaimed browser is not assumed compatible merely because it shares an engine with Chrome. - Origin check: published Native firmware accepts only the production ESPectre portal origins. An opted-in development build accepts HTTP on any port only for exact
localhost,127.0.0.1, or[::1]hosts; host lookalikes remain rejected. - Addressing: the portal accepts a private IP, device name, full device ID, or 6-character ID suffix, and keeps WebSocket and mDNS endpoint syntax out of the connection form. A name or suffix with multiple matches displays every candidate for explicit selection. For each optional Auto-discovery attempt, Web Crypto generates a new 96-bit nonce and contacts only
espectre-devices-<24 hex>.local; compatible Native firmware answers that IPv4 A question without registering or retaining the nonce, then performs one bounded DNS-SD browse and returns validated Native, Streamer, ESPHome, and Matter endpoints at their advertised ports. The former static bootstrap name is not used as a fallback. After selection, the portal negotiates the device's exact Direct capabilities and hides unsupported configuration and runtime actions. It does not scan address ranges, keep a peer inventory, or send device IDs, IPs, hostnames, local URLs, nonces, or discovery payloads to analytics. From a repository checkout,./espectre devicesremains the deterministic host discovery path. - Connection failures: allow Local network access in site settings, confirm the current IP, close other ESPectre tabs if the device's two Direct client slots are occupied, and retry. A protocol error requires matching portal and firmware releases. If hosted Direct is unsupported, use MQTT Monitor or a supported desktop browser.
- No Internet exposure: do not port-forward the Direct endpoint, publish it through UPnP, or treat the local service as remotely authenticated.
Browser policy references: Chrome 147 Local Network Access, Mozilla's mixed-content WebSocket decision, and WebKit's mixed-content WebSocket decision.
RESPONSIBLE DEPLOYMENT
Use the minimum sensing needed.
Before deploying ESPectre, consider the people, place, purpose, and data path involved.
- Have authority: use ESPectre only in spaces and on networks where you have the right to install and operate it.
- Inform affected people: provide clear notice and obtain consent where required by law or appropriate to the context.
- Minimize collection: prefer derived motion state, avoid raw CSI unless a defined research need justifies it, and keep retention short.
- Protect access: secure Wi-Fi and MQTT, use TLS and per-device credentials where available, restrict broker access, and do not commit secrets.
- Maintain the deployment: apply security updates, review integrations, remove abandoned devices, and delete data that is no longer needed.
- Do not treat motion as identity or safety evidence: ESPectre does not identify people, count them, or replace a safety-certified presence sensor.
ABUSE
Illegal or unethical use is not acceptable.
ESPectre rejects covert surveillance, stalking, coercion, discrimination, monitoring without legitimate authority, using occupancy patterns to facilitate intrusion, and any other illegal or unethical use of Wi-Fi sensing.
If you believe ESPectre or related Wi-Fi sensing is being used to harm people or violate the law, report the concern to us and, when appropriate, to the competent law enforcement, regulatory, or data protection authority. Contact local emergency services when someone may be in immediate danger.
Do not obtain evidence unlawfully or publish credentials, private telemetry, personal data, or details that could put someone at further risk. Reporting to the project does not replace reporting to the competent authorities.
VULNERABILITIES
Report security issues privately.
Do not disclose suspected vulnerabilities in public issues. Use GitHub’s private reporting flow, or email the security address if you cannot use GitHub Security Advisories.
Private vulnerability report
Share the affected version, a clear description, reproduction steps, potential impact, and any suggested mitigation. Do not include credentials or other people’s data.
Open private reporting ↗Contact the security team
Use email when GitHub private reporting is unavailable. Give us reasonable time to assess and coordinate a fix before public disclosure.
security@espectre.dev