secubox-openwrt/package/secubox/luci-app-tor-shield/README.md

🧅 Tor Shield - Anonymous Routing Made Simple

Network-wide privacy protection through the Tor network with one-click activation.

✨ Features

🛡️ Protection Modes

Mode	Description	Use Case
🌐 Transparent Proxy	All network traffic routed through Tor automatically	Full network anonymity
🎯 SOCKS Proxy	Apps connect via SOCKS5 (127.0.0.1:9050)	Selective app protection
🔓 Bridge Mode	Uses obfs4/meek bridges to bypass censorship	Restrictive networks

🚀 Quick Start Presets

Preset	Icon	Configuration
Full Anonymity	🛡️	Transparent + DNS over Tor + Kill Switch
Selective Apps	🎯	SOCKS only, no kill switch
Bypass Censorship	🔓	Bridges enabled + obfs4

🔒 Security Features

• 🔐 Kill Switch - Blocks all traffic if Tor disconnects
• 🌍 DNS over Tor - Prevents DNS leaks
• 🔄 New Identity - Request fresh circuits instantly
• 🔍 Leak Test - Verify your protection is working
• 🧅 Hidden Services - Host .onion sites

📊 Dashboard

The dashboard provides real-time monitoring:

┌──────────────────────────────────────────────────┐
│  🧅 Tor Shield                    🟢 Protected   │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌────────────┐    Your Protection Status        │
│  │   🧅      │    ─────────────────────────      │
│  │  Toggle   │    Real IP:     192.168.x.x       │
│  │           │    Tor Exit:    185.220.x.x 🇩🇪   │
│  └────────────┘                                  │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │ 🛡️ Full      │ 🎯 Selective │ 🔓 Censored  │ │
│  │ Anonymity    │ Apps         │ Bypass       │ │
│  └─────────────────────────────────────────────┘ │
│                                                  │
│  🔄 Circuits: 5  │ 📊 45 KB/s  │ ⏱ 2h 15m     │
│  📥 125 MB       │ 📤 45 MB    │              │
│                                                  │
│  ┌─────────┬─────────┬─────────┬─────────┐      │
│  │🟢Service│🟢Boot   │🟢DNS    │🟢Kill   │      │
│  │ Running │ 100%    │Protected│ Active  │      │
│  └─────────┴─────────┴─────────┴─────────┘      │
└──────────────────────────────────────────────────┘

🧅 Hidden Services

Host your services on the Tor network with .onion addresses:

# Via LuCI
Services → Tor Shield → Hidden Services → Add

# Via CLI
ubus call luci.tor-shield add_hidden_service '{"name":"mysite","local_port":80,"virtual_port":80}'

# Get onion address
cat /var/lib/tor/hidden_service_mysite/hostname

Example Hidden Services

Service	Local Port	Onion Port	Use Case
Web Server	80	80	Anonymous website
SSH	22	22	Secure remote access
API	8080	80	Anonymous API endpoint

🌉 Bridges

Bypass network censorship using Tor bridges:

Bridge Types

Type	Description	When to Use
obfs4	Obfuscated protocol	Most censored networks
meek-azure	Domain fronting via Azure	Highly restrictive networks
snowflake	WebRTC-based	Dynamic bridge discovery

Auto-Bridge Detection

# Enable automatic bridge selection
uci set tor-shield.main.auto_bridges=1
uci commit tor-shield
/etc/init.d/tor-shield restart

🔧 Configuration

UCI Settings

# /etc/config/tor-shield

config tor-shield 'main'
    option enabled '1'
    option mode 'transparent'      # transparent | socks
    option dns_over_tor '1'        # Route DNS through Tor
    option kill_switch '1'         # Block traffic if Tor fails
    option auto_bridges '0'        # Auto-detect censorship

config socks 'socks'
    option port '9050'
    option address '127.0.0.1'

config trans 'trans'
    option port '9040'
    option dns_port '9053'
    list excluded_ips '192.168.255.0/24'  # LAN bypass

config bridges 'bridges'
    option enabled '0'
    option type 'obfs4'

config security 'security'
    option exit_nodes ''           # Country codes: {us},{de}
    option exclude_exit_nodes ''   # Avoid: {ru},{cn}
    option strict_nodes '0'

config hidden_service 'hs_mysite'
    option enabled '1'
    option name 'mysite'
    option local_port '80'
    option virtual_port '80'

📡 RPCD API

Status & Control

# Get status
ubus call luci.tor-shield status

# Enable with preset
ubus call luci.tor-shield enable '{"preset":"anonymous"}'

# Disable
ubus call luci.tor-shield disable

# Restart
ubus call luci.tor-shield restart

# Request new identity
ubus call luci.tor-shield new_identity

# Check for leaks
ubus call luci.tor-shield check_leaks

Circuit Management

# Get active circuits
ubus call luci.tor-shield circuits

# Response:
{
  "circuits": [{
    "id": "123",
    "status": "BUILT",
    "path": "$A~Guard,$B~Middle,$C~Exit",
    "purpose": "GENERAL",
    "nodes": [
      {"fingerprint": "ABC123", "name": "Guard"},
      {"fingerprint": "DEF456", "name": "Middle"},
      {"fingerprint": "GHI789", "name": "Exit"}
    ]
  }]
}

Hidden Services

# List hidden services
ubus call luci.tor-shield hidden_services

# Add hidden service
ubus call luci.tor-shield add_hidden_service '{"name":"web","local_port":80,"virtual_port":80}'

# Remove hidden service
ubus call luci.tor-shield remove_hidden_service '{"name":"web"}'

Bandwidth Stats

# Get bandwidth
ubus call luci.tor-shield bandwidth

# Response:
{
  "read": 125000000,      # Total bytes downloaded
  "written": 45000000,    # Total bytes uploaded
  "read_rate": 45000,     # Current download rate (bytes/sec)
  "write_rate": 12000     # Current upload rate (bytes/sec)
}

🛠️ Troubleshooting

Tor Won't Start

# Check logs
logread | grep -i tor

# Verify config
tor --verify-config -f /var/run/tor/torrc

# Check control socket
ls -la /var/run/tor/control

Slow Connections

1. Check bootstrap - Wait for 100% completion
2. Try bridges - Network may be throttling Tor
3. Change circuits - Click "New Identity"
4. Check exit nodes - Some exits are slow

DNS Leaks

# Verify DNS is routed through Tor
nslookup check.torproject.org

# Should resolve via Tor DNS (127.0.0.1:9053)

Kill Switch Issues

# Check firewall rules
iptables -L -n | grep -i tor

# Verify kill switch config
uci get tor-shield.main.kill_switch

📁 File Locations

Path	Description
/etc/config/tor-shield	UCI configuration
/var/run/tor/torrc	Generated Tor config
/var/run/tor/control	Control socket
/var/lib/tor/	Tor data directory
/var/lib/tor/hidden_service_*/	Hidden service keys
/tmp/tor_exit_ip	Cached exit IP
/tmp/tor_real_ip	Cached real IP

🔐 Security Notes

1. Kill Switch - Always enable for maximum protection
2. DNS Leaks - Enable DNS over Tor to prevent leaks
3. Hidden Services - Keys in /var/lib/tor/ are sensitive - back them up securely
4. Exit Nodes - Consider excluding certain countries for sensitive use
5. Bridges - Use if your ISP blocks or throttles Tor

📜 License

MIT License - Copyright (C) 2025 CyberMind.fr