diff --git a/CHANGELOG.md b/CHANGELOG.md index 97a87f3..b31267e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### 🚀 Major Release: Ultra-Optimized Build + Security Hardening + Configuration Enhancement -**This is a major architectural release** migrating from a dual-build structure (45MB) to a single ultra-optimized 17.1MB build with busybox-only dependencies, comprehensive security hardening, simplified multi-mode operation, and enhanced configuration documentation. +**This is a major architectural release** migrating from a dual-build structure (45MB) to a single ultra-optimized 17.1 MB build with busybox-only dependencies, comprehensive security hardening, simplified multi-mode operation, and enhanced configuration documentation. ### ✨ Core Features @@ -28,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * 🌉 **Bridge relay with obfs4** - Integrated lyrebird for pluggable transport (drop-in replacement for `thetorproject/obfs4-bridge`) * 🔧 **ENV-based configuration** - Full relay setup via environment variables (TOR_*, official bridge naming compatible) * 📊 **Smart diagnostics** - 4 busybox-only tools: `status`, `health`, `fingerprint`, `bridge-line` -* 📉 **Image size** - Reduced from ~45MB to ~17.1MB (busybox-only, no bash/python/jq) +* 📉 **Image size** - Reduced from ~45MB to ~17.1 MB (busybox-only, no bash/python/jq) * 🩺 **Smart healthcheck** - New `healthcheck.sh` works with both mounted configs and ENV variables * 🔄 **Weekly rebuilds** - Automated Sunday 18:30 UTC rebuilds with latest Alpine/Tor patches (same version tag, fresh packages) @@ -121,7 +121,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * **CRITICAL**: Fixed missing Tor bootstrap logs in container output (added `Log notice stdout`) * Fixed healthcheck failures on ENV-based deployments * Fixed version references across all scripts and documentation -* Corrected image size documentation (~35MB → ~17.1MB) +* Corrected image size documentation (~35MB → ~17.1 MB) ### 🔄 Migration Path diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index e974bc8..0d96bf0 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -64,11 +64,13 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at r3bo0tbx1@brokenbotnet.com. + All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. -Encrypted communication is available upon request for sensitive or high impact reports. + +Encrypted communication [0xB3BD6196E1CFBFB4 🔑](https://keys.openpgp.org/vks/v1/by-fingerprint/33727F5377D296C320AF704AB3BD6196E1CFBFB4) is available upon request for sensitive or high impact reports. ## Enforcement Guidelines diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcc0eba..b03314e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -283,7 +283,7 @@ fi services: relay: # Service configuration - image: "r3bo0tbx1/onion-relay:latest" + image: "r3bo0tbx1/onion-relay:latest" # or ghcr.io/r3bo0tbx1/onion-relay:latest ``` --- diff --git a/LICENSE.txt b/LICENSE.txt index 19159bc..54e5244 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -MIT License +MIT License 📜 SPDX-License-Identifier: MIT Copyright (c) 2025 r3bo0tbx1 diff --git a/README.md b/README.md index 508a85d..0afa6fd 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ ### Why Choose This Project? -- 🛡️ **Security-First** - Hardened Alpine Linux, non-root operation, ultra-minimal 17.1MB image +- 🛡️ **Security-First** - Hardened Alpine Linux, non-root operation, ultra-minimal 17.1 MB image - 🎯 **Simple** - One command to deploy, minimal configuration needed - 📊 **Observable** - 4 busybox-only diagnostic tools with JSON health API - 🌉 **Multi-Mode** - Supports guard, exit, and bridge (obfs4) relays diff --git a/SECURITY-AUDIT-REPORT.md b/SECURITY-AUDIT-REPORT.md deleted file mode 100644 index c692a05..0000000 --- a/SECURITY-AUDIT-REPORT.md +++ /dev/null @@ -1,362 +0,0 @@ -# Security Audit Report - Tor Guard Relay Project -**Date**: 2025-11-13 -**Auditor**: Claude Code Security Audit -**Scope**: Complete codebase security hardening review - ---- - -## Executive Summary - -A comprehensive line-by-line security audit was performed on the Tor Guard Relay project. This audit identified **32 security issues** ranging from CRITICAL to LOW severity. - -**Statistics:** -- **CRITICAL**: 6 issues (must fix immediately) -- **HIGH**: 8 issues (should fix before release) -- **MEDIUM**: 10 issues (should address) -- **LOW**: 8 issues (nice to have) - ---- - -## CRITICAL Issues (Must Fix Immediately) - -### 1. Command Injection via OBFS4V_* Environment Variables -**File**: `docker-entrypoint.sh:238-242` -**Severity**: CRITICAL -**CWE**: CWE-78 (OS Command Injection), CWE-94 (Code Injection) - -**Issue**: -```sh -env | grep '^OBFS4V_' | sort | while IFS='=' read -r key value; do - torrc_key="${key#OBFS4V_}" - echo "$torrc_key $value" >> "$TOR_CONFIG" -done -``` - -- No input validation on `$value` -- No quoting around variables in echo -- Allows injection of arbitrary torrc directives -- `env` output can be manipulated - -**Impact**: Attacker can inject malicious torrc configuration, potentially: -- Redirect Tor traffic -- Disable security features -- Execute arbitrary commands via ControlPort directives - -**Fix**: Implement strict input validation and proper escaping. - ---- - -### 2. Health Check Failure on ENV-Based Deployments -**File**: `Dockerfile:108-109` -**Severity**: CRITICAL -**CWE**: CWE-703 (Improper Check or Handling of Exceptional Conditions) - -**Issue**: -```dockerfile -HEALTHCHECK --interval=10m --timeout=15s --start-period=30s --retries=3 \ - CMD tor --verify-config -f /etc/tor/torrc || exit 1 -``` - -Hardcoded path `/etc/tor/torrc` doesn't exist when using environment variables for configuration. - -**Impact**: -- Health checks always fail for ENV-based deployments -- Orchestrators (Kubernetes, Docker Swarm) will restart healthy containers -- Service disruption - -**Fix**: Make health check conditional or use a wrapper script. - ---- - -### 3. Privilege Escalation Attempt with Silent Failure -**File**: `docker-entrypoint.sh:107-109` -**Severity**: CRITICAL -**CWE**: CWE-250 (Execution with Unnecessary Privileges) - -**Issue**: -```sh -if command -v chown >/dev/null 2>&1; then - chown -R tor:tor "$TOR_DATA_DIR" "$TOR_LOG_DIR" /run/tor 2>/dev/null || true -fi -``` - -Container runs as user `tor` (UID 100), but `chown` requires root. The `|| true` silently masks the failure. - -**Impact**: -- Permissions won't be fixed -- Runtime failures due to permission issues -- Silent failure hides the problem from debugging - -**Fix**: Remove the chown attempt (permissions should be set at build time or mount time). - ---- - -### 4. Inadequate Input Validation -**File**: `docker-entrypoint.sh:120-140` -**Severity**: CRITICAL -**CWE**: CWE-20 (Improper Input Validation) - -**Issue**: Minimal validation of critical configuration parameters: -- `TOR_NICKNAME`: Only checks length and alphanumeric, doesn't validate against reserved names -- `TOR_CONTACT_INFO`: Minimal length check, no format validation -- `TOR_ORPORT`, `TOR_DIRPORT`, `TOR_OBFS4_PORT`: No validation at all -- `TOR_RELAY_MODE`: Not validated in validation function -- No sanitization of special characters - -**Impact**: -- Malformed torrc generation -- Potential injection attacks -- Invalid Tor configuration causing crashes - -**Fix**: Implement comprehensive input validation with whitelisting. - ---- - -### 5. Workflow Permission Over-Granting -**File**: `.github/workflows/release.yml:21-23` -**Severity**: CRITICAL -**CWE**: CWE-269 (Improper Privilege Management) - -**Issue**: -```yaml -permissions: - contents: write - packages: write -``` - -Permissions granted globally to all jobs, violating principle of least privilege. - -**Impact**: -- If earlier jobs are compromised, they can modify repository or packages -- Increased attack surface -- Compliance violations - -**Fix**: Scope permissions per-job. - ---- - -### 6. Temporary File Race Condition -**File**: `docker-entrypoint.sh:266-267` -**Severity**: CRITICAL -**CWE**: CWE-377 (Insecure Temporary File) - -**Issue**: -```sh -VERIFY_TMP=$(mktemp) -trap 'rm -f "$VERIFY_TMP"' EXIT -``` - -Trap set AFTER mktemp, creating a window where signals can leave temp files. - -**Impact**: -- Temp file leak -- Potential information disclosure if temp file contains sensitive data - -**Fix**: Set trap immediately, use proper temp directory with restricted permissions. - ---- - -## HIGH Severity Issues (Should Fix Before Release) - -### 7. JSON Injection in Health Tool -**File**: `tools/health:58-69` -**Severity**: HIGH -**CWE**: CWE-116 (Improper Encoding or Escaping of Output) - -**Issue**: JSON output doesn't escape special characters in fingerprint or nickname. - -**Fix**: Implement proper JSON escaping or use jq for generation. - ---- - -### 8. Bash-Specific Features in Portable Scripts -**Files**: `scripts/migration/*.sh`, `scripts/utilities/relay-status.sh` -**Severity**: HIGH -**CWE**: CWE-1104 (Use of Unmaintained Third Party Components) - -**Issue**: Scripts use `#!/bin/bash` with bash-specific features (`[[`, `$EUID`, arrays) but project claims POSIX sh compatibility. - -**Impact**: Won't work on systems without bash (Alpine, busybox, etc). - -**Fix**: Rewrite using POSIX sh or document bash requirement. - ---- - -### 9. Multiple Tor Process Handling -**File**: `tools/health:22` -**Severity**: HIGH -**CWE**: CWE-366 (Race Condition within a Thread) - -**Issue**: `TOR_PID=$(pgrep -x tor)` doesn't handle multiple tor processes. - -**Fix**: Add validation to ensure only one tor process. - ---- - -### 10. Sudo Hardcoding in Utility Scripts -**File**: `scripts/utilities/relay-status.sh` (multiple locations) -**Severity**: HIGH -**CWE**: CWE-250 (Execution with Unnecessary Privileges) - -**Issue**: Script hard codes `sudo` without checking if user has sudo privileges or if running as root. - -**Fix**: Detect privilege level and use sudo only if needed. - ---- - -### 11. Fingerprint Length Assumption -**File**: `tools/status:63-64` -**Severity**: HIGH -**CWE**: CWE-1284 (Improper Validation of Specified Quantity in Input) - -**Issue**: -```sh -FP_START=$(printf "%s" "$FINGERPRINT" | cut -c1-8) -FP_END=$(printf "%s" "$FINGERPRINT" | cut -c33-40) -``` - -Assumes fingerprint is exactly 40 characters without validation. - -**Fix**: Validate fingerprint length before substring extraction. - ---- - -### 12. Bridge Line Information Disclosure -**File**: `tools/bridge-line:78-85` -**Severity**: HIGH -**CWE**: CWE-200 (Exposure of Sensitive Information) - -**Issue**: Falls back to reading bridge line from logs which may be world-readable. - -**Fix**: Remove fallback or add permission check. - ---- - -### 13. Tor Startup Validation Missing -**File**: `docker-entrypoint.sh:320-322` -**Severity**: HIGH -**CWE**: CWE-754 (Improper Check for Unusual or Exceptional Conditions) - -**Issue**: -```sh -tor -f "$TOR_CONFIG" & -TOR_PID=$! -``` - -No check if tor actually started successfully. - -**Fix**: Add startup validation with timeout. - ---- - -### 14. Workflow Syntax Validation Wrong Tool -**File**: `.github/workflows/validate.yml:85-86` -**Severity**: HIGH -**CWE**: CWE-1177 (Use of Prohibited Code) - -**Issue**: Uses `bash -n` to validate POSIX sh scripts. - -**Fix**: Use `sh -n` for POSIX compliance checking. - ---- - -## MEDIUM Severity Issues (Should Address) - -### 15. Integer Overflow in Loop Counter -**File**: `docker-entrypoint.sh:331` -**Severity**: MEDIUM -**Issue**: `log_wait` arithmetic could overflow on some systems. - -### 16. Impro per Error Handling in Workflows -**File**: `.github/workflows/validate.yml:68` -**Severity**: MEDIUM -**Issue**: `|| true` prevents job failure on docker build errors. - -### 17. No Secret Validation -**Files**: Multiple workflow files -**Severity**: MEDIUM -**Issue**: No validation of secret values before use. - -### 18. Progress Extraction Fragility -**File**: `tools/status:42-43` -**Severity**: MEDIUM -**Issue**: sed extraction could fail with non-standard log formats. - -### 19. Missing Disk Space Check -**File**: `.github/workflows/validate.yml:317` -**Severity**: MEDIUM -**Issue**: Image saved to `/tmp` without checking available disk space. - -### 20. Hardcoded Package Installation -**File**: `.github/workflows/release.yml:140` -**Severity**: MEDIUM -**Issue**: No verification of dos2unix package integrity. - -### 21. Bash Arrays in Tag Generation -**File**: `.github/workflows/release.yml:194-219` -**Severity**: MEDIUM -**Issue**: Uses bash arrays which breaks on minimal systems. - -### 22. AWK Changelog Extraction Edge Cases -**File**: `.github/workflows/release.yml:264-268` -**Severity**: MEDIUM -**Issue**: Doesn't handle missing version sections properly. - -### 23. No CRLF Protection -**Files**: All tool scripts -**Severity**: MEDIUM -**Issue**: If scripts get CRLF line endings, shebang `#!/bin/sh\r` will fail. - -### 24. Bridge Mode Auto-Detection Fragility -**File**: `docker-entrypoint.sh:29` -**Severity**: MEDIUM -**Issue**: Auto-detection could be more robust. - ---- - -## LOW Severity Issues (Nice to Have) - -### 25-32. Code Quality & Maintainability -- Inconsistent error handling patterns -- Hardcoded paths without configurability -- No rate limiting for external calls -- Missing documentation for edge cases -- Resource limits not enabled by default in compose files -- Example .env lacks prominent "DO NOT COMMIT" warning -- `restart: unless-stopped` may not be appropriate for all deployments -- Hardcoded paths in migration scripts without validation - ---- - -## Recommendations - -1. **Immediate Actions**: - - Fix all CRITICAL issues before any release - - Implement input validation framework - - Remove privilege escalation attempts - - Fix health check for all deployment modes - -2. **Short-term Actions**: - - Address all HIGH severity issues - - Implement proper JSON/shell escaping - - Add comprehensive testing for edge cases - - Document bash requirements or migrate to POSIX sh - -3. **Long-term Actions**: - - Implement automated security scanning in CI/CD - - Add fuzz testing for input validation - - Create security policy and disclosure process - - Regular third-party security audits - ---- - -## Conclusion - -This audit identified significant security vulnerabilities that must be addressed before production use. The most critical issues involve command injection, improper privilege handling, and inadequate input validation. All CRITICAL and HIGH severity issues should be resolved immediately. - -**Overall Risk Rating**: HIGH (before fixes) -**Recommendation**: Do not deploy to production until CRITICAL and HIGH issues are resolved. - ---- - -*End of Report* diff --git a/SECURITY.md b/SECURITY.md index 2e6e322..4c92de9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -121,7 +121,7 @@ docker run -d \ -v $(pwd)/relay.conf:/etc/tor/torrc:ro \ -v tor-guard-data:/var/lib/tor \ -v tor-guard-logs:/var/log/tor \ - r3bo0tbx1/onion-relay:latest + r3bo0tbx1/onion-relay:latest # or ghcr.io/r3bo0tbx1/onion-relay:latest ``` ```yaml diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh index 9898e21..f4d59ed 100644 --- a/docker-entrypoint.sh +++ b/docker-entrypoint.sh @@ -1,6 +1,6 @@ #!/bin/sh # docker-entrypoint.sh - Tor Guard Relay initialization and process management -# 🆕 v1.1.1 - Ultra-optimized 17.1MB build with multi-mode support +# 🆕 v1.1.1 - Ultra-optimized 17.1 MB build with multi-mode support set -e diff --git a/docs/LOCAL-TESTING.md b/docs/LOCAL-TESTING.md index 5b80f65..020f5ec 100644 --- a/docs/LOCAL-TESTING.md +++ b/docs/LOCAL-TESTING.md @@ -279,7 +279,7 @@ After building locally: - [ ] Diagnostic tools produce correct output - [ ] Input validation catches invalid values - [ ] OBFS4V_* whitelist blocks dangerous options -- [ ] Image size is ~17.1MB (`docker images localhost:5000/onion-relay:test`) +- [ ] Image size is ~17.1 MB (`docker images localhost:5000/onion-relay:test`) --- diff --git a/src/exit.png b/src/exit.png index dc3eccf..c450970 100644 Binary files a/src/exit.png and b/src/exit.png differ diff --git a/src/obfs4.png b/src/obfs4.png index 3dd5be5..e1db4b5 100644 Binary files a/src/obfs4.png and b/src/obfs4.png differ diff --git a/src/onion.png b/src/onion.png index fd1a126..8d9c61e 100644 Binary files a/src/onion.png and b/src/onion.png differ diff --git a/templates/cosmos-compose-bridge-official.json b/templates/cosmos-compose-bridge-official.json index 937d9c9..bbaf19d 100644 --- a/templates/cosmos-compose-bridge-official.json +++ b/templates/cosmos-compose-bridge-official.json @@ -1,5 +1,5 @@ { - "minVersion": "0.8.0", + "minVersion": "0.16.0", "services": { "obfs4-bridge": { "image": "r3bo0tbx1/onion-relay:latest", diff --git a/templates/cosmos-compose-bridge.json b/templates/cosmos-compose-bridge.json index 22f2603..17715be 100644 --- a/templates/cosmos-compose-bridge.json +++ b/templates/cosmos-compose-bridge.json @@ -1,5 +1,5 @@ { - "minVersion": "0.8.0", + "minVersion": "0.16.0", "services": { "tor-bridge": { "image": "r3bo0tbx1/onion-relay:latest", diff --git a/templates/cosmos-compose-exit.json b/templates/cosmos-compose-exit.json index a213eb5..6a60d5f 100644 --- a/templates/cosmos-compose-exit.json +++ b/templates/cosmos-compose-exit.json @@ -1,5 +1,5 @@ { - "minVersion": "0.8.0", + "minVersion": "0.16.0", "services": { "tor-exit-relay": { "image": "r3bo0tbx1/onion-relay:latest", diff --git a/templates/cosmos-compose-guard.json b/templates/cosmos-compose-guard.json index c94a1d8..959ff9b 100644 --- a/templates/cosmos-compose-guard.json +++ b/templates/cosmos-compose-guard.json @@ -1,5 +1,5 @@ { - "minVersion": "0.8.0", + "minVersion": "0.16.0", "services": { "tor-guard-relay": { "image": "r3bo0tbx1/onion-relay:latest", diff --git a/templates/cosmos-compose-multi-relay.json b/templates/cosmos-compose-multi-relay.json index 91d2b9f..8b7ce62 100644 --- a/templates/cosmos-compose-multi-relay.json +++ b/templates/cosmos-compose-multi-relay.json @@ -1,5 +1,5 @@ { - "minVersion": "0.8.0", + "minVersion": "0.16.0", "services": { "TorRelay1": { "image": "r3bo0tbx1/onion-relay:latest", @@ -159,7 +159,7 @@ "tor-relay-3-logs": { "driver": "local" } }, "metadata": { - "description": "🧅 Tor Guard Multi-Relay Stack - 3 relays with ultra-optimized 17.1MB containers", + "description": "🧅 Tor Guard Multi-Relay Stack - 3 relays with ultra-optimized 17.1 MB containers", "version": "1.1.1", "author": "r3bo0tbx1", "tags": ["tor", "relay", "privacy", "multi-relay"] diff --git a/templates/docker-compose-bridge-official.yml b/templates/docker-compose-bridge-official.yml index 5d8ba50..4f1b159 100644 --- a/templates/docker-compose-bridge-official.yml +++ b/templates/docker-compose-bridge-official.yml @@ -10,7 +10,7 @@ version: "3.8" # - Weekly security rebuilds (Sundays 18:30 UTC) # - 4 diagnostic tools (status, health, fingerprint, bridge-line) # - JSON health API for monitoring integration -# - Ultra-minimal 17.1MB Alpine Linux base +# - Ultra-minimal 17.1 MB Alpine Linux base # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ services: @@ -164,7 +164,7 @@ volumes: # 1. Stop the old container: # docker-compose down # -# 2. Update docker-compose.yml with this file (or change image to r3bo0tbx1/onion-relay:latest) +# 2. Update docker-compose.yml with this file (or change image to r3bo0tbx1/onion-relay:latest or ghcr.io/r3bo0tbx1/onion-relay:latest) # # 3. Start with same volumes (preserves bridge keys): # docker-compose -f docker-compose-bridge-official.yml up -d diff --git a/templates/docker-compose-bridge.yml b/templates/docker-compose-bridge.yml index f448ce1..6e06e13 100644 --- a/templates/docker-compose-bridge.yml +++ b/templates/docker-compose-bridge.yml @@ -7,7 +7,7 @@ version: '3.8' services: tor-bridge: - image: r3bo0tbx1/onion-relay:latest + image: r3bo0tbx1/onion-relay:latest # or use ghcr.io/r3bo0tbx1/onion-relay:latest container_name: tor-bridge restart: unless-stopped network_mode: host diff --git a/templates/docker-compose-exit.yml b/templates/docker-compose-exit.yml index 2431fcc..f51245d 100644 --- a/templates/docker-compose-exit.yml +++ b/templates/docker-compose-exit.yml @@ -7,7 +7,7 @@ version: '3.8' services: tor-exit-relay: - image: r3bo0tbx1/onion-relay:latest + image: r3bo0tbx1/onion-relay:latest # or use ghcr.io/r3bo0tbx1/onion-relay:latest container_name: tor-exit-relay restart: unless-stopped network_mode: host diff --git a/templates/docker-compose-guard-env.yml b/templates/docker-compose-guard-env.yml index 93a8f4f..834ec57 100644 --- a/templates/docker-compose-guard-env.yml +++ b/templates/docker-compose-guard-env.yml @@ -7,7 +7,7 @@ version: '3.8' services: tor-guard-relay: - image: r3bo0tbx1/onion-relay:latest + image: r3bo0tbx1/onion-relay:latest # or use ghcr.io/r3bo0tbx1/onion-relay:latest container_name: tor-guard-relay restart: unless-stopped network_mode: host diff --git a/templates/docker-compose-multi-relay.yml b/templates/docker-compose-multi-relay.yml index d2e5c5f..9b87b71 100644 --- a/templates/docker-compose-multi-relay.yml +++ b/templates/docker-compose-multi-relay.yml @@ -5,7 +5,7 @@ version: '3.8' services: tor-relay-1: - image: r3bo0tbx1/onion-relay:latest + image: r3bo0tbx1/onion-relay:latest # or use ghcr.io/r3bo0tbx1/onion-relay:latest container_name: guard-relay-1 restart: unless-stopped network_mode: host