Raven Scott
@@ -0,0 +1,185 @@
|
||||
# Security
|
||||
|
||||
## Overview
|
||||
|
||||
Holesail Browser is a system that runs a native process with your user privileges and installs a root CA certificate into your OS trust store. Understanding the security model is important before installing it.
|
||||
|
||||
---
|
||||
|
||||
## Certificate Authority
|
||||
|
||||
### What It Is
|
||||
|
||||
The native host generates a local root CA named `Holesail Browser CA` using `node-forge`. This CA is used to sign a wildcard TLS certificate for `*.hole.sail`, which the HTTPS proxy presents to the browser.
|
||||
|
||||
### Why It Is Needed
|
||||
|
||||
Browsers enforce TLS for all HTTPS connections. The local HTTPS proxy (`127.0.0.1:8443`) must present a valid certificate for `*.hole.sail` hostnames, or the browser will show a certificate error and refuse to load the page. Installing the local CA into the OS trust store makes the browser trust this certificate.
|
||||
|
||||
### What It Can Do
|
||||
|
||||
Once installed, the `Holesail Browser CA` can sign certificates for **any domain** — not just `*.hole.sail`. This is an inherent property of root CA trust. However:
|
||||
|
||||
- The CA private key is stored locally at `holesail-browser-certs/ca.key.pem`, accessible only to your user account.
|
||||
- The HTTPS proxy only issues certificates for `*.hole.sail` hostnames.
|
||||
- The CA is not shared with any third party.
|
||||
|
||||
### Certificate Lifetime
|
||||
|
||||
| Certificate | Validity |
|
||||
|-------------|---------|
|
||||
| Root CA | 10 years |
|
||||
| `*.hole.sail` wildcard | 1 year |
|
||||
|
||||
If the CA expires or is regenerated, you must re-install it via Dashboard → Proxy & CA → Install CA.
|
||||
|
||||
### CA Storage
|
||||
|
||||
```
|
||||
holesail-browser-certs/
|
||||
├── ca.key.pem ← Root CA private key (keep secret)
|
||||
├── ca.cert.pem ← Root CA certificate
|
||||
└── wildcard.hole.sail/
|
||||
├── key.pem ← Wildcard cert private key
|
||||
└── cert.pem ← Wildcard cert + CA chain
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## P2P Connection Encryption
|
||||
|
||||
All Holesail connections are encrypted end-to-end using the [Noise protocol](https://noiseprotocol.org/) (`Noise_XX_25519_XChaChaPoly_BLAKE2b`). This provides:
|
||||
|
||||
- **Mutual authentication** — both peers verify each other's public keys
|
||||
- **Forward secrecy** — session keys are ephemeral; compromising a long-term key does not expose past sessions
|
||||
- **Integrity** — all data is authenticated with a MAC; tampering is detected
|
||||
|
||||
Encryption is handled automatically by Holesail. No configuration is required.
|
||||
|
||||
---
|
||||
|
||||
## Native Host Privilege Model
|
||||
|
||||
### What the Native Host Can Do
|
||||
|
||||
The native host runs as your user account. It can:
|
||||
|
||||
- Make arbitrary network connections (P2P via Holesail tunnels)
|
||||
- Read and write files in `holesail-browser-storage/` and `holesail-browser-certs/`
|
||||
- Spawn child processes (the `ssh` binary, `tar` for backups, `osascript` for CA installation on macOS)
|
||||
- Listen on local TCP ports (8442, 8443, 19000+, 20000–21999 for SSH, 22000–23999 for Remote Desktop)
|
||||
|
||||
### What the Native Host Cannot Do
|
||||
|
||||
- It cannot access files outside its working directory unless explicitly instructed via a command
|
||||
- It cannot access other users' data
|
||||
- It does not run as root (except briefly during CA installation on macOS, where `osascript` prompts for your password)
|
||||
|
||||
### Extension ↔ Native Host Trust
|
||||
|
||||
The browser extension communicates with the native host via Chrome/Firefox native messaging. The native messaging manifest (`com.holesail.browser.json`) specifies which extension IDs are allowed to connect. Only the extension with the matching ID can send commands to the native host.
|
||||
|
||||
---
|
||||
|
||||
## Threat Model
|
||||
|
||||
### Threats Mitigated
|
||||
|
||||
| Threat | Mitigation |
|
||||
|--------|-----------|
|
||||
| Eavesdropping on P2P connections | Noise protocol end-to-end encryption |
|
||||
| Peer identity spoofing | Cryptographic key pairs; Noise mutual authentication |
|
||||
| Man-in-the-middle on P2P | Noise protocol; keys are verified before data exchange |
|
||||
| Malicious peers flooding connections | `maxPeers` option on `new Holesail({ maxPeers: N })` |
|
||||
| Unauthorized extension connecting to native host | `allowed_origins` in native messaging manifest |
|
||||
| Certificate errors for `*.hole.sail` | Local CA installed in OS trust store |
|
||||
| Stale CA after regeneration | `isRootCAInstalled` checks fingerprint, not just CN |
|
||||
|
||||
### Threats Not Mitigated
|
||||
|
||||
| Threat | Notes |
|
||||
|--------|-------|
|
||||
| Malicious `hs://` URLs | Any `hs://` key you add as a virtual host will receive your HTTP requests. Only add keys from sources you trust. |
|
||||
| Local network attacks | The HTTPS proxy and CONNECT proxy listen on `127.0.0.1` only, not on network interfaces. |
|
||||
| Compromised native host binary | If the binary is replaced by a malicious version, it has full user-level access. Only install from trusted sources. |
|
||||
| CA private key theft | If `holesail-browser-certs/ca.key.pem` is stolen, the attacker can issue certificates trusted by your browser. Protect this file. |
|
||||
|
||||
---
|
||||
|
||||
## Proxy Security
|
||||
|
||||
### HTTPS Proxy (`127.0.0.1:8443`)
|
||||
|
||||
- Listens on loopback only — not accessible from the network
|
||||
- Presents the `*.hole.sail` wildcard certificate for all `*.hole.sail` requests
|
||||
- Only forwards requests to hostnames registered as virtual hosts via `holesailManager.getLocalBackend()`
|
||||
- Unknown hostnames receive a 502 error
|
||||
|
||||
### CONNECT Proxy (`127.0.0.1:8442`)
|
||||
|
||||
- Listens on loopback only
|
||||
- Accepts `CONNECT` requests from the browser (via the PAC script)
|
||||
- Pipes raw TCP to the HTTPS proxy on port 8443
|
||||
- Does not inspect or modify the tunneled traffic
|
||||
|
||||
### PAC Script
|
||||
|
||||
The PAC script routes only `*.hole.sail` traffic through the local proxy. All other traffic goes directly (`DIRECT`). The extension re-applies the PAC script if it is overridden by another extension or system setting.
|
||||
|
||||
---
|
||||
|
||||
## SSH Security
|
||||
|
||||
SSH sessions use the system `ssh` binary with:
|
||||
|
||||
```
|
||||
-o StrictHostKeyChecking=no
|
||||
-o UserKnownHostsFile=/dev/null
|
||||
```
|
||||
|
||||
These options disable host key verification because the SSH connection goes to `127.0.0.1` (the Holesail tunnel endpoint), not the actual remote host. The Holesail tunnel itself provides authentication — only the peer with the correct `hs://` key can receive the connection.
|
||||
|
||||
If you require SSH host key verification, you can configure it manually by editing the `sshArgs` array in `native-host/ssh-manager.js`.
|
||||
|
||||
---
|
||||
|
||||
## Tunnel State Storage
|
||||
|
||||
Tunnel configuration (server tunnels, virtual hosts, service tunnels) is persisted to:
|
||||
|
||||
```
|
||||
native-host/holesail-browser-storage/state.json
|
||||
```
|
||||
|
||||
This file is owned by your user account and contains only tunnel metadata (ports, hostnames, `hs://` keys). No tunnel traffic is written to disk.
|
||||
|
||||
---
|
||||
|
||||
## Remote Desktop Security
|
||||
|
||||
VNC and RDP sessions are forwarded over Holesail tunnels, so the connection is encrypted end-to-end by the Noise protocol. However:
|
||||
|
||||
- **VNC passwords** are handled by the VNC server's own authentication. The native host acts as a transparent byte pipe; it does not inspect VNC credentials.
|
||||
- **RDP passwords** are passed to `node-rdpjs-2` and transmitted over the Holesail tunnel. They are held in memory only for the duration of the session and are never written to `state.json`.
|
||||
- The WebSocket servers for Remote Desktop sessions (`127.0.0.1:23000+`) listen on loopback only.
|
||||
|
||||
---
|
||||
|
||||
## Backup Security
|
||||
|
||||
Backup archives (`tar.gz`) contain `state.json` (which includes `hs://` keys and connection metadata) and the CA private key (`ca.key.pem`). Treat backup files with the same care as the originals:
|
||||
|
||||
- Backup files are stored in `holesail-browser-storage/backups/` with user-only permissions
|
||||
- Do not share backup files — they contain your CA private key and all tunnel keys
|
||||
- After restoring a backup, reinstall the CA if the certificates changed
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. **Only add `hs://` URLs from sources you trust.** A virtual host forwards your browser's HTTP requests to the remote peer.
|
||||
2. **Protect `holesail-browser-certs/ca.key.pem`.** This file allows issuing certificates trusted by your browser.
|
||||
3. **Protect backup archives.** They contain the CA private key and all tunnel metadata.
|
||||
4. **Review the extension permissions.** The extension has `proxy` permission (required to set the PAC script) and `nativeMessaging` (required to communicate with the native host).
|
||||
5. **Keep the native host up to date.** Security fixes may be released as updates.
|
||||
6. **Uninstall the CA when you uninstall Holesail Browser.** See [INSTALLATION.md](INSTALLATION.md) for uninstall instructions.
|
||||
Reference in New Issue
Block a user