ESPectre
No promiscuous capture
Our firmware works as a normal Wi-Fi client and never listens to other people's traffic (promiscuous mode). It must join a network, and protected networks need the password.
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 only senses while connected to a Wi-Fi network, and normally shares only motion information.
Derive motion locally
The firmware processes CSI on the ESP32 and shares only movement, motion state, and a few diagnostics. Raw CSI is available only on request, for research, over one local connection (GET /espectre/v1/csi).
Limit what leaves the device
MQTT messages contain no raw CSI, Wi-Fi names, access point addresses, IP or MAC addresses, packet captures, or serial logs. The device ID is derived from the MAC with SHA-256, so it hides the MAC but never changes. Messages still include that ID, the labels you set, movement data, and diagnostics.
Important limitation: needing to join a network is a safeguard, not proof of permission. Open networks have no password, valid passwords can be misused, and open-source software can be modified. Whoever installs ESPectre is responsible for how it is used.
LOCAL ACCESS
Direct HTTP stays on your local network.
This website talks to your device directly from the browser. Chrome asks for permission before a website can reach a device on your local network: allow it only when you want to manage a device on this network. If Chrome says access is denied, turn on Local network access in the site settings; on systems with their own local network privacy setting (such as macOS), Chrome must be allowed there too.
- Browser support: tested with Chrome 151 or later on macOS. Chrome 151 or later on Windows and Linux should work but is not tested on real hardware yet, and automatic discovery depends on the system's mDNS setup. Firefox, Safari, Edge, mobile Chrome, and WSL may not work. The setup guide has the current compatibility table.
- Origin check: published Native firmware accepts requests only from the ESPectre website. A development build can also allow
localhost,127.0.0.1, or[::1]on any port, and nothing else. - Embedding: if another site embeds this website in a frame, the tools stay hidden and do not start. The documentation works without JavaScript, but device controls work only on the ESPectre website itself.
- Addressing: you can connect with an IP address, device name, full device ID, or the last 6 characters of the ID. If several devices match, the website shows them all.
- Auto-discovery: each attempt looks up a new random name,
espectre-devices-<24 hex>.local. An ESPectre device answers without storing the name, searches the network once for other ESPectre devices, and sends back their addresses. The setup guide explains how it works. - Capability checks: after you pick a device, the website asks what it supports and hides everything else.
- Discovery data: the website does not scan your network, keep a list of devices, or send device IDs, addresses, names, discovery data, or raw CSI to analytics.
- Host discovery: from a repository checkout,
./espectre deviceslists devices from your computer instead of the browser. - Connection failures: allow Local network access in the site settings, check the device's IP, and close other ESPectre tabs (a device accepts two browser connections at a time), then retry. If mDNS does not work on your network, use the IPv4 address from USB setup or your router; names and IDs need mDNS. A protocol error means the website and firmware versions do not match. If nothing works, use a supported desktop browser.
- No Internet exposure: never forward the device's port on your router or open it with UPnP. Direct HTTP has no login meant for remote access.
Browser policy reference: Chrome 147 Local Network Access.
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