Skip to content

Security

Overview

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

Threat Model

TermBeam is designed for trusted local networks. It is NOT designed as a production-grade remote access tool. Use with caution when exposing to the internet.

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: lax 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.

QR Code & Share Auto-Login (Share Tokens)

  • 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

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
  • Returns HTTP 429 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

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

Best Practices

Never Run Without a Password on a Public Network

Without authentication, anyone on the network can access your terminal with your user permissions.

  1. Password is on by default — use --no-password only for trusted localhost scenarios. --public requires password authentication and will refuse to start without it
  2. Localhost is the default — use --lan only when you need LAN access
  3. 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
  4. Close TermBeam when done — it's not a daemon, don't leave it running
  5. Use on trusted networks — TermBeam is not designed for hostile environments

Reporting Vulnerabilities

If you find a security vulnerability, please email the maintainers directly rather than opening a public issue. See the repository for contact details.