SPDX-License-Identifier: MIT

This policy covers the Tor Guard Relay Docker image, scripts, and workflows in this repository. Issues related to the Tor network itself should be reported directly to The Tor Project.

We actively support the following versions with security updates:

Support policy: Only the latest released version receives updates. When a new version is released, all previous versions automatically become unsupported and no longer receive maintenance, security fixes, or scheduled rebuild updates. Historical tags remain available in registries for reproducibility.

• Affects vulnerable OpenSSL package ranges in Alpine-based images.
• Fix target for this project is openssl >= 3.5.6-r0 via base image/package refresh and rebuild.
• Mitigation is image-level: pull updated image tags after release.

• This is a Linux kernel vulnerability and is in CISA KEV.
• Mitigation is primarily host-level: update/pin host kernels using your distro or cloud vendor guidance.
• Pulling a new container image does not patch an unpatched host kernel.

This project follows an ultra-minimal security architecture:

• ✅ NO monitoring HTTP endpoints - Removed for maximum security
• ✅ NO exposed metrics ports - All monitoring via docker exec only
• ✅ Only Tor protocol ports exposed - ORPort (configurable), obfs4 (bridge mode), DirPort (disabled)
• ✅ ~16.8 MB image - Minimal attack surface

Ports exposed depend on relay mode and configuration:

PUBLIC PORTS:
  TOR_ORPORT   (default: 9001)  →  Tor ORPort (relay traffic)
  TOR_DIRPORT                   →  Directory service (optional, disabled by default)

PUBLIC PORTS:
  TOR_ORPORT   (default: 9001)  →  Tor ORPort (relay traffic)
  TOR_DIRPORT                   →  Directory service (optional, disabled by default)

PUBLIC PORTS:
  TOR_ORPORT      (default: 9001)  →  Tor ORPort (relay traffic)
  TOR_OBFS4_PORT  (default: 9002)  →  obfs4 pluggable transport

All port numbers are fully configurable via environment variables.

ZERO exposed monitoring services:

• ❌ No metrics HTTP endpoints
• ❌ No health check HTTP APIs
• ❌ No dashboard web interfaces
• ✅ All diagnostics via docker exec commands only

Available diagnostic tools (container exec only):

docker exec tor-relay status        # Health report with emojis
docker exec tor-relay health        # JSON health output
docker exec tor-relay fingerprint   # Display fingerprint
docker exec tor-relay bridge-line   # Get bridge line (bridge mode)
docker exec tor-relay gen-auth      # Generate Control Port hash
docker exec tor-relay gen-family    # Generate/view Happy Family key (Tor 0.4.9.2-alpha or later)

This project uses host networking mode (--network host) for best Tor performance:

Why host networking?

• ✅ IPv6 Support - Direct access to host's IPv6 stack
• ✅ No NAT - Tor binds directly to ports without translation
• ✅ Better Performance - Eliminates network overhead
• ✅ Tor Recommended - Follows Tor Project best practices

Security with host networking:

• ✅ Runs as non-root user (tor UID 100)
• ✅ Drops all capabilities, adds only required ones
• ✅ Uses no-new-privileges:true
• ✅ Minimal Alpine Linux base (~16.8 MB)
• ✅ No exposed monitoring ports
• ✅ Automatic permission healing

Why this matters:

• ✅ Minimizes attack surface - Only Tor protocol ports exposed
• ✅ No monitoring vulnerabilities - Cannot attack what doesn't exist
• ✅ Follows Tor best practices - Standard relay configuration
• ✅ Defense in depth - Ultra-minimal design philosophy

Security implications:

• Exposed ORPort: Required for Tor relay operation (configurable)
• Disabled DirPort: Not necessary unless you operate a Directory Authority
• Exposed obfs4 port: Only in bridge mode (configurable)
• NO other services are accessible (internal or external)

# Docker CLI with host networking (recommended)
docker run -d \
  --name tor-relay \
  --network host \
  --security-opt no-new-privileges:true \
  --restart unless-stopped \
  -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 # or ghcr.io/r3bo0tbx1/onion-relay:latest

# Docker Compose with host networking
services:
  tor-relay:
    image: r3bo0tbx1/onion-relay:latest
    container_name: tor-relay
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./relay.conf:/etc/tor/torrc:ro
      - tor-guard-data:/var/lib/tor
      - tor-guard-logs:/var/log/tor

External monitoring is used for maximum security and minimal image size:

# Check status
docker exec tor-relay status

# Get JSON health (raw)
docker exec tor-relay health

# Parse with jq (requires jq on host)
docker exec tor-relay health | jq .

# View fingerprint
docker exec tor-relay fingerprint

Create your own HTTP wrapper if needed:

#!/usr/bin/env python3
from flask import Flask, jsonify
import subprocess
import json

app = Flask(__name__)

@app.route('/health')
def health():
    result = subprocess.run(
        ['docker', 'exec', 'tor-relay', 'health'],
        capture_output=True,
        text=True
    )
    return jsonify(json.loads(result.stdout))

if __name__ == '__main__':
    app.run(host='127.0.0.1', port=9100)  # Bind to localhost only!

Use dedicated Tor exporters for Prometheus integration:

# Use tor_exporter for detailed metrics
docker run -d --name tor-exporter \
  --network host \
  ghcr.io/atx/prometheus-tor_exporter:latest \
  --tor.control-address=127.0.0.1:9051

See Monitoring Guide for complete integration examples.

Recommended firewall rules for guard/middle relay:

# UFW (Ubuntu/Debian)
sudo ufw default deny incoming
sudo ufw allow 9001/tcp  # ORPort (or your custom port)
sudo ufw enable

# iptables
sudo iptables -A INPUT -p tcp --dport 9001 -j ACCEPT
sudo iptables -A INPUT -j DROP

# firewalld (RHEL/CentOS)
sudo firewall-cmd --permanent --add-port=9001/tcp
sudo firewall-cmd --reload

For bridge mode:

# UFW (Ubuntu/Debian)
sudo ufw allow 9001/tcp  # ORPort
sudo ufw allow 9002/tcp  # obfs4 port

For custom ports:

# Replace with your configured ports
sudo ufw allow <TOR_ORPORT>/tcp  # guard/exit only
sudo ufw allow <TOR_OBFS4_PORT>/tcp  # bridge only

• Security patches are released as soon as possible after discovery
• Critical vulnerabilities are prioritized
• Weekly automated builds include the latest Alpine and Tor security updates
• Subscribe to GitHub Releases for notifications

To reduce patch-lag risk, GitHub Actions automatically:

1. Pulls the latest Alpine base image
2. Installs the latest Tor package
3. Applies security patches
4. Rebuilds multi-architecture images
5. Publishes to Docker Hub and GHCR

Rebuild schedule: Sundays at 18:30 UTC

These rebuilds include Alpine CVE patches and Tor security fixes without changing functionality.

Do NOT report security vulnerabilities through public GitHub issues.

Email: r3bo0tbx1@brokenbotnet.com Subject: [SECURITY] Tor Guard Relay – <short summary>

Please use my PGP key 0xB3BD6196E1CFBFB4 🔑 to encrypt if your report contains sensitive technical details.

1. Description of the vulnerability
2. Steps to reproduce the issue
3. Impact assessment (who is affected, what's at risk)
4. Suggested fix (if you have one)
5. Your contact information for follow-up

• Acknowledgment: within 48 hours
• Initial assessment: within 1 week
• Status updates: every 2 weeks until resolved

Resolution timelines:

We follow responsible disclosure practices:

1. Report received → We acknowledge and investigate
2. Fix developed → We create and test a patch
3. Coordinated release → We agree on disclosure timing
4. Public disclosure → We release the fix and advisory
5. Credit given → We acknowledge the reporter (unless anonymity is requested)

# Secure your relay.conf file
chmod 600 /path/to/relay.conf
chown root:root /path/to/relay.conf

# Use read-only mounts
-v /path/to/relay.conf:/etc/tor/torrc:ro

# CIISS v3 format (recommended) - generate at https://torcontactinfogenerator.netlify.app/
ContactInfo email:tor-relay[]example.com url:https://example.com proof:uri-familyid-ed25519 pgp:EF6E286DDA85EA2A4BA7DE684E2C6E8793298290 ciissversion:3

# With abuse contact (recommended for exits)
ContactInfo email:tor-relay[]example.com abuse:abuse[]example.com url:https://example.com proof:uri-familyid-ed25519 ciissversion:3

📝 CIISS v3: The ContactInfo Information Sharing Specification provides a machine-readable, verifiable format. The proof:uri-familyid-ed25519 method lets tools verify your relay ownership by checking https://your-domain/.well-known/tor-relay/ed25519-family-id.txt for your Happy Family ID (Tor 0.4.9.2-alpha or later).

# Regular security updates
apt update && apt upgrade -y   # Ubuntu/Debian
yum update -y                  # RHEL/CentOS

# Verify firewall rules
sudo ufw status numbered
sudo iptables -L -n -v

# Pull latest security-patched image
docker pull r3bo0tbx1/onion-relay:latest

# Log monitoring
docker logs tor-relay 2>&1 | grep -iE "(error|warn|critical)"

# Health checks via diagnostic tools
docker exec tor-relay status

# JSON health check for automation (raw)
docker exec tor-relay health

# Parse with jq (requires jq on host)
docker exec tor-relay health | jq .

# Resource monitoring
docker stats tor-relay --no-stream

• Never commit secrets or API keys
• Use .gitignore for sensitive files
• Review dependencies for vulnerabilities
• Follow the principle of least privilege
• Validate all user inputs
• Use POSIX sh only (no bash dependencies)

# Always specify explicit base version
FROM alpine:3.24.1  # Pinned version for reproducibility

# Run as non-root user
USER tor

# Use Docker security options
--security-opt no-new-privileges:true
--cap-drop ALL
--cap-add NET_BIND_SERVICE
--cap-add CHOWN
--cap-add SETUID
--cap-add SETGID
--cap-add DAC_OVERRIDE

# NEVER do this:
git add relay.conf  # Contains sensitive info!

# Instead:
echo "*.conf" >> .gitignore
echo "relay.conf" >> .gitignore

What‼️: Container uses --network host

Why ⁉️: Enables Tor dual-stack (IPv4 + IPv6) support and eliminates NAT overhead

Security Impact:

• ✅ Container runs as non-root user (tor UID 100)
• ✅ Drops all capabilities, adds only required ones
• ✅ Uses no-new-privileges:true
• ✅ No exposed monitoring services
• ⚠️ Shares host network namespace (required for IPv6)
• ⚠️ Relies on firewall for port isolation

Mitigations:

• Drops all capabilities by default
• Adds only NET_BIND_SERVICE, CHOWN, SETUID, SETGID, DAC_OVERRIDE
• Uses no-new-privileges:true
• Ultra-minimal Alpine base (~16.8 MB)
• NO monitoring HTTP endpoints to attack
• Automatic permission healing
• Configuration validation before start

What: Persistent volumes store keys and state Security Impact: Keys live in /var/lib/tor; protect from unauthorized access

Mitigation:

# Check volume permissions
docker volume inspect tor-guard-data

# The container automatically sets:
chmod 700 /var/lib/tor
chown tor:tor /var/lib/tor

UID/GID in Alpine:

• tor user: UID 100, GID 101
• Different from Debian-based images (UID 101)
• Automatic permission healing on startup

What: Configuration is mounted from the host Impact: May reveal bandwidth limits, ContactInfo, etc.

Mitigation:

• Use read-only mount (:ro)
• Set restrictive file permissions (600)
• Never commit configs to Git
• Sanitize before sharing

• ✅ Non-root operation (user tor UID 100)
• ✅ Minimal base image (Alpine Linux ~16.8 MB)
• ✅ Drops all capabilities, adds only required ones
• ✅ Read-only configuration mount
• ✅ Automatic permission healing
• ✅ Configuration validation on startup
• ✅ NO exposed monitoring HTTP endpoints
• ✅ Busybox-only tools (no bash/python dependencies)
• ✅ Smart healthcheck.sh for Docker health checks
• ✅ Input validation for all ENV variables
• ✅ OBFS4V_* whitelist to prevent command injection

The container supports three relay modes:

Default: Guard/middle relay (lowest risk)

Changing modes:

-e TOR_RELAY_MODE=guard   # Guard/middle relay (default)
-e TOR_RELAY_MODE=exit    # Exit relay (understand legal risks!)
-e TOR_RELAY_MODE=bridge  # obfs4 bridge

See docs/MULTI-MODE.md and docs/LEGAL.md for details.

To ensure ongoing hardening, CI automatically:

1. Pulls latest Alpine base (weekly)
2. Installs updated Tor package
3. Applies available security patches
4. Rebuilds for AMD64 + ARM64
5. Publishes to Docker Hub and GHCR

Schedule: Sundays at 18:30 UTC

Enable automatic updates in Cosmos:

"cosmos-auto-update": "true",
"cosmos-auto-update-notify": "true"

Running a Tor relay is legal in most countries, but:

• ⚠️ Check local laws and ISP terms of service
• ⚠️ Understand guard vs. exit vs. bridge differences
• ⚠️ Keep contact information accurate
• ⚠️ Read docs/LEGAL.md before deployment

This project supports guard, exit, and bridge modes (configurable via TOR_RELAY_MODE).

• Tor relays do not log traffic content
• Relay fingerprints are public (guard/exit modes)
• Bridge fingerprints are NOT public (distributed via BridgeDB)
• Contact information and bandwidth statistics are public (guard/exit modes)

If you receive abuse complaints:

1. Verify it's actually your relay
2. Review Tor Project abuse response templates
3. Respond professionally
4. Consider your legal position
5. Join tor-relays mailing list for help

• Tor Relay Guide
• Tor Security Documentation
• Good/Bad Relays Criteria
• EFF Tor Legal FAQ

• Docker Security Best Practices
• CIS Docker Benchmark
• OWASP Docker Security Cheat Sheet

• Alpine Security
• Alpine Package Updates

#!/bin/bash
# security-audit.sh - Quick security audit for Tor Guard Relay

echo "🔒 Tor Guard Relay Security Audit"
echo "==========================================="

# Check container is using host networking
echo ""
echo "1. Checking network mode..."
NETWORK_MODE=$(docker inspect tor-relay --format='{{.HostConfig.NetworkMode}}')
if [ "$NETWORK_MODE" = "host" ]; then
  echo "✅ Using host networking (recommended)"
else
  echo "⚠️  Not using host networking: $NETWORK_MODE"
fi

# Test Tor ports
echo ""
echo "2. Testing Tor port accessibility..."
PUBLIC_IP=$(curl -s https://icanhazip.com)
timeout 5 nc -zv $PUBLIC_IP 9001 && echo "✅ ORPort accessible" || echo "❌ ORPort not accessible"

# Verify diagnostic tools work
echo ""
echo "3. Testing diagnostic tools..."
docker exec tor-relay status > /dev/null 2>&1 && echo "✅ status tool works" || echo "❌ status tool failed"
docker exec tor-relay health > /dev/null 2>&1 && echo "✅ health tool works" || echo "❌ health tool failed"

# Check file permissions
echo ""
echo "4. Checking critical file permissions..."
docker exec tor-relay ls -la /var/lib/tor | grep -E "keys|fingerprint"

# Check process user
echo ""
echo "5. Checking process user..."
docker exec tor-relay ps aux | grep -E "^tor" | grep -v grep | head -1

# Check capabilities
echo ""
echo "6. Checking container capabilities..."
docker inspect tor-relay --format='{{.HostConfig.CapDrop}}' | grep -q "ALL" && echo "✅ All capabilities dropped" || echo "⚠️  Capabilities not fully restricted"

# Check volumes
echo ""
echo "7. Checking volume mounts..."
docker inspect tor-relay --format='{{range .Mounts}}{{.Source}} → {{.Destination}} ({{.Mode}}){{println}}{{end}}'

echo ""
echo "==========================================="
echo "✅ Audit complete!"

Security researchers who responsibly disclose vulnerabilities will be listed here:

No vulnerabilities reported yet.

• Security Issues: r3bo0tbx1@brokenbotnet.com
• General Questions: GitHub Discussions
• Project Maintainer: rE-Bo0t.bx1

Thank you for helping keep this project secure! 🔒🧅

Last Updated: 2026-06-05 | Current Stable: 2.0.0