SSHubble

Operator-approved SSH reverse tunnels for PowerShell diagnostics on customer Windows machines.

Purpose

SSHubble establishes temporary, operator-approved SSH reverse tunnels from customer Windows machines back to the PCT relay, enabling AI agents (miAgents/Claude) to run PowerShell commands on customer machines to diagnose and fix issues.

Architecture

• NetBird VPN (Primary): The agent script natively provisions NetBird VPN (connecting to our self-hosted NetBird at https://netbird.pctbin.com) to establish a secure peer-to-peer connection for PowerShell remoting.
• WebSocket Tunnel (Fallback): If NetBird VPN is unavailable, it gracefully falls back to a custom wss:// -> localhost:22 bridge over port 443.
• Relay Server: Node.js/TypeScript Express app that manages sessions, ephemeral SSH keys, and an MCP server.
• Agent Script: PowerShell script (sshubble-agent.ps1) that runs as Administrator on the customer machine, installs/starts OpenSSH if needed, and opens the reverse tunnel.
• MCP Server: Provides tools to AI agents to execute PowerShell commands through the established tunnels.

Entrypoint

• Server: npm start (Relay on port 3005)
• Agent: irm https://sshubble.pctbin.com/agent.ps1 | iex (Production)

Dependencies

• Node.js: express, better-sqlite3, ssh2, @modelcontextprotocol/sdk
• Windows: OpenSSH Client and Server capabilities.

Risk Level: Medium

• Remote Execution: Relay executes commands as Administrator.
• Mitigations:
  • Manual operator approval required for each session.
  • Ephemeral, session-scoped SSH keys.
  • SSH permitopen and ForceCommand restrictions.
  • Full audit transcript of all commands and outputs.

Environment Variables

See .env.example for required fields.

• PORT: Relay HTTP port (default 3005).
• SSHUBBLE_API_TOKEN: Bearer token for API authentication.
• SQLITE_PATH: Path to the transcript database.
• AUTHORIZED_KEYS_PATH: Path to the relay's authorized_keys file for the tunnel user.
• AGENT_SSH_KEY_PATH: Path to the relay's identity key for SSHing into customers.

Infrastructure Setup (VMID 114)

1. Create sshubble-tunnel Linux user with no login shell.
2. Configure sshd_config to allow reverse tunnels for this user.
3. Ensure the Node.js process has write access to /home/sshubble-tunnel/.ssh/authorized_keys.
4. Deploy the service using systemd.

Development

npm install
npm run dev   # Start relay with hot reload
npm test      # Run unit tests