# 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](#overview)
2. [Test Suite Components](#test-suite-components)
3. [Unit Tests](#unit-tests)
4. [Integration Tests](#integration-tests)
5. [Network Verification](#network-verification)
6. [Continuous Monitoring](#continuous-monitoring)
7. [Reporting & Compliance](#reporting--compliance)
8. [CI/CD Integration](#cicd-integration)
9. [Troubleshooting](#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**:
```bash
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**:
```bash
# 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**:
```bash
# 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**:
```bash
./Scripts/tor-health-monitor.sh
```

**Daemon Mode** (Continuous monitoring):
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```yaml
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**:
```yaml
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**:
```xml
<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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
#!/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**:
```bash
# 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**:
```bash
# 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**:
```bash
# Verify appsettings.json exists
ls -l TeleBot/appsettings.json

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

---

**Problem**: Integration tests timeout

**Solution**:
```bash
# 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**:
```bash
# 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*