feat(security): finish Windows firewall Public opt-in wiring + vuln-disclosure + doc cleanup
Firewall (the service.rs core landed in efb1ba2): scope the web-console rule
(TCP 47992) to Domain+Private by default with a `--allow-public-network` opt-in
that deletes-then-re-adds the rule, and add the installer "Allow connections on
Public networks" task (unchecked) forwarding the flag to `service install` and
`web setup`. Default is now trusted-networks-only; Public is explicit.
Vulnerability disclosure: SECURITY.md (report to security@punktfunk.com, scope,
SLAs, safe harbor), a Gitea issue-template contact link, a README security line,
and a Reporting section on the docs Security page.
Docs: the Security page now documents the Private/Domain firewall default (and
how to fix a misclassified-Public network / opt in); removed internal design-doc
and CLAUDE.md links from the user-facing docs.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -19,8 +19,8 @@ punktfunk-host serve
|
||||
Add `--gamestream` (alias `--moonlight`) to **also** run the GameStream/Moonlight-compatible planes
|
||||
(nvhttp pairing, RTSP, ENet control, `_nvstream` mDNS) — required for stock [Moonlight](/docs/moonlight)
|
||||
clients. This is **opt-in** because GameStream carries inherent on-path weaknesses (pairing over plain
|
||||
HTTP; its legacy control encryption can reuse GCM nonces — security-review #5/#9), so enable it **only
|
||||
on a trusted LAN**. The native plane is immune to those issues.
|
||||
HTTP; its legacy control encryption can reuse GCM nonces), so enable it **only on a trusted LAN**. The
|
||||
native plane is immune to those issues.
|
||||
|
||||
```sh
|
||||
punktfunk-host serve --gamestream
|
||||
|
||||
@@ -8,8 +8,8 @@ always-available host, run it as a service. There are two cases.
|
||||
|
||||
> The bundled unit `scripts/punktfunk-host.service` runs `serve --gamestream`, so it serves both the
|
||||
> native `punktfunk/1` plane and stock [Moonlight](/docs/moonlight) clients. For a **secure native-only
|
||||
> host** (no GameStream — its pairing runs over plain HTTP and its legacy encryption is weaker;
|
||||
> security-review #5/#9), drop `--gamestream` from the unit's `ExecStart` and use bare `serve`.
|
||||
> host** (no GameStream — its pairing runs over plain HTTP and its legacy encryption is weaker), drop
|
||||
> `--gamestream` from the unit's `ExecStart` and use bare `serve`.
|
||||
|
||||
## A. A desktop you log into
|
||||
|
||||
@@ -101,9 +101,15 @@ registers + starts the service for you (`/VERYSILENT` for unattended). Upgrades
|
||||
handled through Add/Remove Programs.
|
||||
|
||||
Prefer the CLI? Run `punktfunk-host service install` from an elevated prompt — see
|
||||
[Windows service](https://git.unom.io/unom/punktfunk/src/branch/main/docs/windows-service.md). For
|
||||
hardware encode you need a GPU — NVIDIA (NVENC), AMD (AMF), or Intel (QSV); the host falls back to
|
||||
software H.264 without one.
|
||||
[Windows Host](/docs/windows-host). For hardware encode you need a GPU — NVIDIA (NVENC), AMD (AMF), or
|
||||
Intel (QSV); the host falls back to software H.264 without one.
|
||||
|
||||
> **Firewall scope.** The installer opens the streaming + console ports on **Private and Domain**
|
||||
> networks only — not **Public**. If your LAN is (mis)classified Public, clients won't connect until
|
||||
> you set it to Private (Windows Settings → Network), and the host logs a warning when it's on a Public
|
||||
> network. For a trusted network Windows insists is Public, tick **"Allow connections on Public
|
||||
> networks"** at install (or pass `--allow-public-network` to `service install`). See
|
||||
> [Security & Safe Use](/docs/security) for the reasoning.
|
||||
|
||||
## Verifying
|
||||
|
||||
|
||||
@@ -54,12 +54,21 @@ If you want to stream from outside your home, tunnel in instead of opening up:
|
||||
- **Don't** map a router port to the host. A port-forward turns "trusted LAN service" into
|
||||
"internet-facing service" with none of the protections that implies.
|
||||
|
||||
A note for **portable machines**: the installer opens the streaming ports on the firewall for *all*
|
||||
network profiles, including Public. That's convenient at home but means that if you take a laptop host
|
||||
onto an untrusted network — a café, a hotel, a conference — other devices on that network can reach the
|
||||
ports and attempt to pair. Pairing still protects you (an attacker who doesn't know the PIN can't get
|
||||
in), but the safest habit is to stop the host service, or firewall it off, when you're on a network you
|
||||
don't control.
|
||||
A note on **Windows network profiles**: the installer opens the streaming and console ports only on
|
||||
**Private and Domain** networks — the profiles Windows uses for networks you've marked as trusted. On a
|
||||
network Windows classifies as **Public** (cafés, hotels, conferences — the default for unknown
|
||||
networks), the ports stay **closed**, so a laptop host won't accept connections there. That's the safe
|
||||
default, and it's the behavior you want on the move. Two things follow from it:
|
||||
|
||||
- **If your home network is *misclassified* as Public, clients won't connect.** Set it to Private
|
||||
(Windows Settings → Network & internet → your network → **Private network**). The host also logs a
|
||||
warning at startup when it detects it's on a Public network, so this doesn't fail silently.
|
||||
- **If you have a trusted network that Windows insists on marking Public** (some headless or
|
||||
no-gateway LAN setups), you can opt in during install — the **"Allow connections on Public
|
||||
networks"** checkbox (off by default). Only do this for a network you actually trust.
|
||||
|
||||
Either way, pairing is what ultimately gates access — but keeping the host off untrusted networks is
|
||||
the first line, and on the move the safest habit is still to stop the service when you don't need it.
|
||||
|
||||
## What actually protects you
|
||||
|
||||
@@ -109,9 +118,7 @@ We mitigate this deliberately:
|
||||
full-system. (This is why punktfunk dropped ViGEmBus.)
|
||||
- **Sealed internal channels.** The desktop-frame ring and the gamepad input/output channels are
|
||||
passed between the host and its drivers as duplicated handles to unnamed objects, so another local
|
||||
service can't open them by name to read your screen or forge controller input. (Details:
|
||||
[`idd-push-security.md`](https://git.unom.io/unom/punktfunk/src/branch/main/design/idd-push-security.md)
|
||||
and [`gamepad-channel-sealing.md`](https://git.unom.io/unom/punktfunk/src/branch/main/design/gamepad-channel-sealing.md).)
|
||||
service can't open them by name to read your screen or forge controller input.
|
||||
- **Secrets are locked down.** The management token, the host identity key, and the console password
|
||||
are stored with Administrators/SYSTEM-only permissions.
|
||||
|
||||
@@ -142,12 +149,20 @@ applies: keep it on a trusted LAN or a VPN, require pairing, and don't expose it
|
||||
- **Keep the host updated** — security fixes ship in new builds.
|
||||
- **On portable hosts**, stop the service when you're on an untrusted network.
|
||||
|
||||
## For the technically curious
|
||||
## Reporting a vulnerability
|
||||
|
||||
The deeper security design lives in the repository, and it's candid about residual limits:
|
||||
Found a security issue? **Email [security@punktfunk.com](mailto:security@punktfunk.com).** Please
|
||||
don't open a public issue, pull request, or chat post for a suspected vulnerability — that exposes
|
||||
other users before a fix is available.
|
||||
|
||||
- [`design/idd-push-security.md`](https://git.unom.io/unom/punktfunk/src/branch/main/design/idd-push-security.md) — the sealed frame channel (why the Windows capture path is isolated), and its honest floor.
|
||||
- [`design/gamepad-channel-sealing.md`](https://git.unom.io/unom/punktfunk/src/branch/main/design/gamepad-channel-sealing.md) — the sealed gamepad channel.
|
||||
- [`design/security-review-2026-06-28.md`](https://git.unom.io/unom/punktfunk/src/branch/main/design/security-review-2026-06-28.md) and [`design/security-review.md`](https://git.unom.io/unom/punktfunk/src/branch/main/design/security-review.md) — the standing security reviews.
|
||||
Helpful things to include:
|
||||
|
||||
Found a security issue? Please report it privately rather than opening a public issue.
|
||||
- The component and version — e.g. `punktfunk-host 0.6.0`, Windows or Linux, and which client.
|
||||
- The impact, and the attacker's position (same LAN, a paired client, a local service account,
|
||||
admin, …).
|
||||
- Steps to reproduce, a proof-of-concept, or a crash/log if you have one.
|
||||
|
||||
We acknowledge reports within **3 business days** and practice coordinated disclosure — we'll keep
|
||||
you posted, agree a disclosure date, and credit you when the fix ships (unless you'd rather stay
|
||||
anonymous). The full policy is in
|
||||
[`SECURITY.md`](https://git.unom.io/unom/punktfunk/src/branch/main/SECURITY.md).
|
||||
|
||||
@@ -4,8 +4,7 @@ description: "Where the work stands across the core, the host, and the native cl
|
||||
---
|
||||
|
||||
A high-level view of where punktfunk stands. The ordered plan of work is on the
|
||||
[Roadmap](/docs/roadmap), and milestone-level detail lives in
|
||||
[`CLAUDE.md`](https://git.unom.io/unom/punktfunk/src/branch/main/CLAUDE.md).
|
||||
[Roadmap](/docs/roadmap).
|
||||
|
||||
## Milestones at a glance
|
||||
|
||||
|
||||
Reference in New Issue
Block a user