littleshop/TeleBot/TESTING-AND-VERIFICATION.md

TeleBot TOR Testing & Verification Guide

Comprehensive Testing Framework for Location Privacy

Version: 1.0 Date: 2025-10-01 Security Level: CRITICAL Author: Mr Tickles, Security Consultant

---

Table of Contents

1. Overview
2. Test Suite Components
3. Unit Tests
4. Integration Tests
5. Network Verification
6. Continuous Monitoring
7. Reporting & Compliance
8. CI/CD Integration
9. Troubleshooting

---

Overview

This document describes the comprehensive testing framework established to prove and maintain that TeleBot routes ALL traffic through TOR, ensuring complete location privacy.

Testing Philosophy

Mr Tickles' Security Principle:

"Trust, but verify. Then verify again. Then monitor continuously."

Test Coverage

Component	Test Type	Purpose	Frequency
Configuration	Unit	Verify TOR is enabled	Every build
SOCKS5 Handler	Unit	Verify proxy configuration	Every build
HttpClient Setup	Unit	Verify all clients use SOCKS5	Every build
TOR Connectivity	Integration	Verify actual TOR connection	Daily
IP Verification	Integration	Verify IP masking	Daily
Traffic Analysis	Network	Detect IP leaks	Continuous
Health Monitoring	System	Monitor TOR service	Every minute
Compliance Reports	Audit	Prove TOR usage	Weekly/Monthly

---

Test Suite Components

1. Unit Tests (TeleBot.Tests/Security/)

Location: /TeleBot.Tests/Security/TorProxyTests.cs

Purpose: Verify TOR configuration at code level

Tests Included:

• ✅ Socks5HttpHandler_WithTorEnabled_ConfiguresProxy - Verifies SOCKS5 proxy is configured
• ✅ Socks5HttpHandler_WithTorDisabled_NoProxy - Verifies fallback behavior
• ✅ Socks5HttpHandler_WithTorEnabled_DisablesAutoRedirect - Security check
• ✅ Socks5HttpHandler_WithTorEnabled_ConfiguresConnectionPooling - Performance check
• ✅ Socks5HttpHandler_ProxyBypassLocal_IsFalse - All traffic through TOR
• ✅ Socks5HttpHandler_DefaultCredentials_IsFalse - Security check
• ✅ Configuration_AppsettingsFormat_IsCorrect - Config validation

Run Command:

cd TeleBot.Tests
dotnet test --filter "FullyQualifiedName~TorProxy"

Expected Output:

Passed! - 12 test(s), 0 failed, 0 skipped

---

2. Integration Tests (TeleBot.Tests/Security/)

Location: /TeleBot.Tests/Security/TorConnectivityTests.cs

Purpose: Verify actual TOR connectivity with real network

Tests Included:

• ✅ TorConnection_WhenAvailable_CanConnect - Tests connection through TOR
• ✅ TorConnection_ChecksRealIP_IsDifferent - Verifies IP masking
• ✅ TorConnection_Timeout_IsReasonable - Performance check
• ✅ TorProxy_Address_IsLocalhost - Security validation
• ✅ TorProxy_Protocol_IsSocks5 - Protocol verification

Prerequisites:

• TOR service running on localhost:9050

Run Command:

# Ensure TOR is running
sudo systemctl start tor

# Run integration tests
cd TeleBot.Tests
dotnet test --filter "FullyQualifiedName~TorConnectivity"

Note: These tests are skipped if TOR is not available (CI/CD safe).

---

3. Network Verification Script

Location: /TeleBot/Scripts/verify-tor-traffic.sh

Purpose: Capture and analyze network traffic to prove TOR usage

Features:

• Traffic capture using tcpdump
• DNS leak detection
• External connection analysis
• Active connection monitoring
• Configuration verification

Usage:

# Run 60-second traffic capture
sudo ./Scripts/verify-tor-traffic.sh 60

# Run 5-minute capture
sudo ./Scripts/verify-tor-traffic.sh 300

Output:

/tmp/telebot-tor-verification/tor-verification-20251001_123045.txt
/tmp/telebot-tor-verification/traffic-20251001_123045.pcap

What It Checks:

1. ✅ TOR service is running
2. ✅ TOR SOCKS5 proxy is listening
3. ✅ TOR circuits are established
4. ✅ TeleBot process is running
5. ✅ TeleBot has connections to TOR
6. ✅ NO direct external connections
7. ✅ NO DNS leaks
8. ✅ Configuration is correct

Verdict Codes:

• ✓ PASS - All traffic through TOR
• ⚠ PASS WITH WARNINGS - Review warnings
• ✗ FAIL - CRITICAL: Location exposed!

---

4. TOR Health Monitor

Location: /TeleBot/Scripts/tor-health-monitor.sh

Purpose: Continuous monitoring of TOR connectivity and health

Features:

• Real-time TOR service monitoring
• Circuit health tracking
• IP leak detection
• Performance metrics
• Automated alerting
• Historical logging

Usage:

One-time Check:

./Scripts/tor-health-monitor.sh

Daemon Mode (Continuous monitoring):

# Monitor every 60 seconds
./Scripts/tor-health-monitor.sh --daemon --interval=60

# With email alerts
./Scripts/tor-health-monitor.sh --daemon --email=admin@example.com

Systemd Service:

# Create service file
sudo tee /etc/systemd/system/telebot-tor-monitor.service << 'EOF'
[Unit]
Description=TeleBot TOR Health Monitor
After=tor.service telebot.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/telebot
ExecStart=/opt/telebot/Scripts/tor-health-monitor.sh --daemon --interval=60
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable telebot-tor-monitor
sudo systemctl start telebot-tor-monitor

# Check status
sudo systemctl status telebot-tor-monitor

# View logs
sudo journalctl -u telebot-tor-monitor -f

Checks Performed:

1. TOR service status
2. SOCKS5 proxy availability
3. TOR circuit establishment
4. IP verification (TOR vs Direct)
5. TeleBot process status
6. IP leak detection
7. DNS leak detection
8. TOR latency measurement

Alerts Triggered:

• TOR service down
• SOCKS5 proxy unavailable
• IP leak detected
• DNS leak detected
• Poor health score (<80%)

Logs:

• Health: /var/log/telebot/tor-health.log
• Alerts: /var/log/telebot/tor-alerts.log
• State: /var/lib/telebot/

---

5. TOR Usage Report Generator

Location: /TeleBot/Scripts/generate-tor-report.sh

Purpose: Generate compliance reports proving TOR usage

Features:

• Historical data analysis
• Performance metrics
• Security event tracking
• Compliance proof
• HTML and text formats
• Cryptographic signatures

Usage:

# Daily report
./Scripts/generate-tor-report.sh --period=daily

# Weekly report
./Scripts/generate-tor-report.sh --period=weekly

# Monthly report
./Scripts/generate-tor-report.sh --period=monthly

# Custom output directory
./Scripts/generate-tor-report.sh --period=weekly --output=/var/reports/custom

Output:

/var/reports/telebot-tor/tor-usage-report-20251001_123045.txt
/var/reports/telebot-tor/tor-usage-report-20251001_123045.html

Report Sections:

1. Executive Summary

   • TOR protection status
   • Overall uptime
   • Health check statistics
   • Security alerts

2. Network Privacy

   • Real IP address
   • Current TOR exit IP
   • IP verification status

3. Performance Metrics

   • Average latency
   • Circuit health
   • Connection statistics

4. Security Events

   • Alert history
   • Incident tracking
   • Remediation status

5. Compliance Proof

   • Service status verification
   • Configuration verification
   • Log references
   • Cryptographic signature

6. Audit Trail

   • Report metadata
   • Verification instructions
   • SHA256 signature

Automated Scheduling:

# Add to crontab
crontab -e

# Daily report at 23:00
0 23 * * * /opt/telebot/Scripts/generate-tor-report.sh --period=daily

# Weekly report on Sunday at 23:00
0 23 * * 0 /opt/telebot/Scripts/generate-tor-report.sh --period=weekly

# Monthly report on 1st at 00:00
0 0 1 * * /opt/telebot/Scripts/generate-tor-report.sh --period=monthly

---

6. CI/CD Verification Pipeline

Location: /TeleBot/Scripts/ci-cd-tor-verification.sh

Purpose: Automated verification for CI/CD pipelines

Features:

• Configuration validation
• Build verification
• Security checks
• JUnit XML output
• Exit codes for automation

Usage in CI/CD:

GitHub Actions:

name: TOR Verification

on: [push, pull_request]

jobs:
  tor-security-check:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: '9.0.x'

    - name: Run TOR Verification
      run: |
        cd TeleBot
        ./Scripts/ci-cd-tor-verification.sh        

    - name: Upload Test Results
      if: always()
      uses: actions/upload-artifact@v3
      with:
        name: tor-verification-results
        path: test-results/

GitLab CI:

tor-verification:
  stage: test
  script:
    - cd TeleBot
    - ./Scripts/ci-cd-tor-verification.sh
  artifacts:
    when: always
    reports:
      junit: test-results/tor-verification-results.xml

TeamCity:

<build-type>
  <step type="simpleRunner">
    <param name="script.content" value="./TeleBot/Scripts/ci-cd-tor-verification.sh" />
  </step>
</build-type>

Checks Performed:

1. ✅ TOR enabled in appsettings.json
2. ✅ Socks5HttpHandler implementation exists
3. ✅ Program.cs configures TOR
4. ✅ TelegramBotService uses TOR
5. ✅ LittleShop.Client supports TOR
6. ✅ No IP address disclosure in code
7. ✅ No hardcoded external IPs
8. ✅ Project builds successfully
9. ✅ Unit tests pass

Exit Codes:

• 0 - All checks passed (TOR properly configured)
• 1 - Checks failed (BLOCK DEPLOYMENT)

---

Testing Workflow

Pre-Deployment Testing

# 1. Run unit tests
cd TeleBot.Tests
dotnet test --filter "FullyQualifiedName~TorProxy"

# 2. Run CI/CD verification
cd ../TeleBot
./Scripts/ci-cd-tor-verification.sh

# 3. Build Release
dotnet build --configuration Release

# 4. If deploying to server with TOR, run integration tests
dotnet test --filter "FullyQualifiedName~TorConnectivity"

Post-Deployment Verification

# 1. Wait for TeleBot to start (30 seconds)
sleep 30

# 2. Run traffic verification (5 minutes)
sudo ./Scripts/verify-tor-traffic.sh 300

# 3. Check health
./Scripts/tor-health-monitor.sh

# 4. Review results
cat /tmp/telebot-tor-verification/tor-verification-*.txt

Continuous Monitoring

# Set up daemon monitoring
./Scripts/tor-health-monitor.sh --daemon --interval=60 --email=admin@example.com

# Schedule reports
crontab -e
# Add: 0 23 * * * /opt/telebot/Scripts/generate-tor-report.sh --period=daily

---

Interpreting Results

Unit Test Results

PASS:

✓ PASS - 12 test(s), 0 failed

Action: Continue deployment

FAIL:

✗ FAIL - 8 test(s), 4 failed

Action: STOP DEPLOYMENT - Fix configuration errors

---

Traffic Verification Results

PASS:

✓ PASS - TeleBot is correctly routing ALL traffic through TOR
Total Tests: 8
Passed: 8
Warnings: 0
Errors: 0

Action: TOR is working correctly

FAIL:

✗ FAIL - TeleBot is NOT properly using TOR!
Errors: 3
- Detected 5 direct external connections
- DNS LEAK detected
- TOR circuits not established

Action: CRITICAL - Location is exposed! Fix immediately!

---

Health Monitor Results

Healthy:

[SUCCESS] TOR service is running
[SUCCESS] TOR SOCKS5 proxy is listening
[SUCCESS] TOR circuits are established
[SUCCESS] TeleBot has 3 active TOR connections
[SUCCESS] No IP leaks detected
Health Score: 100%

Action: System operating normally

Unhealthy:

[ERROR] Detected 2 direct external connections - IP LEAK!
[ALERT] IP Leak Detected
Health Score: 62%

Action: IMMEDIATE ATTENTION REQUIRED

---

Automated Compliance Proof

Daily Automated Workflow

#!/bin/bash
# /opt/telebot/daily-compliance-check.sh

# Run health check
/opt/telebot/Scripts/tor-health-monitor.sh > /tmp/health-check.log

# Capture traffic
sudo /opt/telebot/Scripts/verify-tor-traffic.sh 300 > /tmp/traffic-check.log

# Generate report
/opt/telebot/Scripts/generate-tor-report.sh --period=daily

# Email results
mail -s "TeleBot TOR Daily Compliance Report" compliance@example.com < /tmp/health-check.log

Schedule:

# Daily at 23:00
0 23 * * * /opt/telebot/daily-compliance-check.sh

Audit Trail Maintenance

All reports are cryptographically signed and include:

• Timestamp
• System configuration snapshot
• Network traffic analysis
• TOR circuit status
• SHA256 signature for verification

Verify Report Integrity:

# Extract signature from report
SIGNATURE=$(grep "Signature:" report.txt | cut -d' ' -f2)

# Recalculate
CALCULATED=$(sha256sum report.txt | cut -d' ' -f1)

# Compare
if [ "$SIGNATURE" = "$CALCULATED" ]; then
    echo "✓ Report integrity verified"
else
    echo "✗ Report may be tampered!"
fi

---

Troubleshooting

Test Failures

Problem: Unit tests fail with "Configuration not found"

Solution:

# Verify appsettings.json exists
ls -l TeleBot/appsettings.json

# Check TOR configuration
grep -A 5 '"Privacy"' TeleBot/appsettings.json

---

Problem: Integration tests timeout

Solution:

# Check TOR is running
sudo systemctl status tor

# Test TOR connectivity manually
curl --socks5 127.0.0.1:9050 https://check.torproject.org

# Check TOR logs
sudo journalctl -u tor -f

---

Problem: Traffic verification shows IP leaks

Solution:

# 1. Stop TeleBot
sudo systemctl stop telebot

# 2. Verify configuration
grep '"EnableTor"' /opt/telebot/appsettings.json

# 3. Check for direct HTTP clients
grep -r "new HttpClient()" TeleBot/*.cs

# 4. Restart with verbose logging
export ASPNETCORE_ENVIRONMENT=Development
dotnet run | grep -i "tor\|socks"

---

Summary

Test Execution Checklist

• Unit tests pass (12/12)
• Integration tests pass (if TOR available)
• CI/CD verification passes (9/9)
• Build succeeds with zero errors
• Traffic verification shows no leaks
• Health monitor shows 100% score
• Daily reports generated
• Compliance proof documented

Continuous Assurance

• Health monitor running as daemon
• Daily reports scheduled (cron)
• Alert emails configured
• Log rotation configured
• Compliance reports archived

Emergency Response

If any test fails:

1. STOP - Do not deploy
2. INVESTIGATE - Review logs and test output
3. FIX - Correct configuration
4. VERIFY - Re-run all tests
5. DOCUMENT - Record incident and fix

---

Remember: Privacy is not optional. Test rigorously. Monitor continuously. Verify constantly.

---

End of Testing & Verification Guide