Tunnel Fox - Advanced Telegram Bot Platform

A comprehensive, production-ready Telegram bot platform combining DevOps automation, network tunneling, VPN services, and AI-powered code analysis.

✨ Overview

Tunnel Fox is a sophisticated Telegram bot that serves as a unified platform for DevOps automation, network security, and development workflow management. Built with Go and designed for cloud deployment, it integrates Jenkins CI/CD, V2Ray VPN, HTTP proxies, SSH tunneling, and AI-powered code review capabilities.

🚀 Key Features

🏗️ CI/CD & DevOps Automation

• Jenkins Integration: Complete job lifecycle management via Telegram
• Interactive Build Wizard: Step-by-step job selection with parameter configuration
• Build Monitoring: Real-time build status notifications and console output
• Advanced Console Filtering: Filter console output with grep patterns and keywords
• Queue Management: View and control Jenkins build queues
• Parameter Support: Execute parameterized builds with custom values
• Multi-folder Support: Browse jobs in specific folders or view all recursively
• Caching System: Intelligent job list caching for improved performance
• Docker Integration: Container log monitoring and management

🌐 Network & Security Services

🛡️ V2Ray VPN Server

• VLESS + Reality Protocol: State-of-the-art traffic masking technology
• Port 443 Operation: Seamless HTTPS port utilization
• Auto Key Generation: Dynamic security key creation per session
• Multi-client Support: Compatible with v2rayNG, Shadowrocket, ClashX, v2rayN
• Zero Configuration: Automatic client configuration generation
• Traffic Obfuscation: Advanced DPI bypass capabilities

🌍 HTTP Proxy Services

• Dual Proxy Stack: goproxy + 3proxy for maximum compatibility and flexibility
• Authentication Support: Username/password and IP-based access control
• Protocol Support: HTTP/HTTPS with full CONNECT method support for tunneling
• Browser Integration: Direct browser proxy configuration with automatic settings
• Port Flexibility: Configurable listening ports for different use cases
• Load Balancing: Multiple proxy instance management and failover support
• Advanced Logging: Comprehensive access logs with rotation and management
• Connection Testing: Built-in proxy functionality testing and diagnostics

🔗 SSH Tunneling System

• Reverse Tunneling: Expose local services through remote SSH servers with advanced routing
• Multi-auth Support: SSH key and password authentication with secure key management
• Port Forwarding: Multiple simultaneous port forwards with conflict detection
• Auto-reconnection: Intelligent connection recovery with exponential backoff
• Dynamic Configuration: Real-time tunnel management via Telegram with live updates
• YAML Configuration: Advanced configuration support for complex tunnel setups
• Comprehensive Logging: Detailed connection logs with rotation and analysis tools
• Status Monitoring: Real-time tunnel status monitoring with health checks
• Rospo Integration: Professional-grade SSH tunneling library for enterprise reliability

🤖 AI & Code Analysis

🧠 OpenAI Integration

• Intelligent Code Review: AI-powered pull request analysis with detailed feedback
• Natural Language Processing: Query and modify your codebase in plain English
• Build Troubleshooting: Automated failure diagnosis and solution recommendations
• Documentation Generation: Auto-generate project documentation and comments
• Code Quality Assessment: Advanced static analysis with improvement suggestions
• Multi-project Support: Work with any project in configured TFS repositories
• Topic-based Access: Secure topic-based permissions for group chat operations
• Review Management: Store, retrieve, and manage AI review history and records

🔄 TFS/Azure DevOps Integration

• Pull Request Automation: Complete PR lifecycle management with approval workflows
• Queue-based Processing: Automatic PR approval queue with status monitoring
• Code Review Workflows: Automated review assignment and tracking with manual override
• Branch Management: Real-time branch status monitoring and notifications
• Work Item Integration: Seamless Azure DevOps work item tracking and updates
• User Permission Management: Individual PR lists and permission-based access
• Duplicate Detection: Advanced duplicate PR detection and cleanup utilities
• Manual Trigger Support: Manual PR status check and notification triggers

🔐 Security & Access Control

• User Whitelisting: Granular user access control with username-based permissions
• Token-based Authentication: Secure API access management with rotation support
• Environment Variable Security: Zero hardcoded credentials with secure secret management
• Topic-based Permissions: Telegram group topic access control for different functions
• SSH Key Management: Secure key storage, rotation, and multi-format support
• Audit Logging: Comprehensive action tracking with user attribution
• Command History: Secure command history storage with user-specific access
• Message Management: Automated message cleanup and reaction management
• Session Management: Secure session handling with automatic cleanup

📊 Monitoring & Observability

• Health Monitoring: Real-time service health checks with automated diagnostics
• Centralized Logging: Structured logging with rotation, filtering, and archival
• Performance Metrics: Resource usage and performance tracking with trends
• Status Dashboards: Real-time system status via Telegram with interactive menus
• Alert System: Proactive issue notifications with severity classification
• Docker Integration: Container log monitoring with multi-server support
• Connection Statistics: Detailed proxy, VPN, and tunnel usage analytics
• Error Tracking: Comprehensive error logging with pattern analysis
• Service Dependencies: Monitor and track inter-service dependencies and health

🏗️ Architecture

graph TB
    TG[Telegram Bot API] --> API[HTTP API :8081]
    API --> BOT[Bot Core Engine]
    BOT --> JENKINS[Jenkins Client]
    BOT --> V2RAY[V2Ray Server :443]
    BOT --> PROXY[HTTP Proxy :1080]
    BOT --> SSH[SSH Tunnel Manager]
    BOT --> DB[(SQLite Database)]
    BOT --> TFS[TFS/Azure Client]
    BOT --> AI[OpenAI Integration]
    
    JENKINS --> J1[Jenkins Instance 1]
    JENKINS --> J2[Jenkins Instance N]
    
    V2RAY --> XRAY[Xray Core]
    PROXY --> GP[goproxy]
    PROXY --> P3[3proxy]
    SSH --> ROSPO[Rospo Library]
    
    TFS --> AZURE[Azure DevOps]
    AI --> OPENAI[OpenAI API]

Loading

🛠️ Installation & Deployment

Prerequisites

• Docker: 20.10+ with Linux container support
• Ports: 8081 (API), 443 (V2Ray), 1080 (Proxy), 2222 (SSH)
• Telegram Bot Token: Obtain from @BotFather
• System Requirements: 512MB RAM, 1GB storage minimum

🚀 Quick Start

1. Docker Deployment (Recommended)

# Pull the latest image (replace with your registry)
docker pull your-registry/tunnel-fox:latest

# Run with basic configuration
docker run -d --name tunnel-fox \
  -p 8081:8081 \
  -p 443:443 \
  -p 1080:1080 \
  -e ALLOWED_USERS="your_telegram_username" \
  your-registry/tunnel-fox:latest

# Initialize the bot
curl -X POST http://localhost:8081/init \
  -H "Content-Type: application/json" \
  -d '{"telegram_token": "YOUR_BOT_TOKEN"}'

2. Production Deployment with Docker Compose

version: '3.8'
services:
  tunnel-fox:
    image: your-registry/tunnel-fox:latest
    container_name: tunnel-fox
    restart: unless-stopped
    ports:
      - "8081:8081"
      - "443:443"
      - "1080:1080"
      - "2222:22"
    environment:
      - ALLOWED_USERS=user1,user2,user3
      - JENKINS_URL=https://your-jenkins.example.com
      - JENKINS_USER=your-jenkins-user
      - JENKINS_TOKEN=your-jenkins-token
      - TFS_URL=https://dev.azure.com/your-organization
      - TFS_USERNAME=your-username
      - TFS_PASSWORD=your-pat-token
      - OPENAI_API_KEY=your-openai-key
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    networks:
      - tunnel-fox-network

networks:
  tunnel-fox-network:
    driver: bridge

3. Building from Source

# Clone repository
git clone <your-repository-url>
cd tunnel-fox

# Build binary
go mod tidy
CGO_ENABLED=1 go build -o tunnel-fox ./cmd/main.go

# Build Docker image
docker build -t tunnel-fox:local .

⚙️ Configuration

Environment Variables

# Core Configuration
TELEGRAM_BOT_TOKEN="your_bot_token"
ALLOWED_USERS="user1,user2,user3"

# Jenkins Integration
JENKINS_URL="https://your-jenkins.example.com"
JENKINS_USER="jenkins_user"
JENKINS_TOKEN="jenkins_api_token"

# TFS/Azure DevOps
TFS_URL="https://dev.azure.com/your-organization"
TFS_USERNAME="your_username"
TFS_PASSWORD="your_pat_token"

# AI Integration
OPENAI_API_KEY="your_openai_key"

# SSH Configuration
SSH_KEY_DATA="base64_encoded_private_key"
SSH_PASSPHRASE="optional_key_passphrase"

# Topic Configuration (Advanced)
CODEX_TOPICS="topic_id:chat_id,topic_id:chat_id"
LOGS_TOPICS="topic_id:chat_id"

# Logging
PROXY3_LOG_FILE="logs/3proxy.log"
SSH_TUNNEL_LOG_FILE="logs/ssh_tunnel.log"

🤖 Telegram Commands Reference

🏗️ Jenkins Commands

/jobs [path]                       - List available Jenkins jobs in specified path or root
/alljobs                           - Show all jobs recursively (folder1, folder2, folder3)
/run <job_name> [param1=value1 ...]- Start a build with optional parameters
/build_command [filter]            - Interactive job selection and parameter wizard
/bc [filter]                       - Alias for /build_command
/cancel_build                      - Cancel active build wizard
/cb                                - Alias for /cancel_build
/console <job_name> [build_number] [-full | -grep word1,word2] - Get console output
/clear_cache                       - Clear Jenkins jobs cache

🛡️ V2Ray VPN Commands

/v2ray_start                       - Start V2Ray VPN server with VLESS + Reality
/v2ray_stop                        - Stop V2Ray VPN server  
/v2ray_status                      - Display server status and configuration
/v2ray_url                         - Get client connection URL
/v2ray_config                      - Get detailed configuration
/v2ray_logs                        - View recent server logs
/v2ray_config_file                 - Download configuration file

🌍 HTTP Proxy Commands

/proxy_start <user> <pass> [port]  - Start HTTP proxy server (default port: 1080)
/proxy_stop                        - Stop HTTP proxy server
/proxy_status                      - Show proxy server status
/proxy_url                         - Get proxy connection settings
/proxy_test                        - Test proxy functionality

/3proxy_start                      - Start 3proxy server (port 3128)
/3proxy_stop                       - Stop 3proxy server
/3proxy_status                     - Show 3proxy status
/3proxy_logs                       - View 3proxy logs
/3proxy_config                     - Get 3proxy configuration
/3proxy_clear_logs                 - Clear 3proxy logs

🔗 SSH Tunnel Commands

/tunnel_start <host> <ssh_port> <user> <local_port> <remote_port> <auth_type> <auth_value>
/tunnel_yaml [config_path]         - Start tunnel with YAML configuration
/tunnel_stop                       - Stop active SSH tunnel
/tunnel_status                     - Show tunnel status and statistics
/tunnel_logs                       - View tunnel connection logs
/tunnel_clear_logs                 - Clear tunnel log history

📋 Pull Request Commands

/approve_pr <pr_url>               - Approve pull request in TFS using Jenkins account
/queue_pr <pr_url>                 - Add PR to automatic approval queue
/my_prs                            - Show list of your pull requests
/manual_notify_prs                 - Manually trigger PR status check
/remove_pr <pr_url>                - Force remove PR from queue
/remove_duplicate_prs              - Remove duplicate PRs by pr_id

🤖 AI & Code Review Commands

/ai_review <pr_url>                - Perform AI-powered code review
/ai_delete <id>                    - Delete AI review record by ID
/codex <project_name> <base_branch> <prompt> - AI agent for code modification

🐳 Docker Commands

/dockerlogs [server_alias] <container_name> - Show Docker container logs
/dockerlogs <container_name> -file - Download container logs as file

🔧 System & Utility Commands

/start                             - Show welcome message
/help                              - Show interactive help menu with categories
/command_history                   - Show command history by categories
/delete_messages                   - Delete recent messages
/react <emoji>                     - Add reaction to replied message
/print_id                          - Print current chat ID (debug)

📝 Command Examples

# Jenkins Examples
/jobs folder1                      - Show jobs in folder1
/run folder1/job_name buildBranch=develop param2=value2
/console folder2/service -grep error,failed
/build_command                     - Start interactive job selector

# V2Ray Examples  
/v2ray_start                       - Start VPN server
/v2ray_url                         - Get connection URL for clients

# Proxy Examples
/proxy_start myuser mypass         - Start on port 1080
/proxy_start admin secret123 8080  - Start on port 8080
/3proxy_start                      - Start 3proxy on port 3128

# Tunnel Examples
/tunnel_start server.com 22 user 8080 80 key /path/to/key
/tunnel_start server.com 22 user 8080 80 password mypass
/tunnel_yaml                       - Use default config
/tunnel_yaml /path/to/config.yaml  - Use custom config

# AI Examples
/ai_review https://tfs.example.com/project/_git/repo/pullrequest/123
/codex my-project develop fix authentication bugs
/codex common main add JSON validation method

# Docker Examples
/dockerlogs nginx                  - Show nginx container logs
/dockerlogs prod nginx             - Show nginx logs from prod server
/dockerlogs app -file              - Download app logs as file

📱 Client Configuration

V2Ray Clients Setup

Android (v2rayNG)

1. Download from Google Play
2. Use /v2ray_url to get configuration URL
3. Import via QR code or URL

iOS (Shadowrocket)

1. Install from App Store
2. Get configuration from /v2ray_config
3. Import and connect

Windows (v2rayN)

1. Download from GitHub releases
2. Import configuration from bot
3. Set as system proxy

macOS (ClashX)

1. Install ClashX from GitHub
2. Import configuration
3. Enable proxy mode

HTTP Proxy Configuration

Configure applications with proxy settings:

• Server: Your server IP address
• Port: 1080 (default) or custom port
• Protocol: HTTP with authentication
• Username/Password: From /proxy_start command

🔧 API Documentation

Core Endpoints

Bot Management

POST /init
Content-Type: application/json
{
  "telegram_token": "your_bot_token"
}

GET /status
# Returns initialization status

GET /health
# Health check endpoint

V2Ray Management

POST /v2ray/start
# Start V2Ray server

POST /v2ray/stop
# Stop V2Ray server

GET /v2ray/status
# Get server status

GET /v2ray/config
# Get client configuration

Security Best Practices

Access Control

• Configure user whitelist via ALLOWED_USERS environment variable
• Use strong Telegram bot tokens
• Implement topic-based permissions for group chats
• Regular token rotation

Network Security

• V2Ray Reality protocol provides advanced traffic obfuscation
• Use unique UUIDs and keys for each deployment
• Consider firewall rules for exposed ports
• Monitor access logs regularly

Credential Management

• Store all secrets in environment variables
• Use Docker secrets in production
• Implement credential rotation policies
• Audit credential access

📊 Monitoring & Troubleshooting

Health Monitoring

# Check overall health
curl http://localhost:8081/health

# Monitor Docker logs
docker logs -f tunnel-fox

# Check service status via Telegram
/status command in bot

Common Issues

V2Ray Won't Start

# Check port availability
netstat -tulpn | grep :443

# Verify xray installation
docker exec tunnel-fox xray version

# Check permissions for port 443
docker run --privileged ...

Proxy Connection Issues

# Test proxy functionality
curl -x http://user:pass@localhost:1080 http://httpbin.org/ip

# Check proxy logs
docker exec tunnel-fox tail -f /app/logs/proxy.log

SSH Tunnel Problems

# Verify SSH connectivity
ssh -p 22 user@remote-host

# Check tunnel logs
/tunnel_logs command in bot

🚀 Advanced Configuration

Topic-based Group Management

Configure Telegram group topics for different notification types:

# Format: topic_id:chat_id
CODEX_TOPICS="105:-1002631777631,106:-1002631777632"
LOGS_TOPICS="107:-1002631777631"
PR_APPROVAL_TOPICS="108:-1002631777631"

Multi-Jenkins Setup

Configure multiple Jenkins instances:

# Primary Jenkins
JENKINS_URL="https://prod-jenkins.example.com"
JENKINS_USER="prod_user"
JENKINS_TOKEN="prod_token"

# Additional configuration via bot commands
/jenkins_add secondary https://dev-jenkins.example.com dev_user dev_token

📝 Development & Contributing

Project Structure

tunnel-fox/
├── cmd/
│   └── main.go              # Application entry point
├── config/
│   └── config.go            # Configuration management
├── pkg/
│   ├── bot/                 # Telegram bot implementation
│   │   ├── bot.go           # Core bot logic
│   │   ├── bot_methods.go   # Helper methods
│   │   ├── codex.go         # AI integration
│   │   ├── db.go            # Database operations
│   │   └── tfs_client.go    # TFS/Azure DevOps client
│   ├── jenkins/
│   │   └── jenkins.go       # Jenkins API client
│   ├── proxy/
│   │   └── proxy.go         # HTTP proxy server
│   ├── proxy3/
│   │   └── proxy3.go        # 3proxy integration
│   ├── tunnel/
│   │   └── ssh_tunnel.go    # SSH tunneling
│   └── v2ray/
│       └── v2ray.go         # V2Ray VPN server
├── ubuntu/
│   └── Dockerfile           # Ubuntu-based image
├── Dockerfile               # Main Docker image
├── go.mod                   # Go modules
└── README.md               # This file

Building from Source

# Install dependencies
go mod tidy

# Run tests
go test ./...

# Build binary
CGO_ENABLED=1 go build -o tunnel-fox ./cmd/main.go

# Build Docker image
docker build -t tunnel-fox:dev .

Contributing Guidelines

1. Fork the repository on your preferred Git hosting platform
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Quality

• Follow Go best practices and conventions
• Write comprehensive tests for new features
• Update documentation for API changes
• Use descriptive commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support & Community

• Issues: Create GitHub Issues for bug reports and feature requests
• Discussions: Use GitHub Discussions for general questions and community support
• Documentation: Refer to this README for comprehensive setup and usage instructions

🙏 Acknowledgments

• go-telegram-bot-api - Telegram Bot API wrapper
• goproxy - HTTP proxy library
• Xray-core - V2Ray/Xray implementation
• rospo - SSH tunneling library
• 3proxy - Proxy server implementation

---

Built with ❤️ using Go • Docker • Telegram Bot API