- trim container image size - sanitize socktop inputs

2025-11-28 16:20:18 -08:00
parent e224989702
commit 2012504616
7 changed files with 385 additions and 99 deletions
@@ -137,6 +137,74 @@ This project includes a complete CI/CD pipeline using Gitea Actions:
 - **Containerization**: Docker, Kubernetes/k3s
 - **CI/CD**: Gitea Actions

+## Security and Limitations
+
+### Security Model
+
+This application is designed to provide **safe, public terminal access** for demonstration purposes. The security model consists of multiple layers:
+
+#### 1. Restricted Shell
+
+When deployed in production (e.g., https://www.socktop.io), the application uses a restricted shell (`docker/restricted-shell.sh`) that:
+
+- **Allows only 2 commands**: `socktop` and `help`
+- **Blocks all other commands**: Rejects any attempt to run `ls`, `cat`, `bash`, etc.
+- **Validates arguments**: All arguments passed to `socktop` are sanitized to prevent command injection
+- **Prevents shell escapes**: Blocks metacharacters like `;`, `&&`, `|`, `$()`, backticks, etc.
+- **Blocks path traversal**: Prevents attempts like `../../../etc/passwd`
+
+**Example validation:**
+```bash
+# Allowed
+socktop -P local
+socktop -P rpi-master
+socktop ws://192.168.1.100:3000
+
+# Blocked with error message
+socktop $(whoami)          # Command substitution blocked
+socktop ; /bin/bash        # Shell metacharacter blocked
+socktop -P ../etc/passwd   # Path traversal blocked
+```
+
+#### 2. Argument Sanitization
+
+The restricted shell validates all input using regex patterns:
+- Profile names: Only `[a-zA-Z0-9_-]+` characters allowed
+- WebSocket URLs: Only `ws://` or `wss://` with safe characters
+- No environment variable expansion
+- No special characters or shell operators
+
+**Security testing**: Run `./scripts/test-shell-security.sh` to verify all 35 security checks pass.
+
+#### 3. Container Isolation
+
+- Runs inside Docker container (cannot access host system)
+- Non-root user (`socktop` user)
+- Limited resources (CPU/memory limits configurable)
+- No privileged operations
+- Read-only configuration mounts
+
+#### 4. WebSocket Security
+
+The WebSocket endpoint (`/websocket`) is secure by design:
+- Command spawned is **hardcoded at server startup** (via `--command` flag)
+- No way to change which shell is spawned via WebSocket connection
+- No HTTP headers or request parameters influence the spawned command
+- Direct WebSocket connections get the same restricted shell as browser connections
+
+**The Terminado protocol only supports:**
+- `stdin` - Send input to terminal (goes through restricted shell)
+- `stdout` - Receive output from terminal
+- `set_size` - Resize terminal (validated to u16 row/col numbers only)
+
+There is no protocol message type that can bypass the shell or execute arbitrary commands.
+
+### Reporting Security Issues
+
+If you discover a security vulnerability that bypasses the restricted shell or container isolation, please report it via:
+- GetTea Issues (for non-critical issues)
+- Direct contact to maintainer (for critical vulnerabilities)
+
 ## Credits

 This project was originally forked from [webterm](https://github.com/fubarnetes/webterm) by Fabian Freyer. I chose this as a base because other projects were way too complex. His project was simple and easy to understand, but it was not well maintained. I have updated it to modern packages and heavily customized it to display a working demo for socktop.