TermBeam Security

Overview

TermBeam provides access to a real shell on your machine. Security is critical.

Threat Model

TermBeam exposes a real shell over the network. The risk depends entirely on how you run it. Understanding the operating modes below helps you make informed decisions.

Operating Modes

TermBeam has three access layers that combine to determine your risk profile:

Mode	Command	Who Can Connect	Auth	Risk
Default (private tunnel)	`termbeam`	Only you (Microsoft login + password)	Auto-password + tunnel owner auth	✅ Low
Public tunnel	`termbeam --public`	Anyone with the URL + password	Auto-password	⚠️ Medium
LAN-only (localhost)	`termbeam --no-tunnel`	Local machine only	Auto-password	✅ Low
LAN-only (all interfaces)	`termbeam --no-tunnel --lan`	Any device on your network	Auto-password	⚠️ Medium
Localhost, no password	`termbeam --no-tunnel --no-password`	Local processes only	None	⚠️ Medium
LAN, no password	`termbeam --no-tunnel --no-password --lan`	Anyone on your network	None	🔴 High

Private Tunnel (Default)

The default mode creates an ephemeral Azure DevTunnel that requires two layers of authentication:

Microsoft account login — only the tunnel owner can access the URL
TermBeam password — auto-generated on each run

This is the safest way to access your terminal remotely. The tunnel URL is HTTPS, the connection is encrypted end-to-end, and the URL is unguessable.

Public Tunnel

With --public, the tunnel URL is accessible to anyone who has it — no Microsoft login required. Password authentication is still enforced. This mode is useful for sharing temporary access, but the terminal is internet-accessible and protected only by the password and rate limiting (5 attempts/min/IP).

LAN Exposure

With --lan or --host 0.0.0.0, TermBeam binds to all network interfaces. Any device on your local network can reach the server. On trusted home networks this may be acceptable; on shared or public networks (coffee shops, coworking spaces, hotel Wi-Fi) this is risky.

Safe Defaults

Out of the box, TermBeam is configured conservatively:

✅ Password auto-generated — a strong random password is created on every run
✅ Localhost bind — server listens on 127.0.0.1 only
✅ Private tunnel — tunnel requires Microsoft account login (owner-only)
✅ Ephemeral tunnel — tunnel URL is deleted when TermBeam exits
✅ Security headers — X-Frame-Options, CSP, no-store, nosniff on all responses
✅ Rate-limited login — 5 attempts per minute per IP
✅ Constant-time password comparison — prevents timing-based password recovery
✅ httpOnly cookies — tokens not accessible to JavaScript
✅ WebSocket origin validation — cross-origin connections rejected
✅ Shell path validation — only detected shells allowed

Dangerous Modes

The following flags increase your attack surface. Use them only when you understand the trade-offs.

Flag	Effect	When Acceptable
`--public`	Removes Microsoft login from tunnel	Sharing temporary access with someone without a Microsoft account
`--no-password`	Removes password auth	Localhost-only on a single-user machine
`--lan` / `--host 0.0.0.0`	Binds to all interfaces	Trusted home network with password enabled
`--lan --no-password`	LAN-accessible, no auth	Not recommended

Quick Safety Checklist

Before running TermBeam, verify:

Password is enabled — don’t use --no-password unless localhost-only on a trusted machine
Tunnel is private — don’t use --public unless you specifically need anonymous tunnel access
Bind is localhost — don’t use --lan unless you need LAN access on a trusted network
Close when done — TermBeam is not a daemon; don’t leave it running unattended
Check the network — on shared/public Wi-Fi, stick to defaults

Work vs Personal Machine

Personal machine (home network): Default settings are appropriate. If you need LAN access (e.g., phone on the same Wi-Fi), --lan with the auto-generated password is reasonable.

Work machine (corporate network): Use defaults (private tunnel + auto-password). Avoid --public and --lan on corporate networks. TermBeam is a development tool, not a production remote access solution.

Security Features

Authentication

Password is auto-generated by default; can also be set via --password or TERMBEAM_PASSWORD
Tokens are cryptographically random (32 bytes, hex-encoded)
Tokens expire after 24 hours
Session IDs use 128-bit entropy (crypto.randomBytes(16), hex-encoded)
Stored in httpOnly cookies (not accessible via JavaScript)
Cookie uses sameSite: strict to prevent CSRF
Cookie Secure flag is set dynamically based on the request protocol — enabled automatically when accessed over HTTPS (including via X-Forwarded-Proto from tunnel proxies), omitted for plain HTTP
API routes (/api/*) always return JSON 401/429 responses. UI routes redirect to the login page.

On startup, a share token is generated and embedded in the QR code URL as ?ott=<token>
Scanning the QR code sets a full session cookie and redirects to the clean URL — no password typing required
Share tokens are one-time use — consumed on first successful login to prevent replay attacks
Share tokens expire after 5 minutes
The share button generates a fresh share token via GET /api/share-token (authenticated endpoint)
If the user already has a valid session cookie, a repeated ?ott= request simply redirects without re-validating
Raw password is never embedded in any URL

Shell Path Validation

The POST /api/sessions endpoint validates the shell parameter against the list of detected shells on the host
Arbitrary shell paths are rejected — only shells returned by GET /api/shells are allowed
The cwd parameter is validated to be an existing, absolute directory path

Image Upload Validation

The POST /api/upload endpoint validates uploaded images using multiple checks:
- Content-Type must be an image/* MIME type
- Magic bytes are verified against the declared content type to prevent spoofing
- File size is capped at 10 MB (returns HTTP 413 if exceeded)
Uploaded files are stored with UUID-generated filenames to prevent path traversal
Requires authentication to upload or access uploaded files

Terminal Resize Bounds

WebSocket resize messages validate dimensions: columns must be 1–500, rows must be 1–200
Values outside these bounds are silently ignored, preventing DoS via extreme terminal sizes

WebSocket Origin Validation

WebSocket connections include Origin header checks
Cross-origin connections are rejected (close code 1008) unless one side is localhost
Prevents malicious websites from connecting to a local TermBeam instance

Rate Limiting

Login endpoint limited to 5 attempts per minute per IP
WebSocket auth limited to 5 attempts per minute per IP
Returns HTTP 429 (or WebSocket close) when exceeded

HTTP Security Headers

Every response includes:

Header	Value	Purpose
`X-Content-Type-Options`	`nosniff`	Prevent MIME sniffing
`X-Frame-Options`	`DENY`	Prevent clickjacking
`Content-Security-Policy`	script/style/connect sources	Prevent XSS
`Cache-Control`	`no-store`	Prevent caching
`Referrer-Policy`	`no-referrer`	No referrer leaks

Client-Side Features

The following UI features are entirely client-side and introduce no new server-side attack surface:

Command completion notifications — uses the browser Notification API, which requires explicit user permission (opt-in). No data is sent to external services; notifications are generated locally in the browser.
Terminal search — runs in the browser via the xterm.js SearchAddon. Search queries never leave the client.
Command palette — a client-side UI panel that triggers existing actions. No new endpoints or permissions required.

Network Binding

Default: Binds to 127.0.0.1 (localhost only)
Use --lan or --host 0.0.0.0 to allow LAN access
The tunnel feature handles TLS via Azure DevTunnels

Tunnel Token Expiry

DevTunnel auth tokens expire periodically (a Microsoft-imposed limitation)
The DevTunnel CLI handles token refresh automatically via OAuth refresh tokens
If the refresh token itself expires, TermBeam enters auth-wait mode, pausing tunnel operations until the user runs devtunnel user login on the host machine
Once re-authenticated, the watchdog reconnects the tunnel automatically — no server restart required

Best Practices

Password is on by default — use --no-password only for trusted localhost scenarios. --public requires password authentication and will refuse to start without it
Localhost is the default — use --lan only when you need LAN access
Tunnel access is private by default — only you (the tunnel owner) can access it via Microsoft login. Use --public to allow public access, or --no-tunnel for LAN-only mode
Close TermBeam when done — it’s not a daemon, don’t leave it running
Use on trusted networks — TermBeam is not designed for hostile environments

Reporting Vulnerabilities

Please do NOT open a public GitHub issue for security vulnerabilities. Instead, report vulnerabilities privately via the Security Advisories page — click “Report a vulnerability” and provide a detailed description.