Tor Traffic Analysis System

This repo is a Tor traffic analysis playground: upload a PCAP, extract flows, label likely Tor traffic, and correlate activity against public Tor network data (consensus + Onionoo). The UI is a small React app; the backend is FastAPI.

If you want the “what’s in here?” overview, check docs/project_overview.md.

What it does

• PCAP ingestion → flow extraction and feature calculation
• Tor-ish flow detection (ML-based)
• Fetches Tor relay metadata and keeps it refreshed in the background
• Correlates flow timing against relay behavior and produces ranked candidates
• UI pages for flows, results, and a Tor network view

Repo layout

backend/     FastAPI app + processing services
frontend/    React (Vite) UI
geoip/       Optional MaxMind GeoLite2 databases (ignored by git)
scripts/     Convenience run scripts
docs/        Notes / project overview

Quick start

Prereqs:

• Python 3.9+
• Node.js 16+
• Postgres + Redis (local) or Supabase + Upstash/managed Redis

Backend:

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python init_db.py
python main.py

Frontend:

cd frontend
npm install
npm run dev

URLs:

• Backend: http://localhost:8000
• Frontend: http://localhost:5173

For more detailed backend setup notes, see backend/README_SETUP.md and backend/SUPABASE_SETUP.md.

GeoIP (optional)

Some parts of the pipeline can enrich IPs with ASN/city lookups via MaxMind GeoLite2. The .mmdb files are large and license-bound, so the repo ignores geoip/*.mmdb.

1. Download GeoLite2-ASN.mmdb and GeoLite2-City.mmdb from MaxMind.
2. Put them in ./geoip/.
3. Set in backend/.env (absolute paths also work):

   GEOIP_ASN_DB_PATH=geoip/GeoLite2-ASN.mmdb
   GEOIP_CITY_DB_PATH=geoip/GeoLite2-City.mmdb

Useful API endpoints

• POST /api/v1/upload-pcap
• GET /api/v1/flows
• POST /api/v1/analyze-flow/{flow_id}
• POST /api/v1/analyze-all
• GET /api/v1/analysis-results
• WS /api/v1/ws

Config knobs

Most runtime config is in backend/config/settings.py and/or backend/.env. Common ones:

• DATABASE_URL, REDIS_URL
• TOR_REFRESH_INTERVAL
• GEOIP_ASN_DB_PATH, GEOIP_CITY_DB_PATH

Notes

• Windows/Linux convenience scripts live in scripts/.
• If you’re committing work, please avoid committing PCAPs or .mmdb files.