Skip to content

Security: CypherSisters/HomeBotFounders

SECURITY.md

Security Policy

PuffPAI (HomeBot) is the free early version you install yourself, running in real households. This policy describes what we support, how to report a problem, and what we promise you can go verify yourself rather than take on faith.

Supported versions

Only the current build on the main branch is supported. There are no released version tags yet; run against the latest commit on main and report issues against it.

Reporting a vulnerability

Please use GitHub's private vulnerability reporting for this repository (the repo's Security tab → Report a vulnerability) rather than opening a public issue. If you don't see the option, use the fallback below.

There is no security email address. If private reporting is not available on this repository yet, open a public issue titled "security contact request" containing nothing but that request, no details of the vulnerability, no reproduction, no affected file. We will reply on the issue with a private channel to send the details to.

Scope

In scope:

  • The Vault (Zone 1): PIN/recovery-code handling, key derivation, and what's stored encrypted at rest (src/puffpai/zone_vault.py, src/puffpai/security/vault.py).
  • Egress doors: the enumerated outbound-connection registry, its enforcement, and anything that lets the box reach a host that isn't a named, switched-on door (src/puffpai/security/egress_doors.py, src/puffpai/offline_guard.py).
  • Pairing gate: device-approval flow and anything that lets an unpaired device act on the system (src/puffpai/api_server.py pairing handling).
  • Consent gates: consent required before state-changing actions (src/puffpai/security/consent_gate.py, src/puffpai/security/consent_requests.py).
  • Home Assistant control gates: the untargeted/broadcast/lights gates on HA-action requests.
  • Anything that would let one profile/household read another's data, or let an unpaired party act on the system.

Out of scope: denial-of-service against your own local machine, and issues that require an attacker to already have full local access to the box the software runs on (local privilege on an already-compromised host is a platform problem, not a PuffPAI one).

Trust boundaries

Stated plainly so you can judge the design rather than infer it.

  • The trust boundary is "can reach the backend on loopback, with the API key". Inside that boundary there is no further authentication of the caller. Any local process that can open a socket to the backend can assert X-Puff-Device-Id and be believed, because the backend believes that header from a trusted peer (loopback by default), that is how the dashboard proxy and the on-box voice service identify themselves. What such a process cannot do is land in a particular household member's session: the id is an HMAC-SHA256 of the device id under the pairing secret, truncated to 128 bits, so hitting a real vault-chat bucket means guessing 128 bits. An unrecognised id simply gets its own empty bucket.
  • No host packet filter ships with this software. We do not install or manage nftables/iptables rules, and you should not assume one is present. Every gate described here is enforced in application code. If you want the backend port unreachable from the LAN, that is your firewall's job, not ours.
  • PUFFPAI_TRUSTED_PROXY_IPS must stay unset (or loopback-only) unless you genuinely run the dashboard on a different host from the backend. Every address named in it may assert any device identity. There is deliberately no wildcard, and a garbage value trusts nobody rather than everybody.
  • api_server.trusted_proxy_hops must stay 0 unless a real reverse proxy you control sits in front of the backend. Above 0 the backend starts believing X-Forwarded-For, which is a client-settable header: that would let a LAN caller choose the address its rate limiting and per-peer sessions are keyed on, and, because it would let that caller present itself as loopback, cross the trust boundary above and assert device identities.
  • A caller the proxy cannot identify gets nothing, not someone else's session. A legacy v1 pairing cookie, a scoped device token, or an unpaired browser at the knowledge enforcement stage all reach the backend with no device identity. Those requests are marked X-Puff-Anonymous by the proxy, keyed to a single-use session id, and refused vault answers with a "pair this device" message. Sharing one bucket keyed on the proxy's own loopback address would let one member's 300-second vault unlock be inherited by any other unidentified caller.

Response expectations

This is a small team building in the open. We aim to acknowledge a report within a reasonable time and will say so plainly if a fix will take longer than that; we are not promising an SLA we can't back.

Standing security contracts (test these yourself)

These are promises about the software's behavior, stated so you can check them rather than trust them:

  • Zero telemetry. Nothing phones home. Run the app with a local network monitor or a deny-by-default firewall and confirm no outbound traffic occurs beyond what you explicitly configured.
  • Enumerated egress. The set of hosts the running box may reach is finite and named door-by-door in docs/WHAT_CAN_LEAVE_YOUR_HOUSE.md, generated from the registry, not "the internet." Compare what the process actually connects to against that list.
  • Ledger. Door decisions are recorded so you can audit what left the house and when, rather than trust that nothing did.

If any of the above fails to hold on your machine, that's a security bug: please report it through the channel above.

There aren't any published security advisories