👻 GHOSTTRACE v2.0

Advanced Network Routing, Proxy Chain Orchestration & Traffic Analysis Framework

⚡ A NEXT-GENERATION FRAMEWORK FOR NETWORK TRAFFIC ORCHESTRATION

GhostTrace redefines proxy-chain management, providing a unified platform for building, monitoring, and rotating complex routing topologies with surgical precision.

🔗	🌐	🧭	🔄	🧩
Dynamic Multi-Hop	Automated Discovery	Route Visualization	Identity Rotation	Plugin Architecture
📊	⚡	🧪	🔒	🌍
Real-Time Dashboard	FastAPI Backend	Automated Validation	Tor Integration	Fingerprint Profiles

📑 TABLE OF CONTENTS

🌍 Overview	✨ Features	🏗 Architecture
💾 Installation	⚡ Quick Start	📊 Dashboard
🔧 Configuration	🧪 Testing	🗺 Roadmap
🤝 Contributing	⚠ Disclaimer	📜 License

🌍 OVERVIEW

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   GhostTrace is a battle-tested, production-ready           │
│   traffic-routing and proxy-chain management platform       │
│                                                             │
│   Built for:  Security Researchers  •  Developers           │
│              Network Analysts  •  Privacy Professionals     │
│                                                             │
│   The framework transforms complex routing workflows        │
│   into elegant, automated, and observable pipelines.        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🎯 What GhostTrace Solves

Problem	GhostTrace Solution
Manual proxy collection	Automated multi-source harvesting
Dead endpoints in chains	Real-time health validation engine
Complex chain construction	Dynamic multi-hop path building
Static routing configurations	Automated identity rotation
No visibility into routes	Live dashboard with visual mapping
Difficult integration	Full REST API with FastAPI
Limited extensibility	Modular plugin architecture

✨ FEATURES

🔗 Core Routing Dynamic Proxy Chaining Build complex multi-hop paths from validated endpoints Route Persistence Save and reload routing configurations Failover Handling Automatic dead-end detection and rerouting Latency Optimization Smart endpoint selection based on response times	🌐 Proxy Collection Multi-Source Harvesting Aggregate from public lists, APIs, and custom sources Protocol Diversity HTTP, HTTPS, SOCKS4, SOCKS5 support Geographic Filtering Country and region-based selection Anonymity Scoring Automatic anonymity level classification
🧪 Validation Engine Multi-Check Verification Connectivity, speed, and anonymity validation Parallel Testing High-throughput concurrent validation Adaptive Thresholds Configurable timeout and retry policies Historical Tracking Uptime and reliability metrics over time	🔄 Identity Rotation Scheduled Rotation Time-based automatic route refreshing Trigger-Based Rotation Event-driven identity switching Session Continuity Maintain state across rotations Rotation Logging Complete audit trail of identity changes
🔒 Advanced Security Tor Network Integration Optional additional routing layer Fingerprint Profiles Configurable browser identity sets Header Customization Full control over HTTP request headers Traffic Obfuscation Pattern randomization techniques	📊 Monitoring & API Real-Time Dashboard Web-based monitoring interface REST API Full programmatic access via FastAPI WebSocket Streaming Live log and status updates Export Capabilities JSON, CSV, and PDF reports

🏗 ARCHITECTURE

┌─────────────────────────────────────────────────────────────────────┐
│                        GHOSTTRACE CORE SYSTEM                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │   ROUTING   │  │   SESSION   │  │ FINGERPRINT │  │    TOR     │ │
│  │   MANAGER   │  │ CONTROLLER  │  │   MANAGER   │  │ INTEGRATION│ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘ │
│         │                │                │               │         │
│         └────────────────┼────────────────┼───────────────┘         │
│                          │                │                         │
│                   ┌──────┴────────────────┴──────┐                  │
│                   │      ORCHESTRATION BUS       │                  │
│                   └──────┬────────────────┬──────┘                  │
│                          │                │                         │
│         ┌────────────────┼────────────────┼───────────────┐        │
│         │                │                │               │        │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌──────┴──────┐  ┌────┴─────┐  │
│  │  VALIDATION │  │    PROXY    │  │  DASHBOARD  │  │ REPORTING│  │
│  │    ENGINE   │  │  COLLECTOR  │  │    & API    │  │  ENGINE  │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────────┘  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

📦 Component Breakdown

Layer	Component	Responsibility
Core	Routing Manager	Path construction, chaining logic, failover
Core	Session Controller	State management, persistence, rotation
Core	Fingerprint Manager	Browser identity profiles, header sets
Core	Tor Integration	Onion routing layer, circuit management
Service	Validation Engine	Health checks, speed tests, anonymity verification
Service	Proxy Collector	Multi-source harvesting, deduplication
Interface	Dashboard & API	Web UI, REST endpoints, WebSocket streaming
Output	Reporting Engine	Logs, metrics, exports, notifications

💾 INSTALLATION

📋 Prerequisites

Python 3.10+    ✅ Required
Git             ✅ Required
pip             ✅ Required
Tor (optional)  ⚪ For onion routing

🔽 Step-by-Step Setup

# 1. Clone the repository
git clone https://github.com/your-org/ghosttrace.git
cd ghosttrace

# 2. Create virtual environment
python -m venv venv

# 3. Activate environment
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Verify installation
python ghost.py --version

📦 Dependencies

fastapi>=0.104.0
uvicorn>=0.24.0
aiohttp>=3.9.0
requests>=2.31.0
pysocks>=1.7.1
pyyaml>=6.0
rich>=13.7.0
websockets>=12.0
pydantic>=2.5.0

⚡ QUICK START

Platform	Command
🪟 Windows	`run.bat`
🐧 Linux	`chmod +x run.sh && ./run.sh`
🍎 macOS	`chmod +x run.sh && ./run.sh`

🎮 Basic Usage

# Interactive mode
python ghost.py

# Quick chain with 3 hops
python ghost.py --chain --hops 3

# Validate proxy list
python ghost.py --validate proxies.txt

# Start dashboard only
python ghost.py --dashboard

# Full stack with rotation
python ghost.py --full --rotation-interval 120

📡 API Endpoints

GET    /api/status          → System health & metrics
GET    /api/proxies         → Available proxy pool
POST   /api/chain           → Build new routing chain
PUT    /api/rotate          → Trigger identity rotation
GET    /api/sessions        → Active session list
WS     /ws/live             → Real-time log stream

📊 DASHBOARD

┌───────────────────────────────────────────────────────────┐
│                   GHOSTTRACE DASHBOARD                    │
│                     http://127.0.0.1:5000                  │
├───────────────────────────────────────────────────────────┤
│                                                           │
│   📡 Runtime Status        🗺 Route Visualization         │
│   📈 Session Statistics    🌐 Proxy Pool Monitor          │
│   🔍 Diagnostics Panel     📝 Live Log Streaming          │
│   ⚙️ Configuration View    📊 Performance Metrics         │
│                                                           │
└───────────────────────────────────────────────────────────┘

🖥 Dashboard Panels

Panel	Description	Refresh Rate
Status Overview	System health, uptime, active chains	Real-time
Route Map	Visual multi-hop path display	On change
Proxy Pool	Available/active/dead endpoint counts	30s
Session Log	Scrolling live log viewer	Streaming
Metrics	Latency, throughput, success rates	10s
Config	Current active configuration	On change

🔧 CONFIGURATION

📄 `config.yaml` Reference

# ============================================
# GhostTrace v2.0 Configuration
# ============================================

system:
  log_level: INFO          # DEBUG | INFO | WARNING | ERROR
  data_dir: ./data         # Persistent data storage
  temp_dir: /tmp/ghost     # Temporary file location

routing:
  enabled: true
  default_protocol: socks5 # http | https | socks4 | socks5
  connection_timeout: 30   # Seconds
  max_retries: 3           # Per hop

proxy_chain:
  min_length: 2            # Minimum hops
  max_length: 4            # Maximum hops
  require_unique_countries: true
  exclude_countries:
    - CN
    - RU

rotation:
  enabled: true
  interval: 60             # Seconds between rotations
  strategy: round_robin    # round_robin | random | weighted
  on_failure: fallback     # fallback | direct | abort

validation:
  parallel_checks: 50      # Concurrent validations
  test_urls:
    - https://httpbin.org/ip
    - https://api.ipify.org
  speed_threshold: 5000    # Maximum latency in ms
  anonymity_checks: true

proxy_sources:
  enabled:
    - proxyscrape
    - proxy_list_download
    - free_proxy_list
  custom_urls: []
  update_interval: 3600    # Seconds

tor:
  enabled: false
  control_port: 9051
  socks_port: 9050
  auto_renew_circuit: true

fingerprint:
  rotation_with_proxy: true
  profiles_dir: ./profiles
  default_profile: chrome_windows

dashboard:
  enabled: true
  host: 127.0.0.1
  port: 5000
  auth_required: false
  theme: dark              # dark | light

api:
  enabled: true
  host: 127.0.0.1
  port: 8000
  rate_limit: 100          # Requests per minute
  cors_origins:
    - http://localhost:5000

🧪 TESTING

🏃 Run Test Suite

# All tests with verbose output
pytest tests/ -v --tb=long

# Specific test module
pytest tests/test_routing.py -v

# With coverage report
pytest tests/ --cov=ghosttrace --cov-report=html

# Quick smoke test
python ghost.py --test

✅ Test Coverage

Module	Tests	Coverage
Routing Engine	45	94%
Proxy Collector	32	91%
Validation	28	96%
Session Manager	21	89%
Dashboard API	38	93%
Fingerprint Manager	15	87%

🗺 ROADMAP

🎯 v2.1 — Q3 2026

Advanced dashboard analytics with historical charts
Extended PDF/HTML reporting system
Additional validation providers (Whoer, IPQualityScore)
Docker container support with compose files

🚀 v2.2 — Q4 2026

Plugin marketplace with community submissions
Distributed validation worker nodes
gRPC API for high-performance integrations
Kubernetes deployment manifests

🌟 v2.3 — Q1 2027

Machine learning-based proxy scoring
Automated chain optimization algorithms
Desktop GUI application (Electron)
Cloud-based proxy orchestration service

🤝 CONTRIBUTING

┌─────────────────────────────────────────────────────────┐
│              CONTRIBUTION WORKFLOW                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. Fork Repository                                      │
│       ↓                                                 │
│  2. Create Feature Branch                                │
│       ↓                                                 │
│  3. Implement Changes                                    │
│       ↓                                                 │
│  4. Write/Update Tests                                   │
│       ↓                                                 │
│  5. Run Full Test Suite                                  │
│       ↓                                                 │
│  6. Submit Pull Request                                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

📐 Contribution Guidelines

✅ Follow existing code conventions and style
✅ Include comprehensive tests for new features
✅ Keep modules isolated and single-responsibility
✅ Update documentation and docstrings
✅ Ensure all CI checks pass before PR
✅ Write meaningful commit messages (Conventional Commits)

🏆 Contributors

⚠ DISCLAIMER

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   GhostTrace is designed EXCLUSIVELY for:                     ║
║                                                               ║
║   🔬 Security Research                                        ║
║   📚 Educational Purposes                                     ║
║   🔧 Network Experimentation                                  ║
║   ✅ Authorized Testing Environments                          ║
║                                                               ║
║   ⛔ UNAUTHORIZED USE IS STRICTLY PROHIBITED ⛔                ║
║                                                               ║
║   Users bear FULL responsibility for compliance with          ║
║   all applicable laws, regulations, and policies.             ║
║                                                               ║
║   The developers assume NO LIABILITY for misuse or            ║
║   damages resulting from this software.                       ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

📜 LICENSE

MIT License — See LICENSE file for complete terms and conditions.

Copyright (c) 2026 GhostTrace Development Team

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files...

                    ██████╗ ██╗  ██╗ ██████╗ ███████╗████████╗
                   ██╔════╝ ██║  ██║██╔═══██╗██╔════╝╚══██╔══╝
                   ██║  ███╗███████║██║   ██║███████╗   ██║
                   ██║   ██║██╔══██║██║   ██║╚════██║   ██║
                   ╚██████╔╝██║  ██║╚██████╔╝███████║   ██║
                    ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝

BUILT WITH ❤️ FOR MODERN NETWORK RESEARCH

Routing excellence. Automated. Observable. Reliable.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
config		config
core		core
docker		docker
modules		modules
output		output
scrapers		scrapers
tests		tests
tor		tor
web		web
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
ghost.py		ghost.py
package-lock.json		package-lock.json
requirements.txt		requirements.txt
run.bat		run.bat
run.sh		run.sh
temp_torrc		temp_torrc
test.py		test.py

Folders and files

Latest commit

History

Repository files navigation

👻 GHOSTTRACE v2.0

Advanced Network Routing, Proxy Chain Orchestration & Traffic Analysis Framework

⚡ A NEXT-GENERATION FRAMEWORK FOR NETWORK TRAFFIC ORCHESTRATION

📑 TABLE OF CONTENTS

🌍 OVERVIEW

🎯 What GhostTrace Solves

✨ FEATURES

🔗 Core Routing

🌐 Proxy Collection

🧪 Validation Engine

🔄 Identity Rotation

🔒 Advanced Security

📊 Monitoring & API

🏗 ARCHITECTURE

📦 Component Breakdown

💾 INSTALLATION

📋 Prerequisites

🔽 Step-by-Step Setup

📦 Dependencies

⚡ QUICK START

🎮 Basic Usage

📡 API Endpoints

📊 DASHBOARD

🖥 Dashboard Panels

🔧 CONFIGURATION

📄 config.yaml Reference

🧪 TESTING

🏃 Run Test Suite

✅ Test Coverage

🗺 ROADMAP

🎯 v2.1 — Q3 2026

🚀 v2.2 — Q4 2026

🌟 v2.3 — Q1 2027

🤝 CONTRIBUTING

📐 Contribution Guidelines

🏆 Contributors

⚠ DISCLAIMER

📜 LICENSE

BUILT WITH ❤️ FOR MODERN NETWORK RESEARCH

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

📄 `config.yaml` Reference

Packages